CubemapArray in Godot – Complete Guide

Welcome to our comprehensive tutorial on the CubemapArray class in Godot 4, a powerful yet often overlooked feature in game development. If you’re striving to create dynamic and immersive environments, understanding CubemapArrays is a game-changer. This tutorial is constructed with the mindset of unlocking new graphical possibilities for developers of all skill levels. So, whether you’re just starting your Godot journey or looking to elevate your game’s visuals further, this guide will help you harness the potent utility of CubemapArrays.

What is CubemapArray?
CubemapArray, a unique resource in Godot 4, opens the door to advanced texturing techniques. It inherits from ImageTextureLayered, meaning it’s structured to handle multiple layers of textures, specifically cubemaps.

What is it for?

Each CubemapArray consists of an array of Cubemaps, which, in essence, are collections of six textures that map to the faces of a cube. This special array is utilized to efficiently store and render environments in your games, particularly skies and reflection maps, by aggregating several Cubemaps into a single accessible resource.

Why should I learn it?

There’s a myriad of reasons to dive into CubemapArrays:
– They streamline the process of applying multiple environmental textures.
– Shader programming is simplified with a singular reference to multiple Cubemaps.
– They enable a more memory-friendly approach compared to individual Cubemaps.
Understanding CubemapArrays isn’t just about technical skill; it’s about crafting worlds that draw players in with realism and depth. With this knowledge, you’ll take a significant step forward in the art of game design.

CTA Small Image

Creating a CubemapArray in Godot 4

Let us begin by creating a new CubemapArray in Godot 4. We’ll first instantiate it programmatically and then assign cubemaps to it.

var cubemap_array =

# To create a CubemapArray with specific dimensions
cubemap_array.create(1024, 1024, Image.FORMAT_RGBA8)

# To set the number of layers (number of cubemaps in the array)
cubemap_array.layer_count = 6

This sets up a blank slate. Next, we’ll populate our CubemapArray with actual images.

Loading Images into the CubemapArray

For each layer of the CubemapArray, we need to load six images corresponding to the sides of a cube. Below is how you would load images into the first layer.

# Assume 'side_images' holds paths to the six image files
var side_images = [

# Load images into the first layer of the cubemap array
for i in range(6):
    var img =
    cubemap_array.set_layer_data(img, 0, i)

If you have multiple cubemaps to add to the array, you would repeat the process for each layer, changing the layer index each time.

Working with Multiple Cubemaps

If your game includes various environments, you may want to work with multiple cubemaps within the same array. The following snippets show how to add a second cubemap.

# Imagine we have another set of side images for a different environment
var second_set_of_images = [ ... ]

# Load images into the second layer of the cubemap array
for i in range(6):
    var img =
    cubemap_array.set_layer_data(img, 1, i)

This versatility is a powerful tool; by utilizing multiple cubemaps, you can dynamically change the environment’s appearance in your game.

Applying the CubemapArray to Materials

Once you’ve set up your CubemapArray, the next step is to apply it to a material. This could be for a skybox or a reflective surface.

# Assuming you have a material that makes use of environmental textures
var material =

# Assign the CubemapArray to the material
material.set_texture(SpatialMaterial.TEXTURE_REFLECTION, cubemap_array)

Assigning CubemapArrays correctly is vital for various materials, as it can significantly affect the visual fidelity and the performance of your game.Utilizing CubemapArrays in Godot is not limited to just static reflections; they can also be dynamic and respond to in-game changes. Let’s explore more examples that showcase the flexibility of CubemapArray when integrated into your projects.

Updating CubemapArray at Runtime

Sometimes your game might require changing environmental reflections on the fly, perhaps to represent different times of day or weather conditions. Here’s how to update a specific cubemap within the array during runtime.

# Assume 'new_images' contains paths to six images for a new environment
var new_images = [ ... ]

# We want to update the second cubemap (index 1)
for i in range(6):
    var img =
    cubemap_array.set_layer_data(img, 1, i)

By changing the cubemap data, your environment will reflect the updates without needing to reload or recreate the entire array.

Accessing CubemapArray within Shaders

For more complex visual effects, you might want to access the CubemapArray directly in a shader. Below is an example of how you can reference a specific cubemap layer in Godot’s shader language.

// Assuming 'cubemap_array' has been set as a uniform named 'u_cubemaps'
shader_type spatial;

uniform sampler2DArray u_cubemaps;

void fragment() {
    // Access the texture at layer index 0, and the desired texture coordinates
    vec4 cubemap_color = texture(u_cubemaps, vec3(UV, 0.0));

This shader snippet retrieves the color from the first cubemap layer using the texture coordinates provided by `UV`.

Blending Between Cubemaps

For a smoother transition between environments, you can blend between different layers of your CubemapArray. This can create an effect of time passing or weather transitioning.

// Blending between the first two cubemaps (index 0 and 1)
shader_type spatial;

uniform sampler2DArray u_cubemaps;
uniform float blend_factor; // Ranges from 0.0 to 1.0

void fragment() {
    vec4 cubemap_color1 = texture(u_cubemaps, vec3(UV, 0.0));
    vec4 cubemap_color2 = texture(u_cubemaps, vec3(UV, 1.0));
    vec4 final_color = mix(cubemap_color1, cubemap_color2, blend_factor);

Adjusting the `blend_factor` uniform smoothly combines the colors from two different cubemaps.

Interacting with 3D Objects

CubemapArrays can also be used to implement reflection and refraction effects on 3D objects’ surfaces, providing a more realistic interaction with the environment.

// Apply to a reflective object's material
shader_type spatial;

uniform sampler2DArray u_cubemaps;

void fragment() {
    // Calculate reflection vector
    vec3 reflected_dir = reflect(NORMAL, VIEW);
    reflected_dir = normalize(reflected_dir);
    // Sample the cubemap based on the reflected direction
    vec4 reflected_color = texture(u_cubemaps, vec3(reflected_dir.xy * 0.5 + 0.5, 0.0));
    ALBEDO = reflected_color.rgb;

In this example, we calculate the reflection vector and then sample the cubemap to get the reflected color, making the object appear as if it’s reflecting the environment.

Optimizing Performance with CubemapArray

It’s critical to remember that while CubemapArrays are powerful, they must be used judiciously to maintain game performance. Here’s a snippet to illustrate how you might selectively update a cubemap to optimize rendering:

// Update a cubemap only if certain conditions are met
if (environment_has_changed) {
    // Assuming an update function exists that updates your cubemap textures
    update_cubemap_array(cubemap_array, environment_images, layer_index);

This approach ensures that CubemapArrays are updated only when needed, preventing unnecessary computation and helping maintain a smooth frame rate.

By following these examples, you’ll be well-equipped to integrate CubemapArrays into your Godot projects, achieving visually compelling results that don’t compromise performance. Mastery of CubemapArrays is a testament to your commitment to quality and efficiency in game development. Remember, practice is key to fully understanding and making the most of these examples. Happy coding!As a developer, one may not only want to handle static scenes but also dynamic ones where objects or environments change in real-time. Cubemap arrays can adapt to various dynamic scenarios.

Using CubemapArray for Dynamic Reflections

One exciting feature of CubemapArrays is the ability to update them in real-time to reflect dynamic changes. For example, if a moving object should cast reflections, or if lighting conditions change, you can redistribute those changes across the pertaining cubemap layers.

// Pseudo-code for updating CubemapArray with a new reflection dynamically
func update_dynamic_reflection(env_images: Array, cubemap_layer: int):
    for i in range(6):
        var img =
        cubemap_array.set_layer_data(img, cubemap_layer, i)
    # Here, you might grab the images from a camera capturing the scene or similar

By calling `update_dynamic_reflection()`, one would be able to change reflections on an object based on its immediate surroundings.

Generating a CubemapArray from a Capture

When dealing with highly dynamic scenes, you might also want to generate a cubemap in real-time. Utilizing Godot’s `Viewport` nodes, one can render the scene from multiple angles and gather the textures needed to create a complete cubemap.

# Capturing the cubemap from the perspective of a particular object
func capture_cubemap(viewports: Array, cubemap_layer: int):
    var images = []
    for viewport in viewports:
        var img = viewport.get_texture().get_data()
    # Update the CubemapArray with the captured images
    for i in range(6):
        cubemap_array.set_layer_data(images[i], cubemap_layer, i)

For optimized performance, remember that these captures should be used sparingly, such as when a significant change occurs in the scene.

Animating Transitions Between Cubemap Layers

For a game where environmental conditions change over time, like day to night cycles, we can animate the blend between different cubemap layers to simulate the transition.

# Pseudo-code for blending between two cubemap layers based on in-game time
var blend_time = 10.0 # in seconds
var current_blend_factor = 0.0

func _process(delta):
    current_blend_factor = min(current_blend_factor + (delta / blend_time), 1.0)
    material.set_shader_param('blend_factor', current_blend_factor)

This code makes the material progressively blend from one cubemap to another, based on the time variable.

Modifying CubemapArray Environment Based on Player Position

Another dynamic aspect might be changing the environmental reflection based on the player’s location in the world.

# Pseudo-code for changing cubemap layers based on player's zone
func update_environment_cubemap(player_zone):
    match player_zone:
            push_error("Undefined player zone encountered")

func apply_cubemap_layer(layer_index):
    material.set_shader_param('cubemap_layer', layer_index)

By changing the shader parameter to the corresponding layer index, you can instantly alter the surrounding cubemap to match the player’s current zone.

Reflecting Only Certain Objects onto a CubemapArray

Sometimes, you might want to reflect specific objects – not everything in the scene – into the environment. You will have to render these objects onto a separate viewport and then generate the cubemap.

# Pseudo-code for reflecting specific objects
var objects_to_reflect = [obj1, obj2, obj3]
var reflection_viewports = [viewport1, viewport2, viewport3, ..., viewport6]

func capture_selected_reflection(cubemap_layer: int):
    for i in range(6):
        reflection_viewports[i].render_target_update_mode = Viewport.UPDATE_ALWAYS
        for obj in objects_to_reflect:
            obj.visible = true
        var img = reflection_viewports[i].get_texture().get_data()
        cubemap_array.set_layer_data(img, cubemap_layer, i)
        for obj in objects_to_reflect:
            obj.visible = false

This method toggles visibility selectively and captures the reflections from the viewports set up around the object.


CubemapArrays are remarkably versatile, perfect for dynamic reflection and rich environmental effects. They can level up the immersion factor, adding depth to your game that resonates with players. Integrating these concepts and code snippets can enhance visual experiences, bringing your Godot game environments to life. Our goal at Zenva is to arm you with the knowledge that translates into beautiful, efficient, and engaging gaming experiences. Keep experimenting, keep learning, and keep pushing the boundaries of what you can create.

Where to Go Next with Your Godot Education

Your journey into the world of Godot does not have to end here; it’s just beginning! If this tutorial on CubemapArrays in Godot 4 has sparked your interest and you’re hungry for more, there’s a path laid out for you to become proficient in game development with Godot. A perfect next step is exploring our Godot Game Development Mini-Degree. This comprehensive collection of courses is designed to elevate your skills, whether you’re a beginner or someone with foundational knowledge looking to expand your horizons.

Our Godot courses delve into a multitude of topics within the Godot 4 engine, including 2D and 3D game development, GDScript, and fundamental gameplay mechanics. By engaging with the mini-degree, you’ll work your way through different game types and mechanics, building a robust portfolio of projects along the way. Moreover, for a broader exploration of what we have to offer, check out our full range of Godot courses. These resources are tailor-made for aspiring game devs eager to turn their passion into a profession.

Taking the leap with our courses, you’ll not only sharpen your existing skills but also uncover new ones, all while being supported by high-quality content crafted by experienced instructors. So, keep coding, keep creating, and let Zenva be the launchpad for your game development dreams!


Embarking on the journey of mastering CubemapArrays in Godot 4 is a step into the boundless realm of game development. It’s a commitment to drawing every player into the worlds you craft, with skies that stretch infinitely and reflections that captivate. Remember, what you’ve learned today is more than just a feature of a game engine; it’s a brushstroke in your growing canvas as a game creator.

We at Zenva are excited to journey alongside you as you continue to build, refine, and innovate. Let the knowledge from our Godot Game Development Mini-Degree be your guide, your source of inspiration, and your educational partner. From our coding dojo to your game dev studio, every lesson you learn is a pixel in the grand picture of your game development dreams. Keep pushing forward, keep learning—and let the worlds you imagine today be the games we play tomorrow.

Python Blog Image

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