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
Eredita: Resource < RefCounted < Object
Ereditato da: FBXDocument
Classe per importare ed esportare file glTF da Godot.
Descrizione
GLTFDocument supporta la lettura di dati da un file glTF, buffer o scena Godot. È possibile successivamente scrivere questi dati nel file system, buffer o utilizzati per creare una scena Godot.
Tutti i dati in una scena glTF sono archiviati nella classe GLTFState. GLTFDocument elabora oggetti di stato, ma esso stesso non contiene dati di scena. GLTFDocument ha variabili membro per memorizzare impostazioni d'esportazione come il formato immagine, ma è comunque stateless. È possibile elaborare più scene con le stesse impostazioni utilizzando lo stesso oggetto GLTFDocument e diversi oggetti GLTFState.
GLTFDocument può essere esteso con funzionalità arbitrarie estendendo la classe GLTFDocumentExtension e registrandola con GLTFDocument tramite register_gltf_document_extension(). Ciò consente di importare ed esportare dati personalizzati.
Tutorial
Proprietà
|
||
|
||
|
||
|
||
|
||
|
||
|
Metodi
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) |
Enumerazioni
enum RootNodeMode: 🔗
RootNodeMode ROOT_NODE_MODE_SINGLE_ROOT = 0
Tratta il nodo radice della scena Godot come nodo radice del file glTF e lo contrassegna come singolo nodo radice tramite l'estensione glTF GODOT_single_root. Questo verrà elaborato allo stesso modo di ROOT_NODE_MODE_KEEP_ROOT se l'implementazione non supporta GODOT_single_root.
RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1
Tratta il nodo radice della scena Godot come nodo radice del file glTF, ma non lo contrassegnar come qualcosa di speciale. Un ulteriore nodo radice sarà generato durante l'importazione in Godot. Questo utilizza solo le funzionalità vanilla glTF. Ciò equivale al comportamento in Godot 4.1 e precedenti.
RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2
Tratta il nodo radice della scena Godot come il nome della scena glTF e aggiunge tutti i suoi figli come nodi radice del file glTF. Usa solo le funzionalità vanilla glTF. Ciò evita un ulteriore nodo radice, ma sarà preservato solo il nome del nodo radice della scena Godot, poiché non sarà salvato come nodo.
enum TextureMapMode: 🔗
TextureMapMode TEXTURE_MAP_MODE_DO_NOT_REMAP = 0
Import the texture maps in the glTF file as they are, without trying to fit them into specific texture slots suitable for Godot's built-in materials. This may be desirable if using the glTF file with custom shaders, but may not display correctly with Godot's built-in materials. This is equivalent to the behavior in Godot 4.6 and earlier.
TextureMapMode TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL = 1
Import the texture maps in the glTF file remapped to the most suitable texture slots based on Godot's StandardMaterial3D class. This is the default behavior.
enum VisibilityMode: 🔗
VisibilityMode VISIBILITY_MODE_INCLUDE_REQUIRED = 0
Se la scena contiene nodi non visibili, includili, segnali come non visibili con KHR_node_visibility e richiedi agli importatori di rispettarne la non visibilità. Svantaggio: se l'importatore non supporta KHR_node_visibility, il file non può essere importato.
VisibilityMode VISIBILITY_MODE_INCLUDE_OPTIONAL = 1
Se la scena contiene nodi non visibili, includili, segnali come non visibili con KHR_node_visibility e non imporre alcun requisito agli importatori. Svantaggio: se l'importatore non supporta KHR_node_visibility, gli oggetti invisibili saranno visibili.
VisibilityMode VISIBILITY_MODE_EXCLUDE = 2
Se la scena contiene nodi non visibili, non includerli nell'esportazione. Questo è lo stesso comportamento di Godot 4.4 e versioni precedenti. Svantaggio: i nodi invisibili non esisteranno nel file esportato.
flags ImportFlags: 🔗
ImportFlags IMPORT_FLAG_GENERATE_TANGENT_ARRAYS = 8
If true, generate vertex tangents using Mikktspace if the input meshes don't have tangent data. When possible, it's recommended to let the 3D modeling software generate tangents on export instead of relying on this option. Tangents are required for correct display of normal and height maps, along with any material/shader features that require tangents.
If you don't need material features that require tangents, disabling this can reduce output file size and speed up importing if the source 3D file doesn't contain tangents.
ImportFlags IMPORT_FLAG_USE_NAMED_SKIN_BINDS = 16
If checked, use named Skins for animation. The MeshInstance3D node contains 3 properties of relevance here: a skeleton NodePath pointing to the Skeleton3D node (usually ..), a mesh, and a skin:
The Skeleton3D node contains a list of bones with names, their pose and rest, a name, and a parent bone.
The mesh is all of the raw vertex data needed to display a mesh. In terms of the mesh, it knows how vertices are weight-painted and uses some internal numbering often imported from 3D modeling software.
The skin contains the information necessary to bind this mesh onto this Skeleton3D. For each of the internal bone IDs chosen by the 3D modeling software, it contains two things. Firstly, a matrix known as the Bind Pose Matrix, Inverse Bind Matrix, or IBM for short. Secondly, the Skin contains each bone's name (if this flag is enabled), or the bone's index within the Skeleton3D list (if this flag is disabled).
Together, this information is enough to tell Godot how to use the bone poses in the Skeleton3D node to render the mesh from each MeshInstance3D. Note that each MeshInstance3D may share binds, as is common in models exported from Blender, or each MeshInstance3D may use a separate Skin object, as is common in models exported from other tools such as Maya.
ImportFlags IMPORT_FLAG_DISCARD_MESHES_AND_MATERIALS = 32
Ignore meshes and materials on import. When importing a scene as an AnimationLibrary, this flag is always enabled.
ImportFlags IMPORT_FLAG_FORCE_DISABLE_MESH_COMPRESSION = 64
Se true, la compressione della mesh non sarà utilizzata. Considera di abilitarla se noti artefatti a blocchi nelle normali o UV della mesh, o se hai mesh più grandi di qualche migliaio di metri in ogni direzione.
Descrizioni delle proprietà
String fallback_image_format = "None" 🔗
Il nome leggibile in chiaro del formato di immagine di riserva. Viene utilizzato quando si esporta il file glTF, incluso durante la scrittura su un file o su un array di byte.
Questa proprietà può essere solo "None", "PNG" o "JPEG" ed è utilizzata solo quando image_format non è "None", "PNG" o "JPEG". Se si desidera avere più estensioni di formato di immagine, è possibile farlo tramite una classe GLTFDocumentExtension: questa proprietà copre solo il caso d'uso di fornire un'immagine base glTF di riserva quando si utilizza un formato immagine personalizzato.
float fallback_image_quality = 0.25 🔗
La qualità dell'immagine di riserva, se presente. Per i file PNG, questa opzione riduce l'immagine su entrambe le dimensioni di questo fattore. Per i file JPEG, questa opzione rappresenta la qualità lossy dell'immagine. Si consiglia un valore basso, poiché includere più immagini ad alta qualità in un file glTF vanifica i guadagni in dimensioni del file derivanti dall'utilizzo di un formato immagine più efficiente.
Il nome leggibile in chiaro del formato di immagine d'esportazione. Viene utilizzato quando si esporta il file glTF, incluso durante la scrittura su un file o su un array di byte.
Per impostazione predefinita, Godot consente le seguenti opzioni: "None", "PNG", "JPEG", "Lossless WebP" e "Lossy WebP". È possibile aggiungere supporto per altri formati di immagine nelle classi GLTFDocumentExtension. Una singola classe di estensione può fornire più opzioni per il formato specifico da utilizzare o persino un'opzione che utilizza più formati alla volta.
Se image_format è un formato immagine con perdita di dati, questo determina la qualità con perdita dell'immagine. Su un intervallo da 0.0 a 1.0, dove 0.0 è la qualità più bassa e 1.0 è la qualità più alta. Una qualità con perdita di 1.0 non è la stessa cosa di una qualità senza perdita.
RootNodeMode root_node_mode = 0 🔗
void set_root_node_mode(value: RootNodeMode)
RootNodeMode get_root_node_mode()
Come elaborare il nodo radice durante l'esportazione. Il valore predefinito e consigliato è ROOT_NODE_MODE_SINGLE_ROOT.
Nota: A prescindere da come viene esportato il file glTF, durante l'importazione, è possibile sovrascrivere il tipo e il nome del nodo radice nella scheda delle impostazioni di importazione della scena.
TextureMapMode texture_map_mode = 1 🔗
void set_texture_map_mode(value: TextureMapMode)
TextureMapMode get_texture_map_mode()
How to handle texture maps during import. The default and recommended value is TEXTURE_MAP_MODE_REMAP_TO_STANDARD_MATERIAL, which automatically remaps from glTF's flexible texture map system to the more specific texture map slots in Godot's StandardMaterial3D class. Alternatively, TEXTURE_MAP_MODE_DO_NOT_REMAP can be used to preserve the original texture maps from the glTF file, which may be desirable if using the glTF file with custom shaders, but may not display correctly with Godot's built-in materials.
VisibilityMode visibility_mode = 0 🔗
void set_visibility_mode(value: VisibilityMode)
VisibilityMode get_visibility_mode()
Come gestire la visibilità dei nodi durante l'esportazione. Questa impostazione non ha alcun effetto se tutti i nodi sono visibili. Il valore predefinito e consigliato è VISIBILITY_MODE_INCLUDE_REQUIRED, che utilizza l'estensione KHR_node_visibility.
Descrizioni dei metodi
Error append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) 🔗
Accetta un PackedByteArray che definisce un glTF e importa i dati nell'oggetto GLTFState specificato tramite il parametro state.
Nota: Il parametro base_path indica a append_from_buffer() dove trovare le dipendenze e può essere vuoto.
Error append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") 🔗
Accetta un percorso verso un file glTF e importa i dati in quel percorso file nell'oggetto GLTFState specificato tramite il parametro state.
Nota: Il parametro base_path indica a append_from_buffer() dove trovare le dipendenze e può essere vuoto.
Error append_from_scene(node: Node, state: GLTFState, flags: int = 0) 🔗
Accetta un nodo di scena del motore Godot ed esporta esso e i suoi discendenti nell'oggetto GLTFState specificato tramite il parametro state.
GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static 🔗
Determina una mappatura tra il percorso di nodo node_path di Godot e i corrispondenti puntatori JSON del modello d'oggetto glTF nel file glTF generato. I dettagli di questa mappatura vengono restituiti in un oggetto GLTFObjectModelProperty. È possibile fornire ulteriori mappature tramite il metodo di callback GLTFDocumentExtension._import_object_model_property().
PackedByteArray generate_buffer(state: GLTFState) 🔗
Accetta un oggetto GLTFState tramite il parametro state e restituisce un PackedByteArray glTF.
Node generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) 🔗
Accetta un oggetto GLTFState tramite il parametro state e restituisce un nodo scena di Godot Engine.
Il parametro bake_fps sostituisce bake_fps in state.
PackedStringArray get_supported_gltf_extensions() static 🔗
Restituisce una lista di tutte le estensioni glTF supportate, incluse le estensioni supportate direttamente dal motore e le estensioni supportate dalle estensioni utente che registrano le classi GLTFDocumentExtension.
Nota: Se questo metodo viene eseguito prima che un GLTFDocumentExtension sia registrato, le sue estensioni non saranno incluse nella lista. Assicurati di eseguire questo metodo solo dopo che tutte le estensioni sono state registrate. Se viene eseguito all'avvio del motore, considera di attendere un frame prima di chiamare questo metodo per assicurarti che tutte le estensioni siano state registrate.
GLTFObjectModelProperty import_object_model_property(state: GLTFState, json_pointer: String) static 🔗
Determina una mappatura tra il puntatore JSON json_pointer del modello d'oggetto glTF e i percorsi dei nodi Godot corrispondenti nella scena generata di Godot. I dettagli di questa mappatura vengono restituiti in un oggetto GLTFObjectModelProperty. È possibile fornire ulteriori mappature tramite il metodo di callback GLTFDocumentExtension._export_object_model_property().
void register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static 🔗
Registra l'istanza GLTFDocumentExtension specificata con GLTFDocument. Se first_priority è true, questa estensione sarà eseguita per prima. Altrimenti, sarà eseguita per ultima.
Nota: Come GLTFDocument stesso, tutte le classi GLTFDocumentExtension devono essere stateless per funzionare correttamente. Se è necessario memorizzare dati, usa i metodi set_additional_data e get_additional_data in GLTFState o GLTFNode.
void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗
Annulla la registrazione dell'istanza GLTFDocumentExtension specificata.
Error write_to_filesystem(state: GLTFState, path: String) 🔗
Accetta un oggetto GLTFState tramite il parametro state e scrive un file glTF nel file system.
Nota: L'estensione del file glTF determina se si tratta di un file binario .glb o di un file di testo .gltf.