glTF

Purpose

modules/gltf/ is Godot's first-party glTF 2.0 importer and exporter. It produces .tscn scenes from .gltf/.glb files (and writes them back), supports a long list of glTF extensions, and provides the runtime API any project can use to load glTFs at runtime without editor involvement.

Directory layout

modules/gltf/
├── gltf_document.{cpp,h}       Top-level orchestrator (parses JSON + bin, builds Godot scene)
├── gltf_state.{cpp,h}          Per-import state: nodes, meshes, materials, animations, skins
├── gltf_buffer.{cpp,h}         Buffer / buffer view abstraction
├── gltf_animation.{cpp,h}      Animation reconstruction
├── gltf_camera.{cpp,h}, gltf_light.{cpp,h}, gltf_skeleton.{cpp,h}, gltf_skin.{cpp,h}, …
│   GLTFNode, GLTFMesh, GLTFMaterial, GLTFTexture, GLTFAccessor — typed glTF elements
├── extensions/                 Per-extension hooks (KHR_animation_pointer, KHR_materials_*,
│                                MSFT_*, GODOT_*, KHR_xmp_json_ld, …)
├── editor/                     Editor importer plugin (drag .gltf into the project)
├── doc_classes/                XML class reference
└── register_types.cpp          Module entry — registers GLTFDocument + EditorImportPlugin

What gets imported

A glTF asset is unpacked into a Godot scene with:

• A Node3D root and per-glTF-node children.
• MeshInstance3D (or Skeleton3D + BoneAttachment3D) per mesh.
• ImporterMesh resources (later baked into final Mesh resources by the editor's import pipeline).
• BaseMaterial3D / ORMMaterial3D / ShaderMaterial per glTF material, with PBR metallic-roughness, normal/AO/emission/occlusion textures, alpha modes (OPAQUE/MASK/BLEND), and clearcoat / sheen / specular extensions.
• AnimationLibrary resources keyed by glTF animation names.
• Skeleton3D plus Skin resources for skinned meshes.
• OmniLight3D / SpotLight3D / DirectionalLight3D from KHR_lights_punctual.
• Camera3D from glTF cameras.

Pipeline

graph LR
    File[".gltf or .glb"] --> Parse[GLTFDocument::append_from_file]
    Parse --> Buffers[GLTFBuffer / accessors]
    Parse --> JSON[JSON tree]
    JSON --> Nodes[GLTFNode tree]
    Buffers --> Meshes[GLTFMesh / GLTFAccessor]
    JSON --> Materials[GLTFMaterial / textures]
    JSON --> Animations[GLTFAnimation]
    JSON --> Skins[GLTFSkin / GLTFSkeleton]
    Nodes --> Generate[GLTFDocument::generate_scene]
    Materials --> Generate
    Meshes --> Generate
    Animations --> Generate
    Skins --> Generate
    Generate --> Scene[Godot Node3D scene]
    Scene --> Cache[".godot/imported/*.scn"]

The top-level entry point is GLTFDocument::append_from_file (or append_from_buffer / append_from_scene), followed by generate_scene. GLTFState accumulates the parsed entities; the conversion to a Godot scene happens in _create_scene_node and friends.

Runtime usage

The class is exposed to scripting:

var doc := GLTFDocument.new()
var state := GLTFState.new()
var err := doc.append_from_file("user://model.glb", state)
if err == OK:
    add_child(doc.generate_scene(state))

This is how plugins, asset stores, and procedural pipelines load glTF without the editor.

Extensions

extensions/ registers handlers for many glTF extensions. The set tracked includes (non-exhaustive):

Extension	What it adds
KHR_lights_punctual	Point / spot / directional lights
KHR_materials_emissive_strength	Emissive multiplier
KHR_materials_clearcoat	Clearcoat layer for PBR
KHR_materials_sheen	Sheen layer for fabrics
KHR_materials_specular	Per-channel specular
KHR_materials_transmission / volume / ior	Refraction + thickness
KHR_materials_unlit	Unlit shading mode
KHR_texture_transform	Per-texture UV transforms
KHR_animation_pointer	Animate arbitrary properties via JSON pointers
KHR_mesh_quantization	Quantized vertex attributes
KHR_xmp_json_ld	Embedded XMP metadata
MSFT_audio_emitter, MSFT_lod, MSFT_packing_*	Microsoft extensions
GODOT_single_root	Force a single-root output (Godot-specific)

Each extension lives in extensions/gltf_document_extension_*.cpp. Custom extensions can be registered at runtime via GLTFDocument::register_gltf_document_extension(...) — useful when projects need vendor-specific data (e.g., physics shapes embedded in glTF custom properties).

Export

The same GLTFDocument can serialize a Godot scene back to glTF. Limitations apply: features that have no glTF equivalent (custom shaders, particle systems, GPU lightmaps) are dropped or downgraded.

Editor importer

editor/ contributes an EditorSceneFormatImporter that the editor's scene import bus selects for .gltf / .glb extensions. Importer options include skeleton handling, blend shape import, animation track filtering, and physics shape generation.

modules/fbx/ reuses GLTFDocument after converting FBX → glTF via the bundled fbx2gltf binary, so the actual import pipeline for both formats funnels through here.

Key abstractions

Abstraction	File	Role
GLTFDocument	modules/gltf/gltf_document.cpp	Orchestrator (load, save, generate_scene)
GLTFState	modules/gltf/gltf_state.cpp	Per-import state container
GLTFNode, GLTFMesh, GLTFAnimation, GLTFSkeleton, GLTFSkin, GLTFCamera, GLTFLight, GLTFTexture	modules/gltf/gltf_*.cpp	Typed glTF entities
GLTFAccessor, GLTFBufferView	modules/gltf/gltf_*.cpp	glTF binary accessor resolution
GLTFDocumentExtension	modules/gltf/extensions/gltf_document_extension.h	Plugin point for extensions

Integration points

• The editor scene import bus invokes GLTFDocument for .gltf/.glb (and modules/fbx for .fbx).
• EditorImportPlugin subclasses for glTF set the default options surface in the import dock.
• The exporter (file → "Export As" in the scene menu) calls GLTFDocument::write_to_filesystem.
• Custom extensions registered at runtime persist for the lifetime of the engine; the editor reads them when displaying import options.

Entry points for modification

• New extension support → write a GLTFDocumentExtension subclass in extensions/ and register from register_types.cpp.
• Material customization → either supply a BaseMaterial3D template via the importer options, or post-process by running an EditorScenePostImport script.
• Quantization or compression → see KHR_mesh_quantization and EXT_meshopt_compression handlers.