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

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 🔗

• void set_shape(value: Shape3D)

• Shape3D get_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 之間。