Automated glTF Import Scripts in Godot Engine

When glTF or GLB files change within a Godot project, the engine automatically detects the updated assets and triggers an import pipeline driven by specialized internal classes and user-defined scripts. This workflow relies on EditorFileSystem detecting file modifications, invoking the core glTF importer, running any registered GLTFDocumentExtension hooks, and finally executing custom EditorScenePostImport scripts assigned to the asset.

The Import Detection Process

Godot monitors the project directory using the EditorFileSystem class. When an external 3D modeling tool saves or overwrites a .gltf or .glb file, the editor detects the updated timestamp and marks the asset as dirty. Godot then automatically invokes the 3D scene import process via the internal EditorSceneFormatImporterGLTF class, converting the raw glTF data into a native Godot scene hierarchy without requiring manual user intervention.

Custom Post-Import Scripts (EditorScenePostImport)

The primary user-facing automated script triggered on file change is an EditorScenePostImport script. In Godot's Import dock, developers can assign a custom GDScript that extends EditorScenePostImport to the scene.

Whenever the source glTF file updates, the engine rebuilds the scene in memory and passes the root node to this script before saving the final .scn or .res cache. The script executes its _post_import(scene: Node) method automatically. This is standard for tasks such as:

  • Iterating through imported nodes to adjust collision layers or physics materials.
  • Swapping imported materials with pre-existing project materials.
  • Adding components, scripts, or custom metadata to specific meshes based on naming conventions.
  • Generating navigation meshes or adjusting LOD settings programmatically.

glTF Extension Pipeline (GLTFDocumentExtension)

For deeper, lower-level integration introduced in Godot 4, the engine runs scripts extending GLTFDocumentExtension. These extensions plug directly into the GLTFDocument parsing lifecycle and execute automatically on every glTF re-import if registered through an EditorPlugin.

When a glTF modification is detected, Godot executes several virtual methods in registered GLTFDocumentExtension scripts sequentially:

  1. _import_preflight(): Runs validation checks on the glTF state before parsing nodes.
  2. _import_post_parse(): Executes after the JSON and buffers are parsed, allowing data modification before nodes are instantiated.
  3. _import_node(): Runs for every node in the glTF file, allowing scripts to intercept custom glTF extras/extensions and translate them into Godot properties.
  4. _import_post(): Executes right before the imported scene tree is finalized.

Advanced Automation: EditorSceneFormatImporter

At the highest level of customization, Godot allows developers to register custom EditorSceneFormatImporter plugins. While Godot natively routes glTF files through its built-in glTF importer, a custom importer script can intercept the import pipeline completely or provide alternative processing routines when specific custom extensions or companion configuration files change alongside the glTF asset.