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...
RayCast3D
3D 空間中的射線,用於尋找第一個與其相交的碰撞物體。
說明
Raycast 代表的是從它的原點到 target_position 的射線,如果與碰撞物件相交,就能找到路徑上距離最近的物體。
要讓 RayCast3D 忽略某些物件,可以通過將它們加入例外清單,也可以通過讓檢測彙報忽略 Area3D(collide_with_areas)或 PhysicsBody3D(collide_with_bodies),還可以通過設定物理層。
RayCast3D 每一個物理影格都會計算是否相交,且該計算結果會保留到下一個物理影格。如果要立即執行射線投射,或者你想要在同一個物理影格內多次設定 RayCast3D,請使用 force_raycast_update()。
要掃描 3D 空間中的某個區塊,可以使用多個 RayCast3D 或使用 ShapeCast3D 去近似該區塊。
教學
屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
void |
add_exception(node: CollisionObject3D) |
void |
add_exception_rid(rid: RID) |
void |
|
void |
|
get_collider() const |
|
get_collider_rid() const |
|
get_collider_shape() const |
|
get_collision_face_index() const |
|
get_collision_mask_value(layer_number: int) const |
|
get_collision_normal() const |
|
get_collision_point() const |
|
is_colliding() const |
|
void |
|
void |
remove_exception_rid(rid: RID) |
void |
set_collision_mask_value(layer_number: int, value: bool) |
屬性說明
bool collide_with_areas = false 🔗
如果為 true,則會報告與 Area3D 的碰撞。
bool collide_with_bodies = true 🔗
如果為 true,則會報告與 PhysicsBody3D 的碰撞。
射線的碰撞遮罩。只能偵測到至少啟用了一個遮罩中碰撞層的物件。詳情請參閱文件中的《碰撞層與遮罩》。
Color debug_shape_custom_color = Color(0, 0, 0, 1) 🔗
如果在除錯功能表中啟用了可見碰撞形狀,則用於在編輯器中和運作時中繪製形狀的自訂顏色。如果 RayCast3D 與某物發生碰撞,該顏色將在運作時突出顯示。
如果設定為 Color(0.0, 0.0, 0.0)(預設情況下),則使用 ProjectSettings.debug/shapes/collision/shape_color 中設定的顏色。
int debug_shape_thickness = 2 🔗
如果設定為 1,則使用一條線作為除錯形狀。否則,將繪製一個截斷的金字塔來表示 RayCast3D。需要在除錯選單中啟用可見碰撞形狀,以便除錯形狀在運作時可見。
如果為 true,將報告碰撞。
如果為 true,則射線投射不會彙報與其父節點的碰撞。僅在父節點為 CollisionObject3D 時有效。另見 Node.get_parent()、add_exception()。
如果為 true,查詢將命中背部面,這些背部面是啟用了背面的凹多邊形形狀,或高度圖形狀。
bool hit_from_inside = false 🔗
如果為 true,射線會在從形狀內部開始時偵測到命中。在此情況下,碰撞法線將為 Vector3(0, 0, 0)。不會影響無體積的形狀,如凹多邊形和高度圖。
Vector3 target_position = Vector3(0, -1, 0) 🔗
射線的目的點,相對於射線投射的 Node3D.position。
方法說明
void add_exception(node: CollisionObject3D) 🔗
新增碰撞例外,這樣射線就不會報告與 node 節點的碰撞。
void add_exception_rid(rid: RID) 🔗
新增碰撞例外,這樣射線就不會報告與指定 RID 的碰撞。
void clear_exceptions() 🔗
刪除此射線的所有碰撞例外。
void force_raycast_update() 🔗
更新射線的碰撞資訊。使用該方法立即更新碰撞資訊,而不是等待下一個 _physics_process 呼叫,例如,如果射線或其父級已更改狀態。
注意:enabled 不需要為 true 即可生效。
回傳射線相交的第一個物體,如果沒有物體與射線相交則回傳 null(即 is_colliding() 回傳 false)。
注意:該物體不一定是 CollisionObject3D。例如射線與 CSGShape3D 或 GridMap 相交時,方法回傳的就是 CSGShape3D 或 GridMap 實例。
RID get_collider_rid() const 🔗
返回該射線相交的第一個物件的 RID,如果沒有物件與該射線相交,則返回空 RID(即 is_colliding() 返回 false)。
int get_collider_shape() const 🔗
回傳與射線相交的第一個物件的形狀 ID,射線未與任何物件相交時回傳 0(即 is_colliding() 回傳 false 時)。
要取得相交的形狀節點,比如假設目標是 CollisionObject3D,可以使用:
var target = get_collider() # 是 CollisionObject3D 節點。
var shape_id = get_collider_shape() # 碰撞體中的形狀索引。
var owner_id = target.shape_find_owner(shape_id) # 碰撞體中的所有者 ID。
var shape = target.shape_owner_get_owner(owner_id)
var target = (CollisionObject3D)GetCollider(); // 是 CollisionObject3D 節點。
var shapeId = GetColliderShape(); // 碰撞體中的形狀索引。
var ownerId = target.ShapeFindOwner(shapeId); // 碰撞體中的所有者 ID。
var shape = target.ShapeOwnerGetOwner(ownerId);
int get_collision_face_index() const 🔗
回傳碰撞點處碰撞物件的面索引,如果與射線相交的形狀不是 ConcavePolygonShape3D,則回傳 -1。
bool get_collision_mask_value(layer_number: int) const 🔗
返回 collision_mask 中是否啟用了指定的層,給定的 layer_number 應在 1 和 32 之間。
Vector3 get_collision_normal() const 🔗
回傳相交物件的形狀在碰撞點處的法線,如果射線從該形狀內部發出並且 hit_from_inside 為 true,則為 Vector3(0, 0)。
注意:請在呼叫前檢查 is_colliding() 回傳的是否為 true,這樣回傳的法線就是即時有效的。
Vector3 get_collision_point() const 🔗
回傳全域座標系中射線與最近的物體相交的碰撞點。如果 hit_from_inside 為 true 並且射線從碰撞形狀內部開始,則該函式將回傳該射線的原點。
注意:在呼叫該方法之前,請檢查 is_colliding() 是否回傳 true,以確保回傳的點有效且最新。
返回是否有任何物件與射線的向量相交(考慮向量長度)。
void remove_exception(node: CollisionObject3D) 🔗
移除碰撞例外,這樣射線就會報告與 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 之間。