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

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

RID

get_collider_rid ( int index ) const

int

get_collider_shape ( int index ) const

int

get_collision_count ( ) const

bool

get_collision_mask_value ( int layer_number ) const

Vector2

get_collision_normal ( int index ) const

Vector2

get_collision_point ( int index ) const

bool

is_colliding ( ) const

void

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

bool collide_with_bodies = true

  • void set_collide_with_bodies ( bool value )

  • bool is_collide_with_bodies_enabled ( )

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

int collision_mask = 1

  • void set_collision_mask ( int value )

  • int get_collision_mask ( )

该形状的碰撞掩码。只有至少启用了一个在该掩码中的碰撞层的对象才会被检测到。

Array collision_result = []

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

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

float margin = 0.0

  • void set_margin ( float value )

  • float get_margin ( )

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

int max_results = 32

  • void set_max_results ( int value )

  • int get_max_results ( )

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

Shape2D shape

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

Vector2 target_position = Vector2(0, 50)

  • void set_target_position ( Vector2 value )

  • Vector2 get_target_position ( )

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

方法说明

void add_exception ( CollisionObject2D 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

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

float get_closest_collision_unsafe_fraction ( ) const

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

Object get_collider ( int index ) const

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

RID get_collider_rid ( int index ) const

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

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

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

Vector2 get_collision_normal ( int index ) const

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

Vector2 get_collision_point ( int index ) const

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

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

bool is_colliding ( ) const

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

void remove_exception ( CollisionObject2D node )

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

void remove_exception_rid ( RID rid )

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

void set_collision_mask_value ( int layer_number, bool value )

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