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

3D 空间中的射线，用于查找第一个相交的 CollisionObject3D。

描述

Raycast 代表的是从它的原点到 target_position 的射线，如果与碰撞对象相交，就能找到路径上距离最近的 CollisionObject3D。可以用来做很多事情，例如

要让 RayCast3D 忽略某些对象，可以将它们加入例外列表，也可以让检测汇报忽略 Area3D（collide_with_areas）或 PhysicsBody3D（collide_with_bodies），还可以配置物理层。

RayCast3D 每一个物理帧都会计算是否相交，计算结果会保留到下一个物理帧。如果要立即执行射线投射，或者你想要在同一个物理帧内多次配置 RayCast3D，请使用 force_raycast_update。

要扫描 3D 空间中的某个区域，可以使用多个 RayCast3D 去近似，也可以使用 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 ( CollisionObject3D node )

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 ( int layer_number ) const

Vector3

get_collision_normal ( ) const

Vector3

get_collision_point ( ) const

bool

is_colliding ( ) const

void

remove_exception ( CollisionObject3D node )

void

remove_exception_rid ( RID rid )

void

set_collision_mask_value ( int layer_number, bool value )

属性说明

bool collide_with_areas = false

  • void set_collide_with_areas ( bool value )

  • bool is_collide_with_areas_enabled ( )

如果为 true，则会报告与 Area3D 的碰撞。

bool collide_with_bodies = true

  • void set_collide_with_bodies ( bool value )

  • bool is_collide_with_bodies_enabled ( )

如果为 true，则会报告与 PhysicsBody3D 的碰撞。

int collision_mask = 1

  • void set_collision_mask ( int value )

  • int get_collision_mask ( )

射线的碰撞遮罩。只能检测到至少启用了一个遮罩中碰撞层的对象。详情请参阅文档中的《碰撞层与掩码》。

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

  • void set_debug_shape_custom_color ( Color value )

  • 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 ( int value )

  • int get_debug_shape_thickness ( )

如果设置为 1，则使用一条线作为调试形状。否则，将绘制一个截断的金字塔来表示 RayCast3D。需要在调试菜单中启用可见碰撞形状，以便调试形状在运行时可见。

bool enabled = true

  • void set_enabled ( bool value )

  • bool is_enabled ( )

如果为 true，将报告碰撞。

bool exclude_parent = true

  • void set_exclude_parent_body ( bool value )

  • bool get_exclude_parent_body ( )

如果为 true，则该 RayCast3D 的直接父级的碰撞将被忽略。

bool hit_back_faces = true

  • void set_hit_back_faces ( bool value )

  • bool is_hit_back_faces_enabled ( )

如果为 true，射线将命中背部面，这些背部面是启用了背面的凹多边形形状，或高度图形状。

bool hit_from_inside = false

  • void set_hit_from_inside ( bool value )

  • bool is_hit_from_inside_enabled ( )

如果为 true，射线会在从形状内部开始时检测到命中。在此情况下，碰撞法线将为 Vector3(0, 0, 0)。不会影响无体积的形状，如凹多边形和高度图。

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

  • void set_target_position ( Vector3 value )

  • Vector3 get_target_position ( )

射线的目标点，相对于该 RayCast 的 position。

方法说明

void add_exception ( CollisionObject3D node )

添加碰撞例外，这样射线就不会报告与指定 CollisionObject3D 节点的碰撞。

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）。

RID get_collider_rid ( ) const

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

int get_collider_shape ( ) const

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

int get_collision_face_index ( ) const

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

bool get_collision_mask_value ( int layer_number ) const

返回 collision_mask 中是否启用了指定的层，给定的 layer_number 应在 1 和 32 之间。

Vector3 get_collision_normal ( ) const

返回相交对象形状在碰撞点处的法线；或者如果射线从形状内部开始并且 hit_from_inside 为 true，则返回 Vector3(0, 0, 0)。

Vector3 get_collision_point ( ) const

返回射线与最近的物体相交的碰撞点。

注意：这个点是在全局坐标系中。

bool is_colliding ( ) const

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

void remove_exception ( CollisionObject3D node )

移除一个碰撞例外，以便射线确实报告与指定 CollisionObject3D 节点的碰撞。

void remove_exception_rid ( RID rid )

移除碰撞例外，这样射线就会报告与指定的 RID 的碰撞。

void set_collision_mask_value ( int layer_number, bool value )

根据 value，启用或禁用 collision_mask 中指定的层，给定的 layer_number 应在 1 和 32 之间。