Table of Contents

Class GLTFDocument

Class for importing and exporting glTF files in and out of Godot.

Inheritance
GLTFDocument
Derived

Remarks

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 the GLTFState 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 different GLTFState objects.

GLTFDocument can be extended with arbitrary functionality by extending the GLTFDocumentExtension class and registering it with GLTFDocument via GLTFDocument.register_gltf_document_extension. This allows for custom data to be imported and exported.

See Also

Runtime file loading and saving
glTF 'What the duck?' guide
Khronos glTF specification

Properties

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 in GLTFDocumentExtension classes.

var image_format : String = "PNG"

Property Value

String

Remarks

  • void set_image_format(String value)
  • String get_image_format

lossy_quality

If image_format is a lossy image format, this determines the lossy quality of the image. On a range of 0.0 to 1.0, where 0.0 is the lowest quality and 1.0 is the highest quality. A lossy quality of 1.0 is not the same as lossless.

var lossy_quality : float = 0.75

Property Value

float

Remarks

  • void set_lossy_quality(float value)
  • float get_lossy_quality

root_node_mode

How to process the root node during export. See RootNodeMode for details. The default and recommended value is GLTFDocument.ROOT_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.

var root_node_mode : int = 0

Property Value

int

Remarks

  • void set_root_node_mode(int value)
  • int get_root_node_mode

Methods

append_from_buffer(PackedByteArray, String, GLTFState, int)

Takes a PackedByteArray defining a glTF and imports the data to the given GLTFState object through the state parameter.

Note: The base_path tells GLTFDocument.append_from_buffer where to find dependencies and can be empty.

int append_from_buffer(PackedByteArray bytes, String base_path, GLTFState state, int flags)

Parameters

bytes PackedByteArray
base_path String
state GLTFState
flags int

append_from_file(String, GLTFState, int, String)

Takes a path to a glTF file and imports the data at that file path to the given GLTFState object through the state parameter.

Note: The base_path tells GLTFDocument.append_from_file where to find dependencies and can be empty.

int append_from_file(String path, GLTFState state, int flags, String base_path)

Parameters

path String
state GLTFState
flags int
base_path String

append_from_scene(Node, GLTFState, int)

Takes a Godot Engine scene node and exports it and its descendants to the given GLTFState object through the state parameter.

int append_from_scene(Node node, GLTFState state, int flags)

Parameters

node Node
state GLTFState
flags int

export_object_model_property(GLTFState, NodePath, Node, int)

Qualifiers: static

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

GLTFObjectModelProperty export_object_model_property(GLTFState state, NodePath node_path, Node godot_node, int gltf_node_index)

Parameters

state GLTFState
node_path NodePath
godot_node Node
gltf_node_index int

generate_buffer(GLTFState)

Takes a GLTFState object through the state parameter and returns a glTF PackedByteArray.

PackedByteArray generate_buffer(GLTFState state)

Parameters

state GLTFState

generate_scene(GLTFState, float, bool, bool)

Takes a GLTFState object through the state parameter and returns a Godot Engine scene node.

The bake_fps parameter overrides the bake_fps in state.

Node generate_scene(GLTFState state, float bake_fps, bool trimming, bool remove_immutable_tracks)

Parameters

state GLTFState
bake_fps float
trimming bool
remove_immutable_tracks bool

get_supported_gltf_extensions

Qualifiers: static

Returns a list of all support glTF extensions, including extensions supported directly by the engine, and extensions supported by user plugins registering GLTFDocumentExtension 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.

PackedStringArray get_supported_gltf_extensions

import_object_model_property(GLTFState, String)

Qualifiers: static

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

GLTFObjectModelProperty import_object_model_property(GLTFState state, String json_pointer)

Parameters

state GLTFState
json_pointer String

register_gltf_document_extension(GLTFDocumentExtension, bool)

Qualifiers: static

Registers the given GLTFDocumentExtension instance with GLTFDocument. If first_priority is true, 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 the set_additional_data and get_additional_data methods in GLTFState or GLTFNode.

void register_gltf_document_extension(GLTFDocumentExtension extension, bool first_priority)

Parameters

extension GLTFDocumentExtension
first_priority bool

unregister_gltf_document_extension(GLTFDocumentExtension)

Qualifiers: static

Unregisters the given GLTFDocumentExtension instance.

void unregister_gltf_document_extension(GLTFDocumentExtension extension)

Parameters

extension GLTFDocumentExtension

write_to_filesystem(GLTFState, String)

Takes a GLTFState object through the state 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.

int write_to_filesystem(GLTFState state, String path)

Parameters

state GLTFState
path String