GLTFDocumentExtension in Godot – Complete Guide

So, you’re tinkering with Godot 4 and stoked to delve into the world of 3D game development, but you’ve encountered a curious class named GLTFDocumentExtension. Whether you’re a seasoned developer or just starting out, the prospect of expanding the already mighty capabilities of a game engine can be both thrilling and intimidating. Fear not! We’re here to guide you through the GLTFDocumentExtension class, illuminating its purpose and demonstrating just how powerful it can be in your development arsenal.

What is the GLTFDocumentExtension Class?

The GLTFDocumentExtension class is a resource in Godot 4 that offers developers the opportunity to extend the functionality specifically for GLTF import or export processes. GLTF, short for GL Transmission Format, is a versatile file format designed for efficient delivery and loading of 3D models. It’s akin to having a Swiss Army knife for 3D graphics—you can pack everything you need in one compact, portable format that’s ready for real-time use.

How Does It Benefit Your Godot Projects?

By using the GLTFDocumentExtension, you gain the power to customize the import and export pipeline of GLTF files within Godot. This means having the ability to insert your own logic and tweaks at various stages of the process. For instance, you might want to inject custom nodes, implement non-standard file extensions, or manipulate the JSON output for specialized use cases.

Why Should You Explore GLTFDocumentExtension?

Understanding and leveraging the GLTFDocumentExtension class can significantly boost the interoperability of your Godot engine projects. It grants you the flexibility to work fluidly with various 3D models and assets, tailor the data handling to match your precise needs, and ensure that your game or application stands out with its unique character and functionality. Essentially, it’s about putting you in the driver’s seat of the import/export process, ensuring that your creative vision is captured down to the finest detail.

Whether you’re a beginner looking to learn the ropes of 3D game development or an experienced coder seeking to polish your skills, this exploration of GLTFDocumentExtension is sure to provide valuable insights and knowledge that will enrich your Godot endeavours.

CTA Small Image

Extending GLTF Import with Custom Properties

To begin extending the GLTF import process, we can start by adding custom properties to our nodes. Here’s how you might create a simple extension to add a “difficulty” property to each imported node:

class CustomGLTFImportExtension extends GLTFDocumentExtension:

    func import_animation_track(track: AnimationTrackType, animation: Animation, node: Object, property_path: NodePath, track_data: Dictionary) -> bool:
        if "difficulty" in track_data:
            node.set_meta("difficulty", track_data["difficulty"])
            return true
        return false

In this snippet, we check if the imported track data contains a “difficulty” field and, if so, we store it as metadata on the node. This technique lets us preserve custom properties from our GLTF files in the Godot scene tree.

Modifying Mesh Data During Import

Customizing mesh data during the import process allows you to make adjustments to the vertices, normals, textures, and more. The following example demonstrates how you can scale all mesh instances within the imported scene:

class CustomMeshScaleExtension extends GLTFDocumentExtension:

    func import_mesh(mesh_instance: MeshInstance, mesh_data: Dictionary) -> bool:
        var scale_factor = Vector3(2.0, 2.0, 2.0)  # Scale all axes uniformly
        mesh_instance.scale *= scale_factor
        return true

Here we multiply the current scale of each mesh instance by our desired scale factor, effectively doubling the size of every mesh in the GLTF file upon import.

Injecting Custom Nodes into the Scene Tree

Sometimes you may want to add nodes that are not defined in the GLTF file. Custom nodes can be anything from triggers to waypoints. You can easily add a new Spatial node with a custom script attached to it using the following method:

class CustomNodeInjectorExtension extends GLTFDocumentExtension:

    func import_node(node: Node, node_data: Dictionary) -> bool:
        if == "my_special_node":
            var custom_node =
            return true
        return false

This code checks for a node with a specific name and injects a new spatial node with a preloaded script as a child.

Adjusting Material Properties on the Fly

GLTFDocumentExtension also allows you to change material properties during import. Here’s a way to alter the emissive color of every material to make it brighter:

class CustomMaterialPropertyExtension extends GLTFDocumentExtension:

    func import_material(material: Material, material_data: Dictionary) -> bool:
        var emission_color = Color(1.0, 1.0, 0.5) # A bright yellow emission color
        material.set("emission_color", emission_color)
        material.set("emission_enabled", true)
        return true

By modifying the ’emission_color’ property, we make the materials glow with a specific color, which can be a great way to highlight certain objects or areas in your game.

With these examples, you’ve learned the basics of extending the GLTF import process in Godot 4. We’ve covered adding custom properties, manipulating mesh data, injecting nodes, and modifying materials—all crucial areas which showcase the level of customization you can achieve with GLTFDocumentExtension. Stay tuned for the next part of our tutorial where we will delve into further practical applications and creative possibilities.

Now that we have a good grasp of what the GLTFDocumentExtension class can do, let’s explore some more advanced manipulations that might come in handy for your projects.

When working with 3D models, adjusting animation data can add that extra layer of polish to your characters or objects. For example, let’s look at how you can speed up or slow down all animations in the imported GLTF file:

class CustomAnimationSpeedExtension extends GLTFDocumentExtension:

    func import_animation(animation: Animation, animation_data: Dictionary) -> bool:
        var speed_factor = 0.5  # Slow down to half speed
        return true

The set_speed_scale method changes the playback speed of the animation sequences, which can help synchronize timings or create dramatic slow-motion effects.

Another interesting possibility is adding collision shapes to imported nodes automatically based on their mesh. This can be a huge time saver for setting up physics in your scene:

class CustomCollisionShapeExtension extends GLTFDocumentExtension:

    func import_mesh_instance(mesh_instance: MeshInstance, mesh_data: Dictionary) -> bool:
        var shape =
        var collider =
        return true

This code snippet creates a ConcavePolygonShape based on the faces of the mesh and attaches it to a new StaticBody which is added as a child of the mesh instance, effectively converting your 3D models into ready-to-use physics objects.

You might also encounter times when you need to correct or adjust the materials of specific nodes, such as changing the texture filtering or repeat patterns:

class CustomTextureSettingsExtension extends GLTFDocumentExtension:

    func import_material(material: Material, material_data: Dictionary) -> bool:
        if material is SpatialMaterial:
            var texture = material.get_texture(SpatialMaterial.TEXTURE_ALBEDO)
            if texture:
                texture.flags &= ~Texture.FLAG_REPEAT  # Disable repeating
                texture.flags |= Texture.FLAG_FILTER  # Enable filtering
        return true

Here, we’re accessing the SpatialMaterial‘s albedo texture and modifying its flags to disable texture repeating and enable filtering, which can help with things like avoiding tiling artifacts or ensuring smooth texture transitions.

In addition to modifying existing properties, you can also extend your GLTF assets with custom-made components. For example, attaching a particle system to create an effect like a torch or engine flame is a breeze:

class CustomParticleEffectExtension extends GLTFDocumentExtension:

    func import_node(node: Node, node_data: Dictionary) -> bool:
            var particles =
            return true
        return false

Whenever a node’s name contains “_flame”, this extension will add a new CPUParticles node with specific properties, emulating a flame effect. This approach can dynamically enrich your scenes without manual setup.

These are just a few examples of the myriad ways in which GLTFDocumentExtension can help you customize your game assets during the import phase. Exploring this class is an excellent way to ensure that the assets you import match the technical and artistic requirements of your Godot projects, streamlining your workflow and harnessing the full power of this incredible game engine.

The possibilities with the GLTFDocumentExtension class are virtually endless. So far, we’ve discussed augmenting animations, adding physics bodies, modifying textures, and creating particle effects. Let’s dive even deeper into this well of creativity and discover more ways to customize your GLTF imports to fit your needs perfectly.

Imagine you want to set up a system where imported models with a certain naming convention get a specific script attached to them. This can automate the process of differentiating enemy types, environmental objects, or interactive elements within your game:

class CustomScriptAttachmentExtension extends GLTFDocumentExtension:

    func import_node(node: Node, node_data: Dictionary) -> bool:
        return true

This snippet checks the node’s name and attaches the corresponding script based on its prefix, streamlining the setup for complex scenes with many interactive elements.

Now, let’s talk about lighting. Perhaps you need to calibrate the intensity and color of lights within an imported scene to maintain a consistent atmosphere:

class CustomLightIntensityExtension extends GLTFDocumentExtension:

    func import_light(light: Light, light_data: Dictionary) -> bool: = 2.0  # Increase default intensity
        light.color = Color(0.8, 0.7, 0.6)  # Warm color tone
        return true

In this code, every light’s energy is boosted, and a warm color tone is applied, giving the scene a different mood compared to the default one defined in the GLTF file.

For a project that involves importing a large number of assets, you’ll likely need some organization to keep track of everything. You can use the GLTFDocumentExtension class to automatically add imported nodes into groups:

class CustomNodeGroupingExtension extends GLTFDocumentExtension:

    func import_node(node: Node, node_data: Dictionary) -> bool:
        if "type" in node_data:
        return true

By adding nodes to groups based on their custom “type” property, you can easily manage and reference these nodes later in your game code using Godot’s grouping system.

Optimizing the imported scenes for performance might require reducing the complexity of certain meshes. This can be particularly useful for mobile games or virtual reality applications where performance is crucial:

class CustomMeshOptimizationExtension extends GLTFDocumentExtension:

    func import_mesh(mesh_instance: MeshInstance, mesh_data: Dictionary) -> bool:
        var surface_count = mesh_instance.mesh.get_surface_count()
        for i in range(surface_count):
            var surface = mesh_instance.mesh.surface_get(i)
            if surface.get_vertex_count() > 10000:
                mesh_instance.mesh.surface_set_material(i, preload("res://low_poly_material.tres"))
        return true

This snippet checks the vertex count of each surface in the mesh and applies a lower-poly material if the count exceeds a certain threshold, helping to maintain higher framerates.

If you’re creating a game with different levels or themes, setting up environment maps per scene can be tedious. Automating this during import can save lots of time:

class CustomEnvironmentMapExtension extends GLTFDocumentExtension:

    func import_scene(scene: Scene, scene_data: Dictionary) -> bool:
   = preload("res://desert_environment_map.tres")
   = preload("res://ocean_environment_map.tres")
        return true

The above example loads a different environment map based on the scene’s name suffix, instantly creating the right atmosphere for each level or area in your game.

These are various practical ways to enhance the process of importing GLTF files into Godot using the powerful GLTFDocumentExtension class, from automatic script attachment and lighting adjustments to optimizing performance. Armed with these capabilities, you can tailor your asset pipeline to suit your project’s needs, reducing redundant work, and focusing on the creative aspects of game development.

Whether tweaking imported data to fit your game world or automating mundane tasks, the GLTFDocumentExtension class is an invaluable tool for Godot developers. We at Zenva encourage you to experiment with these examples and explore your own unique extensions to unlock the full potential of your game assets.

Continuing Your Godot Development Journey

If you’ve enjoyed delving into the capabilities of the GLTFDocumentExtension class in Godot 4 and are keen to expand your skill set even further, we’ve got just the resources to help you press forward. Learning and mastering new concepts can seem daunting, but with the right guidance and a structured pathway, you’re bound to succeed.

The Godot Game Development Mini-Degree is an outstanding collection of courses tailor-made to equip you with the knowledge and skills to create cross-platform games. From mastering GDScript to crafting intricate 3D environments and dynamic gameplay experiences, this program is perfect for aspiring developers who have set their sights on becoming proficient in using the Godot engine. And remember, Godot 4’s versatility and user-friendly approach make it an excellent choice for both beginners and seasoned professionals looking to polish their craft.

For those interested in exploring a wider array of topics or seeking to complement their learning experience with additional content, you can browse through our broad collection of Godot courses. Each course is packed with project-based learning that will aid you in building a strong portfolio to showcase your capabilities. At Zenva, we provide accessible, high-quality education to help you go from beginner to professional at your own pace, anytime, anywhere.

So, what’s next? Whether you’re just starting out on your game development journey or looking to add new techniques to your development toolkit, embrace the challenge, and keep learning. There’s always something new to discover with Godot, and we’re excited to see what you’ll create next!


Unlocking the potential of Godot 4 with the GLTFDocumentExtension class is just the beginning of an exhilarating journey into game development. By harnessing this feature, you’ve seen how you can bend the import process to your will, making your workflow more efficient and your games more robust. But remember, this is just one aspect of what you can achieve with the comprehensive tools that Godot offers. With each new skill and technique you master, you’re building a stronger foundation for your development career.

We at Zenva are thrilled to be a part of your educational quest and are always here to support you with our Godot Game Development Mini-Degree. Join us as we continue to explore the vast and vibrant world of game creation—where your curiosity leads to innovation and your passion culminates in the games you’ve always dreamed of making. Happy developing!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.