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...
GLTFDocument
繼承： Resource < RefCounted < Object
被繼承： FBXDocument
用於在 Godot 中匯入和匯出 glTF 檔案的類別。
說明
GLTFDocument 支援從 glTF 檔案、緩衝區或 Godot 場景中讀取資料。然後可以將該資料寫入檔案系統、緩衝區或用於建立 Godot 場景。
glTF 場景中的所有資料都儲存在 GLTFState 類中。GLTFDocument 處理狀態物件，但本身不包含任何場景資料。GLTFDocument 有成員變數來儲存如影像格式等匯出設定設定，但在其他方面是無狀態的。可以使用相同的 GLTFDocument 物件和不同的 GLTFState 物件以相同的設定處理多個場景。
通過擴充 GLTFDocumentExtension 類並通過 register_gltf_document_extension() 將其注冊到 GLTFDocument，則可以使用任意功能來擴充 GLTFDocument。這允許自訂資料被匯入和匯出。
教學
屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) |
|
append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") |
|
append_from_scene(node: Node, state: GLTFState, flags: int = 0) |
|
export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static |
|
generate_buffer(state: GLTFState) |
|
generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) |
|
get_supported_gltf_extensions() static |
|
import_object_model_property(state: GLTFState, json_pointer: String) static |
|
void |
register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static |
void |
unregister_gltf_document_extension(extension: GLTFDocumentExtension) static |
write_to_filesystem(state: GLTFState, path: String) |
列舉
enum RootNodeMode: 🔗
RootNodeMode ROOT_NODE_MODE_SINGLE_ROOT = 0
將Godot場景的根節點視為glTF檔案的根節點，並透過GODOT_single_root glTF擴充將其標記為單一根節點。這如果實作不支援GODOT_single_root，則會與ROOT_NODE_MODE_KEEP_ROOT 相同的解析。
RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1
將Godot場景的根節點視為glTF檔案的根節點，但不要將其標記為任何特殊的東西。匯入Godot時會產生一個額外的根節點。這僅使用普通glTF 功能。這相當於Godot 4.1 及更早版本中的行為。
RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2
將 Godot 場景的根節點視為 glTF 場景的名稱，並將其所有子節點新增為 glTF 檔案的根節點。這只使用普通 glTF 功能。這避免了一個額外的根節點，但只會保留Godot 場景根節點的名稱，因為它不會儲存為節點。
enum TextureMapMode: 🔗
TextureMapMode TEXTURE_MAP_MODE_DO_NOT_REMAP = 0
直接匯入 glTF 檔案中的紋理貼圖，而不嘗試將其適配到適合 Godot 內建材質的特定紋理槽位中。如果將 glTF 檔案與自訂著色器一起使用，這可能很理想；但在 Godot 的內建材質中可能無法正確顯示。此設定等同於 Godot 4.6 及更早版本中的行為。
TextureMapMode TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL = 1
將 glTF 檔案中的紋理貼圖重新映射到基於 Godot StandardMaterial3D 類的最合適的紋理槽位中。這是預設行為。
enum VisibilityMode: 🔗
VisibilityMode VISIBILITY_MODE_INCLUDE_REQUIRED = 0
如果場景中包含不可見節點，則會包含這些節點，使用 KHR_node_visibility 將它們標記為不可見，要求匯入器將這些節點處理為不可見。缺點：如果匯入器不支援 KHR_node_visibility 就無法匯入該檔案。
VisibilityMode VISIBILITY_MODE_INCLUDE_OPTIONAL = 1
如果場景中包含不可見節點，則會包含這些節點，使用 KHR_node_visibility 將它們標記為不可見，但並不對匯入器施加任何要求。缺點：如果匯入器不支援 KHR_node_visibility，本應不可見的物件就會可見。
VisibilityMode VISIBILITY_MODE_EXCLUDE = 2
如果場景中包含不可見節點，則匯出的場景中不包含這些節點。與 Godot 4.4 及之前版本的行為一致。缺點：匯出後的檔案中不存在不可見節點。
flags ImportFlags: 🔗
ImportFlags IMPORT_FLAG_GENERATE_TANGENT_ARRAYS = 8
如果設為 true，當輸入的網格體（meshes）沒有切線資料時，將使用 Mikktspace 算法來生成頂點切線。如果條件允許，更推薦讓 3D 建模軟體在匯出模型時直接生成切線，而不是相依性這個選項。法線貼圖（normal maps）和高度貼圖（height maps），以及任何需要切線的材質或著色器（shader）功能，都必須要有切線資料才能正確顯示。
如果你不需要那些相依性切線的材質功能，停用此選項可以在源 3D 檔案不包含切線的情況下，減小輸出檔案的大小，並加快匯入速度。
ImportFlags IMPORT_FLAG_USE_NAMED_SKIN_BINDS = 16
如果勾選此項，動畫將使用帶名稱的 Skin（皮膚）資源。MeshInstance3D（網格實例 3D）節點在這裡包含 3 個關鍵屬性：一個指向 Skeleton3D（骨骼 3D）節點的骨架 NodePath（節點路徑，通常是 ..）、一個網格（mesh），以及一個皮膚（skin）。
Skeleton3D 節點包含一個骨骼清單，其中記錄了骨骼的名稱、姿態（pose）和靜止狀態（rest），以及父級骨骼的資訊。
網格（mesh）包含了顯示模型所需的所有原始頂點資料。就網格本身而言，它知道頂點是如何進行權重繪製（weight-painted）的，並且使用了一些通常從 3D 建模軟體匯入的內部編號。
皮膚（skin）包含了將這個網格綁定到該 Skeleton3D 上所需的必要資訊。對於 3D 建模軟體選定的每一個內部骨骼 ID，它都包含兩項內容。首先，是一個被稱為“綁定姿態矩陣”、“反向綁定矩陣”或簡稱 IBM 的矩陣。其次，Skin 還包含每根骨骼的名稱（如果啟用了此標誌），或者包含該骨骼在 Skeleton3D 清單中的索引（如果停用了此標誌）。
綜合這些資訊，就足以告訴 Godot 如何利用 Skeleton3D 節點中的骨骼姿態，來渲染每個 MeshInstance3D。請注意，每個 MeshInstance3D 可以共享綁定資訊（這在從 Blender 匯出的模型中很常見），或者每個 MeshInstance3D 也可以使用獨立的 Skin 物件（這在從 Maya 等其他工具匯出的模型中很常見）。
ImportFlags IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS = 32
在匯入時忽略網格（Meshes）和材質（Materials）。當將場景作為 AnimationLibrary（動畫庫）進行匯入時，此選項會始終處於啟用狀態。
ImportFlags IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION = 64
如果為 true，則不會使用網格壓縮。如果你在網格法線或 UV 中發現塊狀偽影，或者如果你的網格在每個方向都大於幾千米，請考慮啟用。
屬性說明
String fallback_image_format = "None" 🔗
回退影像格式的使用者友好名稱，用於匯出 glTF 檔案，包括寫入檔案和寫入位元組陣列。
該選項只能在“None”“PNG”“JPEG”中選擇一個，只有在 image_format 不是“None”“PNG”“JPEG”三者之一時會用到。如果希望有多個擴充影像格式，可以使用 GLTFDocumentExtension 類來實現——此屬性只適合在使用自訂影像格式時提供基本的 glTF 回退影像。
float fallback_image_quality = 0.25 🔗
回退影像的品質，可能不存在。對於 PNG 檔案而言，會根據這個係數縮小影像的寬高。對於 JPEG 檔案而言，則是影像的失真品質。建議使用較低的值，因為在 glTF 檔案中包含多個高品質影像會抵消使用更高效影像格式所帶來的檔案大小優勢。
匯出影像格式的使用者友好名稱，用於匯出 glTF 檔案，包括寫入檔案和寫入位元組陣列。
預設情況下，Godot 允許在“None”“PNG”“JPEG”“Lossless WebP”“Lossy WebP”中選擇一個。可以在 GLTFDocumentExtension 類中新增對更多影像格式的支援。一個擴充類可以提供對特定格式的多種選項，甚至可以提供一個同時使用多種格式的選項。
如果image_format是有損影像格式，則這決定了影像的有損品質。範圍在0.0到1.0 ``\ ，其中\ ``0.0 是最低質量，1.0 是最高品質。1.0 有損質量與無損不同。“，““，“ “，“錯誤的”，””，”，””
modules/gltf/doc_classes/GLTFDocument.xml"
RootNodeMode root_node_mode = 0 🔗
void set_root_node_mode(value: RootNodeMode)
RootNodeMode get_root_node_mode()
匯出時如何處理根節點。預設和推薦值為 ROOT_NODE_MODE_SINGLE_ROOT。
注意：無論 glTF 檔案如何匯出，匯入時，根節點型別和名稱都可以在場景匯入設定分頁中被覆蓋。
TextureMapMode texture_map_mode = 1 🔗
void set_texture_map_mode(value: TextureMapMode)
TextureMapMode get_texture_map_mode()
匯入時如何處理紋理貼圖。預設且推薦的值是 TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL，它會自動將 glTF 靈活的紋理映射系統重新映射到 Godot 的 StandardMaterial3D 類中更具體的紋理貼圖槽位。或者，可以使用 TEXTURE_MAP_MODE_DO_NOT_REMAP 來保留 glTF 檔案中的原始紋理貼圖，這在將 glTF 檔案與自訂著色器一起使用時可能很理想，但在 Godot 的內建材質中可能無法正確顯示。
VisibilityMode visibility_mode = 0 🔗
void set_visibility_mode(value: VisibilityMode)
VisibilityMode get_visibility_mode()
匯出時如何處理節點的可見性。如果所有節點都可見，則該設定不做任何事情。預設推薦值為 VISIBILITY_MODE_INCLUDE_REQUIRED，使用 KHR_node_visibility 擴充。
方法說明
Error append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) 🔗
接受定義 glTF 的 PackedByteArray，將資料匯入通過 state 參數給定的 GLTFState 物件。
注意：base_path 代表 append_from_buffer() 尋找相依項目的位置，可以為空。
Error append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") 🔗
接受 glTF 檔案的路徑，將檔案路徑處的資料匯入通過 state 參數給定的 GLTFState 物件。
注意：base_path 代表 append_from_file() 尋找相依項目的位置，可以為空。
Error append_from_scene(node: Node, state: GLTFState, flags: int = 0) 🔗
接收一個 Godot 引擎的場景節點，並通過 state 參數將其及其後代匯出到給定的 GLTFState 對象。
GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static 🔗
確定給定 Godot node_path 與生成的 glTF 檔案中相應的 glTF 物件模型 JSON 指針之間的映射。該映射的詳細資訊以 GLTFObjectModelProperty 物件的形式回傳。可以通過 GLTFDocumentExtension._import_object_model_property() 回呼方法提供額外的映射。
PackedByteArray generate_buffer(state: GLTFState) 🔗
通過 state 參數接收一個 GLTFState 物件，並回傳一個 glTF PackedByteArray。
Node generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) 🔗
通過 state 參數接收一個 GLTFState 物件，並回傳一個 Godot 引擎的場景節點。
bake_fps 參數會覆蓋 state 中的 bake_fps。
PackedStringArray get_supported_gltf_extensions() static 🔗
回傳所有支援的 glTF 擴充清單，包括引擎直接支援的擴充和使用者外掛注冊的 GLTFDocumentExtension 類支援的擴充。
注意：如果在注冊 GLTFDocumentExtension 之前執行該方法，則清單中不會包含它所對應的擴充。請確保在注冊所有擴充後再執行該方法。如果在引擎啟動時執行該方法，請考慮在呼叫g該方法之前等待一影格，確保所有擴充都已注冊。
GLTFObjectModelProperty import_object_model_property(state: GLTFState, json_pointer: String) static 🔗
確定給定 glTF 物件模型 json_pointer 與生成的 Godot 場景中相應的 Godot 節點路徑之間的映射。該映射的詳細資訊以 GLTFObjectModelProperty 物件的形式回傳。可以通過 GLTFDocumentExtension._export_object_model_property() 回呼方法提供額外的映射。
void register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static 🔗
使用 GLTFDocument 注冊給定的 GLTFDocumentExtension 實例。如果 first_priority 為 true，則該擴充將被首先執行。否則，它將被最後執行。
注意：與 GLTFDocument 本身一樣，所有 GLTFDocumentExtension 類都必須是無狀態的才能正常執行。如果需要儲存資料，使用 GLTFState 或 GLTFNode 中的 set_additional_data 和 get_additional_data 方法。
void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗
將給定的 GLTFDocumentExtension 實例取消註冊。
Error write_to_filesystem(state: GLTFState, path: String) 🔗
通過 state 參數接收一個 GLTFState 物件，並將一個 glTF 檔案寫入檔案系統。
注意：glTF 檔案的副檔名決定了它是一個 .glb 二進位檔案還是一個 .gltf 文字檔案。