VoxelGI in Godot – Complete Guide

Diving into the world of game development can sometimes feel overwhelming with the myriad of tools and terms to learn. But among these, some truly stand out due to their impact on the visual fidelity of games. In this tutorial, we’ll explore the VoxelGI class in Godot 4, a powerful tool designed to give your scenes high-quality, real-time indirect lighting, and reflections. Get ready to illuminate your worlds and understand how to use VoxelGI to its full potential!

What is VoxelGI?

VoxelGI (Voxel Global Illumination) represents Godot’s cutting-edge solution for simulating complex indirect lighting effects in real time. It’s an advanced feature that allows Light3D nodes and static geometry to precompute lighting interactions, which then applies to dynamic objects in your scene.

What is VoxelGI for?

This sophisticated system is used to enhance the visual realism of a game by accounting for the subtle ways light bounces off objects, which is crucial for creating immersive and dynamic environments. It takes the visual appearance of areas within your game to the next level with realistic soft shadows, color bleeding, and ambient occlusion effects.

Why should I learn it?

Learning to implement VoxelGI in your game projects paves the way for creating more atmospheric and engaging experiences. It’s not only about making games look pretty, but also about harnessing the power of light to guide players, convey moods, and breathe life into your virtual worlds. While VoxelGI can be performance-intensive, understanding its intricacies and learning how to optimize it effectively ensures that you can deliver stunning visuals without compromising performance.

CTA Small Image

Setting Up the Scene

Before diving into coding, ensure your Godot 4 environment is properly set up, and you’ve added all necessary nodes to your scene. You’ll need a mesh with a material that uses Global Illumination to observe the effects of VoxelGI. Start with a simple cube:

var cube = MeshInstance.new()
cube.mesh = CubeMesh.new()
cube.material_override = SpatialMaterial.new()
cube.material_override.feature_mask=128 # Enable Global Illumination

After you’ve added the mesh instance, you can instantiate the VoxelGI node. Do this in your main scene script:

var voxel_gi = VoxelGI.new()

Set up the basic VoxelGI properties to illuminate your scene. This should be done in the same script, just below where you’ve instantiated it:

voxel_gi.bounds = AABB(Vector3(-10, -1, -10), Vector3(20, 20, 20))
voxel_gi.voxel_scale = 0.25
voxel_gi.extents = Vector3(20, 20, 20)

This configures the VoxelGI’s bounds, voxel granularity and the overall size of the area it affects.

Configuring the Material for Global Illumination

Now, let’s focus on the materials within your scene, as they need to interact correctly with VoxelGI. Below, we configure the material of our cube to interact with global illumination:

cube.material_override.gi_mode = SpatialMaterial.GI_MODE_BAKED

The “GI_MODE_BAKED” setting is pivotal as it indicates that the object’s material is intended to interact with indirect lighting.

Adding Light to the Scene

Your scene will need light sources for VoxelGI to process. Let’s set up a simple DirectionalLight:

var light = DirectionalLight.new()
light.direction = Vector3(-1, -1, -1)

Create this light node and position it to ensure that your cube is well-lit.
Next, adjust the light’s parameters to work with VoxelGI:

light.light_bake_mode = Light3D.BAKE_STATIC
light.light_energy = 1.0

The “BAKE_STATIC” mode signifies that the light’s interactions are precomputed in scenes that involve baked GI solutions.

Running the Scene

At this stage, our setup should be ready to render with VoxelGI. When you run your scene, you should notice an immediate difference in the quality of the indirect lighting.

Please note that up to this point, we have assumed that the scripting is done within the Godot editor, and that you have enabled the “Gdscript” scripting language which comes standard in Godot 4. If you run into any trouble, check your scene hierarchy and ensure all nodes are correctly named and referenced.

In the next section, we will look into fine-tuning the VoxelGI parameters and learning how to optimize your setup for the best performance and visual quality. Stay tuned as we continue to dive deeper into real-time global illumination with Godot 4!Fantastic, now that our scene is running with basic VoxelGI, it’s time to fine-tune our setup. This section will guide you through optimizing and adjusting parameters to achieve the best balance between performance and visual fidelity.

Fine-Tuning VoxelGI Parameters

To start, we’ll look at how to adjust the quality and performance of VoxelGI. The voxel scale and extents dictate how much detail the VoxelGI can capture and how large an area it affects. For larger scenes, a larger voxel scale may be needed:

voxel_gi.voxel_scale = 0.5 # Adjusts the granularity of the voxel grid
voxel_gi.extents = Vector3(40, 40, 40) # Influences the area VoxelGI affects

However, remember that increasing the voxel scale can lead to a loss in detail of the indirect lighting, and increasing the extents will require more memory and processing power.

The subdivision parameter directly impacts the resolution of the gi probe data:

voxel_gi.subdiv = VoxelGI.SUBDIV_128 # The options are 64, 128, 256, and 512

Choosing a higher subdivision will increase the quality but also the performance cost. Use higher values only if necessary for your scene’s complexity.

For fine control over the indirect lighting intensity and the color of the bounced light, you can manipulate these properties:

voxel_gi.bias = 0.03 # Helps with avoiding light leaking
voxel_gi.normal_bias = 1.5 # Adjust if you notice artifacts in lighting
voxel_gi.indirect_energy = 1.0 # Governs the brightness of indirect light
voxel_gi.propagation = 0.7 # Controls how far the light bounces carry the color

Adjust the ‘indirect_energy’ and ‘propagation’ if the indirect light is too dim or overly saturated. In many cases, subtle adjustments can create a more natural look.

Dynamic Objects and VoxelGI

If you have dynamic objects in your scene that should receive indirect lighting, you need to ensure their materials are set up correctly:

# Assuming 'dynamicCube' is a MeshInstance
dynamicCube.material_override.gi_mode = SpatialMaterial.GI_MODE_DYNAMIC

Dynamic objects use a different mode to interact with VoxelGI so that they can be included in the real-time GI calculations efficiently.

Optimizing VoxelGI

Optimizing VoxelGI is critical, as it’s a resource-intensive process. To reduce the computational load, consider limiting the number of dynamic objects influenced by VoxelGI and optimizing their materials:

voxel_gi.use_dynamic_gi = false # If you don't have dynamic objects

When you don’t have any dynamic objects in your scene, disabling the dynamic GI can save resources.

Furthermore, pay attention to your game’s target platform. If you’re developing for less powerful hardware, you might want to reduce VoxelGI’s complexity:

voxel_gi.subdiv = VoxelGI.SUBDIV_64 # Lower subdivision for performance
voxel_gi.high_quality = false # By default, it's false. Set to true for better quality on powerful hardware

Debugging VoxelGI

For troubleshooting and optimization, Godot provides options to visualize how VoxelGI affects your scene:

voxel_gi.debug_mode = VoxelGI.DEBUG_MODE_ALBEDO # Visualizes voxel albedo, options include NORMAL, LIGHT, etc.

The debug mode has several options, each visualizing a different aspect of the VoxelGI computation, which can be immensely helpful when diagnosing issues.

Another useful trick is to activate the “Read GI Probe” option in the Material:

cube.material_override.proximity_fade = true # Helps materials read GI Probe data accurately for objects close to VoxelGI bounds.

This can help materials to more accurately read the GI probe data, especially for objects close to the bounds of the VoxelGI.

Through these insights and techniques, you can use VoxelGI to illuminate your Godot 4 games with incredible realism. Remember that refining the visual outcome while maintaining performance requires practice and experimentation. As with any advanced feature, finding the right balance for your game is key. Happy coding, and may your games shine bright with real-time global illumination!Great! Expanding further into our VoxelGI adventure, let’s explore additional layers of control and sophistication that can be introduced to further enhance the visual quality and performance of your Godot scenes.

One important aspect is ensuring our light sources are optimized to work with VoxelGI. Lights have a property called `bake_mode` that should be set correctly:

light.bake_mode = Light3D.BAKE_INDIRECT # For real-time changes in lighting

Keep in mind that `BAKE_INDIRECT` allows for dynamic objects to be impacted by the light changes. This setting helps maintain performance while still benefiting from VoxelGI’s indirect lighting.

Moreover, the `energy` setting of a light contributes greatly to how VoxelGI behaves, as it determines the light’s intensity. This can be tuned in a way that it matches your scene’s aesthetic:

light.light_energy = 1.5 # Increase this value for stronger light intensity

Remember that the energy of your light sources will affect the VoxelGI pass, so find a balance that provides a realistic look without overwhelming the scene with too much brightness.

Let’s not forget about shadows! Shadows play a crucial part in realism and can be enhanced through VoxelGI. Adjusting the `light`’s shadow properties is key:

light.shadow_enabled = true
light.shadow_normal_bias = 1.1
light.shadow_bias = 0.05

Enabling shadows and tweaking the bias settings can help avoid artefacts, such as shadow acne or peter-panning, which can break the visual immersion.

Now, one interesting feature of VoxelGI is its ability to reflect environmental lighting onto your objects. For this, ensure your material can reflect light properly:

cube.material_override.roughness = 0.1 # A lower value will increase reflectivity
cube.material_override.metallic = 0.0 # Adjust metallic nature of the surface reflects light

By playing with roughness and metallic properties, you influence how light reflects off surfaces, giving you fine control over the realism of different materials.

Additionally, the `diffuse_mode` property can significantly impact the look of materials under VoxelGI:

cube.material_override.diffuse_mode = SpatialMaterial.DIFFUSE_OREN_NAYAR

Different `diffuse_mode` settings can simulate how light spreads across the surface, from Lambertian, which offers a matte finish, to Oren-Nayar, which better simulates rough surfaces.

Next, for scenes that make use of volumetric effects, such as fog or smoke, you’ll want to ensure these effects work in tandem with VoxelGI:

voxel_gi.use_volumetrics = true
voxel_gi.volumetric_fog_energy = 1.0
voxel_gi.volumetric_fog_albedo = Color(1, 1, 1, 1)
voxel_gi.volumetric_fog_emission = Color(1, 1, 1, 0)

Turning on `use_volumetrics` will take the VoxelGI computations into account when rendering volumetric effects, thus elevating the environmental ambience of your scenes.

Finally, it’s important to review your VoxelGI settings in relation to performance. Sometimes, making slight adjustments to parameters such as `bias` and `normal_bias` can yield significant results:

voxel_gi.bias = 0.02 # Slight tweak in bias can reduce artefacts
voxel_gi.normal_bias = 1.2 # Optimal normal bias value can prevent self-shadowing without losing detail

Playing around with these values may prevent common problems like light leaking and ensure a more robust global illumination solution.

Utilizing these techniques, you can push Godot’s VoxelGI to its limits, giving you professional level lighting in your games. Nevertheless, it’s suggested that you profile your game regularly, as you adjust these settings. Too high values can tax the rendering engine more than necessary, so testing changes in context while keeping an eye on performance is crucial.

Through strategic adjustment of VoxelGI parameters and light material properties, you are one step closer to achieving breathtakingly lit scenes that bring your game world to life. Keep exploring, refining, and most importantly, have fun sculpting your world with light!

Continuing Your Game Development Journey

Mastering VoxelGI in Godot 4 is just one step in the vast and exciting journey of game development. If you’ve enjoyed what you’ve learned and are eager to continue building your skills, we at Zenva would love to guide you further. Our Godot Game Development Mini-Degree is an extensive collection of courses designed to help you dive deeper into the world of Godot 4 and create compelling cross-platform games. Whether you’re just starting out or looking to sharpen your developer toolkit, these courses cover a wide range of topics that can lift your game development prowess to new heights.

Yet, the journey doesn’t stop there. Our comprehensive suite of Godot courses offer learning opportunities for various game mechanics, programming concepts, and creative explorations that are relevant to both beginners and seasoned game creators. With Zenva, you can flexibly learn at your own pace, practice coding in-browser, and build a strong portfolio to set you on the path to becoming a professional game developer.

As you continue to craft amazing game experiences, remember that the learning path is continuous, and each new skill opens the door to innovative possibilities. We’re here to support your growth every step of the way. Embark on your next chapter with confidence and take your creativity to new heights with Zenva’s educational resources!


In this tutorial, we’ve illuminated the intricacies of VoxelGI, offering a beacon to navigate the exciting possibilities of real-time global illumination in Godot 4. We’ve demystified the concept, highlighted its applications, and provided hands-on strategies for implementation and optimization. This knowledge empowers you to create not just games, but dynamic, living worlds that captivate players with stunningly realistic visuals.

The power to craft awe-inspiring games is at your fingertips, and we at Zenva are thrilled to be part of your creative journey. Elevate your skills, fulfill your game development aspirations, and join a community of passionate developers by exploring our Godot Game Development Mini-Degree. The journey of learning and creating never truly ends—it evolves with every line of code. Let’s continue to turn your vision into reality, one pixel at a time!

Python Blog Image

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