Description

GLTFDocument supports reading data from a glTF file, buffer, or Godot scene. This data can then be written to the filesystem, buffer, or used to create a Godot scene.

All of the data in a glTF scene is stored in theGLTFState class. GLTFDocument processes state objects, but does not contain any scene data itself. GLTFDocument has member variables to store export configuration settings such as the image format, but is otherwise stateless. Multiple scenes can be processed with the same settings using the same GLTFDocument object and differentGLTFState objects.

GLTFDocument can be extended with arbitrary functionality by extending theGLTFDocumentExtension class and registering it with GLTFDocument viaregister_gltf_document_extension(). This allows for custom data to be imported and exported.

Tutorials

• Runtime file loading and saving

• glTF 'What the duck?' guide

• Khronos glTF specification

Properties

Methods

Enumerations

enumRootNodeMode:🔗

RootNodeModeROOT_NODE_MODE_SINGLE_ROOT =0

Treat the Godot scene's root node as the root node of the glTF file, and mark it as the single root node via theGODOT_single_root glTF extension. This will be parsed the same asROOT_NODE_MODE_KEEP_ROOT if the implementation does not supportGODOT_single_root.

RootNodeModeROOT_NODE_MODE_KEEP_ROOT =1

Treat the Godot scene's root node as the root node of the glTF file, but do not mark it as anything special. An extra root node will be generated when importing into Godot. This uses only vanilla glTF features. This is equivalent to the behavior in Godot 4.1 and earlier.

RootNodeModeROOT_NODE_MODE_MULTI_ROOT =2

Treat the Godot scene's root node as the name of the glTF scene, and add all of its children as root nodes of the glTF file. This uses only vanilla glTF features. This avoids an extra root node, but only the name of the Godot scene's root node will be preserved, as it will not be saved as a node.

Property Descriptions

Stringimage_format ="PNG"🔗

• voidset_image_format(value:String)

• Stringget_image_format()

The user-friendly name of the export image format. This is used when exporting the glTF file, including writing to a file and writing to a byte array.

By default, Godot allows the following options: "None", "PNG", "JPEG", "Lossless WebP", and "Lossy WebP". Support for more image formats can be added inGLTFDocumentExtension classes.

floatlossy_quality =0.75🔗

• voidset_lossy_quality(value:float)

• floatget_lossy_quality()

Ifimage_format is a lossy image format, this determines the lossy quality of the image. On a range of0.0 to1.0, where0.0 is the lowest quality and1.0 is the highest quality. A lossy quality of1.0 is not the same as lossless.

RootNodeModeroot_node_mode =0🔗

• voidset_root_node_mode(value:RootNodeMode)

• RootNodeModeget_root_node_mode()

How to process the root node during export. SeeRootNodeMode for details. The default and recommended value isROOT_NODE_MODE_SINGLE_ROOT.

Note: Regardless of how the glTF file is exported, when importing, the root node type and name can be overridden in the scene import settings tab.

Method Descriptions

Errorappend_from_buffer(bytes:PackedByteArray, base_path:String, state:GLTFState, flags:int = 0)🔗

Takes aPackedByteArray defining a glTF and imports the data to the givenGLTFState object through thestate parameter.

Note: Thebase_path tellsappend_from_buffer() where to find dependencies and can be empty.

Errorappend_from_file(path:String, state:GLTFState, flags:int = 0, base_path:String = "")🔗

Takes a path to a glTF file and imports the data at that file path to the givenGLTFState object through thestate parameter.

Note: Thebase_path tellsappend_from_file() where to find dependencies and can be empty.

Errorappend_from_scene(node:Node, state:GLTFState, flags:int = 0)🔗

Takes a Godot Engine scene node and exports it and its descendants to the givenGLTFState object through thestate parameter.

GLTFObjectModelPropertyexport_object_model_property(state:GLTFState, node_path:NodePath, godot_node:Node, gltf_node_index:int)static🔗

Determines a mapping between the given Godotnode_path and the corresponding glTF Object Model JSON pointer(s) in the generated glTF file. The details of this mapping are returned in aGLTFObjectModelProperty object. Additional mappings can be supplied via theGLTFDocumentExtension._import_object_model_property() callback method.

PackedByteArraygenerate_buffer(state:GLTFState)🔗

Takes aGLTFState object through thestate parameter and returns a glTFPackedByteArray.

Nodegenerate_scene(state:GLTFState, bake_fps:float = 30, trimming:bool = false, remove_immutable_tracks:bool = true)🔗

Takes aGLTFState object through thestate parameter and returns a Godot Engine scene node.

Thebake_fps parameter overrides the bake_fps instate.

PackedStringArrayget_supported_gltf_extensions()static🔗

Returns a list of all support glTF extensions, including extensions supported directly by the engine, and extensions supported by user plugins registeringGLTFDocumentExtension classes.

Note: If this method is run before a GLTFDocumentExtension is registered, its extensions won't be included in the list. Be sure to only run this method after all extensions are registered. If you run this when the engine starts, consider waiting a frame before calling this method to ensure all extensions are registered.

GLTFObjectModelPropertyimport_object_model_property(state:GLTFState, json_pointer:String)static🔗

Determines a mapping between the given glTF Object Modeljson_pointer and the corresponding Godot node path(s) in the generated Godot scene. The details of this mapping are returned in aGLTFObjectModelProperty object. Additional mappings can be supplied via theGLTFDocumentExtension._export_object_model_property() callback method.

voidregister_gltf_document_extension(extension:GLTFDocumentExtension, first_priority:bool = false)static🔗

Registers the givenGLTFDocumentExtension instance with GLTFDocument. Iffirst_priority istrue, this extension will be run first. Otherwise, it will be run last.

Note: Like GLTFDocument itself, all GLTFDocumentExtension classes must be stateless in order to function properly. If you need to store data, use theset_additional_data andget_additional_data methods inGLTFState orGLTFNode.

voidunregister_gltf_document_extension(extension:GLTFDocumentExtension)static🔗

Unregisters the givenGLTFDocumentExtension instance.

Errorwrite_to_filesystem(state:GLTFState, path:String)🔗

Takes aGLTFState object through thestate parameter and writes a glTF file to the filesystem.

Note: The extension of the glTF file determines if it is a .glb binary file or a .gltf text file.