LightmapGIData in Godot – Complete Guide

Welcome to our comprehensive tutorial on the `LightmapGIData` class in Godot 4, a powerful tool in creating visually stunning games with realistic lighting. This class plays a pivotal role in optimizing your games by managing lightmaps and probe data for the LightmapGI system. By understanding and utilizing this class effectively, you can significantly enhance the visual quality of your scenes with baked lighting. So, let’s dive into the world of lightmapping in Godot and discover how `LightmapGIData` can transform your games from the ordinary to the extraordinary.

What is LightmapGIData?

The `LightmapGIData` class in Godot 4 is a resource that contains all the necessary data for baked lightmaps and dynamic object probe data, which are used with the LightmapGI baking system. This class functions as a repository for all light-related information generated when you bake your scene’s lighting. This data includes the textures and lighting information that will provide static objects within your game environment with a realistic and immersive look.

What is It For?

The `LightmapGIData` is predominantly used to store and handle light textures and other baked lighting info critical for LightmapGI. This means when your scene’s static lighting is calculated, all that data gets baked into textures, which are then used at runtime to offer a high level of detail without the overhead of real-time lighting calculations.

Why Should I Learn It?

Understanding `LightmapGIData` and baking lightmaps is essential for any game developer aiming to create visually appealing games with efficient lighting. Mastering this aspect of Godot can make the difference between a game that looks generic and one that stands out with its realistic, carefully-crafted environments. By learning how to use `LightmapGIData`, you can improve your game’s performance while delivering high-quality graphics, making your game a potential hit amongst players.

CTA Small Image

Creating and Configuring LightmapGIData

To begin utilizing `LightmapGIData` in your Godot 4 projects, you must first create a new LightmapGIData resource. This is the foundational step before proceeding with any lightmapping operations.

var lightmap_gi_data =

Once the LightmapGIData resource is created, you can proceed to configure its properties. For instance, you can set the `energy` value to adjust the overall brightness of baked lighting. = 1.0 # Default is 1. You can increase for brighter lightmaps, or decrease for dimmer ones.

Another important property to set up is the lightmap ‘interior’, which you can enable if your scene is indoors.

lightmap_gi_data.interior = true

Adding LightmapGIData to LightmapGI Node

Once your `LightmapGIData` resource is ready, the next step is to attach it to a LightmapGI node within your scene. This allows the LightmapGI to use the data during baking and runtime.

var lightmap_gi_node = $LightmapGI
lightmap_gi_node.lightmap_data = lightmap_gi_data

For a smoother workflow, ensure your scene’s geometry is properly organized and that materials are lightmap-ready. This means ensuring that your objects have UV2 maps for the lightmap textures to project onto.

Baking Lightmaps with LightmapGIData

With the `LightmapGIData` linked to your LightmapGI node, you can start baking your lightmaps to capture your scene’s static lighting. Here’s how you initiate the bake from script:


Do note that baking can take a significant amount of time depending on the complexity and size of your scene. Moreover, after baking, it’s crucial to save the `LightmapGIData` to avoid losing your baked data.

var saved_path = "res://path_to_save/lightmap_data.lmd", lightmap_gi_data)

This ensures that the next time you run your game, or if you close and reopen the Godot editor, you don’t have to bake the lightmaps again. You can simply load the previously saved LightmapGIData.

Loading and Using LightmapGIData

After your LightmapGIData has been baked and saved, you can load it back into the LightmapGI node whenever needed. Loading is straightforward and essential for using the lightmaps in your game.

var loaded_lightmap_data = load("res://path_to_load/lightmap_data.lmd") as LightmapGIData
lightmap_gi_node.lightmap_data = loaded_lightmap_data

Make sure you have the correct path to your saved `LightmapGIData` resource file. Incorrect paths will result in an error, failing to load your carefully baked lightmaps.

By following these examples, you should be able to successfully create, configure, bake, save, and load `LightmapGIData` within your Godot 4 projects.

Now that you’re comfortable with the basics of `LightmapGIData`, let’s delve deeper and explore some advanced techniques and code examples to maximize the quality and efficiency of your lightmaps.

To further refine your lightmaps, consider adjusting the `max_resolution` property of `LightmapGIData`. This defines the maximum texture size for your lightmaps, allowing you to balance between quality and performance.

lightmap_gi_data.max_resolution = 2048  # Higher for better quality, lower for better performance

You might also want to control the granularity at which the light probes populate the environment. The `cell_subdiv` property is responsible for this.

lightmap_gi_data.cell_subdiv = 4  # Smaller values result in more probes, which can lead to better lighting in complex environments

When you’re satisfied with the lightmap settings, it’s a good idea to perform a test bake to make sure everything is working as expected. Below is how you’d go about doing this programmatically:

func perform_test_bake():
    print("Test bake complete!")

The above code initiates a test bake that only focuses on the lighting without baking the full environmental details. This can save time when you’re adjusting light settings and don’t want to wait for a full bake on every tweak.

Remember to handle errors or interruptions that might occur during the baking process, which can be a lifesaver in large projects with long bake times.

lightmap_gi_node.connect("bake_finished", self, "_on_bake_finished")

func _on_bake_finished():
    if lightmap_gi_node.last_bake_error != OK:
        print("An error occurred during baking: ", lightmap_gi_node.get_last_bake_error_msg())
        print("Baking finished successfully!")

With the above connection, you’ll get feedback if something goes wrong during the baking process, allowing you to troubleshoot more effectively.

It’s also important to ensure that dynamic objects in your scene can interact correctly with the baked lighting. For this, you can use the following snippet to attach a `LightmapGIProbe` to a moving object.

func attach_probe_to_dynamic_object(object):
    var probe_instance =
    probe_instance.lightmap = lightmap_gi_data


Here, the `player` node will now have a `LightmapGIProbe` that allows it to receive indirect lighting information stored in the `LightmapGIData`. This helps the object blend seamlessly into the pre-baked environment for a more natural look.

Last but not least, to maintain good practice, it’s prudent to cleanup after your baking processes, especially when done with scripting.

func cleanup_after_bake():
    print("Cleanup completed. The scene is ready for another bake if necessary.")


This snippet will clear the previous bake, allowing you to start fresh. This can be particularly useful during the iterative processes of level design and light tuning.

In conclusion, by using these code examples and tips, you should be well-equipped to perform efficient, high-quality lightmapping with LightmapGIData in your Godot 4 projects, giving your games the professional polish they deserve.

To enhance the realism and visual appeal even further, you may incorporate several advanced features from `LightmapGIData`. Let’s continue with more examples and insights that can help bring your lighting to the next level.

One way to add variation to your static lighting is to enable or disable certain light groups during the baking process. You can do this by setting the `light_group_cull_mask`. This determines which light groups will affect the lightmap baking.

lightmap_gi_data.light_group_cull_mask = 1  # Only lights in group 1 will affect the baking

To have the lighting update dynamically in certain areas, while still utilizing the lightmap for static areas, you can mark certain meshes with a `LightmapGIProbe` instance which allows them to receive indirect lighting dynamically.

func mark_mesh_for_dynamic_lighting(mesh_instance):
    var gi_probe =
    gi_probe.lightmap = lightmap_gi_data

It’s often helpful to consider the physical size of the environment when configuring lightmap data. You can specify this using the `cell_size` property, which defines the size of each cell used by the LightmapGI system.

lightmap_gi_data.cell_size = 0.5  # Smaller sizes can provide more detailed lighting, but at the cost of performance

For even more precise control over lighting, you might want to customize which objects cast shadows during the bake. This can be accomplished by configuring the `generate_photons` flag for each node that you want to participate in the lightmap.

for node in get_tree().get_nodes_in_group("LightmapShadowCasters"):
    node.generate_photons = true  # This node will now cast shadows in the lightmap

In large projects or scenes, it may be beneficial to split your lightmap into smaller textures, rather than one large one. This can improve performance on certain systems and allows for more efficient memory usage. You can control this with the `texture_size` property.

lightmap_gi_data.texture_size = Vector2(1024, 1024)  # Defines the width and height of the lightmap textures

The quality of the lightmap can be directly impacted by the distribution of the light probes. Adjusting the `subdiv` property can ensure that probes are allocated more densely in areas that require higher detail.

lightmap_gi_data.subdiv = 3  # Adjust subdivision for probe distribution, lower numbers indicate more probes

Remember, these configurations should be made before the baking process to ensure that the generated texture reflects the desired adjustments. Once you’ve baked your lightmaps and adjusted settings to your satisfaction, you can verify the integrity of your `LightmapGIData` with the following:

func verify_lightmap_data():
    if lightmap_gi_data.is_valid():
        print("Lightmap data is valid and ready to use!")
        print("Lightmap data is invalid. Please check the bake and settings.")

Utilizing these examples will help you fine-tune your scene’s lighting to achieve the best possible balance between aesthetics and performance. Remember, lighting can significantly impact the player’s experience and immersion, so it’s worth investing the time to get it right with good lightmap practices.

Continue Your Game Development Journey

Elevate your game development skills and take them to the next level with our Godot Game Development Mini-Degree. This extensive training program is meticulously designed to guide you through the creation of cross-platform games using Godot’s dynamic and flexible engine. Our curriculum, suitable for both beginners and experienced developers, will teach you essential topics ranging from creating engaging 2D and 3D assets to mastering game mechanics across various genres.

For an even broader exploration of what Godot has to offer, we invite you to browse our collection of Godot courses. Immerse yourself in a learning experience that covers all facets of Godot’s powerful capabilities, ensuring you gain the skills needed to succeed in the ever-evolving games market. With project-based courses, quizzes, and completion certificates, we at Zenva are dedicated to providing you with a structured path to becoming a professional game developer.

Start building standout games today and join a community of like-minded developers looking to make an impact in the gaming world. Unlock your potential and make your game development dreams a reality!


Venturing into the realms of game development can be a thrilling journey, and mastering tools like `LightmapGIData` in Godot 4 can set your projects apart, giving life to the worlds you create. As developers, equipping ourselves with the knowledge of advanced lighting techniques forms the backbone of crafting immersive experiences. Whether it’s the delicate play of shadows or the warm glow of a setting sun, light shapes the player’s adventure in subtle, yet powerful ways.

With our Godot Game Development Mini-Degree, you’re not just learning a new skill, you’re elevating your creative vision. You’re shaping not only virtual realms but also your future in the gaming industry. Don’t let your ideas remain in the dark; illuminate them with the power of Godot, and together, let’s bring your game development aspirations to light.

Python Blog Image

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