Class GLTFState

Represents all data of a glTF file.

Inheritance

Resource

RefCounted

Object

GLTFState

Derived

FBXState

Remarks

Contains all nodes and resources of a glTF file. This is used by GLTFDocument as data storage, which allows GLTFDocument and all GLTFDocumentExtension classes to remain stateless.

GLTFState can be populated by GLTFDocument reading a file or by converting a Godot scene. Then the data can either be used to create a Godot scene or save to a glTF file. The code that converts to/from a Godot scene can be intercepted at arbitrary points by GLTFDocumentExtension classes. This allows for custom data to be stored in the glTF file or for custom data to be converted to/from Godot nodes.

See Also

Runtime file loading and saving

glTF asset header schema

Fields

HANDLE_BINARY_DISCARD_TEXTURES

Discards all embedded textures and uses untextured materials.

const HANDLE_BINARY_DISCARD_TEXTURES = 0

HANDLE_BINARY_EXTRACT_TEXTURES

Extracts embedded textures to be reimported and compressed. Editor only. Acts as uncompressed at runtime.

const HANDLE_BINARY_EXTRACT_TEXTURES = 1

HANDLE_BINARY_EMBED_AS_BASISU

Embeds textures VRAM compressed with Basis Universal into the generated scene.

const HANDLE_BINARY_EMBED_AS_BASISU = 2

HANDLE_BINARY_EMBED_AS_UNCOMPRESSED

Embeds textures compressed losslessly into the generated scene, matching old behavior.

const HANDLE_BINARY_EMBED_AS_UNCOMPRESSED = 3

Properties

bake_fps

The baking fps of the animation for either import or export.

var bake_fps : float = 30.0

Property Value

float

Remarks

• void set_bake_fps(float value)
• float get_bake_fps

base_path

The folder path associated with this glTF data. This is used to find other files the glTF file references, like images or binary buffers. This will be set during import when appending from a file, and will be set during export when writing to a file.

var base_path : String = ""

Property Value

String

Remarks

• void set_base_path(String value)
• String get_base_path

buffers

var buffers : PackedByteArray[] = []

Property Value

PackedByteArray[]

Remarks

• void set_buffers(PackedByteArray[] value)
• PackedByteArray[] get_buffers

copyright

The copyright string in the asset header of the glTF file. This is set during import if present and export if non-empty. See the glTF asset header documentation for more information.

var copyright : String = ""

Property Value

String

Remarks

• void set_copyright(String value)
• String get_copyright

create_animations

var create_animations : bool = true

Property Value

bool

Remarks

• void set_create_animations(bool value)
• bool get_create_animations

filename

The file name associated with this glTF data. If it ends with .gltf, this is text-based glTF, otherwise this is binary GLB. This will be set during import when appending from a file, and will be set during export when writing to a file. If writing to a buffer, this will be an empty string.

var filename : String = ""

Property Value

String

Remarks

• void set_filename(String value)
• String get_filename

glb_data

The binary buffer attached to a .glb file.

var glb_data : PackedByteArray = PackedByteArray()

Property Value

PackedByteArray

Remarks

• void set_glb_data(PackedByteArray value)
• PackedByteArray get_glb_data

import_as_skeleton_bones

If true, forces all GLTFNodes in the document to be bones of a single Skeleton3D Godot node.

var import_as_skeleton_bones : bool = false

Property Value

bool

Remarks

• void set_import_as_skeleton_bones(bool value)
• bool get_import_as_skeleton_bones

json

The original raw JSON document corresponding to this GLTFState.

var json : Dictionary = {}

Property Value

Dictionary

Remarks

• void set_json(Dictionary value)
• Dictionary get_json

major_version

var major_version : int = 0

Property Value

int

Remarks

• void set_major_version(int value)
• int get_major_version

minor_version

var minor_version : int = 0

Property Value

int

Remarks

• void set_minor_version(int value)
• int get_minor_version

root_nodes

The root nodes of the glTF file. Typically, a glTF file will only have one scene, and therefore one root node. However, a glTF file may have multiple scenes and therefore multiple root nodes, which will be generated as siblings of each other and as children of the root node of the generated Godot scene.

var root_nodes : PackedInt32Array = PackedInt32Array()

Property Value

PackedInt32Array

Remarks

• void set_root_nodes(PackedInt32Array value)
• PackedInt32Array get_root_nodes

scene_name

The name of the scene. When importing, if not specified, this will be the file name. When exporting, if specified, the scene name will be saved to the glTF file.

var scene_name : String = ""

Property Value

String

Remarks

• void set_scene_name(String value)
• String get_scene_name

use_named_skin_binds

var use_named_skin_binds : bool = false

Property Value

bool

Remarks

• void set_use_named_skin_binds(bool value)
• bool get_use_named_skin_binds

Methods

add_used_extension(String, bool)

Appends an extension to the list of extensions used by this glTF file during serialization. If required is true, the extension will also be added to the list of required extensions. Do not run this in GLTFDocumentExtension._export_post, as that stage is too late to add extensions. The final list is sorted alphabetically.

void add_used_extension(String extension_name, bool required)

Parameters

extension_name String

required bool

append_data_to_buffers(PackedByteArray, bool)

Appends the given byte array data to the buffers and creates a GLTFBufferView for it. The index of the destination GLTFBufferView is returned. If deduplication is true, the buffers will first be searched for duplicate data, otherwise new bytes will always be appended.

int append_data_to_buffers(PackedByteArray data, bool deduplication)

Parameters

data PackedByteArray

deduplication bool

append_gltf_node(GLTFNode, Node, int)

Append the given GLTFNode to the state, and return its new index. This can be used to export one Godot node as multiple glTF nodes, or inject new glTF nodes at import time. On import, this must be called before GLTFDocumentExtension._generate_scene_node finishes for the parent node. On export, this must be called before GLTFDocumentExtension._export_node runs for the parent node.

The godot_scene_node parameter is the Godot scene node that corresponds to this glTF node. This is highly recommended to be set to a valid node, but may be null if there is no corresponding Godot scene node. One Godot scene node may be used for multiple glTF nodes, so if exporting multiple glTF nodes for one Godot scene node, use the same Godot scene node for each.

The parent_node_index parameter is the index of the parent GLTFNode in the state. If -1, the node will be a root node, otherwise the new node will be added to the parent's list of children. The index will also be written to the parent property of the new node.

int append_gltf_node(GLTFNode gltf_node, Node godot_scene_node, int parent_node_index)

Parameters

gltf_node GLTFNode

godot_scene_node Node

parent_node_index int

get_accessors

GLTFAccessor[] get_accessors

get_additional_data(StringName)

Gets additional arbitrary data in this GLTFState instance. This can be used to keep per-file state data in GLTFDocumentExtension classes, which is important because they are stateless.

The argument should be the GLTFDocumentExtension name (does not have to match the extension name in the glTF file), and the return value can be anything you set. If nothing was set, the return value is null.

Variant get_additional_data(StringName extension_name)

Parameters

extension_name StringName

get_animation_player(int)

Returns the AnimationPlayer node with the given index. These nodes are only used during the export process when converting Godot AnimationPlayer nodes to glTF animations.

AnimationPlayer get_animation_player(int idx)

Parameters

idx int

get_animation_players_count(int)

Returns the number of AnimationPlayer nodes in this GLTFState. These nodes are only used during the export process when converting Godot AnimationPlayer nodes to glTF animations.

int get_animation_players_count(int idx)

Parameters

idx int

get_animations

Returns an array of all GLTFAnimations in the glTF file. When importing, these will be generated as animations in an AnimationPlayer node. When exporting, these will be generated from Godot AnimationPlayer nodes.

GLTFAnimation[] get_animations

get_buffer_views

GLTFBufferView[] get_buffer_views

get_cameras

Returns an array of all GLTFCameras in the glTF file. These are the cameras that the camera index refers to.

GLTFCamera[] get_cameras

get_handle_binary_image

int get_handle_binary_image

get_images

Gets the images of the glTF file as an array of Texture2Ds. These are the images that the src_image index refers to.

Texture2D[] get_images

get_lights

Returns an array of all GLTFLights in the glTF file. These are the lights that the light index refers to.

GLTFLight[] get_lights

get_materials

Material[] get_materials

get_meshes

Returns an array of all GLTFMeshes in the glTF file. These are the meshes that the mesh index refers to.

GLTFMesh[] get_meshes

get_node_index(Node)

Returns the index of the GLTFNode corresponding to this Godot scene node. This is the inverse of GLTFState.get_scene_node. Useful during the export process.

Note: Not every Godot scene node will have a corresponding GLTFNode, and not every GLTFNode will have a scene node generated. If there is no GLTFNode index for this scene node, -1 is returned.

int get_node_index(Node scene_node)

Parameters

scene_node Node

get_nodes

Returns an array of all GLTFNodes in the glTF file. These are the nodes that children and root_nodes refer to. This includes nodes that may not be generated in the Godot scene, or nodes that may generate multiple Godot scene nodes.

GLTFNode[] get_nodes

get_scene_node(int)

Returns the Godot scene node that corresponds to the same index as the GLTFNode it was generated from. This is the inverse of GLTFState.get_node_index. Useful during the import process.

Note: Not every GLTFNode will have a scene node generated, and not every generated scene node will have a corresponding GLTFNode. If there is no scene node for this GLTFNode index, null is returned.

Node get_scene_node(int idx)

Parameters

idx int

get_skeletons

Returns an array of all GLTFSkeletons in the glTF file. These are the skeletons that the skeleton index refers to.

GLTFSkeleton[] get_skeletons

get_skins

Returns an array of all GLTFSkins in the glTF file. These are the skins that the skin index refers to.

GLTFSkin[] get_skins

get_texture_samplers

Retrieves the array of texture samplers that are used by the textures contained in the glTF.

GLTFTextureSampler[] get_texture_samplers

get_textures

GLTFTexture[] get_textures

get_unique_animation_names

Returns an array of unique animation names. This is only used during the import process.

String[] get_unique_animation_names

get_unique_names

Returns an array of unique node names. This is used in both the import process and export process.

String[] get_unique_names

set_accessors(GLTFAccessor[])

void set_accessors(GLTFAccessor[] accessors)

Parameters

accessors GLTFAccessor[]

set_additional_data(StringName, Variant)

Sets additional arbitrary data in this GLTFState instance. This can be used to keep per-file state data in GLTFDocumentExtension classes, which is important because they are stateless.

The first argument should be the GLTFDocumentExtension name (does not have to match the extension name in the glTF file), and the second argument can be anything you want.

void set_additional_data(StringName extension_name, Variant additional_data)

Parameters

extension_name StringName

additional_data Variant

set_animations(GLTFAnimation[])

Sets the GLTFAnimations in the state. When importing, these will be generated as animations in an AnimationPlayer node. When exporting, these will be generated from Godot AnimationPlayer nodes.

void set_animations(GLTFAnimation[] animations)

Parameters

animations GLTFAnimation[]

set_buffer_views(GLTFBufferView[])

void set_buffer_views(GLTFBufferView[] buffer_views)

Parameters

buffer_views GLTFBufferView[]

set_cameras(GLTFCamera[])

Sets the GLTFCameras in the state. These are the cameras that the camera index refers to.

void set_cameras(GLTFCamera[] cameras)

Parameters

cameras GLTFCamera[]

set_handle_binary_image(int)

void set_handle_binary_image(int method)

Parameters

method int

set_images(Texture2D[])

Sets the images in the state stored as an array of Texture2Ds. This can be used during export. These are the images that the src_image index refers to.

void set_images(Texture2D[] images)

Parameters

images Texture2D[]

set_lights(GLTFLight[])

Sets the GLTFLights in the state. These are the lights that the light index refers to.

void set_lights(GLTFLight[] lights)

Parameters

lights GLTFLight[]

set_materials(Material[])

void set_materials(Material[] materials)

Parameters

materials Material[]

set_meshes(GLTFMesh[])

Sets the GLTFMeshes in the state. These are the meshes that the mesh index refers to.

void set_meshes(GLTFMesh[] meshes)

Parameters

meshes GLTFMesh[]

set_nodes(GLTFNode[])

Sets the GLTFNodes in the state. These are the nodes that children and root_nodes refer to. Some of the nodes set here may not be generated in the Godot scene, or may generate multiple Godot scene nodes.

void set_nodes(GLTFNode[] nodes)

Parameters

nodes GLTFNode[]

set_skeletons(GLTFSkeleton[])

Sets the GLTFSkeletons in the state. These are the skeletons that the skeleton index refers to.

void set_skeletons(GLTFSkeleton[] skeletons)

Parameters

skeletons GLTFSkeleton[]

set_skins(GLTFSkin[])

Sets the GLTFSkins in the state. These are the skins that the skin index refers to.

void set_skins(GLTFSkin[] skins)

Parameters

skins GLTFSkin[]

set_texture_samplers(GLTFTextureSampler[])

Sets the array of texture samplers that are used by the textures contained in the glTF.

void set_texture_samplers(GLTFTextureSampler[] texture_samplers)

Parameters

texture_samplers GLTFTextureSampler[]

set_textures(GLTFTexture[])

void set_textures(GLTFTexture[] textures)

Parameters

textures GLTFTexture[]

set_unique_animation_names(String[])

Sets the unique animation names in the state. This is only used during the import process.

void set_unique_animation_names(String[] unique_animation_names)

Parameters

unique_animation_names String[]

set_unique_names(String[])

Sets the unique node names in the state. This is used in both the import process and export process.

void set_unique_names(String[] unique_names)

Parameters

unique_names String[]