ImageFormatLoader in Godot – Complete Guide

Welcome to the exciting world of Godot Engine, where game development is not only powerful but also highly customizable. Godot 4 introduces a multitude of new features and tools, and one of those is the ability to extend support for image formats through the ImageFormatLoader class. Engaging with this class will not only enhance your versatility in handling visual assets but also deepen your understanding of how Godot interfaces with different file types.

What Is ImageFormatLoader?

The ImageFormatLoader class in Godot 4 is a base class used for adding support for additional image formats that aren’t natively supported by the engine. This class allows developers to extend the image handling capabilities of Godot beyond the default formats like PNG, SVG, JPEG, and WebP.

What Is It For?

Godot’s ImageFormatLoader class is designed to facilitate the integration of custom image formats into your projects. By leveraging this class, you can implement loaders for formats unique to specific requirements or optimize how your game’s assets are handled, leading to better overall performance and flexibility.

Why Should I Learn It?

Learning how to use the ImageFormatLoader in Godot 4 can be incredibly beneficial for game developers looking to:

– Customize their development process.
– Support unique image formats needed for their game.
– Optimize asset loading to improve game performance.
– Explore advanced features and extend the engine’s capabilities.

Diving into this topic will not only enrich your skillset but also grant you the power to tailor Godot to fit any project’s specific needs. Let’s embark on this journey through Godot’s image handling capabilities and unlock new opportunities for creative development.

CTA Small Image

Implementing a Custom ImageFormatLoader

Before we dive into the code examples, let’s understand the process. Implementing a Custom ImageFormatLoader involves creating a new class that extends the ImageFormatLoader class and overriding its methods. This will enable Godot to understand how to load and save your custom image format.

Here’s a step-by-step guide and code examples for implementing the primary methods.

Firstly, we’ll start by importing the necessary modules and setting up our custom loader class:

from godot import Image, ImageFormatLoader

class MyCustomImageFormatLoader(ImageFormatLoader):

Next, we’ll override the load_image() method which is responsible for the loading logic of your custom image format.

class MyCustomImageFormatLoader(ImageFormatLoader):
    def load_image(self, path, original_path):
        # Custom logic for opening the file and loading the image

Similarly, we’ll override the save_image() method to handle the saving of images in our custom format.

class MyCustomImageFormatLoader(ImageFormatLoader):
    # ... previous code ...

    def save_image(self, image, path):
        # Custom logic for saving the image in the custom format

Finally, we need to register our custom ImageFormatLoader with Godot so it can recognize and use it:

def _init():
    # Register the custom image format loader
    image_loader =

Remember to unregister your custom loader on cleanup to avoid memory leaks or other issues:

def _exit_tree():
    # Unregister the custom image format loader

Handling the Image Data

Within your load_image() method, you will want to open your custom image file and read its data. Here’s a simple structure of what it might look like:

def load_image(self, path, original_path):
    with open(path, 'rb') as file:
        # Read the data from the file
        data =
        # Parse the data to create a godot.Image object
        image =
        # Load the data into the image
        # You will need to write the parsing logic based on your image format
        return image

Similarly, when saving an image, you need to convert the Image data to your custom format and write it to a file:

def save_image(self, image, path):
    # Extract the data from your godot.Image object
    # Convert this data to your custom image format
    custom_data = b''  # Placeholder for the converted data
    with open(path, 'wb') as file:

By following these steps and using these code examples as a baseline, we can extend Godot’s functionality to include customized handling for any image format we require. Remember, the parsing and saving logic will greatly depend on the specifics of your custom format, and these are the areas where you’ll need to apply your format-specific algorithms.In the previous sections, we began building our custom ImageFormatLoader by setting up the class structure and sketching out the foundational methods. Now, let’s dive deeper into the loaders’ workings with more code examples and explore some important considerations while implementing custom image formats.

Identifying the Format

Your custom ImageFormatLoader should have a way to recognize its intended format. This usually involves checking the file’s signature or extension. You can override the `recognize()` method to perform this check:

def recognize(self, path):
    return path.ends_with('.myfmt')  # Replace '.myfmt' with your custom format's extension

Custom Loading Logic

When loading an image, you typically need to parse headers and metadata ahead of the actual image data. Here’s how you might start parsing:

def load_image(self, path, original_path):
    with open(path, 'rb') as file:
        # Read and parse the header
        header =  # Replace 'my_header_size' with your header size
        # Additional parsing logic for header
        # ...
        # Then read the image data based on header information
        image_data =
        # ... process and load the image_data into Godot's Image structure

Error Handling

Always include error handling to manage unexpected content or issues during parsing:

def load_image(self, path, original_path):
        with open(path, 'rb') as file:
            # Loading logic here...
    except Exception as e:
        print(f"Failed to load image: {str(e)}")
        return Image()  # Return an empty image or handle the error as needed

Saving Image Data

When saving an image, aside from the image data, you might also want to write some metadata or a custom header for your format:

def save_image(self, image, path):
    header = b'MYFORMAT'  # Example header identifier
    image_data = b''      # Example placeholder where you would put the image data
    with open(path, 'wb') as file:
        file.write(image_data)  # Assuming image_data contains your formatted image bytes

Converting Godot Image Data

Converting Godot Image data into your format requires understanding the Image structure. For example, if your format only supports RGB8:

def save_image(self, image, path): 
    # Convert to RGB8 if it's not in this format
    if image.get_format() != Image.FORMAT_RGB8:
    # Then access raw pixel data
    pixel_data = image.get_data()
    # Implementation of actual conversion logic goes here

Registering the Loader

While in the initial setup you saw a basic registration process, it’s important to ensure that your loader’s instance remains in scope as long as Godot Engine needs it:

loader_instance =

def _ready():

Unregistering the Loader

Corresponding to the above, don’t forget to unregister the loader when it’s no longer needed:

def _exit_tree():

Aligning the ImageFormatLoader to your custom format demands careful attention to the file structure and bit-level manipulation of data. It’s an advanced topic, but your efforts enable great flexibility and potentially new performance optimizations for your Godot projects. Remember, understanding your format and planning error-handling are just as crucial as the actual data manipulation. Happy coding!When undertaking development with custom image formats, there are a few more considerations to keep in mind. These include managing the image resource lifecycle, integrating with the Godot editor, and ensuring your resource is handled efficiently. Let’s explore these aspects with code examples.

Handling the Resource Lifecycle

In Godot, resources have a lifecycle that includes creation, usage, and deletion. Here’s how you might handle creating a new image resource with your custom loader:

def load_image(self, path, original_path):
    # Assume parse_custom_image_format is a function to parse your custom image data
    image_data = parse_custom_image_format(path)  
    image =
    return image

Integration with Godot Editor

To integrate custom loaders with the Godot editor, you can create an editor plugin that registers your loader when the editor starts. In the plugin’s `_enter_tree` method, you register the loader, and in the `_exit_tree` method, you unregister it:

class CustomImageFormatLoaderPlugin(EditorPlugin):
    def _enter_tree(self):
    def _exit_tree(self):

Efficient Resource Management

Efficient resource management is essential, especially when dealing with large images or multiple files. Here’s an example of how to use a buffer to read in chunks if the images are large:

def load_image_from_large_file(path):
    image =
    buffer_size = 1024 * 1024 # 1 MB chunks
    with open(path, 'rb') as file:
        while True:
            chunk =
            if not chunk:
            # Process the chunk
            # ...
    return image

Adding Image Metadata

Occasionally, you might want to include additional metadata with your images. In such cases, you can manipulate custom properties of the Godot Image object:

image.metadata['author'] = "Your Name"
image.metadata['license'] = "Custom License Information"

For our custom save routine, we may want to include this metadata in the saved file:

def save_image_with_metadata(self, image, path):
    with open(path, 'wb') as file:
        # Assuming `image_metadata_to_bytes` converts metadata dictionary to bytes
        metadata_bytes = image_metadata_to_bytes(image.metadata)
        # Write the actual image data

Creating and Manipulating Image Mipmaps

Mipmaps are an important consideration for game textures. When creating an image manually, you might need to create mipmaps as well:

image.create(width, height, False, Image.FORMAT_RGBA8)
image.generate_mipmaps()  # generates mipmaps for the image

When saving an image, you’ll want to consider whether to preserve the mipmaps. Here’s how you might iterate over them:

if image.has_mipmaps():
    mipmap_count = image.get_mipmap_count()
    for i in range(mipmap_count):
        mipmap_data = image.get_mipmap_data(i)
        # Process and save each mipmap level

These snippets offer a glimpse into the myriad of functionalities and considerations when working with custom ImageFormatLoaders in Godot 4. From efficient file handling to integrating with the editor, these strategies will help ensure your custom formats are seamlessly incorporated into your Godot projects.

Continue Your Game Development Journey

Embarking on the journey of extending Godot 4’s image handling through the ImageFormatLoader is just the beginning—there are endless possibilities to what you can create and learn in the realm of game development. To continue building your expertise and to explore the wealth of features Godot 4 offers, we at Zenva encourage you to delve into our Godot Game Development Mini-Degree. This comprehensive series of courses will walk you through the basics of the Godot engine and guide you towards mastering advanced game development concepts.

Whether you’re a beginner looking to learn the fundamentals or a seasoned developer seeking to polish your skills with the latest Godot updates, our curriculum offers a flexible, self-paced learning path to fit your schedule and learning style. Our thorough collection of Godot tutorials is waiting for you, featuring topics from 2D and 3D game creation, to GDScript, to complex game mechanics. And for those eager to expand their horizons even further, check out our full range of Godot courses.

Continue your learning journey with Zenva; leverage our treasure trove of resources to turn your creative visions into reality and become a confident, skilled game developer with a portfolio to prove it. Your next game development adventure awaits!


The road to mastering game development is both thrilling and rewarding. With Godot 4 and the power of custom ImageFormatLoaders, your toolkit for creating diverse and vibrant games expands significantly. Remember, each new topic you learn not only enhances your development process but also brings your unique game ideas that much closer to fruition. Don’t stop here; let this be the spark that ignites your passion for learning and creating within the Godot universe.

We at Zenva are excited to be part of your journey and are always here to help guide you through every challenge and triumph. Dive into our Godot Game Development Mini-Degree and take your skills to new heights. Whether it’s your first time scripting or you’re already dreaming in GDScript, Zenva’s courses are the stepping stones to your success in game development. The path to becoming a game creation pro starts here, and we can’t wait to see what worlds you’ll build next!

Python Blog Image

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