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
Hérite de : Resource < RefCounted < Object
Hérité par : FBXDocument
Classe pour l'importation et l'exportation de fichiers glTF dans et hors de Godot.
Description
GLTFDocument prend en charge la lecture de données d'un fichier glTF, d'un buffer ou d'une scène Godot. Ces données peuvent ensuite être écrites vers le système de fichiers, un buffer ou être utilisées pour créer une scène Godot.
Toutes les données d'une scène glTF sont stockées dans la classe GLTFState. GLTFDocument traite des objets d'état, mais ne contient aucune donnée de scène elle-même. GLTFDocument a des variables membres pour stocker des paramètres de configuration d'exportation tels que le format d'image, mais est autrement sans état. Plusieurs scènes peuvent être traitées avec les mêmes paramètres en utilisant le même objet GLTFDocument et des objets GLTFState différents.
GLTFDocument peut être étendue avec des fonctionnalités arbitraires en étendant la classe GLTFDocumentExtension et en l’enregistrant avec GLTFDocument via register_gltf_document_extension(). Cela permet d'importer et d'exporter des données personnalisées.
Tutoriels
Propriétés
|
||
|
||
|
||
|
||
|
||
|
||
|
Méthodes
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) |
Énumérations
enum RootNodeMode: 🔗
RootNodeMode ROOT_NODE_MODE_SINGLE_ROOT = 0
Traite le nœud racine de la scène Godot comme nœud racine du fichier glTF, et le marque comme le nœud racine unique via l'extension glTF GODOT_single_root. Cela sera parsé de la même manière que ROOT_NODE_MODE_KEEP_ROOT si l'implémentation ne supporte pas GODOT_single_root.
RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1
Traite le nœud racine de la scène Godot comme nœud racine du fichier glTF, mais ne le marque pas comme quelque chose de spécial. Un nœud racine supplémentaire sera généré lors de l'import dans Godot. Ceci utilise seulement les fonctionnalités de base du glTF. C'est équivalent au comportement dans Godot 4.1 et antérieur.
RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2
Traite le nœud racine de la scène Godot comme le nom de la scène glTF, et ajoute tous ses enfants comme nœuds racines du fichier glTF. Ceci utilise seulement les fonctionnalités de base du glTF. Cela évite un nœud racine supplémentaire, mais seulement le nom du nœud racine de la scène Godot sera préservé, car il ne sera pas sauvegardé comme nœud.
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
Si la scène contient des nœuds non visibles, les inclut, les marque comme non visibles avec KHR_node_visibility, et exige que les importeurs respectent leur non-visibilité. Désavantage : Si l'importateur ne supporte pas KHR_node_visibility, le fichier ne peut pas être importé.
VisibilityMode VISIBILITY_MODE_INCLUDE_OPTIONAL = 1
Si la scène contient des nœuds non visibles, les inclut, les marque comme non visibles avec KHR_node_visibility, et n'impose pas d'exigences sur les importeurs. Désavantage : Si l'importateur ne supporte pas KHR_node_visibility, les objets invisibles seront visibles.
VisibilityMode VISIBILITY_MODE_EXCLUDE = 2
Si la scène contient des nœuds non visibles, ne les inclut pas dans l'export. Il s'agit du comportement de Godot 4.4 et antérieur. Désavantage : Les nœuds invisibles n'existeront pas dans le fichier exporté.
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
Si true, la compression du maillage ne sera pas utilisée. Envisagez d'activer ceci si vous remarquez des artéfacts de blocs dans vos normales ou UVs du maillage, ou si vous avez des maillages plus grands que quelques milliers de mètres dans chaque direction.
Descriptions des propriétés
String fallback_image_format = "None" 🔗
The user-friendly name of the fallback image format. This is used when exporting the glTF file, including writing to a file and writing to a byte array.
This property may only be one of "None", "PNG", or "JPEG", and is only used when the image_format is not one of "None", "PNG", or "JPEG". If having multiple extension image formats is desired, that can be done using a GLTFDocumentExtension class - this property only covers the use case of providing a base glTF fallback image when using a custom image format.
float fallback_image_quality = 0.25 🔗
La qualité de l'image de repli, le cas échéant. Pour les fichiers PNG, cela réduit l'image sur les deux dimensions par ce facteur. Pour les fichiers JPEG, c'est la qualité de perte de l'image. Une faible valeur est recommandée, puisque l'inclusion de multiples images de haute qualité dans un fichier glTF annule les gains de taille de fichier grâce à l'utilisation d'un format d'image plus efficace.
Le nom facilement lisible du format d'image d'exportation. Ceci est utilisé lors de l'exportation du fichier glTF, y compris l'écriture vers un fichier et l'écriture vers un tableau d'octets.
Par défaut, Godot permet les options suivantes : "None", "PNG", "JPEG", "Lossless WebP", et "Lossy WebP". Le support pour plus de formats d'image peut être ajouté dans des classes GLTFDocumentExtension. Une seule classe d'extension peut fournir plusieurs options pour le format spécifique à utiliser, ou même une option qui utilise plusieurs formats à la fois.
Si image_format est un format d'image avec pertes, cela détermine la qualité de la perte de l'image. Sur un intervalle de 0.0 à 1.0, où 0.0 est la plus basse qualité et 1.0 est la plus haute qualité. Une qualité de perde de 1.0 n'est pas la même chose que le sans-perte.
RootNodeMode root_node_mode = 0 🔗
void set_root_node_mode(value: RootNodeMode)
RootNodeMode get_root_node_mode()
Comment traiter le nœud racine pendant l'export. La valeur par défaut et recommandée est ROOT_NODE_MODE_SINGLE_ROOT.
Note : Quelle que soit la façon dont le fichier glTF est exporté, lors de l'importation, le type et le nom du nœud racine peuvent être redéfinis dans l'onglet Paramètres d'import de la scène.
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()
Comment gérer la visibilité du nœud lors de l'export. Ce paramètre ne fait rien si tous les nœuds sont visibles. La valeur par défaut et recommandée est VISIBILITY_MODE_INCLUDE_REQUIRED, qui utilise l'extension KHR_node_visibility.
Descriptions des méthodes
Error append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) 🔗
Prend un PackedByteArray définissant un glTF et importe les données dans l'objet GLTFState donné par le paramètre state.
Note : Le chemin de base base_path indique à append_from_buffer() où trouver les dépendances et peut être vide.
Error append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") 🔗
Prend un chemin vers un fichier glTF et importe les données à ce chemin de fichier vers l'objet GLTFState donné par le paramètre state.
Note : Le chemin de base base_path indique à append_from_buffer() où trouver les dépendances et peut être vide.
Error append_from_scene(node: Node, state: GLTFState, flags: int = 0) 🔗
Prend un nœud de scène Godot Engine et l'exporte lui et ses descendants vers l'objet GLTFState donné par le paramètre state.
GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static 🔗
Détermine une association entre le chemin de nœud Godot node_path donné et le(s) pointeur(s) JSON de modèle d'objet glTF correspondant(s) dans le fichier glTF généré. Les détails de cette association sont renvoyés dans un objet GLTFObjectModelProperty. Des associations supplémentaires peuvent être fournies via la méthode de callback GLTFDocumentExtension._import_object_model_property().
PackedByteArray generate_buffer(state: GLTFState) 🔗
Prend un objet GLTFState à travers le paramètre state et renvoie un PackedByteArray de glTF.
Node generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) 🔗
Prend un objet GLTFState à travers le paramètre state et renvoie un nœud de scène Godot Engine.
Le paramètre bake_fps remplace le bake_fps dans state.
PackedStringArray get_supported_gltf_extensions() static 🔗
Renvoie une liste de toutes les extensions glTF supportées, y compris les extensions supportées directement par le moteur, et les extensions supportées par les plugins d'utilisateurs enregistrant des classes GLTFDocumentExtension.
Note : Si cette méthode est exécutée avant l'enregistrement d'une GLTFDocumentExtension, ses extensions ne seront pas incluses dans la liste. Assurez-vous de seulement exécuter cette méthode après que toutes les extensions soient enregistrées. Si vous exécutez cela lorsque le moteur démarre, envisagez d'attendre une trame avant d'appeler cette méthode pour vous assurer que toutes les extensions sont enregistrées.
GLTFObjectModelProperty import_object_model_property(state: GLTFState, json_pointer: String) static 🔗
Détermine une association entre le pointeur JSON json_pointer de modèle d'objet glTF donné et le chemin de nœud Godot correspondant dans la scène Godot générée. Les détails de cette association sont renvoyés dans un objet GLTFObjectModelProperty. Des associations supplémentaires peuvent être fournies via la méthode de callback GLTFDocumentExtension._export_object_model_property().
void register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static 🔗
Enregistre l'instance GLTFDocumentExtension donnée avec le GLTFDocument. Si first_priority vaut true, cette extension sera exécutée en premier. Sinon, elle le sera en dernier.
Note : Comme GLTFDocument lui-même, toutes les classes GLTFDocumentExtension doivent être sans état afin de fonctionner correctement. Si vous devez stocker des données, utilisez les méthodes set_additional_data et get_additional_data dans GLTFState ou GLTFNode.
void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗
Désenregistre l'instance GLTFDocumentExtension donnée.
Error write_to_filesystem(state: GLTFState, path: String) 🔗
Prend un objet GLTFState à travers le paramètre state et écrit un fichier glTF dans le système de fichiers.
Note : L'extension du fichier glTF détermine si c'est un fichier binaire .glb ou un fichier texte .gltf.