Index · Object → Node → Node3D → RayCast3D

RayCast3D

A ray in 3D space, used to find the first collision object it intersects.

Class Description

A raycast represents a ray from its origin to its target_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 ignore Area3Ds (collide_with_areas) or PhysicsBody3Ds (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 a RayCast3D multiple times within the same physics frame, use force_raycast_update().

To sweep over a region of 3D space, you can approximate the region with multiple RayCast3Ds or use ShapeCast3D.

Properties

var collide_with_areas: bool = false

If true, collisions with Area3Ds will be reported.

var collide_with_bodies: bool = true

If true, collisions with PhysicsBody3Ds will be reported.

var collision_mask: int = 1

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

var debug_shape_custom_color: Color = Color(0, 0, 0, 1)

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

If set to Color(0.0, 0.0, 0.0) (by default), the color set in ProjectSettings.debug/shapes/collision/shape_color is used.

var debug_shape_thickness: int = 2

If set to 1, a line is used as the debug shape. Otherwise, a truncated pyramid is drawn to represent the RayCast3D. Requires Visible Collision Shapes to be enabled in the Debug menu for the debug shape to be visible at run-time.

var enabled: bool = true

If true, collisions will be reported.

var exclude_parent: bool = true

If true, this raycast will not report collisions with its parent node. This property only has an effect if the parent node is a CollisionObject3D. See also Node.get_parent() and add_exception().

var hit_back_faces: bool = true

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

var hit_from_inside: bool = false

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

var target_position: Vector3 = Vector3(0, -1, 0)

The ray's destination point, relative to this raycast's Node3D.position.

Inherited from Node3D (17)
var position: Vector3 = Vector3(0, 0, 0)
var rotation: Vector3 = Vector3(0, 0, 0)
var rotation_order: EulerOrder = 2
var scale: Vector3 = Vector3(1, 1, 1)
var top_level: bool = false
var transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)
var visibility_parent: NodePath = NodePath("")
var visible: bool = true
Inherited from Node (14)
var owner: Node

Methods

func add_exception(node: CollisionObject3D) -> void

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

func add_exception_rid(rid: RID) -> void

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

func clear_exceptions() -> void

Removes all collision exceptions for this ray.

func force_raycast_update() -> void

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 be true for this to work.

func get_collider() -> Object

Returns the first object that the ray intersects, or null if no object is intersecting the ray (i.e. is_colliding() returns false).

Note: This object is not guaranteed to be a CollisionObject3D. For example, if the ray intersects a CSGShape3D or a GridMap, the method will return a CSGShape3D or GridMap instance.

func get_collider_rid() -> RID

Returns the RID of the first object that the ray intersects, or an empty RID if no object is intersecting the ray (i.e. is_colliding() returns false).

func get_collider_shape() -> int

Returns the shape ID of the first object that the ray intersects, or 0 if no object is intersecting the ray (i.e. is_colliding() returns false).

To get the intersected shape node, for a CollisionObject3D target, use:

var target = get_collider() # A CollisionObject3D.
var shape_id = get_collider_shape() # The shape index in the collider.
var owner_id = target.shape_find_owner(shape_id) # The owner ID in the collider.
var shape = target.shape_owner_get_owner(owner_id)
func get_collision_face_index() -> int

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

func get_collision_mask_value(layer_number: int) -> bool

Returns whether or not the specified layer of the collision_mask is enabled, given a layer_number between 1 and 32.

func get_collision_normal() -> Vector3

Returns the normal of the intersecting object's shape at the collision point, or Vector3(0, 0, 0) if the ray starts inside the shape and hit_from_inside is true.

Note: Check that is_colliding() returns true before calling this method to ensure the returned normal is valid and up-to-date.

func get_collision_point() -> Vector3

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

Note: Check that is_colliding() returns true before calling this method to ensure the returned point is valid and up-to-date.

func is_colliding() -> bool

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

func remove_exception(node: CollisionObject3D) -> void

Removes a collision exception so the ray can report collisions with the specified node.

func remove_exception_rid(rid: RID) -> void

Removes a collision exception so the ray can report collisions with the specified RID.

func set_collision_mask_value(layer_number: int, value: bool) -> void

Based on value, enables or disables the specified layer in the collision_mask, given a layer_number between 1 and 32.

Inherited from Node3D (37)
func add_gizmo(gizmo: Node3DGizmo) -> void
func clear_gizmos() -> void
func force_update_transform() -> void
func get_gizmos() -> Node3DGizmo[]
func global_rotate(axis: Vector3, angle: float) -> void
func global_scale(scale: Vector3) -> void
func global_translate(offset: Vector3) -> void
func hide() -> void
func look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func orthonormalize() -> void
func rotate(axis: Vector3, angle: float) -> void
func rotate_object_local(axis: Vector3, angle: float) -> void
func rotate_x(angle: float) -> void
func rotate_y(angle: float) -> void
func rotate_z(angle: float) -> void
func scale_object_local(scale: Vector3) -> void
func set_disable_scale(disable: bool) -> void
func set_identity() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) -> void
func show() -> void
func to_global(local_point: Vector3) -> Vector3
func to_local(global_point: Vector3) -> Vector3
func translate(offset: Vector3) -> void
func translate_object_local(offset: Vector3) -> void
func update_gizmos() -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Node3D (1)
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)