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

ShapeCast2D

继承： Node2D < CanvasItem < Node < Object

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

描述

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

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

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

属性

bool

collide_with_areas

false

bool

collide_with_bodies

true

int

collision_mask

1

Array

collision_result

[]

bool

enabled

true

bool

exclude_parent

true

float

margin

0.0

int

max_results

32

Shape2D

shape

Vector2

target_position

Vector2(0, 50)

方法

void

add_exception(node: CollisionObject2D)

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

Vector2

get_collision_normal(index: int) const

Vector2

get_collision_point(index: int) const

bool

is_colliding() const

void

remove_exception(node: CollisionObject2D)

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，则会报告与 Area2D 的碰撞。

bool collide_with_bodies = true 🔗

  • void set_collide_with_bodies(value: bool)

  • bool is_collide_with_bodies_enabled()

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

int collision_mask = 1 🔗

  • void set_collision_mask(value: int)

  • int get_collision_mask()

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

Array collision_result = [] 🔗

  • Array get_collision_result()

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

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

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

Shape2D shape 🔗

用于碰撞查询的形状。

Vector2 target_position = Vector2(0, 50) 🔗

  • void set_target_position(value: Vector2)

  • Vector2 get_target_position()

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

方法说明

void add_exception(node: CollisionObject2D) 🔗

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

void add_exception_rid(rid: RID) 🔗

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

void clear_exceptions() 🔗

移除该形状的所有碰撞例外。

void force_shapecast_update() 🔗

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

注意：不将 enabled 设置为 true 也可以生效。

float get_closest_collision_safe_fraction() const 🔗

返回从投射原点到 target_position 之间的分数，形状在不触发碰撞的情况下能够移动多远，是一个 0.0 到 1.0 之间的值。

float get_closest_collision_unsafe_fraction() const 🔗

返回从投射原点到 target_position 之间的分数，形状移动多远才能够触发碰撞，是一个 0.0 到 1.0 之间的值。

在理想条件下与 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 之间。

Vector2 get_collision_normal(index: int) const 🔗

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

Vector2 get_collision_point(index: int) const 🔗

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

注意：这个点使用全局坐标系。

bool is_colliding() const 🔗

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

void remove_exception(node: CollisionObject2D) 🔗

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

void remove_exception_rid(rid: RID) 🔗

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

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

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