VoxelGIData in Godot – Complete Guide

Welcome to our fascinating journey into the world of Voxel Global Illumination (GI) in Godot 4, one of the most exciting game engines out there today. Global illumination is a critical element in creating immersive and visually compelling game environments. It simulates how light bounces off surfaces, allowing for realistic indirect lighting and shadows. In this tutorial, we’ll dive deep into the VoxelGIData class within Godot 4, which plays a pivotal role in baking and adjusting voxel-based global illumination for games. Prepare to unlock the potential of dynamic lighting in your game projects!

What is VoxelGIData?

VoxelGIData is a resource class within Godot 4 that contains and manages baked voxel global illumination data, which is crucial for achieving realistic environmental lighting in your scenes. “Voxel” refers to volume pixels, which are tiny cubes that create a grid to simulate 3D space in a computationally efficient way. This data is then utilized by a VoxelGI node to control various properties, like indirect lighting and reflections, to enhance the aesthetics of your game’s environment.

What is it for?

VoxelGIData is specifically designed for handling the intricate details of global illumination within a game scene. The class offers you the flexibility to tweak lighting parameters to your desired effect without the need to re-bake your illumination data constantly. It serves to improve your game’s visual fidelity with accurate and efficient lighting simulations tailored to your scene’s unique requirements.

Why Should I Learn It?

Incorporating global illumination into your game can be a transformative step toward creating lifelike and engaging environments. Learning to work with VoxelGIData is essential because:

– It empowers you to control light interactions dynamically, providing a more immersive experience for players.
– It offers runtime adjustments, giving you creative freedom to fine-tune lighting on the fly, significantly enhancing the development workflow.
– Fundamental knowledge of how lighting works at a technical level can dramatically improve the quality of any game project you undertake.

Understanding VoxelGIData will not only improve your games visually but also give you invaluable insights into the workings of advanced rendering techniques used in modern game development. Let’s step into the world of Godot 4 and learn how to harness the power of VoxelGIData for your own game development adventures!

CTA Small Image

Setting Up the Scene for Voxel GI

Before diving into code examples, we need to ensure that your scene in Godot 4 is set up correctly to make use of VoxelGI. This includes adding a VoxelGI node to your scene and configuring it properly.

# First, add a VoxelGI node to your scene through Godot's editor.

# Once added, configure its size to encompass the area that you want to affect with global illumination.
var voxel_gi = VoxelGI.new()
voxel_gi.bounds = AABB(Vector3(0, 0, 0), Vector3(10, 10, 10)) # adjust this to your needs

# Add the VoxelGI node to your scene as a child of the root node or another appropriate parent node.

Initializing VoxelGIData

Every VoxelGI node requires an instance of VoxelGIData to hold and manage global illumination data.

# Create a new instance of VoxelGIData 
var gi_data = VoxelGIData.new()

# Set the data onto the VoxelGI node
voxel_gi.gi_data = gi_data

Baking Global Illumination Data

To obtain the global illumination effect, we need to bake the data that captures how light interacts with the environment. Let’s see how we can trigger this baking process.

# Ensure your scene is set up with proper lighting and materials

# Then, initiate a bake operation

After the baking process, the VoxelGIData object will contain the baked data, ready to provide global illumination effects in your scene.

Adjusting Voxel GI Properties

You can modify various properties of the VoxelGIData to achieve different lighting effects. Here are some examples of properties you might want to adjust:

# Energy property adjusts the brightness of indirect light.
gi_data.energy = 2.0

# The propagation parameter affects how far indirect light spreads.
gi_data.propagation = 0.7

# The interior flag tells whether the bake is considered to be indoors.
gi_data.interior = true

Adjusting these settings allows you to fine-tune the lighting to your scene’s specific needs and aesthetics.

Saving and Loading VoxelGIData

For efficiency, it’s often a good idea to save baked VoxelGIData for later use or to load it when the game runs, eliminating the need to bake in real-time.

# Save the baked data to a resource file.
var gi_data_file = "res://your_path/voxel_gi_data.res"
ResourceSaver.save(gi_data_file, gi_data)

# Load the baked data from the resource file at runtime.
var loaded_gi_data = load(gi_data_file) as VoxelGIData
voxel_gi.gi_data = loaded_gi_data

This ability to save and load illumination data allows for more optimized game performance and quicker load times.

In the next part, we will continue exploring practical examples of using VoxelGIData in Godot 4, diving even further into more advanced techniques and optimizations. Stay tuned to build upon this foundation and make your game environments truly shine.In this section, we’ll explore some advanced uses of VoxelGIData that can significantly enhance your lighting setup. Keep in mind, the following examples assume you already have a VoxelGI node with a VoxelGIData instance correctly configured.

Improving Performance with VoxelGI Subdivisions

The quality and performance of voxel-based GI depend on the number of subdivisions within the VoxelGI node’s bounds. Adjusting subdivision levels allows you to find a balance between performance and visual fidelity.

# Increase subdivisions for a more detailed, higher quality bake
voxel_gi.subdiv = 128

# Decrease subdivisions for a less detailed but better-performing bake
voxel_gi.subdiv = 64

Dynamically Changing Indirect Lighting

VoxelGIData allows for dynamic changes at runtime. For instance, you can adjust the indirect lighting energy.

# Adjust indirect lighting energy in response to gameplay events
func adjust_light_energy(new_energy):
    gi_data.energy = new_energy
    voxel_gi.bake() # Re-bake to apply changes

This technique can be useful for creating dramatic mood shifts or signaling in-game time changes.

Using Multiple Bakes for Different Environments

Sometimes, you might want to switch between different lighting setups, such as when transitioning between indoor and outdoor environments.

# Load different GI data based on the player's environment
func switch_environment(is_outdoor):
    var gi_data_file = "res://your_path/" + (is_outdoor ? "outdoor" : "indoor") + "_voxel_gi_data.res"
    var loaded_gi_data = load(gi_data_file) as VoxelGIData
    voxel_gi.gi_data = loaded_gi_data

This helps create a more dynamic and responsive lighting system in your game.

Adjusting Color and Brightness Through Code

You can also programmatically alter the voxel GI to reflect various light temperatures and effects.

# Change the GI's color to simulate different times of day or lighting conditions.
gi_data.gi_diffuse_color = Color(1.0, 0.8, 0.6) # Warm light for a sunset
gi_data.gi_specular_color = Color(1.0, 0.9, 0.8) # Slightly brighter specular component

# Modify the bounce light brightness to simulate a night scene
gi_data.gi_diffuse_color = gi_data.gi_diffuse_color.darkened(0.5)
gi_data.gi_specular_color = gi_data.gi_specular_color.darkened(0.5)

Altering Reflection Settings

Reflections add an additional layer of realism to your scenes, and by tweaking the related VoxelGIData properties, you can fine-tune how your scene reflects its environment.

# Adjust to have more pronounced reflections
gi_data.reflection_brightness = 1.5

# Reduce reflection intensity for a subtler effect
gi_data.reflection_brightness = 0.7

Remember that changing these settings might require you to re-bake the VoxelGIData to see the results in your scene.

Creating a Night-to-Day Transition

Combining multiple properties, you can create a smooth transition from night to day lighting.

# Example function that smoothly transitions from night to day parameters
func transition_night_to_day(duration):
    var timer = 0.0
    var start_diffuse = gi_data.gi_diffuse_color
    var end_diffuse = Color(1, 1, 1) # Daylight color
    var start_energy = gi_data.energy
    var end_energy = 2.0 # Brighter energy for daylight

    while timer < duration:
        var progress = timer / duration
        gi_data.gi_diffuse_color = start_diffuse.linear_interpolate(end_diffuse, progress)
        gi_data.energy = lerp(start_energy, end_energy, progress)
        voxel_gi.bake() # Re-bake to apply changes each frame
        timer += get_process_delta_time()
        yield(get_tree(), "idle_frame") # Wait for the next frame

Creating such a transition can add a dynamic element of realism to your game’s environment.

Each of these examples illustrates how flexible the VoxelGIData class is for managing and adjusting global illumination within your Godot 4 projects. Understand that while these modifications can greatly enhance the visual quality of your game, they should also be considered within the context of your game’s performance budget. With careful management and creative use of VoxelGIData, you can create stunning and dynamic lighting for your game worlds.Continuing our exploration of VoxelGIData’s capabilities, we will delve into more nuanced adjustments and techniques that can elevate your Godot game’s lighting to the next level. These examples showcase the power and flexibility of voxel global illumination in achieving unique lighting scenarios.

Optimizing with Voxels Per Subdivision

Adjusting the number of voxels per subdivision can impact both the appearance and performance of your VoxelGI effects.

# Increase the detail of the voxel grid, good for complex scenes
voxel_gi.voxels_per_subdiv = 64

# Decrease detail for improved performance, suitable for simpler scenes
voxel_gi.voxels_per_subdiv = 32

Just like adjusting subdivisions, tweaking voxels per subdivision allows you to make performance-related decisions without sacrificing too much on quality.

Effect of Cones Per Voxel on Reflections

The cones per voxel setting influences the quality of specular reflections created by the VoxelGI. More cones yield higher-quality reflections at the cost of performance.

# For high-quality reflections, especially on shiny surfaces
voxel_gi.cones_per_voxel = 16

# Opt for fewer cones in scenarious where reflection quality is less critical
voxel_gi.cones_per_voxel = 8

Strike the right balance depending on the materials and importance of reflections in your scene.

Implementing Runtime Light Baking

Baking lighting data at runtime can allow for dynamic changes in the game environment; for example, altering structures within the VoxelGI bounds and updating the scene’s lighting to match.

# Check for conditions under which you want to re-bake lighting
func update_lighting_if_needed():
    if conditions_for_lighting_update_met:

Use this sparingly as runtime baking can be resource-intensive and should be performed under controlled circumstances.

Utilizing Ambient Occlusion

VoxelGIData also lets you harness ambient occlusion to simulate soft shadows in areas where light is less likely to reach, adding depth and realism to the scene.

# Enable ambient occlusion
voxel_gi.use_occlusion = true

# Adjust the strength and the spread of the ambient occlusion effect
gi_data.occlusion_strength = 1.2
gi_data.occlusion_darkness = 1.0

Ambient occlusion settings should be tested extensively to ensure they contribute positively to the scene’s atmosphere and don’t overly darken areas that should have some indirect lighting.

Using Emission with VoxelGI

Emissive materials can be used with VoxelGI to create light sources within your scene, adding a new layer of depth with self-illuminating objects.

# Assuming you have a material with emission, tell the VoxelGI to use it for illumination
voxel_gi.use_emission = true

# You can control the intensity of emission globally for the VoxelGI node
gi_data.emission_scale = 1.5

Emission can simulate things like neon lights or glowing elements in a scene, contributing to the visual storytelling of your game.

Adjusting the Bounce Tint

Modify the color of the light as it bounces off surfaces to influence the overall mood of your environment. This can also be used to simulate different materials’ influence on lighting.

# Create a cool tint for bounces, simulating light reflecting off a blue surface
gi_data.bounce_tint = Color(0.5, 0.6, 1.0)

# Alternatively, a warm tint could suggest a sunlit area with much natural wood
gi_data.bounce_tint = Color(1.0, 0.8, 0.6)

These color adjustments can have a significant impact on the emotion and visual perception of your game scenes.

Integrating VoxelGIData into your Godot game development process offers a diverse range of lighting possibilities. Through the strategic use of these properties and methods, your game can benefit from optimized, dynamic, and visually stunning lighting scenarios. Keep experimenting with different settings to find the best combination for your specific use case, always being mindful of balancing performance and visual quality.

Where to Go Next with Your Godot Learning Journey

Congratulations on taking your first steps into working with Voxel Global Illumination and VoxelGIData in Godot 4! We’ve touched on powerful techniques to light up your game worlds with vibrant, dynamic, and realistic lighting. But, the path to mastering game development is an ongoing adventure.

To continue expanding your game development skills, we invite you to check out our Godot Game Development Mini-Degree. This collection of courses is meticulously designed to teach you how to build cross-platform games using the Godot 4 engine. You’ll learn about everything from 2D and 3D game creation, to mastering GDScript, and much more, giving you a well-rounded foundation for creating professional-quality games.

Additionally, our broad collection of Godot courses cover a variety of topics for all skill levels. Whether you’re a beginner or looking to refine your developer skills, Zenva’s project-based courses deliver hands-on experience to help you build an impressive portfolio of real game projects.

As always, at Zenva, our goal is to empower you with the knowledge and practical skills to turn your creative visions into playable realities. Dive into our Godot Game Development Mini-Degree or browse our extensive course library, and take your next steps toward becoming a proficient game developer with Zenva. Your adventure in game development is just beginning, and we’re excited to be a part of it!


With the power of Voxel Global Illumination and the versatility of VoxelGIData in your hands, you’re now equipped to bring stunning, realistic lighting into your Godot 4 game projects. We’ve explored how these techniques can enhance the visual storytelling of your games and provide your players with an immersive gaming experience. Remember, the art of game development is not just about coding—it’s about creating worlds that captivate and inspire.

In your quest for game development mastery, we at Zenva are here to support you every step of the way. Take the leap to deepen your understanding and expand your skillset with our Godot Game Development Mini-Degree. Forge ahead, and let the worlds you imagine take flight into realms of tangible, interactive experiences. Your journey continues, and the next great game lies just beyond your next line of code.

Python Blog Image

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