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

CSGShape3D

繼承： GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

被繼承： CSGCombiner3D, CSGPrimitive3D

CSG 基底類別。

說明

這是 CSG 的基底類別，為 Godot 中的各種 CSG 節點提供 CSG 運算支援。

效能：CSG 節點僅適用於原型設計，存在顯著的 CPU 效能消耗。請考慮將最終的 CSG 運算結果烘焙為靜態幾何體，替換 CSG 節點。

使用選中 CSG 根節點後顯示的編輯器選單可以將各個 CSG 根節點的結果烘焙為使用靜態資源的節點。

使用腳本也可以將各個 CSG 根節點烘焙為靜態資源，可視網格請呼叫 bake_static_mesh()，物理碰撞請呼叫 bake_collision_shape()。

使用編輯器的 gltf 場景匯出器可以將由 CSG 節點構成的整個場景烘焙為靜態幾何體：場景 > 匯出為... > glTF 2.0 場景...

教學

屬性

bool

autosmooth

false

bool

calculate_tangents

true

int

collision_layer

1

int

collision_mask

1

float

collision_priority

1.0

Operation

operation

0

float

smoothing_angle

50.0

float

snap

bool

use_collision

false

方法

ConcavePolygonShape3D

bake_collision_shape()

ArrayMesh

bake_static_mesh()

bool

get_collision_layer_value(layer_number: int) const

bool

get_collision_mask_value(layer_number: int) const

Array

get_meshes() const

bool

is_root_shape() const

void

set_collision_layer_value(layer_number: int, value: bool)

void

set_collision_mask_value(layer_number: int, value: bool)

列舉

enum Operation: 🔗

Operation OPERATION_UNION = 0

合併兩個圖元的幾何體，移除相交的幾何體。

Operation OPERATION_INTERSECTION = 1

僅保留相交的幾何，其餘的將被移除。

Operation OPERATION_SUBTRACTION = 2

從第一個形狀減去第二個形狀，留下一個帶有其形狀的凹痕。

屬性說明

bool autosmooth = false 🔗

  • void set_autosmooth(value: bool)

  • bool is_autosmooth()

啟用自動平滑。這將覆蓋 CSG 節點上的任何原有平滑設定，轉而使用 smoothing_angle（平滑角度）根據面與面之間的夾角來計算法線。

CSGCombiner3D 節點的所有子節點將被視為一個單一的網格體。

bool calculate_tangents = true 🔗

  • void set_calculate_tangents(value: bool)

  • bool is_calculating_tangents()

計算允許使用法線貼圖的 CSG 形狀的切線。僅適用於根形狀，該設定在所有子級上均被忽略。設定為 false 可以略微加速形狀的生成。

int collision_layer = 1 🔗

  • void set_collision_layer(value: int)

  • int get_collision_layer()

這個區域所處的實體層。

可碰撞的物體可以存在於 32 個不同層中的任何一個。這些層的工作就像一個標籤系統，而不是視覺化的。一個可碰撞物體可以使用這些層來選擇它可以與哪些物體碰撞，使用 collision_mask 屬性。

如果物件 A 在物件 B 所掃描的任何層中，或者物件 B 在物件 A 所掃描的任何層中，就會偵測到接觸。詳情請參閱文件中的《碰撞層與遮罩》。

int collision_mask = 1 🔗

  • void set_collision_mask(value: int)

  • int get_collision_mask()

該 CSG 形狀掃描碰撞的實體層。僅當 use_collision 為 true 時有效。有關更多資訊，請參閱文件中的《碰撞層與遮罩》。

float collision_priority = 1.0 🔗

  • void set_collision_priority(value: float)

  • float get_collision_priority()

發生穿透時用於解算碰撞的優先順序。僅當 use_collision 為 true 時有效。優先順序越高，對對象的穿透力就越低。例如，這可以用來防止玩家突破關卡的邊界。

Operation operation = 0 🔗

在此形狀上執行的操作。對於第一個 CSG 子節點，將忽略此操作，因為操作是在此節點與該節點父級的上一個子級之間進行的。

float smoothing_angle = 50.0 🔗

  • void set_smoothing_angle(value: float)

  • float get_smoothing_angle()

當自動平滑（autosmooth）啟用時，面與面之間的夾角小於該值的會被平滑處理，而夾角大於該值的則會保持銳利（保留稜角）。

注意：將該角度設定為低於 0.1 的值會導致所有平滑效果被停用，這可以用來提升效能。

float snap 🔗

已棄用： The CSG library no longer uses snapping.

該屬性無效。

bool use_collision = false 🔗

  • void set_use_collision(value: bool)

  • bool is_using_collision()

為我們的 CSG 形狀向物理引擎新增碰撞形狀。這樣行為就始終與靜態物體類似。請注意，即使 CSG 形狀本身被隱藏，碰撞形狀仍處於活動狀態。另見 collision_mask 和 collision_priority。

方法說明

ConcavePolygonShape3D bake_collision_shape() 🔗

回傳針對該節點 CSG 運算結果烘焙的物理 ConcavePolygonShape3D。如果該節點不是 CSG 根節點或者不包含有效的幾何體，則回傳空形狀。

效能：如果 CSG 運算得到的是包含大量細節的幾何體，面數很多，那麼物理效能可能非常慢。一般來說，凹面形狀應該只用來製作靜態關卡幾何體，不應用來製作可以移動的動態物體。

注意：CSG 網格資料是延遲更新的，即延遲一個渲染影格後更新。為了避免取得到空形狀或過時的網格資料，請確保在 Node._ready() 中使用 bake_collision_shape() 之前，或在更改 CSGShape3D 的屬性後，呼叫 await get_tree().process_frame。

ArrayMesh bake_static_mesh() 🔗

回傳該節點 CSG 運算結果烘焙得到的靜態 ArrayMesh。相關 CSG 節點的材質會作為額外的網格表面新增。如果該節點不是 CSG 根節點或沒有有效的幾何體，則回傳空網格。

注意：CSG 網格資料是延遲更新的，存在一個渲染影格的更新延遲。要避免取得到空的形狀或過時的網格資料，請確保在 Node._ready() 中使用 bake_static_mesh() 之前以及在修改 CSGShape3D 的屬性後呼叫 await get_tree().process_frame。

bool get_collision_layer_value(layer_number: int) const 🔗

返回 collision_layer 中是否啟用了指定的層，給定的 layer_number 應在 1 和 32 之間。

bool get_collision_mask_value(layer_number: int) const 🔗

返回 collision_mask 中是否啟用了指定的層，給定的 layer_number 應在 1 和 32 之間。

Array get_meshes() const 🔗

回傳一個包含兩個元素的 Array，第一個元素是該節點的 Transform3D，第二個元素是該節點的根 Mesh。僅在該節點為根形狀時有效。

注意：CSG 網格資料是延遲更新的，存在一個渲染影格的更新延遲。要避免取得到空的形狀或過時的網格資料，請確保在 Node._ready() 中使用 get_meshes() 之前以及在修改 CSGShape3D 的屬性後呼叫 await get_tree().process_frame。

bool is_root_shape() const 🔗

如果這是根形狀，因此是渲染的物件，則返回 true。

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

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

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

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