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 = [] 🔗

  • Array get_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 🔗

The shape to be used for collision queries.

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

  • void set_target_position(value: Vector3)

  • Vector3 get_target_position()

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

方法說明

void add_exception(node: CollisionObject3D) 🔗

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 之間。

Vector3 get_collision_normal(index: int) const 🔗

返回相交物件 index 處多次碰撞之一的法線。

Vector3 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: CollisionObject3D) 🔗

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

void remove_exception_rid(rid: RID) 🔗

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

void resource_changed(resource: Resource) 🔗

已棄用： Use Resource.changed instead.

This method does nothing.

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

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