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 🔗

The shape to be used for collision queries.

Vector2 target_position = Vector2(0, 50) 🔗

  • void set_target_position(value: Vector2)

  • Vector2 get_target_position()

The shape's destination point, relative to this node's Node2D.position.

方法說明

void add_exception(node: CollisionObject2D) 🔗

Adds a collision exception so the shape does not report collisions with the specified node.

void add_exception_rid(rid: RID) 🔗

新增碰撞例外，使該形狀不彙報與指定 RID 節點的碰撞。

void clear_exceptions() 🔗

移除該形狀的所有碰撞例外。

void force_shapecast_update() 🔗

Updates the collision information for the shape immediately, without waiting for the next _physics_process call. Use this method, for example, when the shape or its parent has changed state.

Note: Setting enabled to true is not required for this to work.

float get_closest_collision_safe_fraction() const 🔗

Returns the fraction from this cast's origin to its target_position of how far the shape can move without triggering a collision, as a value between 0.0 and 1.0.

float get_closest_collision_unsafe_fraction() const 🔗

Returns the fraction from this cast's origin to its target_position of how far the shape must move to trigger a collision, as a value between 0.0 and 1.0.

In ideal conditions this would be the same as get_closest_collision_safe_fraction(), however shape casting is calculated in discrete steps, so the precise point of collision can occur between two calculated positions.

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 🔗

Returns the collision point of one of the multiple collisions at index where the shape intersects the colliding object.

Note: This point is in the global coordinate system.

bool is_colliding() const 🔗

返回是否有任何物件與形狀的向量相交（考慮向量長度）。

void remove_exception(node: CollisionObject2D) 🔗

Removes a collision exception so the shape does report collisions with the specified node.

void remove_exception_rid(rid: RID) 🔗

移除碰撞例外，使該形狀能夠彙報與指定 RID 的碰撞。

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

根據 value，啟用或禁用 collision_mask 中指定的層，給定的 layer_number 應在 1 和 32 之間。