CompressedCubemap in Godot – Complete Guide

Welcome to our tutorial on utilizing the CompressedCubemap class in Godot 4! If you’re venturing into the world of 3D rendering within Godot, understanding cubemaps is an essential skill. This guide aims to demystify CompressedCubemap, uncovering the potential it offers for your game development projects. Whether you’re looking to optimize your 3D environments, bring efficiency in texture memory usage, or just curious about this feature—this article is designed for everyone!

What is CompressedCubemap?

CompressedCubemap is a critical class in Godot 4’s rendering armor. It allows developers to use cubic textures in their projects, which can dramatically enhance the realism of reflective surfaces and the environment. Cubemaps consist of six square textures that represent the views along the axes of a 3D world — think of looking up, down, left, right, forward, and backward from inside a cube.

What is it for?

Cubemaps are typically used for creating skyboxes, where the player is surrounded by distant scenery, or for adding realistic reflections to objects in a 3D space. With CompressedCubemap, these textures can be compressed in various ways to find the perfect balance between visual fidelity, file size, and performance for your specific needs in Godot.

Why Should I Learn It?

A grasp of CompressedCubemap empowers you to:
– Create immersive 3D worlds with the efficient use of resources.
– Optimize your game’s performance by understanding different compression methods.
– Improve loading times and runtime memory usage, which is especially important for large-scale projects or mobile platforms.
Learning how to use CompressedCubemap is an investment in your game’s quality and in your skills as a developer. Let’s embark on this exciting journey into the realm of cubemaps in Godot 4!

CTA Small Image

Creating a Basic Cubemap

To start working with CompressedCubemap in Godot 4, let’s create a basic uncompressed cubemap first. This will serve as the foundation for understanding how to implement compression later on.

var cubemap =
var size = 512 # Define the size for each face of the cubemap
cubemap.create(size, size, false, Image.FORMAT_RGBA8)

In this example, we initialize a new Image object and create a cubemap with a specified size for each face. We are using a simple RGBA8 format, which is not compressed.

Next, let’s populate the faces of the cubemap:

cubemap.set_data_partial(Image.FORMAT_RGB8, ImageLoader.load_image("res://left.png"), Vector2(), cubemap.get_size(), Image.CUBEMAP_LEFT)
cubemap.set_data_partial(Image.FORMAT_RGB8, ImageLoader.load_image("res://right.png"), Vector2(), cubemap.get_size(), Image.CUBEMAP_RIGHT)
# Repeat the above for the remaining faces: FRONT, BACK, TOP, BOTTOM

In the code, we use `set_data_partial` to load each face of the cubemap from an image file.

Compressing the Cubemap

Now that we have a basic cubemap, let’s apply compression. Godot provides various compression formats, such as DXT1, DXT3, DXT5, and more.


In the example above, we use S3TC compression, which is a balance of quality and performance.

It’s crucial to know that your textures need to be in a compatible size for compression, typically a power of 2. Additionally, you can specify the compression mode:

cubemap.compress(Image.COMPRESS_S3TC, Image.COMPRESS_SOURCE_GENERIC, true)

Here we have defined the source as `Image.COMPRESS_SOURCE_GENERIC` and set a flag asking for lossless compression where possible.

Using the Cubemap in a SpatialMaterial

With your cubemap ready and compressed, you can now apply it to a material in your 3D scene.

var material =
material.texture_albedo = cubemap

The above lines show how to create a new SpatialMaterial and set the albedo texture to our compressed cubemap.

Remember, you need to properly configure the material for the effect you are looking for, like reflections:

material.metallic = 1.0 # Full reflection
material.roughness = 0.0 # Completely smooth surface

These properties will give you a mirror-like reflection, using the cubemap for realistic lighting effects on the material’s surface.

Loading and Saving Compressed Cubemaps

Finally, you’ll probably want to save and reuse your compressed cubemaps. Here’s how to save them to a file:


And you can load the cubemap back into your game with the following code:

var cubemap_from_file =

It’s essential to note that the file extension is `.cube`. This ensures that Godot recognizes the file as a cubemap.

Wrapping up part two of our tutorial, we have covered the basics of creating, compressing, utilizing, and persisting cubemaps in Godot 4. Stick with us for the next part of the tutorial, where we will dive deeper into advanced usage and optimization tips for CompressedCubemap!In this third section of our tutorial, we will explore advanced techniques for working with CompressedCubemap in Godot 4. These methods will help you optimize your game’s visuals and performance even further.

When you are working with cubemaps, you might need to update them dynamically. Here’s an example where we change the image data of one face of the cubemap at runtime:

var new_image_for_top = ImageLoader.load_image("res://new_top.png")
cubemap.set_data_partial(new_image_for_top, Vector2(), new_image_for_top.get_size(), Image.CUBEMAP_TOP)

In the code above, we load a new image and use `set_data_partial` to update the top face of the cubemap.

Sometimes, you may only want to compress a certain face of the cubemap instead of the whole set. You can do this as follows:

var right_face_image = ImageLoader.load_image("res://right.png")
cubemap.set_data_partial(right_face_image, Vector2(), right_face_image.get_size(), Image.CUBEMAP_RIGHT)

By individually compressing each face, you can process each texture according to its unique needs which might be different in terms of detail or color variance.

Let’s talk about quality control. It’s important to ensure your compressed cubemap maintains the visual quality you need. Here’s how to check if the compression was successful:

if cubemap.compress(Image.COMPRESS_ETC2, Image.COMPRESS_SOURCE_SRGB, true):
    print("Cubemap compressed successfully!")
    print("Compression failed.")

In the snippet above, we use ETC2 compression and a sRGB source, and we also output a message to the console based on whether or not the compression was successful.

When your cubemap is ready, you may want to use it for environment reflections. Here’s how you could assign it to an Environment node for global reflections:

var environment =
environment.background_mode = Environment.BG_MODE_SKY = cubemap

With this code, we create a new Environment node and set the background mode to use a sky. We then assign our compressed cubemap as the sky, which will be reflected in the scene.

In some cases, you might need to process or modify your cubemap via code. Here’s a way to flip one of the faces horizontally:


This example uses the `flip_x` method to flip the right face of the cubemap. You can perform similar operations for the other faces with `flip_y` or apply other processing methods available in the Image class.

Lastly, if you need to ensure your cubemap is being wrapped properly and avoid seams on the edges, you can enable repeat:

cubemap.repeat_enabled = true

This line of code will make Godot use repeating texture addresses, which can be especially useful for skyboxes and large reflective surfaces where the edges of the cubemap might become visible.

By now, you should have a robust understanding of working with cubemaps in Godot 4. With the compression and optimization techniques outlined above, you’ll be able to create stunning 3D environments with efficient resource usage. Continue experimenting with the various compression formats and methods to find the best fit for your particular game’s style and platform requirements. Keep practicing and exploring all the possibilities that Godot’s powerful engine has to offer!Moving forward in our advanced exploration, let’s delve into the versatility of the CompressedCubemap class with further examples. Whether it’s handling HDR (High Dynamic Range) images, adjusting mipmap settings, setting up for procedural generation, or even sequencing cubemaps for dynamic environments, Godot 4 offers robust support for your creative endeavors.

If you’re working with HDR images for your cubemap, it’s crucial to ensure you maintain the right format to handle the extended range values. Here’s how to create and compress an HDR cubemap:

var hdr_cubemap =
hdr_cubemap.create(size, size, false, Image.FORMAT_RGBE9995)

In the code snippet above, we’re creating a new Image with the `FORMAT_RGBE9995` which is designed for HDR data. Then, we apply `RGTC` compression which is suitable for HDR images.

To control the amount of detail at different distances and optimize performance, you should consider generating mipmaps for your cubemap:


By calling `generate_mipmaps`, you enable the cubemap to use smaller versions of the textures when objects are further away, reducing the rendering load and improving performance.

For those looking to create cubemaps procedurally—say, for a dynamic sky that changes over time—you can update the cubemap dynamically using a shader:

var shader_material =
shader_material.shader = preload("res://cubemap_shader.tres")
shader_material.set_shader_param("sky_color", Color(0.4, 0.5, 0.6))

In the example above, we preload a shader that generates cubemap textures on the fly and pass in a parameter to change its sky color.

Let’s consider a scenario in which the environment in your game changes based on the player’s actions or other events. You would want to sequence through different cubemap textures to reflect this change:

func update_environment(new_env_image_path: String):
    var new_env_cubemap = ImageLoader.load_image(new_env_image_path)
    # Assuming you have an Environment node set up already = new_env_cubemap

This function can be called to load a new image for the environment and apply ETC2 compression to it, maintaining quality while ensuring good performance.

Godot also affords you the flexibility of blending between two cubemaps to achieve transitions such as day-to-night cycles.

Here’s how you might blend two cubemaps over time:

var day_cubemap = preload("res://day.cube")
var night_cubemap = preload("res://night.cube")
var blend_factor = 0.0 # Ranges from 0.0 (day) to 1.0 (night)

# On every frame or timed interval
blend_factor = min(blend_factor + delta * 0.1, 1.0)
environment.background_sky_blend_factor = blend_factor = day_cubemap
environment.sky_custom = night_cubemap

In this example, `blend_factor` is updated over time, and the `background_sky_blend_factor` of the Environment node is used to interpolate between the `day_cubemap` and `night_cubemap`.

Lastly, if you need to alter color values or apply specific effects to your cubemap, Godot’s Image class comes with a variety of manipulation methods:

var colored_cubemap = ImageLoader.load_image("res://cubemap.png")

With the `adjust_color` method, you can easily tweak the contrast, brightness, and saturation of your cubemap, ensuring your 3D environment always looks exactly how you envisioned it.

By implementing these advanced techniques, your proficiency in handling cubemaps within Godot 4 will be significantly enhanced. Embrace these tools, and you’ll be well-equipped to elevate the quality and performance of your 3D worlds in Godot. Keep coding, keep experimenting, and let the power of Godot’s rendering engine shine in your projects!

Continuing Your Godot Journey

Now that you’ve tackled the intricacies of CompressedCubemap in Godot 4, you’re well on your way to creating visually stunning and performance-optimized 3D games. But don’t stop here! This is just the beginning of an exciting and fulfilling adventure in game development with Godot.

To continue building your skills and dive even deeper into Godot’s robust features, our Godot Game Development Mini-Degree is the perfect next step. Tailored for both budding creators and seasoned developers, this comprehensive collection of courses will guide you through building cross-platform games using the powerful, easy-to-learn Godot 4 engine. Gain a solid foundation in everything from 2D and 3D assets to gameplay control flow and beyond, as you work your way up from zero experience to crafting your first game in record time.

Don’t miss out on exploring our broader collection of Godot courses as well, which offer even more opportunities to enhance your expertise. With Zenva, your possibilities are limitless. Embrace the learning, start creating, and watch your game development dreams come to life!


Embarking on the journey of mastering Godot 4 with its CompressedCubemap feature is only the beginning of what you can achieve. By understanding and utilizing these valuable techniques, you set the stage for your 3D games to flourish in both aesthetics and efficiency. Remember, every step forward in your game development skills is a leap towards transforming your innovative ideas into captivating gaming experiences.

Don’t let the momentum stop here! Continue to expand your knowledge and expertise with us at Zenva. Our Godot Game Development Mini-Degree is designed to evolve your abilities, ensuring you’re equipped with the tools and know-how to tackle any challenge in game creation. Join our thriving community of learners, harness the full potential of Godot, and let’s build remarkable games together!

Python Blog Image

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