LightmapGI

Inherits: VisualInstance3D < Node3D < Node < Object

Computes and stores baked lightmaps for fast global illumination.

Description

The LightmapGI node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. LightmapGI can also provide rough reflections using spherical harmonics if directional is enabled. Dynamic objects can receive indirect lighting thanks to light probes, which can be automatically placed by setting generate_probes_subdiv to a value other than GENERATE_PROBES_DISABLED. Additional lightmap probes can also be added by creating LightmapProbe nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a LightmapGI node is also slower compared to VoxelGI.

Procedural generation: Lightmap baking functionality is only available in the editor. This means LightmapGI is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use VoxelGI or SDFGI instead (see Environment.sdfgi_enabled).

Performance: LightmapGI provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices.

Note: Due to how lightmaps work, most properties only have a visible effect once lightmaps are baked again.

Note: Lightmap baking on CSGShape3Ds and PrimitiveMeshes is not supported, as these cannot store UV2 data required for baking.

Note: If no custom lightmappers are installed, LightmapGI can only be baked when using the Vulkan backend (Clustered or Mobile), not OpenGL.

Properties

float

bias

0.0005

int

bounces

1

CameraAttributes

camera_attributes

bool

directional

false

Color

environment_custom_color

float

environment_custom_energy

Sky

environment_custom_sky

EnvironmentMode

environment_mode

0

GenerateProbes

generate_probes_subdiv

0

bool

interior

false

LightmapGIData

light_data

int

max_texture_size

16384

BakeQuality

quality

1

bool

use_denoiser

true

Enumerations

enum BakeQuality:


enum GenerateProbes:

  • GENERATE_PROBES_DISABLED = 0 --- Don't generate lightmap probes for lighting dynamic objects.

  • GENERATE_PROBES_SUBDIV_4 = 1 --- Lowest level of subdivision (fastest bake times, smallest file sizes).

  • GENERATE_PROBES_SUBDIV_8 = 2 --- Low level of subdivision (fast bake times, small file sizes).

  • GENERATE_PROBES_SUBDIV_16 = 3 --- High level of subdivision (slow bake times, large file sizes).

  • GENERATE_PROBES_SUBDIV_32 = 4 --- Highest level of subdivision (slowest bake times, largest file sizes).


enum BakeError:

  • BAKE_ERROR_OK = 0 --- Lightmap baking was successful.

  • BAKE_ERROR_NO_LIGHTMAPPER = 1 --- Lightmap baking failed as there is no lightmapper available in this Godot build.

  • BAKE_ERROR_NO_SAVE_PATH = 2 --- Lightmap baking failed as the LightmapGIData save path isn't configured in the resource.

  • BAKE_ERROR_NO_MESHES = 3 --- Lightmap baking failed as there are no meshes whose GeometryInstance3D.gi_mode is GeometryInstance3D.GI_MODE_STATIC and with valid UV2 mapping in the current scene. You may need to select 3D scenes in the Import dock and change their global illumination mode accordingly.

  • BAKE_ERROR_MESHES_INVALID = 4 --- Lightmap baking failed as the lightmapper failed to analyze some of the meshes marked as static for baking.

  • BAKE_ERROR_CANT_CREATE_IMAGE = 5 --- Lightmap baking failed as the resulting image couldn't be saved or imported by Godot after it was saved.

  • BAKE_ERROR_USER_ABORTED = 6 --- The user aborted the lightmap baking operation (typically by clicking the Cancel button in the progress dialog).


enum EnvironmentMode:

  • ENVIRONMENT_MODE_DISABLED = 0 --- Ignore environment lighting when baking lightmaps.

  • ENVIRONMENT_MODE_SCENE = 1 --- Use the scene's environment lighting when baking lightmaps.

Note: If baking lightmaps in a scene with no WorldEnvironment node, this will act like ENVIRONMENT_MODE_DISABLED. The editor's preview sky and sun is not taken into account by LightmapGI when baking lightmaps.

Property Descriptions

Default

0.0005

Setter

set_bias(value)

Getter

get_bias()

The bias to use when computing shadows. Increasing bias can fix shadow acne on the resulting baked lightmap, but can introduce peter-panning (shadows not connecting to their casters). Real-time Light3D shadows are not affected by this bias property.


Default

1

Setter

set_bounces(value)

Getter

get_bounces()

Number of light bounces that are taken into account during baking. Higher values result in brighter, more realistic lighting, at the cost of longer bake times. If set to 0, only environment lighting, direct light and emissive lighting is baked.


Setter

set_camera_attributes(value)

Getter

get_camera_attributes()

The CameraAttributes resource that specifies exposure levels to bake at. Auto-exposure and non exposure properties will be ignored. Exposure settings should be used to reduce the dynamic range present when baking. If exposure is too high, the LightmapGI will have banding artifacts or may have over-exposure artifacts.


Default

false

Setter

set_directional(value)

Getter

is_directional()

If true, bakes lightmaps to contain directional information as spherical harmonics. This results in more realistic lighting appearance, especially with normal mapped materials and for lights that have their direct light baked (Light3D.light_bake_mode set to Light3D.BAKE_STATIC). The directional information is also used to provide rough reflections for static and dynamic objects. This has a small run-time performance cost as the shader has to perform more work to interpret the direction information from the lightmap. Directional lightmaps also take longer to bake and result in larger file sizes.

Note: The property's name has no relationship with DirectionalLight3D. directional works with all light types.


  • Color environment_custom_color

Setter

set_environment_custom_color(value)

Getter

get_environment_custom_color()

The color to use for environment lighting. Only effective if environment_mode is ENVIRONMENT_MODE_CUSTOM_COLOR.


  • float environment_custom_energy

Setter

set_environment_custom_energy(value)

Getter

get_environment_custom_energy()

The color multiplier to use for environment lighting. Only effective if environment_mode is ENVIRONMENT_MODE_CUSTOM_COLOR.


  • Sky environment_custom_sky

Setter

set_environment_custom_sky(value)

Getter

get_environment_custom_sky()

The sky to use as a source of environment lighting. Only effective if environment_mode is ENVIRONMENT_MODE_CUSTOM_SKY.


Default

0

Setter

set_environment_mode(value)

Getter

get_environment_mode()

The environment mode to use when baking lightmaps.


Default

0

Setter

set_generate_probes(value)

Getter

get_generate_probes()

The level of subdivision to use when automatically generating LightmapProbes for dynamic object lighting. Higher values result in more accurate indirect lighting on dynamic objects, at the cost of longer bake times and larger file sizes.

Note: Automatically generated LightmapProbes are not visible as nodes in the Scene tree dock, and cannot be modified this way after they are generated.

Note: Regardless of generate_probes_subdiv, direct lighting on dynamic objects is always applied using Light3D nodes in real-time.


Default

false

Setter

set_interior(value)

Getter

is_interior()

If true, ignore environment lighting when baking lightmaps.


Setter

set_light_data(value)

Getter

get_light_data()

The LightmapGIData associated to this LightmapGI node. This resource is automatically created after baking, and is not meant to be created manually.


  • int max_texture_size

Default

16384

Setter

set_max_texture_size(value)

Getter

get_max_texture_size()

The maximum texture size for the generated texture atlas. Higher values will result in fewer slices being generated, but may not work on all hardware as a result of hardware limitations on texture sizes. Leave max_texture_size at its default value of 16384 if unsure.


Default

1

Setter

set_bake_quality(value)

Getter

get_bake_quality()

The quality preset to use when baking lightmaps. This affects bake times, but output file sizes remain mostly identical across quality levels.

To further speed up bake times, decrease bounces, disable use_denoiser and increase the lightmap texel size on 3D scenes in the Import doc.


Default

true

Setter

set_use_denoiser(value)

Getter

is_using_denoiser()

If true, uses a CPU-based denoising algorithm on the generated lightmap. This eliminates most noise within the generated lightmap at the cost of longer bake times. File sizes are generally not impacted significantly by the use of a denoiser, although lossless compression may do a better job at compressing a denoised image.

Note: The built-in denoiser (OpenImageDenoise) may crash when denoising lightmaps in large scenes. If you encounter a crash at the end of lightmap baking, try disabling use_denoiser.