Cubemap in Godot – Complete Guide

Welcome to the intriguing world of Cubemap in Godot 4, an essential building block for those who are venturing into the realm of 3D game development. Cubemaps are powerful assets that enable developers to create more immersive and visually appealing environments. Whether you’re a novice coder or have experience under your belt, understanding how to harness the capabilities of Cubemap will undoubtedly amplify the quality of your projects. So, get ready to dive into this comprehensive tutorial that will guide you through the fundamentals of Cubemap, as well as provide you with practical examples to solidify your understanding.

What is Cubemap?

A Cubemap is a unique texture type that consists of six square 2D images that represent the faces of a cube. In Godot 4, it is a resource that falls under the class hierarchy of ImageTextureLayered < TextureLayered < Texture. The primary purpose of a Cubemap is to simulate environments as if they are reflected on surfaces within a 3D space.

What is Cubemap Used For?

Cubemaps are primarily used for faking reflections without the computational intensity of real-time reflections. They can be applied to 3D objects to give the illusion that the objects are reflective, emulating materials like metal or water. This technique is a staple in rendering realistic lighting and environments in games.

Why Should I Learn About Cubemaps?

Understanding Cubemaps is essential for any 3D game developer looking to add realism and depth to their games. By learning how to implement and manipulate Cubemaps, you can:

– Create efficient reflections that don’t bog down the game’s performance.
– Enhance the overall aesthetic appeal of your 3D scenes.
– Utilize them in custom shaders to achieve various visual effects.
With this foundational knowledge, you’re well on your way to mastering a key concept that plays a significant role in high-quality 3D rendering. Let’s start exploring how you can leverage Cubemaps in your Godot projects!

CTA Small Image

Creating a Basic Cubemap in Godot 4

Before we dive into the practical examples, make sure you have a 3D scene ready in Godot 4 with a Camera and a Light source. This ensures that the reflections are visible and accurately simulated.

The first step is to create a Cubemap resource. You can do this directly from the Godot Editor.

var cubemap =

Once you have the Cubemap resource, you need to prepare the six images that will be the faces of the Cubemap.

cubemap.create(ImageTextureLayered.ImageType.IMAGE_TYPE_CUBE_MAP, 512)
cubemap.set_layer_data(your_image_surface, 0)
cubemap.set_layer_data(your_image_surface, 1)
cubemap.set_layer_data(your_image_surface, 2)
cubemap.set_layer_data(your_image_surface, 3)
cubemap.set_layer_data(your_image_surface, 4)
cubemap.set_layer_data(your_image_surface, 5)

Replace ‘your_image_surface’ with the actual image resources. The order in which you set them is important: right, left, top, bottom, front, back.

Applying The Cubemap to Materials

After creating your Cubemap, the next step is to apply it to a material that will be used on a 3D object. Let’s assume you have a SpatialMaterial you want to apply reflections to:

var material =
material.flags_use_reflection = true
material.reflection_texture = cubemap

Now, assign this material to a MeshInstance’s material slot:

var mesh_instance =
mesh_instance.mesh = some_mesh
mesh_instance.material_override = material

Replace ‘some_mesh’ with your 3D mesh resource. The Material now uses the Cubemap to simulate reflections on the mesh’s surface.

Updating Cubemap Images At Runtime

Sometimes you may want to update the Cubemap images at runtime, maybe to reflect a change in the environment. Here’s how you could do it:

cubemap.set_layer_data(new_your_image_surface, 0) // Right face
cubemap.set_layer_data(new_your_image_surface, 1) // Left face
// ... update all faces as necessary

Just replace ‘new_your_image_surface’ with the updated image resource for each face. Keep in mind that updating textures at runtime can be performance-intensive, so use this feature sparingly.

Creating Reflections Using a Cubemap

To illustrate reflections using Cubemaps, here’s a quick example where you set up reflections on a simple sphere:

var sphere_mesh_instance =
sphere_mesh_instance.mesh =
sphere_mesh_instance.material_override = material

And make sure the mesh instance is added to the scene:


Remember, ‘material’ is the SpatialMaterial with the Cubemap texture we created earlier. This will simulate reflections on the sphere’s surface, giving it a realistic metallic look.

By following these steps, you can set the groundwork for reflections in your 3D scenes using Cubemaps in Godot 4. In the next part, we’ll delve deeper into more advanced examples and optimizations for our Cubemaps.

Advanced Cubemap Techniques

To push our cubemap skills further, let’s explore some advanced techniques. We can start by optimizing cubemap reflections based on the viewer’s position to achieve a more dynamic effect.

Dynamic Reflection Mapping:

// Assuming 'player' is your player node or camera:
var reflection_probe =
reflection_probe.mode = ReflectionProbe.Mode.MODE_REALTIME
reflection_probe.update_mode = ReflectionProbe.UpdateMode.UPDATE_ONCE

func _process(delta):
    reflection_probe.translation = player.translation

This code snippet creates a ReflectionProbe node that updates its reflections based on the player’s position. By setting the update mode to ‘UPDATE_ONCE’, we’re optimizing performance as it doesn’t continuously update the reflection every frame.

If the environment changes frequently, and you need more accurate reflections, such as in a racing game with dynamic weather, you may want to update more frequently:

reflection_probe.update_mode = ReflectionProbe.UpdateMode.UPDATE_ALWAYS

Environment Mapping: To create a skybox effect, you might want to reflect the environment onto your objects:

var sky_material =
sky_material.panorama = preload("res://path_to_your_hdr_panorama_image.hdr")
get_tree().current_environment.background_sky = sky_material
get_tree().current_environment.background_mode = Environment.BG_SKY

This panorama sky will appear as the environment in reflections across reflective materials in your scene.

Creating a Cubemap from a Scene: You can use a Camera node to render a scene into a cubemap. This way, you won’t need to prepare the six images beforehand:

var cubemap_scene = preload("res://path_to_your_cubemap_scene.tscn").instance()
var camera =
camera.project_settings_override = true
// Configure camera settings here...

Remember, for this technique, you will have to render the six faces of the cubemap yourself, which can be done by rotating the camera and rendering the scene to a texture for each side.

Applying Roughness and Metallic Parameters: To further control the appearance of the reflections:

material.roughness = 0.5 // A value from 0 (smooth) to 1 (rough)
material.metallic = 1.0 // A value from 0 (non-metallic) to 1 (metallic)

Adjusting the roughness and metallic parameters allows you to customize the reflectivity of the material’s surface from rough, diffuse reflections to sharp, mirror-like reflections.

With these advanced techniques, you can create more convincing and adaptable 3D environments in Godot 4. Remember to balance quality with performance, as real-time reflections and dynamic updates can be computationally expensive. Each game and scene will have unique requirements, so tweak these settings to find the sweet spot for your particular project.

We’ve looked at how to create and apply a basic Cubemap and touched upon some advanced techniques. Now let’s delve into more nuanced applications that will give your games an edge in visual appeal.

Using Cubemaps for Skyboxes:

To apply a Cubemap as a skybox, which serves as the backdrop for your entire 3D scene, you have to set it up in the Environmental background settings:

var environment =
var cubemap_sky =
cubemap_sky.panorama = cubemap
environment.background_sky = cubemap_sky
environment.background_mode = Environment.BG_SKY
get_tree().current_environment = environment

This will apply your Cubemap in a way that surrounds the entire scene, providing a static backdrop that looks like it’s far away. This is perfect for space scenes or creating distant mountains around your game’s environment.

Reflection Probes with Cubemaps:

If you want more localized reflections rather than global ones, ReflectionProbe nodes can utilize Cubemaps to reflect the immediately surrounding environment:

var local_reflection_probe =
local_reflection_probe.cull_mask = ... // Set the layers you want the probe to consider
local_reflection_probe.extents = Vector3(10, 10, 10) // Set the size of the probe area
local_reflection_probe.update_mode = ReflectionProbe.UpdateMode.UPDATE_ONCE

This code creates a ReflectionProbe that captures and reflects only what’s within a defined area, allowing you to create reflections that change based on specific locations in your scene.

Lighting from Cubemaps:

You can use Cubemaps to provide light information by using them in an Environment node:

environment.background_sky = cubemap_sky
environment.background_energy = 1.0
environment.ambient_light_energy = 0.5
environment.ambient_light_sky_contrib = 0.5

This code will give the Cubemap a subtle lighting effect, as if the ambient light in the scene is partially coming from the Cubemap’s colors themselves, contributing to ambient occlusion.

Loading Cubemaps From Disk:

If you have a Cubemap saved as a file, you can load it into the game dynamically:

var loaded_cubemap = preload("res://path_to_your_cubemap.tres") as ImageTextureLayered
material.reflection_texture = loaded_cubemap

This method is particularly useful if you have different environments and want to switch between them without having to create new Cubemaps from scratch each time.

Adjusting Reflection Map Size:

With Godot, you can adjust the size of the reflection map to balance its quality against performance:

reflection_probe.max_distance = 50
reflection_probe.resolution = 256

Here, ‘max_distance’ defines how far from the probe the reflections reach. A smaller ‘resolution’ value will result in lower-quality reflections but will improve performance, particularly on lower-end hardware.

Remember that writing high-quality shaders that use Cubemaps can push your game’s visual presentation to new heights. Embedding Cubemaps into your shaders can be a bit more complex, but it offers full control over how these textures influence the final output. Here’s a little taste:

shader_type spatial;
uniform samplerCube my_cubemap;

void fragment() {
    vec3 reflected_dir = reflect(NORMAL, VIEW);
    ALBEDO = texture(my_cubemap, reflected_dir).rgb;

This is a rudimentary shader script where ‘my_cubemap’ is a uniform referring to the Cubemap texture. It reflects the view direction over the normal surface, and the resulting color is read from the Cubemap.

With these additional examples, we’ve covered a range of methods to manipulate and apply Cubemaps to enhance the visual quality of your 3D games in Godot 4. As always, trial and experimentation will be your best guides to mastering these techniques within your own projects.

Your Next Steps in Learning Godot Game Development

Congratulations on diving into the world of Cubemaps in Godot 4! Mastering different aspects of game development is a journey of continuous learning and practicing. To further enhance your skills, we welcome you to explore our Godot Game Development Mini-Degree. This comprehensive program covers key topics to help you develop cross-platform games and is perfect for both beginners and experienced developers looking to refine their skills.

Our Mini-Degree includes a variety of game development aspects such as 2D and 3D asset use, gameplay control flow, combat systems, UI development, and mechanics tailored to multiple game genres. Plus, the project-based curriculum will help you create a stunning portfolio of real Godot projects.

For those seeking a broader range of topics in Godot, we also invite you to browse our extensive collection of Godot courses. Each is thoughtfully designed to cater to your learning needs, from the basics to more sophisticated game development techniques. Keep learning, keep coding, and you’ll soon be on your way from beginner to professional with Zenva!


In the dynamic universe of game development, mastering Cubemaps in Godot 4 can significantly elevate the visual fidelity and atmospheric depth of your projects. Armed with this knowledge, you’re well-positioned to push the boundaries of creativity and craft truly immersive 3D worlds. As you continue your journey, remember that the art of game creation is a blend of technical proficiency and imaginative flair – both of which you’ll continue to nurture with every new project.

Whether you aspire to build your dream game or become a professional game developer, our Godot Game Development Mini-Degree is your companion on this exciting path. We are here to support your growth every step of the way, providing you with the skills, practice, and confidence to succeed. So keep exploring, keep innovating, and let your game development adventure soar to new heights with Zenva.

Python Blog Image

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