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 🔗

• 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 之间。