Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

RayCast3D

繼承： Node3D < Node < Object

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

說明

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.

教學

屬性

bool	collide_with_areas	`false`
bool	collide_with_bodies	`true`
int	collision_mask	`1`
Color	debug_shape_custom_color	`Color(0, 0, 0, 1)`
int	debug_shape_thickness	`2`
bool	enabled	`true`
bool	exclude_parent	`true`
bool	hit_back_faces	`true`
bool	hit_from_inside	`false`
Vector3	target_position	`Vector3(0, -1, 0)`

方法

void	add_exception(node: CollisionObject3D)
void	add_exception_rid(rid: RID)
void	clear_exceptions()
void	force_raycast_update()
Object	get_collider() const
RID	get_collider_rid() const
int	get_collider_shape() const
int	get_collision_face_index() const
bool	get_collision_mask_value(layer_number: int) const
Vector3	get_collision_normal() const
Vector3	get_collision_point() const
bool	is_colliding() const
void	remove_exception(node: CollisionObject3D)
void	remove_exception_rid(rid: RID)
void	set_collision_mask_value(layer_number: int, value: bool)

屬性說明

bool collide_with_areas = false 🔗

void set_collide_with_areas(value: bool)
bool is_collide_with_areas_enabled()

如果為 true，則會報告與 Area3D 的碰撞。

bool collide_with_bodies = true 🔗

void set_collide_with_bodies(value: bool)
bool is_collide_with_bodies_enabled()

如果為 true，則會報告與 PhysicsBody3D 的碰撞。

int collision_mask = 1 🔗

void set_collision_mask(value: int)
int get_collision_mask()

射線的碰撞遮罩。只能偵測到至少啟用了一個遮罩中碰撞層的物件。詳情請參閱文件中的《碰撞層與遮罩》。

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

void set_debug_shape_custom_color(value: Color)
Color get_debug_shape_custom_color()

如果在除錯功能表中啟用了可見碰撞形狀，則用於在編輯器中和運作時中繪製形狀的自訂顏色。如果 RayCast3D 與某物發生碰撞，該顏色將在運作時突出顯示。

如果設定為 Color(0.0, 0.0, 0.0)（預設情況下），則使用 ProjectSettings.debug/shapes/collision/shape_color 中設定的顏色。

int debug_shape_thickness = 2 🔗

void set_debug_shape_thickness(value: int)
int get_debug_shape_thickness()

如果設定為 1，則使用一條線作為除錯形狀。否則，將繪製一個截斷的金字塔來表示 RayCast3D。需要在除錯選單中啟用可見碰撞形狀，以便除錯形狀在運作時可見。

bool enabled = true 🔗

void set_enabled(value: bool)
bool is_enabled()

如果為 true，將報告碰撞。

bool exclude_parent = true 🔗

void set_exclude_parent_body(value: bool)
bool get_exclude_parent_body()

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().

bool hit_back_faces = true 🔗

void set_hit_back_faces(value: bool)
bool is_hit_back_faces_enabled()

如果為 true，查詢將命中背部面，這些背部面是啟用了背面的凹多邊形形狀，或高度圖形狀。

bool hit_from_inside = false 🔗

void set_hit_from_inside(value: bool)
bool is_hit_from_inside_enabled()

如果為 true，射線會在從形狀內部開始時偵測到命中。在此情況下，碰撞法線將為 Vector3(0, 0, 0)。不會影響無體積的形狀，如凹多邊形和高度圖。

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

void set_target_position(value: Vector3)
Vector3 get_target_position()

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

方法說明

void add_exception(node: CollisionObject3D) 🔗

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

void add_exception_rid(rid: RID) 🔗

新增碰撞例外，這樣射線就不會報告與指定 RID 的碰撞。

void clear_exceptions() 🔗

刪除此射線的所有碰撞例外。

void force_raycast_update() 🔗

更新射線的碰撞資訊。使用該方法立即更新碰撞資訊，而不是等待下一個 _physics_process 呼叫，例如，如果射線或其父級已更改狀態。

注意：enabled 不需要為 true 即可生效。

Object get_collider() const 🔗

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.

RID get_collider_rid() const 🔗

返回該射線相交的第一個物件的 RID，如果沒有物件與該射線相交，則返回空 RID（即 is_colliding() 返回 false）。

int get_collider_shape() const 🔗

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)

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

int get_collision_face_index() const 🔗

返回相交物件的形狀在碰撞點處的法線，如果射線從該形狀內部發出並且 hit_from_inside 為 true，則為 Vector2(0, 0)。

bool get_collision_mask_value(layer_number: int) const 🔗

返回 collision_mask 中是否啟用了指定的層，給定的 layer_number 應在 1 和 32 之間。

Vector3 get_collision_normal() const 🔗

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.

Vector3 get_collision_point() const 🔗

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.

bool is_colliding() const 🔗

返回是否有任何物件與射線的向量相交（考慮向量長度）。

void remove_exception(node: CollisionObject3D) 🔗

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

void remove_exception_rid(rid: RID) 🔗

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

void set_collision_mask_value(layer_number: int, value: bool) 🔗

根據 value，啟用或禁用 collision_mask 中指定的層，給定的 layer_number 應在 1 和 32 之間。