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.

RayCast3D

繼承: Node3D < Node < Object

3D 空間中的射線,用於尋找第一個與其相交的碰撞物體。

說明

Raycast 代表的是從它的原點到 target_position 的射線,如果與碰撞物件相交,就能找到路徑上距離最近的物體。

要讓 RayCast3D 忽略某些物件,可以通過將它們加入例外清單,也可以通過讓檢測彙報忽略 Area3D(collide_with_areas)或 PhysicsBody3D(collide_with_bodies),還可以通過設定物理層。

RayCast3D 每一個物理影格都會計算是否相交,且該計算結果會保留到下一個物理影格。如果要立即執行射線投射,或者你想要在同一個物理影格內多次設定 RayCast3D,請使用 force_raycast_update()。

要掃描 3D 空間中的某個區塊,可以使用多個 RayCast3D 或使用 ShapeCast3D 去近似該區塊。

教學

屬性

bool

collide_with_areas

false

bool

collide_with_bodies

true

int

collision_mask

1

Color

debug_shape_custom_color

Color(0, 0, 0, 1)

int

debug_shape_thickness

2

bool

enabled

true

bool

exclude_parent

true

bool

hit_back_faces

true

bool

hit_from_inside

false

Vector3

target_position

Vector3(0, -1, 0)

方法

void

add_exception(node: CollisionObject3D)

void

add_exception_rid(rid: RID)

void

clear_exceptions()

void

force_raycast_update()

Object

get_collider() const

RID

get_collider_rid() const

int

get_collider_shape() const

int

get_collision_face_index() const

bool

get_collision_mask_value(layer_number: int) const

Vector3

get_collision_normal() const

Vector3

get_collision_point() const

bool

is_colliding() const

void

remove_exception(node: CollisionObject3D)

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,則會報告與 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()

射線的碰撞遮罩。只能偵測到至少啟用了一個遮罩中碰撞層的物件。詳情請參閱文件中的《碰撞層與遮罩》。


Color debug_shape_custom_color = Color(0, 0, 0, 1) 🔗

  • void set_debug_shape_custom_color(value: Color)

  • Color get_debug_shape_custom_color()

如果在除錯功能表中啟用了可見碰撞形狀,則用於在編輯器中和運作時中繪製形狀的自訂顏色。如果 RayCast3D 與某物發生碰撞,該顏色將在運作時突出顯示。

如果設定為 Color(0.0, 0.0, 0.0)(預設情況下),則使用 ProjectSettings.debug/shapes/collision/shape_color 中設定的顏色。


int debug_shape_thickness = 2 🔗

  • void set_debug_shape_thickness(value: int)

  • int get_debug_shape_thickness()

如果設定為 1,則使用一條線作為除錯形狀。否則,將繪製一個截斷的金字塔來表示 RayCast3D。需要在除錯選單中啟用可見碰撞形狀,以便除錯形狀在運作時可見。


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,則射線投射不會彙報與其父節點的碰撞。僅在父節點為 CollisionObject3D 時有效。另見 Node.get_parent()、add_exception()。


bool hit_back_faces = true 🔗

  • void set_hit_back_faces(value: bool)

  • bool is_hit_back_faces_enabled()

如果為 true,查詢將命中背部面,這些背部面是啟用了背面的凹多邊形形狀,或高度圖形狀。


bool hit_from_inside = false 🔗

  • void set_hit_from_inside(value: bool)

  • bool is_hit_from_inside_enabled()

如果為 true,射線會在從形狀內部開始時偵測到命中。在此情況下,碰撞法線將為 Vector3(0, 0, 0)。不會影響無體積的形狀,如凹多邊形和高度圖。


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

  • void set_target_position(value: Vector3)

  • Vector3 get_target_position()

射線的目的點,相對於射線投射的 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 即可生效。


Object get_collider() const 🔗

回傳射線相交的第一個物體,如果沒有物體與射線相交則回傳 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)

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,以確保回傳的點有效且最新。


bool is_colliding() const 🔗

返回是否有任何物件與射線的向量相交(考慮向量長度)。


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