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 空间中的射线，用于查找第一个与其相交的物体。

描述

Raycast 代表的是从它的原点到 target_position 的射线，如果与碰撞对象相交，就能找到路径上距离最近的物体。

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

如果为 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 的 position。

方法说明

void add_exception(node: CollisionObject3D) 🔗

添加碰撞例外，这样射线就不会报告与指定 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）。

注意：该物体不一定是 CollisionObject3D。例如射线与 CSGShape3D 或 GridMap 相交时，方法返回的就是 CSGShape3D 或 GridMap 实例。

RID get_collider_rid() const 🔗

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

int get_collider_shape() const 🔗

返回与射线相交的第一个对象的形状 ID，射线未与任何对象相交时返回 0（即 is_colliding() 返回 false 时）。

要获取相交的形状节点，比如假设目标是 CollisionObject3D，可以使用：

var target = get_collider() # 是 CollisionObject3D 节点。
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)

int get_collision_face_index() const 🔗

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

bool get_collision_mask_value(layer_number: int) const 🔗

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

Vector3 get_collision_normal() const 🔗

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

注意：请在调用前检查 is_colliding() 返回的是否为 true，这样返回的法线就是即时有效的。

Vector3 get_collision_point() const 🔗

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

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

bool is_colliding() const 🔗

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

void remove_exception(node: CollisionObject3D) 🔗

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

void remove_exception_rid(rid: RID) 🔗

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

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

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