RayCast

继承： Item3D < Item < Object

三维空间中的一条射线，用于找到它相交的第一个物体。

描述

光线投射表示从它的原点到它的target_position的光线，如果它与任何物体相交，它会沿着它的路径找到最近的物体。

RayCast可以通过将某些对象添加到异常列表、使其检测报告忽略AreaTrigger（collide_with_areas）或PhysicsBulkBase（collide_with_bodies）或配置物理层来忽略它们。

RayCast计算每个物理帧的交集，并将结果保存到下一个物理帧。对于即时光线投射，或者如果您想在同一物理帧内多次配置RayCast，请使用force_raycast_update()。

要扫描3D空间的区域，您可以使用多个RayCast来近似该区域或使用ShapeCast。

属性

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: ColliderObjectBase)
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: ColliderObjectBase)
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，则会报告与AreaTrigger的冲突。

---

bool collide_with_bodies = true 🔗

• void set_collide_with_bodies(value: bool)

• bool is_collide_with_bodies_enabled()

如果true，则会报告与PhysicsBulkBase的冲突。

---

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

如果Debug菜单中启用了可见碰撞形状，则在运行时用于在编辑器中绘制形状的自定义颜色。如果RayCast与某物碰撞，此颜色将在运行时突出显示。

如果设置为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，则使用一条线作为调试形状。否则，将绘制一个截断的金字塔来表示RayCast。需要在调试菜单中启用可见碰撞形状，调试形状才能在运行时可见。

---

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

如果true，则此RayCast3D的直接父级将忽略冲突。

---

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

射线的目标点，相对于RayCast的位置。

---

方法说明

void add_exception(node: ColliderObjectBase) 🔗

添加冲突异常，以便射线不报告与指定ColliderObjectBase节点的冲突。

---

void add_exception_rid(rid: RID) 🔗

添加冲突异常，以便射线不报告与指定RID的冲突。

---

void clear_exceptions() 🔗

删除此射线的所有碰撞异常。

---

void force_raycast_update() 🔗

立即更新射线的碰撞信息，无需等待下一次_physics_process调用。例如，当射线或其父射线更改状态时，请使用此方法。

注意：enabled不需要是true即可工作。

---

Object get_collider() const 🔗

返回射线相交的第一个对象，如果没有对象与射线相交，则返回null（即is_colliding()返回false）。

注意：此对象不保证是ColliderObjectBase。例如，如果光线与ICSGShapeBase或GridMap相交，则该方法将返回ICSGShapeBase或GridMap实例。

---

RID get_collider_rid() const 🔗

返回射线相交的第一个对象的RID，如果没有对象与射线相交，则返回空的RID（即is_colliding()返回false）。

---

int get_collider_shape() const 🔗

返回光线相交的第一个对象的形状ID，如果没有对象与光线相交（即is_colliding()返回false），则返回0。

要获取相交的形状节点，对于ColliderObjectBase目标，使用：

t .. tabs:

.. code-tab:: s3script

   var target = get_collider() # 一个 ColliderObjectBase.
   var shape_id = get_collider_shape() # 碰撞体中的形状索引.
   var owner_id = target.shape_find_owner(shape_id) # 碰撞体中的所有者 ID.
   var shape = target.shape_owner_get_owner(owner_id)

.. code-tab:: csharp

   var target = (ColliderObjectBase)GetCollider(); // 一个 ColliderObjectBase.
   var shapeId = GetColliderShape(); // 碰撞体中的形状索引.
   var ownerId = target.ShapeFindOwner(shapeId); // 碰撞体中的所有者 ID.
   var shape = target.ShapeOwnerGetOwner(ownerId);

---

int get_collision_face_index() const 🔗

返回碰撞对象在碰撞点的面索引，如果与射线相交的形状不是ConcavePolygonShape3D，则返回-1。

---

bool get_collision_mask_value(layer_number: int) const 🔗

返回collision_mask的指定层是否启用，给定介于1和32之间的layer_number。

---

Vector3 get_collision_normal() const 🔗

返回相交对象在碰撞点的形状的法线，或者Vector3（0,0,0）如果光线在形状内部开始并且hit_from_inside为true。

注意：在调用此方法之前检查is_colliding()返回true以确保返回的法线有效且是最新的。

---

Vector3 get_collision_point() const 🔗

返回光线在全局坐标系中与最近物体相交的碰撞点。如果hit_from_inside为true并且光线从碰撞形状内部开始，则此函数将返回光线的原点。

注意：在调用此方法之前检查is_colliding()返回true，以确保返回的点有效且是最新的。

---

bool is_colliding() const 🔗

返回是否有任何对象与射线的向量相交（考虑向量长度）。

---

void remove_exception(node: ColliderObjectBase) 🔗

删除冲突异常，以便射线确实报告与指定ColliderObjectBase节点的冲突。

---

void remove_exception_rid(rid: RID) 🔗

删除冲突异常，以便射线确实报告与指定RID的冲突。

---

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

基于value，启用或禁用collision_mask中的指定层，给定1到32之间的layer_number。