Table of Contents

Class LightmapGI

Computes and stores baked lightmaps for fast global illumination.

Inheritance
LightmapGI

Remarks

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 LightmapGI.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 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 from devices that support the Forward+ or Mobile renderers.

Note: The LightmapGI node only bakes light data for child nodes of its parent. Nodes further up the hierarchy of the scene will not be baked.

See Also

Using Lightmap global illumination

Properties

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.

var bias : float = 0.0005

Property Value

float

Remarks

bounce_indirect_energy

The energy multiplier for each bounce. Higher values will make indirect lighting brighter. A value of 1.0 represents physically accurate behavior, but higher values can be used to make indirect lighting propagate more visibly when using a low number of bounces. This can be used to speed up bake times by lowering the number of bounces then increasing bounce_indirect_energy.

Note: bounce_indirect_energy only has an effect if bounces is set to a value greater than or equal to 1.

var bounce_indirect_energy : float = 1.0

Property Value

float

Remarks

  • void set_bounce_indirect_energy(float value)
  • float get_bounce_indirect_energy

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.

var bounces : int = 3

Property Value

int

Remarks

  • void set_bounces(int value)
  • int get_bounces

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.

var camera_attributes : CameraAttributes

Property Value

CameraAttributes

Remarks

denoiser_range

The distance in pixels from which the denoiser samples. Lower values preserve more details, but may give blotchy results if the lightmap quality is not high enough. Only effective if use_denoiser is true and rendering/lightmapping/denoising/denoiser is set to JNLM.

var denoiser_range : int = 10

Property Value

int

Remarks

  • void set_denoiser_range(int value)
  • int get_denoiser_range

denoiser_strength

The strength of denoising step applied to the generated lightmaps. Only effective if use_denoiser is true and rendering/lightmapping/denoising/denoiser is set to JNLM.

var denoiser_strength : float = 0.1

Property Value

float

Remarks

  • void set_denoiser_strength(float value)
  • float get_denoiser_strength

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 (light_bake_mode set to Light3D.BAKE_STATIC and with editor_only set to false). 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.

var directional : bool = false

Property Value

bool

Remarks

  • void set_directional(bool value)
  • bool is_directional

environment_custom_color

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

var environment_custom_color : Color = Color(1, 1, 1, 1)

Property Value

Color

Remarks

  • void set_environment_custom_color(Color value)
  • Color get_environment_custom_color

environment_custom_energy

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

var environment_custom_energy : float = 1.0

Property Value

float

Remarks

  • void set_environment_custom_energy(float value)
  • float get_environment_custom_energy

environment_custom_sky

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

var environment_custom_sky : Sky

Property Value

Sky

Remarks

  • void set_environment_custom_sky(Sky value)
  • Sky get_environment_custom_sky

environment_mode

The environment mode to use when baking lightmaps.

var environment_mode : int = 1

Property Value

int

Remarks

  • void set_environment_mode(int value)
  • int get_environment_mode

generate_probes_subdiv

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.

var generate_probes_subdiv : int = 2

Property Value

int

Remarks

  • void set_generate_probes(int value)
  • int get_generate_probes

interior

If true, ignore environment lighting when baking lightmaps.

var interior : bool = false

Property Value

bool

Remarks

  • void set_interior(bool value)
  • bool is_interior

light_data

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

var light_data : LightmapGIData

Property Value

LightmapGIData

Remarks

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.

var max_texture_size : int = 16384

Property Value

int

Remarks

  • void set_max_texture_size(int value)
  • int get_max_texture_size

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/or decrease texel_scale.

To further increase quality, enable supersampling and/or increase texel_scale.

var quality : int = 1

Property Value

int

Remarks

  • void set_bake_quality(int value)
  • int get_bake_quality

shadowmask_mode

The shadowmasking policy to use for directional shadows on static objects that are baked with this LightmapGI instance.

Shadowmasking allows DirectionalLight3D nodes to cast shadows even outside the range defined by their directional_shadow_max_distance property. This is done by baking a texture that contains a shadowmap for the directional light, then using this texture according to the current shadowmask mode.

Note: The shadowmask texture is only created if shadowmask_mode is not LightmapGIData.SHADOWMASK_MODE_NONE. To see a difference, you need to bake lightmaps again after switching from LightmapGIData.SHADOWMASK_MODE_NONE to any other mode.

var shadowmask_mode : int = 0

Property Value

int

Remarks

  • void set_shadowmask_mode(int value)
  • int get_shadowmask_mode

supersampling

If true, lightmaps are baked with the texel scale multiplied with supersampling_factor and downsampled before saving the lightmap (so the effective texel density is identical to having supersampling disabled).

Supersampling provides increased lightmap quality with less noise, smoother shadows and better shadowing of small-scale features in objects. However, it may result in significantly increased bake times and memory usage while baking lightmaps. Padding is automatically adjusted to avoid increasing light leaking.

var supersampling : bool = false

Property Value

bool

Remarks

  • void set_supersampling_enabled(bool value)
  • bool is_supersampling_enabled

supersampling_factor

The factor by which the texel density is multiplied for supersampling. For best results, use an integer value. While fractional values are allowed, they can result in increased light leaking and a blurry lightmap.

Higher values may result in better quality, but also increase bake times and memory usage while baking.

See supersampling for more information.

var supersampling_factor : float = 2.0

Property Value

float

Remarks

  • void set_supersampling_factor(float value)
  • float get_supersampling_factor

texel_scale

Scales the lightmap texel density of all meshes for the current bake. This is a multiplier that builds upon the existing lightmap texel size defined in each imported 3D scene, along with the per-mesh density multiplier (which is designed to be used when the same mesh is used at different scales). Lower values will result in faster bake times.

For example, doubling texel_scale doubles the lightmap texture resolution for all objects on each axis, so it will quadruple the texel count.

var texel_scale : float = 1.0

Property Value

float

Remarks

  • void set_texel_scale(float value)
  • float get_texel_scale

use_denoiser

If true, uses a GPU-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.

var use_denoiser : bool = true

Property Value

bool

Remarks

  • void set_use_denoiser(bool value)
  • bool is_using_denoiser

use_texture_for_bounces

If true, a texture with the lighting information will be generated to speed up the generation of indirect lighting at the cost of some accuracy. The geometry might exhibit extra light leak artifacts when using low resolution lightmaps or UVs that stretch the lightmap significantly across surfaces. Leave use_texture_for_bounces at its default value of true if unsure.

Note: use_texture_for_bounces only has an effect if bounces is set to a value greater than or equal to 1.

var use_texture_for_bounces : bool = true

Property Value

bool

Remarks

  • void set_use_texture_for_bounces(bool value)
  • bool is_using_texture_for_bounces