Table of Contents

Class GLTFDocumentExtension

GLTFDocument extension class.

Inheritance
GLTFDocumentExtension
Derived

Remarks

Extends the functionality of the GLTFDocument class by allowing you to run arbitrary code at various stages of glTF import or export.

To use, make a new class extending GLTFDocumentExtension, override any methods you need, make an instance of your class, and register it using GLTFDocument.register_gltf_document_extension.

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.

See Also

Runtime file loading and saving

Methods

_convert_scene_node(GLTFState, GLTFNode, Node)

Qualifiers: virtual

Part of the export process. This method is run after GLTFDocumentExtension._export_preflight and before GLTFDocumentExtension._export_post_convert.

Runs when converting the data from a Godot scene node. This method can be used to process the Godot scene node data into a format that can be used by GLTFDocumentExtension._export_node.

void _convert_scene_node(GLTFState state, GLTFNode gltf_node, Node scene_node)

Parameters

state GLTFState
gltf_node GLTFNode
scene_node Node

_export_node(GLTFState, GLTFNode, Dictionary, Node)

Qualifiers: virtual

Part of the export process. This method is run after _get_saveable_image_formats and before GLTFDocumentExtension._export_post. If this GLTFDocumentExtension is used for exporting images, this runs after GLTFDocumentExtension._serialize_texture_json.

This method can be used to modify the final JSON of each node. Data should be primarily stored in gltf_node prior to serializing the JSON, but the original Godot Node is also provided if available. node may be null if not available, such as when exporting glTF data not generated from a Godot scene.

int _export_node(GLTFState state, GLTFNode gltf_node, Dictionary json, Node node)

Parameters

state GLTFState
gltf_node GLTFNode
json Dictionary
node Node

_export_object_model_property(GLTFState, NodePath, Node, int, Object, int)

Qualifiers: virtual

Part of the export process. Allows GLTFDocumentExtension classes to provide mappings for properties of nodes in the Godot scene tree, to JSON pointers to glTF properties, as defined by the glTF object model.

Returns a GLTFObjectModelProperty instance that defines how the property should be mapped. If your extension can't handle the property, return null or an instance without any JSON pointers (see has_json_pointers). You should use GLTFObjectModelProperty.set_types to set the types, and set the JSON pointer(s) using the json_pointers property.

The parameters provide context for the property, including the NodePath, the Godot node, the GLTF node index, and the target object. The target_object will be equal to godot_node if no sub-object can be found, otherwise it will point to a sub-object. For example, if the path is ^"A/B/C/MeshInstance3D:mesh:surface_0/material:emission_intensity", it will get the node, then the mesh, and then the material, so target_object will be the Material resource, and target_depth will be 2 because 2 levels were traversed to get to the target.

GLTFObjectModelProperty _export_object_model_property(GLTFState state, NodePath node_path, Node godot_node, int gltf_node_index, Object target_object, int target_depth)

Parameters

state GLTFState
node_path NodePath
godot_node Node
gltf_node_index int
target_object Object
target_depth int

_export_post(GLTFState)

Qualifiers: virtual

Part of the export process. This method is run last, after all other parts of the export process.

This method can be used to modify the final JSON of the generated glTF file.

int _export_post(GLTFState state)

Parameters

state GLTFState

_export_post_convert(GLTFState, Node)

Qualifiers: virtual

Part of the export process. This method is run after GLTFDocumentExtension._convert_scene_node and before GLTFDocumentExtension._export_preserialize.

This method can be used to modify the converted node data structures before serialization with any additional data from the scene tree.

int _export_post_convert(GLTFState state, Node root)

Parameters

state GLTFState
root Node

_export_preflight(GLTFState, Node)

Qualifiers: virtual

Part of the export process. This method is run first, before all other parts of the export process.

The return value is used to determine if this GLTFDocumentExtension instance should be used for exporting a given glTF file. If @GlobalScope.OK, the export will use this GLTFDocumentExtension instance. If not overridden, @GlobalScope.OK is returned.

int _export_preflight(GLTFState state, Node root)

Parameters

state GLTFState
root Node

_export_preserialize(GLTFState)

Qualifiers: virtual

Part of the export process. This method is run after GLTFDocumentExtension._export_post_convert and before _get_saveable_image_formats.

This method can be used to alter the state before performing serialization. It runs every time when generating a buffer with GLTFDocument.generate_buffer or writing to the file system with GLTFDocument.write_to_filesystem.

int _export_preserialize(GLTFState state)

Parameters

state GLTFState

_generate_scene_node(GLTFState, GLTFNode, Node)

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._import_pre_generate and before GLTFDocumentExtension._import_node.

Runs when generating a Godot scene node from a GLTFNode. The returned node will be added to the scene tree. Multiple nodes can be generated in this step if they are added as a child of the returned node.

Note: The scene_parent parameter may be null if this is the single root node.

Node3D _generate_scene_node(GLTFState state, GLTFNode gltf_node, Node scene_parent)

Parameters

state GLTFState
gltf_node GLTFNode
scene_parent Node

_get_image_file_extension

Qualifiers: virtual

Returns the file extension to use for saving image data into, for example, ".png". If defined, when this extension is used to handle images, and the images are saved to a separate file, the image bytes will be copied to a file with this extension. If this is set, there should be a ResourceImporter class able to import the file. If not defined or empty, Godot will save the image into a PNG file.

String _get_image_file_extension

_get_saveable_image_formats

Qualifiers: virtual

Part of the export process. This method is run after GLTFDocumentExtension._convert_scene_node and before GLTFDocumentExtension._export_node.

Returns an array of the image formats that can be saved/exported by this extension. This extension will only be selected as the image exporter if the GLTFDocument's image_format is in this array. If this GLTFDocumentExtension is selected as the image exporter, one of the GLTFDocumentExtension._save_image_at_path or GLTFDocumentExtension._serialize_image_to_bytes methods will run next, otherwise GLTFDocumentExtension._export_node will run next. If the format name contains "Lossy", the lossy quality slider will be displayed.

PackedStringArray _get_saveable_image_formats

_get_supported_extensions

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._import_preflight and before GLTFDocumentExtension._parse_node_extensions.

Returns an array of the glTF extensions supported by this GLTFDocumentExtension class. This is used to validate if a glTF file with required extensions can be loaded.

PackedStringArray _get_supported_extensions

_import_node(GLTFState, GLTFNode, Dictionary, Node)

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._generate_scene_node and before GLTFDocumentExtension._import_post.

This method can be used to make modifications to each of the generated Godot scene nodes.

int _import_node(GLTFState state, GLTFNode gltf_node, Dictionary json, Node node)

Parameters

state GLTFState
gltf_node GLTFNode
json Dictionary
node Node

_import_object_model_property(GLTFState, PackedStringArray, NodePath[])

Qualifiers: virtual

Part of the import process. Allows GLTFDocumentExtension classes to provide mappings for JSON pointers to glTF properties, as defined by the glTF object model, to properties of nodes in the Godot scene tree.

Returns a GLTFObjectModelProperty instance that defines how the property should be mapped. If your extension can't handle the property, return null or an instance without any NodePaths (see has_node_paths). You should use GLTFObjectModelProperty.set_types to set the types, and GLTFObjectModelProperty.append_path_to_property function is useful for most simple cases.

In many cases, partial_paths will contain the start of a path, allowing the extension to complete the path. For example, for /nodes/3/extensions/MY_ext/prop, Godot will pass you a NodePath that leads to node 3, so the GLTFDocumentExtension class only needs to resolve the last MY_ext/prop part of the path. In this example, the extension should check split.size() > 4 and split[0] == "nodes" and split[2] == "extensions" and split[3] == "MY_ext" at the start of the function to check if this JSON pointer applies to it, then it can use partial_paths and handle split[4].

GLTFObjectModelProperty _import_object_model_property(GLTFState state, PackedStringArray split_json_pointer, NodePath[] partial_paths)

Parameters

state GLTFState
split_json_pointer PackedStringArray
partial_paths NodePath[]

_import_post(GLTFState, Node)

Qualifiers: virtual

Part of the import process. This method is run last, after all other parts of the import process.

This method can be used to modify the final Godot scene generated by the import process.

int _import_post(GLTFState state, Node root)

Parameters

state GLTFState
root Node

_import_post_parse(GLTFState)

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._parse_node_extensions and before GLTFDocumentExtension._import_pre_generate.

This method can be used to modify any of the data imported so far after parsing each node, but before generating the scene or any of its nodes.

int _import_post_parse(GLTFState state)

Parameters

state GLTFState

_import_pre_generate(GLTFState)

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._import_post_parse and before GLTFDocumentExtension._generate_scene_node.

This method can be used to modify or read from any of the processed data structures, before generating the nodes and then running the final per-node import step.

int _import_pre_generate(GLTFState state)

Parameters

state GLTFState

_import_preflight(GLTFState, PackedStringArray)

Qualifiers: virtual

Part of the import process. This method is run first, before all other parts of the import process.

The return value is used to determine if this GLTFDocumentExtension instance should be used for importing a given glTF file. If @GlobalScope.OK, the import will use this GLTFDocumentExtension instance. If not overridden, @GlobalScope.OK is returned.

int _import_preflight(GLTFState state, PackedStringArray extensions)

Parameters

state GLTFState
extensions PackedStringArray

_parse_image_data(GLTFState, PackedByteArray, String, Image)

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._parse_node_extensions and before GLTFDocumentExtension._parse_texture_json.

Runs when parsing image data from a glTF file. The data could be sourced from a separate file, a URI, or a buffer, and then is passed as a byte array.

int _parse_image_data(GLTFState state, PackedByteArray image_data, String mime_type, Image ret_image)

Parameters

state GLTFState
image_data PackedByteArray
mime_type String
ret_image Image

_parse_node_extensions(GLTFState, GLTFNode, Dictionary)

Qualifiers: virtual

Part of the import process. This method is run after _get_supported_extensions and before GLTFDocumentExtension._import_post_parse.

Runs when parsing the node extensions of a GLTFNode. This method can be used to process the extension JSON data into a format that can be used by GLTFDocumentExtension._generate_scene_node. The return value should be a member of the Error enum.

int _parse_node_extensions(GLTFState state, GLTFNode gltf_node, Dictionary extensions)

Parameters

state GLTFState
gltf_node GLTFNode
extensions Dictionary

_parse_texture_json(GLTFState, Dictionary, GLTFTexture)

Qualifiers: virtual

Part of the import process. This method is run after GLTFDocumentExtension._parse_image_data and before GLTFDocumentExtension._generate_scene_node.

Runs when parsing the texture JSON from the glTF textures array. This can be used to set the source image index to use as the texture.

int _parse_texture_json(GLTFState state, Dictionary texture_json, GLTFTexture ret_gltf_texture)

Parameters

state GLTFState
texture_json Dictionary
ret_gltf_texture GLTFTexture

_save_image_at_path(GLTFState, Image, String, String, float)

Qualifiers: virtual

Part of the export process. This method is run after _get_saveable_image_formats and before GLTFDocumentExtension._serialize_texture_json.

This method is run when saving images separately from the glTF file. When images are embedded, GLTFDocumentExtension._serialize_image_to_bytes runs instead. Note that these methods only run when this GLTFDocumentExtension is selected as the image exporter.

int _save_image_at_path(GLTFState state, Image image, String file_path, String image_format, float lossy_quality)

Parameters

state GLTFState
image Image
file_path String
image_format String
lossy_quality float

_serialize_image_to_bytes(GLTFState, Image, Dictionary, String, float)

Qualifiers: virtual

Part of the export process. This method is run after _get_saveable_image_formats and before GLTFDocumentExtension._serialize_texture_json.

This method is run when embedding images in the glTF file. When images are saved separately, GLTFDocumentExtension._save_image_at_path runs instead. Note that these methods only run when this GLTFDocumentExtension is selected as the image exporter.

This method must set the image MIME type in the image_dict with the "mimeType" key. For example, for a PNG image, it would be set to "image/png". The return value must be a PackedByteArray containing the image data.

PackedByteArray _serialize_image_to_bytes(GLTFState state, Image image, Dictionary image_dict, String image_format, float lossy_quality)

Parameters

state GLTFState
image Image
image_dict Dictionary
image_format String
lossy_quality float

_serialize_texture_json(GLTFState, Dictionary, GLTFTexture, String)

Qualifiers: virtual

Part of the export process. This method is run after GLTFDocumentExtension._save_image_at_path or GLTFDocumentExtension._serialize_image_to_bytes, and before GLTFDocumentExtension._export_node. Note that this method only runs when this GLTFDocumentExtension is selected as the image exporter.

This method can be used to set up the extensions for the texture JSON by editing texture_json. The extension must also be added as used extension with GLTFState.add_used_extension, be sure to set required to true if you are not providing a fallback.

int _serialize_texture_json(GLTFState state, Dictionary texture_json, GLTFTexture gltf_texture, String image_format)

Parameters

state GLTFState
texture_json Dictionary
gltf_texture GLTFTexture
image_format String