Description

A raycast represents a ray from its origin to itstarget_position that finds the closest object along its path, if it intersects any.

RayCast3D can ignore some objects by adding them to an exception list, by making its detection reporting ignoreArea3Ds (collide_with_areas) orPhysicsBody3Ds (collide_with_bodies), or by configuring physics layers.

RayCast3D calculates intersection every physics frame, and it holds the result until the next physics frame. For an immediate raycast, or if you want to configure aRayCast3D multiple times within the same physics frame, useforce_raycast_update().

To sweep over a region of 3D space, you can approximate the region with multipleRayCast3Ds or useShapeCast3D.

Tutorials

• Ray-casting

• 3D Voxel Demo

Properties

Methods

Property Descriptions

boolcollide_with_areas =false🔗

• voidset_collide_with_areas(value:bool)

• boolis_collide_with_areas_enabled()

Iftrue, collisions withArea3Ds will be reported.

boolcollide_with_bodies =true🔗

• voidset_collide_with_bodies(value:bool)

• boolis_collide_with_bodies_enabled()

Iftrue, collisions withPhysicsBody3Ds will be reported.

intcollision_mask =1🔗

• voidset_collision_mask(value:int)

• intget_collision_mask()

The ray's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. SeeCollision layers and masks in the documentation for more information.

Colordebug_shape_custom_color =Color(0,0,0,1)🔗

• voidset_debug_shape_custom_color(value:Color)

• Colorget_debug_shape_custom_color()

The custom color to use to draw the shape in the editor and at run-time ifVisible Collision Shapes is enabled in theDebug menu. This color will be highlighted at run-time if theRayCast3D is colliding with something.

If set toColor(0.0,0.0,0.0) (by default), the color set inProjectSettings.debug/shapes/collision/shape_color is used.

intdebug_shape_thickness =2🔗

• voidset_debug_shape_thickness(value:int)

• intget_debug_shape_thickness()

If set to1, a line is used as the debug shape. Otherwise, a truncated pyramid is drawn to represent theRayCast3D. RequiresVisible Collision Shapes to be enabled in theDebug menu for the debug shape to be visible at run-time.

boolenabled =true🔗

• voidset_enabled(value:bool)

• boolis_enabled()

Iftrue, collisions will be reported.

boolexclude_parent =true🔗

• voidset_exclude_parent_body(value:bool)

• boolget_exclude_parent_body()

Iftrue, collisions will be ignored for this RayCast3D's immediate parent.

boolhit_back_faces =true🔗

• voidset_hit_back_faces(value:bool)

• boolis_hit_back_faces_enabled()

Iftrue, the ray will hit back faces with concave polygon shapes with back face enabled or heightmap shapes.

boolhit_from_inside =false🔗

• voidset_hit_from_inside(value:bool)

• boolis_hit_from_inside_enabled()

Iftrue, the ray will detect a hit when starting inside shapes. In this case the collision normal will beVector3(0,0,0). Does not affect shapes with no volume like concave polygon or heightmap.

Vector3target_position =Vector3(0,-1,0)🔗

• voidset_target_position(value:Vector3)

• Vector3get_target_position()

The ray's destination point, relative to the RayCast'sposition.

Method Descriptions

voidadd_exception(node:CollisionObject3D)🔗

Adds a collision exception so the ray does not report collisions with the specifiedCollisionObject3D node.

voidadd_exception_rid(rid:RID)🔗

Adds a collision exception so the ray does not report collisions with the specifiedRID.

voidclear_exceptions()🔗

Removes all collision exceptions for this ray.

voidforce_raycast_update()🔗

Updates the collision information for the ray immediately, without waiting for the next_physics_process call. Use this method, for example, when the ray or its parent has changed state.

Note:enabled does not need to betrue for this to work.

Objectget_collider()const🔗

Returns the first object that the ray intersects, ornull if no object is intersecting the ray (i.e.is_colliding() returnsfalse).

Note: This object is not guaranteed to be aCollisionObject3D. For example, if the ray intersects aCSGShape3D or aGridMap, the method will return aCSGShape3D orGridMap instance.

RIDget_collider_rid()const🔗

Returns theRID of the first object that the ray intersects, or an emptyRID if no object is intersecting the ray (i.e.is_colliding() returnsfalse).

intget_collider_shape()const🔗

Returns the shape ID of the first object that the ray intersects, or0 if no object is intersecting the ray (i.e.is_colliding() returnsfalse).

To get the intersected shape node, for aCollisionObject3D target, use:

vartarget=get_collider()# A CollisionObject3D.varshape_id=get_collider_shape()# The shape index in the collider.varowner_id=target.shape_find_owner(shape_id)# The owner ID in the collider.varshape=target.shape_owner_get_owner(owner_id)

vartarget=(CollisionObject3D)GetCollider();// A CollisionObject3D.varshapeId=GetColliderShape();// The shape index in the collider.varownerId=target.ShapeFindOwner(shapeId);// The owner ID in the collider.varshape=target.ShapeOwnerGetOwner(ownerId);

intget_collision_face_index()const🔗

Returns the collision object's face index at the collision point, or-1 if the shape intersecting the ray is not aConcavePolygonShape3D.

boolget_collision_mask_value(layer_number:int)const🔗

Returns whether or not the specified layer of thecollision_mask is enabled, given alayer_number between 1 and 32.

Vector3get_collision_normal()const🔗

Returns the normal of the intersecting object's shape at the collision point, orVector3(0,0,0) if the ray starts inside the shape andhit_from_inside istrue.

Note: Check thatis_colliding() returnstrue before calling this method to ensure the returned normal is valid and up-to-date.

Vector3get_collision_point()const🔗

Returns the collision point at which the ray intersects the closest object, in the global coordinate system. Ifhit_from_inside istrue and the ray starts inside of a collision shape, this function will return the origin point of the ray.

Note: Check thatis_colliding() returnstrue before calling this method to ensure the returned point is valid and up-to-date.

boolis_colliding()const🔗

Returns whether any object is intersecting with the ray's vector (considering the vector length).

voidremove_exception(node:CollisionObject3D)🔗

Removes a collision exception so the ray does report collisions with the specifiedCollisionObject3D node.

voidremove_exception_rid(rid:RID)🔗

Removes a collision exception so the ray does report collisions with the specifiedRID.

voidset_collision_mask_value(layer_number:int, value:bool)🔗

Based onvalue, enables or disables the specified layer in thecollision_mask, given alayer_number between 1 and 32.