CompressedTextureLayered in Godot – Complete Guide

Welcome to our tutorial on the CompressedTextureLayered class in Godot 4! If you’re venturing into the world of game creation, or you’re an experienced developer looking to harness the latest features in Godot, you’ve arrived at the right place. Compressed textures are an important aspect of game development that can drastically affect performance, memory usage, and the visual quality of your game. Through this guide, we’ll explore the foundations and applications of the CompressedTextureLayered class in an engaging, understandable way.

What is CompressedTextureLayered?

The CompressedTextureLayered class is a cornerstone in Godot 4 for working with texture arrays that can be compressed to optimize performance. It’s a part of a family that includes CompressedCubemap, CompressedCubemapArray, and CompressedTexture2DArray – all designed to handle different types of texture data efficiently. Compressed textures have the benefit of reducing the memory footprint and potentially increasing the rendering speed.

What is it for?

Textures are a fundamental element in any 3D environment, adding detail and realism to your game objects. However, high-quality textures come with a cost of increased memory usage. CompressedTextureLayered serves the purpose of balancing quality and performance. It allows developers to store texture data in a manner that is more memory-efficient without significant loss of quality.

Why should I learn it?

Understanding how to use CompressedTextureLayered can give you a significant advantage in game development:

– It leads to better game performance, especially on devices with limited resources.
– It helps to maintain a smooth and enjoyable player experience by reducing the chance of lag or stutter caused by large, uncompressed textures.
– Learning to use texture compression effectively is part of becoming a well-rounded game developer. It combines technical skill with artistic considerations, bridging the gap between programming and game art.

Stay with us as we delve into the practical aspects of using the CompressedTextureLayered class with examples that will make you comfortable with this powerful feature in Godot. Whether you’re a beginner or a seasoned pro, you’ll find something valuable in the sections ahead. Let’s get started!

CTA Small Image

Creating a CompressedTextureLayered

To begin working with CompressedTextureLayered in Godot 4, you need to know how to create one. We will look at creating a simple CompressedTexture2DArray as an example. This can be a starting point for your 3D objects or 2D sprites when using texture arrays.

var texture_array =
var image =
# Replace 'res://path_to_your_image.png' with the actual path to your image file
texture_array.create_from_images([image], Image.FORMAT_RGBA8)

Once you have created the CompressedTexture2DArray, you can set it to be used by your materials or shaders as necessary.

Setting Material Textures

Now, let’s see how you can apply the CompressedTextureLayered as a texture in a material. This example will show you how to set a texture to the albedo (color) property of a SpatialMaterial.

var material =
material.albedo_texture = texture_array
# Apply the material to a MeshInstance
$MeshInstance.material_override = material

Make sure that the MeshInstance node is selected and pointing to your 3D model.

Accessing Layers in Shaders

If you’re working with shaders, you’ll also need to know how to access specific layers of a texture array. Here’s how you could access a texture from a CompressedTexture2DArray in a shader:

shader_type spatial;

uniform sampler2DArray my_texture_array;

void fragment() {
    vec4 color = texture(my_texture_array, vec3(UV, 0)); // Access the first layer
    // ... Rest of your shader code

Remember, when accessing texture layers in shaders, you need to use a 3-component vector where the third component represents the layer index within the array.

Managing Compression Formats

Compressing textures is all about finding the right balance between quality and performance. Godot supports different compression formats, and you can choose the one that fits your needs. Here’s how you can set the compression format of your images:

var image =
# Here we use the FORMAT_ETC2_R8G8B8A8V_UNORM compression format as an example

Make sure to experiment with different formats to see what works best for your textures and target platform.

Remember that these are basics, and there’s still a lot to cover when it comes to using compressed textures in your games effectively. In the next parts of this tutorial, we will take a closer look at more advanced usage and tips for optimizing your textures. Stay tuned!Continuing from where we left off, let’s dive deeper into working with CompressedTextureLayered and its variants, exploring more advanced usage and optimization strategies. We’ll also touch on potential pitfalls and how to avoid them.

Loading and Compressing a Texture Array

When dealing with texture arrays, one common task is loading multiple images and compressing them into a single texture array. Here’s how you might go about loading multiple images at once, compressing them, and creating a CompressedTexture2DArray.

var texture_array =
var images = ["res://texture1.png", "res://texture2.png", "res://texture3.png"]

var loaded_images = []
for image_path in images:
    var image =
    image.compress(Image.FORMAT_ETC2_R8G8B8A8_UNORM)  # Compress the image

texture_array.create_from_images(loaded_images, Image.FORMAT_ETC2_R8G8B8A8_UNORM)

This code will loop through each image path, load the image, compress it, and then store it in an array to be used in creating the CompressedTexture2DArray.

Updating Texture Layers Dynamically

There might be cases where you need to update the content of a layer dynamically. Below is an example of how to update the Nth layer of a CompressedTexture2DArray.

var new_image =
# Suppose we want to update the second layer (index 1)
var layer_index = 1
texture_array.set_layer_data(new_image, layer_index)

Keep in mind that frequent updates to texture arrays can be costly, so you should use this sparingly, such as for dynamic content that cannot be precomputed.

Optimizing Compression Formats per Platform

Different platforms may support different compression formats. It is important to select the appropriate format for the target platform. Here’s a snippet on how you might select a compression format based on the platform:

var image =

if OS.get_name() == "Windows":
elif OS.get_name() == "OSX":
elif OS.get_name() == "Android":
# ... And so on for other platforms

Handling Mipmaps

Mipmaps are used to improve performance and reduce aliasing at different distances and scales. Here’s how you can generate mipmaps for a compressed texture array:

# Assuming your compressed texture array is already created as 'texture_array'

This will create the mipmap chain for the texture array, which will be used automatically based on the distance of the object from the camera.

Using with Texture Rects in 2D

CompressedTexture2DArray isn’t just for 3D; it can also be used in 2D. Below is an example of how to use one with a TextureRect node:

# Assuming 'texture_array' is your CompressedTexture2DArray
$TextureRect.texture = texture_array
# Select which layer to display in the TextureRect
$TextureRect.region_rect = Rect2(0, 0, texture_array.get_width(), texture_array.get_height())
$TextureRect.frame = 2  # This would display the third layer in the array

In summary, mastering CompressedTextureLayered and its associated classes allows you to optimize your game assets for various platforms while maintaining visual fidelity. Experiment with different formats and techniques to find the right balance for your game’s requirements. Remember, the more efficient your textures, the smoother the gaming experience for your players.The journey continues with more insights and applications of CompressedTextureLayered in Godot 4. We’ll examine various scenarios and code examples to broaden your understanding and skill set with texture compression.

Advanced Texture Compression

Let’s look into some more advanced features involving texture compression, like handling different texture formats and loading textures in the background.

Loading Textures with Threads:
To avoid stutters or freezes while loading large textures, you can use threads. Here’s how you might load a texture in the background:

var thread =

func _load_texture_in_background(path):
    var image =
    return image

func _thread_start():
    thread.start(self, "_load_texture_in_background", 'res://large_texture.png')

func _thread_done(image, result):
    if image:
        print("Texture loaded and compressed")
        # Further processing with the image

if thread.is_active():
    var result = thread.wait_to_finish()


Supporting Multiple Resolutions:
You might want your game to support multiple resolutions of textures. You can check the screen resolution or user settings and load appropriate textures:

var texture_array_hd =
var texture_array_sd =

func _load_textures_depending_on_resolution():
    var image_hd =
    var image_sd =
    texture_array_hd.create_from_images([image_hd], Image.FORMAT_ETC2_R8G8B8A8_UNORM)
    texture_array_sd.create_from_images([image_sd], Image.FORMAT_ETC2_R8G8B8A8_UNORM)
    if OS.get_screen_size().x > 1920:  # Arbitrary resolution example
        $MeshInstance.material_override.albedo_texture = texture_array_hd
        $MeshInstance.material_override.albedo_texture = texture_array_sd

Texture Compression and GPU Compatibility

One thing to keep in mind is that not all GPUs support all compression formats. It’s important to handle cases where a compression format is not supported by a user’s graphics hardware:

var image =

if image.detect_3d_texture_format(Image.FORMAT_ETC2_R8G8B8A8_UNORM) != Image.FORMAT_UNSUPPORTED:
    print("ETC2 compression format not supported, falling back to uncompressed")

Using Different Asset Paths for Different Platforms:
In some cases, you might want to have different paths for assets depending on the platform, containing textures that are already compressed in the most suitable format:

var texture_path = ""

if OS.get_name() == "Windows":
    texture_path = "res://assets/windows/my_texture_etc2.stex"
elif OS.get_name() == "OSX":
    texture_path = "res://assets/osx/my_texture_s3tc.stex"
elif OS.get_name() == "Android":
    texture_path = "res://assets/android/my_texture_etc.stex"

var texture = ResourceLoader.load(texture_path)
$MeshInstance.material_override.albedo_texture = texture

Inspecting Texture Compression in Editor:
Within the Godot editor, you might want to inspect how a texture’s compression looks. Let’s consider a script that could be attached to an EditorPlugin to quickly compress and preview a texture:

extends EditorPlugin

func _compress_texture_preview(image_path):
    var image =
    if image.load(image_path) == OK:
        # Preview or export the image as needed

These examples showcase how CompressedTextureLayered and related functionalities can be used to effectively manage game assets, ensuring compatibility across different platforms and graphic hardware capabilities, and improving runtime performance. As you work with texture compression in Godot 4, keep in mind the target platform and the balance between visual quality and performance. Happy coding!

Continuing Your Game Development Journey with Godot

Congratulations on taking the time to explore the CompressedTextureLayered class and its practical uses within Godot 4! While we’ve covered substantial ground here, the world of game development is vast and always evolving. To continue expanding your skillset and to dive into new, exciting challenges, we invite you to check out our Godot Game Development Mini-Degree. This comprehensive collection of courses is tailored for those eager to build cross-platform games and deepen their understanding of Godot 4’s capabilities.

We encourage you to keep learning and honing your skills. Whether you’re a beginner or looking to refine your existing knowledge, Zenva offers over 250 courses that cater to a range of expertise. By joining our Godot courses, you’ll gain access to flexible learning options like live coding and quizzes, and you’ll work on projects that could be a spectacular addition to your portfolio. Dive in and let us help you achieve tangible outcomes—be it launching your game or elevating your career in the gaming industry. Keep coding, keep creating, and most importantly, keep enjoying the journey!


As we wrap up our exploration of the CompressedTextureLayered class in Godot 4, it’s clear that mastering texture compression is key to developing visually stunning and performance-optimized games. This understanding not only elevates the quality of your work but also boosts your confidence as a skilled game developer. Always remember that each step forward in learning is a step towards creating the amazing games you envision.

So, what are you waiting for? Unleash your full potential by diving into our comprehensive Godot Game Development Mini-Degree, and let us accompany you on your journey to greatness one course at a time. This is just the beginning—keep exploring, keep experimenting, and elevate your creations beyond the limits of the sky. Happy game developing!

Python Blog Image

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