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

ShapeCast3D

继承： Node3D < Node < Object

3D 形状，会扫描空间中某个区域，用于检测 CollisionObject3D。

描述

形状投射会将其 shape 沿着 target_position 确定的投射方向进行扫描，能够检测到碰撞对象。类似于 RayCast3D，但是能够扫描空间中的一个区域，而不仅仅是一条直线。ShapeCast3D 能够检测到多个碰撞对象。可用于实现较宽的激光射线，或者将简单的形状吸附到地面。

要立即检测碰撞重叠，可以将 target_position 设置为 Vector3(0, 0, 0)，并在同一个物理帧中调用 force_shapecast_update。这样就能够克服 Area3D 在进行连续区域检测时的局限性，因为它无法立即获取碰撞信息。

注意：形状投射比射线投射的计算量更大。

属性

bool	collide_with_areas	false
bool	collide_with_bodies	true
int	collision_mask	1
Array	collision_result	[]
Color	debug_shape_custom_color	Color(0, 0, 0, 1)
bool	enabled	true
bool	exclude_parent	true
float	margin	0.0
int	max_results	32
Shape3D	shape
Vector3	target_position	Vector3(0, -1, 0)

方法

void	add_exception(node: CollisionObject3D)
void	add_exception_rid(rid: RID)
void	clear_exceptions()
void	force_shapecast_update()
float	get_closest_collision_safe_fraction() const
float	get_closest_collision_unsafe_fraction() const
Object	get_collider(index: int) const
RID	get_collider_rid(index: int) const
int	get_collider_shape(index: int) const
int	get_collision_count() const
bool	get_collision_mask_value(layer_number: int) const
Vector3	get_collision_normal(index: int) const
Vector3	get_collision_point(index: int) const
bool	is_colliding() const
void	remove_exception(node: CollisionObject3D)
void	remove_exception_rid(rid: RID)
void	resource_changed(resource: Resource)
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()

形状的碰撞掩码。只有至少启用了一个在该掩码中的碰撞层的对象才会被检测到。有关详细信息，请参阅文档中的《碰撞层和掩码》。

---

Array collision_result = [] 🔗

从碰撞扫描返回完整的碰撞信息。返回的数据与 PhysicsDirectSpaceState3D.get_rest_info 方法中的数据相同。

---

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

• void set_debug_shape_custom_color(value: Color)

• Color get_debug_shape_custom_color()

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

如果设置为 Color(0.0, 0.0, 0.0)（默认值），则使用 ProjectSettings.debug/shapes/collision/shape_color 中设置的颜色。

---

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，父节点将被排除在碰撞检测之外。

---

float margin = 0.0 🔗

• void set_margin(value: float)

• float get_margin()

该形状的碰撞边距。较大的边距有助于更一致地检测碰撞，但代价是牺牲精度。

---

int max_results = 32 🔗

• void set_max_results(value: int)

• int get_max_results()

可以使用这个参数来限制相交点的数量，减少处理时间。

---

Shape3D shape 🔗

• void set_shape(value: Shape3D)

• Shape3D get_shape()

派生自 Shape3D 的形状，用于碰撞查询。

---

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

• void set_target_position(value: Vector3)

• Vector3 get_target_position()

该形状的目标点，相对于该节点的 position。

---

方法说明

void add_exception(node: CollisionObject3D) 🔗

添加碰撞例外，让该形状不再汇报与指定 CollisionObject3D 节点的碰撞。

---

void add_exception_rid(rid: RID) 🔗

添加碰撞例外，使该形状不汇报与指定 RID 节点的碰撞。

---

void clear_exceptions() 🔗

移除该 ShapeCast3D 的所有碰撞例外。

---

void force_shapecast_update() 🔗

立即更新形状的碰撞信息，不等待下一次的 _physics_process 调用。例如，请在形状或其父级更改状态后使用该方法。

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

---

float get_closest_collision_safe_fraction() const 🔗

从 ShapeCast3D 的原点到其 target_position（介于 0 和 1 之间）的分数，即形状可以在不触发碰撞的情况下移动多远。

---

float get_closest_collision_unsafe_fraction() const 🔗

从 ShapeCast3D 的原点到其 target_position 的分数（介于 0 和 1 之间），即形状必须移动多远才能触发碰撞。

在理想条件下，这将与 get_closest_collision_safe_fraction 相同，但是形状投射是分步骤计算的，因此精确的碰撞点可能发生在两个计算位置之间。

---

Object get_collider(index: int) const 🔗

返回 index 处多次碰撞之一的碰撞 Object，如果没有对象与形状相交（即 is_colliding 返回 false），则返回 null。

---

RID get_collider_rid(index: int) const 🔗

返回 index 处多次碰撞之一的碰撞对象的 RID。

---

int get_collider_shape(index: int) const 🔗

返回 index 处多次碰撞之一的碰撞形状的形状 ID，如果没有对象与该形状相交（即 is_colliding 返回 false），则返回 0。

---

int get_collision_count() const 🔗

在撞击点检测到的碰撞次数。使用它来迭代由 get_collider、get_collider_shape、get_collision_point 和 get_collision_normal 方法提供的多个碰撞。

---

bool get_collision_mask_value(layer_number: int) const 🔗

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

---

Vector3 get_collision_normal(index: int) const 🔗

返回相交对象 index 处多次碰撞之一的法线。

---

Vector3 get_collision_point(index: int) const 🔗

返回形状与碰撞对象相交的 index 处多次碰撞之一的碰撞点。

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

---

bool is_colliding() const 🔗

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

---

void remove_exception(node: CollisionObject3D) 🔗

移除碰撞例外，让该形状汇报与指定 CollisionObject3D 节点的碰撞。

---

void remove_exception_rid(rid: RID) 🔗

移除碰撞例外，使该形状能够汇报与指定 RID 的碰撞。

---

void resource_changed(resource: Resource) 🔗

已弃用： Use Resource.changed instead.

这个方法什么也不做。

---

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

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