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.

GLTFDocumentExtension

Inherits: Resource < RefCounted < Object

Inherited By: GLTFDocumentExtensionConvertImporterMesh

GLTFDocument extension class.

Description

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.

Tutorials

Methods

void

_convert_scene_node(state: GLTFState, gltf_node: GLTFNode, scene_node: Node) virtual

Error

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

Error

_export_post(state: GLTFState) virtual

Error

_export_preflight(state: GLTFState, root: Node) virtual

Error

_export_preserialize(state: GLTFState) virtual

Node3D

_generate_scene_node(state: GLTFState, gltf_node: GLTFNode, scene_parent: Node) virtual

String

_get_image_file_extension() virtual

PackedStringArray

_get_saveable_image_formats() virtual

PackedStringArray

_get_supported_extensions() virtual

Error

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

Error

_import_post(state: GLTFState, root: Node) virtual

Error

_import_post_parse(state: GLTFState) virtual

Error

_import_preflight(state: GLTFState, extensions: PackedStringArray) virtual

Error

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

Error

_parse_node_extensions(state: GLTFState, gltf_node: GLTFNode, extensions: Dictionary) virtual

Error

_parse_texture_json(state: GLTFState, texture_json: Dictionary, ret_gltf_texture: GLTFTexture) virtual

Error

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

PackedByteArray

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

Error

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


Method Descriptions

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

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

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 _export_node.


Error _export_node(state: GLTFState, gltf_node: GLTFNode, json: Dictionary, node: Node) virtual

Part of the export process. This method is run after _get_saveable_image_formats and before _export_post. If this GLTFDocumentExtension is used for exporting images, this runs after _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. The node may be null if not available, such as when exporting GLTF data not generated from a Godot scene.


Error _export_post(state: GLTFState) 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.


Error _export_preflight(state: GLTFState, root: Node) 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.


Error _export_preserialize(state: GLTFState) virtual

Part of the export process. This method is run after _convert_scene_node 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.


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

Part of the import process. This method is run after _import_post_parse and before _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.


String _get_image_file_extension() 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.


PackedStringArray _get_saveable_image_formats() virtual

Part of the export process. This method is run after _convert_scene_node and before _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 GLTFDocument.image_format is in this array. If this GLTFDocumentExtension is selected as the image exporter, one of the _save_image_at_path or _serialize_image_to_bytes methods will run next, otherwise _export_node will run next. If the format name contains "Lossy", the lossy quality slider will be displayed.


PackedStringArray _get_supported_extensions() virtual

Part of the import process. This method is run after _import_preflight and before _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.


Error _import_node(state: GLTFState, gltf_node: GLTFNode, json: Dictionary, node: Node) virtual

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

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


Error _import_post(state: GLTFState, root: Node) 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.


Error _import_post_parse(state: GLTFState) virtual

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

This method can be used to modify any of the data imported so far after parsing, before generating the nodes and then running the final per-node import step.


Error _import_preflight(state: GLTFState, extensions: PackedStringArray) 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.


Error _parse_image_data(state: GLTFState, image_data: PackedByteArray, mime_type: String, ret_image: Image) virtual

Part of the import process. This method is run after _parse_node_extensions and before _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.


Error _parse_node_extensions(state: GLTFState, gltf_node: GLTFNode, extensions: Dictionary) virtual

Part of the import process. This method is run after _get_supported_extensions and before _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 _generate_scene_node. The return value should be a member of the Error enum.


Error _parse_texture_json(state: GLTFState, texture_json: Dictionary, ret_gltf_texture: GLTFTexture) virtual

Part of the import process. This method is run after _parse_image_data and before _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.


Error _save_image_at_path(state: GLTFState, image: Image, file_path: String, image_format: String, lossy_quality: float) virtual

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

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


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

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

This method is run when embedding images in the GLTF file. When images are saved separately, _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.


Error _serialize_texture_json(state: GLTFState, texture_json: Dictionary, gltf_texture: GLTFTexture, image_format: String) virtual

Part of the export process. This method is run after _save_image_at_path or _serialize_image_to_bytes, and before _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.


User-contributed notes

Please read the User-contributed notes policy before submitting a comment.