Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

LightmapGI

繼承： VisualInstance3D < Node3D < Node < Object

計算並儲存烘焙光照貼圖，以實作快速全域照明。

說明

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 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.

教學

屬性

float

bias

0.0005

float

bounce_indirect_energy

1.0

int

bounces

3

CameraAttributes

camera_attributes

int

denoiser_range

10

float

denoiser_strength

0.1

bool

directional

false

Color

environment_custom_color

Color(1, 1, 1, 1)

float

environment_custom_energy

1.0

Sky

environment_custom_sky

EnvironmentMode

environment_mode

1

GenerateProbes

generate_probes_subdiv

2

bool

interior

false

LightmapGIData

light_data

int

max_texture_size

16384

BakeQuality

quality

1

ShadowmaskMode

shadowmask_mode

0

bool

supersampling

false

float

supersampling_factor

2.0

float

texel_scale

1.0

bool

use_denoiser

true

bool

use_texture_for_bounces

true

列舉

enum BakeQuality: 🔗

BakeQuality BAKE_QUALITY_LOW = 0

較低的烘焙品質（最快的烘焙時間）。可以通過更改 ProjectSettings.rendering/lightmapping/bake_quality/low_quality_ray_count 和 ProjectSettings.rendering/lightmapping/bake_quality/low_quality_probe_ray_count 來調整此預設的品質。

BakeQuality BAKE_QUALITY_MEDIUM = 1

中等的烘焙品質（較快的烘焙時間）。可以通過更改 ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_ray_count 和 ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_probe_ray_count 來調整此預設的品質。

BakeQuality BAKE_QUALITY_HIGH = 2

較高的烘焙品質（較慢的烘焙時間）。可以通過更改 ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count 和 ProjectSettings.rendering/lightmapping/bake_quality/high_quality_probe_ray_count 來調整此預設的品質。

BakeQuality BAKE_QUALITY_ULTRA = 3

最高的烘焙品質（最慢的烘焙時間）。可以通過更改 ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count 和 ProjectSettings.rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count 來調整此預設的品質。

enum GenerateProbes: 🔗

GenerateProbes GENERATE_PROBES_DISABLED = 0

不要為光照動態物件生成光照貼圖探查。

GenerateProbes GENERATE_PROBES_SUBDIV_4 = 1

最低級別的細分（烘焙時間最快，檔大小最小）。

GenerateProbes GENERATE_PROBES_SUBDIV_8 = 2

較低級別的細分（烘焙時間較快，檔大小較小）。

GenerateProbes GENERATE_PROBES_SUBDIV_16 = 3

較高級別的細分（烘焙時間較慢，檔大小較大）。

GenerateProbes GENERATE_PROBES_SUBDIV_32 = 4

最高級別的細分（烘焙時間最慢，檔大小最大）。

enum BakeError: 🔗

BakeError BAKE_ERROR_OK = 0

光照貼圖烘焙成功。

BakeError BAKE_ERROR_NO_SCENE_ROOT = 1

光照貼圖烘焙失敗，原因是無法存取所編輯場景的根節點。

BakeError BAKE_ERROR_FOREIGN_DATA = 2

光照貼圖烘焙失敗，原因是光照貼圖資料嵌入在外部資源之中。

BakeError BAKE_ERROR_NO_LIGHTMAPPER = 3

光照貼圖烘焙失敗，原因是這個 Godot 建構中沒有可用的光照貼圖器。

BakeError BAKE_ERROR_NO_SAVE_PATH = 4

光照貼圖烘焙失敗，原因是資源中沒有配置 LightmapGIData 保存路徑。

BakeError BAKE_ERROR_NO_MESHES = 5

光照貼圖烘焙失敗，原因是目前場景中沒有 GeometryInstance3D.gi_mode 為 GeometryInstance3D.GI_MODE_STATIC 且具有有效 UV2 對應的網格。可能需要在匯入停靠面板中選擇 3D 場景，並相應地更改它們的全域照明模式。

BakeError BAKE_ERROR_MESHES_INVALID = 6

光照貼圖烘焙失敗，原因是光照貼圖器無法分析一些標記為靜態的網格以進行烘焙。

BakeError BAKE_ERROR_CANT_CREATE_IMAGE = 7

光照貼圖烘焙失敗，原因是最終的圖像無法保存，或保存後無法被 Godot 匯入。

BakeError BAKE_ERROR_USER_ABORTED = 8

使用者中止了光照貼圖烘焙操作（通常通過點擊進度對話方塊中的取消按鈕）。

BakeError BAKE_ERROR_TEXTURE_SIZE_TOO_SMALL = 9

光照貼圖烘焙失敗，原因是光照貼圖器無法分析一些標記為靜態的網格以進行烘焙。

BakeError BAKE_ERROR_LIGHTMAP_TOO_SMALL = 10

Lightmap baking failed as the lightmap is too small.

BakeError BAKE_ERROR_ATLAS_TOO_SMALL = 11

Lightmap baking failed as the lightmap was unable to fit into an atlas.

enum EnvironmentMode: 🔗

EnvironmentMode ENVIRONMENT_MODE_DISABLED = 0

烘焙光照貼圖時忽略環境光照。

EnvironmentMode ENVIRONMENT_MODE_SCENE = 1

烘焙光照貼圖時，使用場景的環境光照。

注意：如果在沒有 WorldEnvironment 節點的場景中烘焙光照貼圖，這將表現得像 ENVIRONMENT_MODE_DISABLED。在烘焙光照貼圖時，LightmapGI 不會考慮編輯器的預覽天空和太陽。

EnvironmentMode ENVIRONMENT_MODE_CUSTOM_SKY = 2

烘焙光照貼圖時，使用 environment_custom_sky 作為環境光照來源。

EnvironmentMode ENVIRONMENT_MODE_CUSTOM_COLOR = 3

烘焙光照貼圖時，使用 environment_custom_color 和 environment_custom_energy 相乘的結果作為環境光照的恒定來源。

屬性說明

float bias = 0.0005 🔗

計算陰影時使用的偏置。增加 bias 可以修復生成的烘焙光照貼圖上的陰影失真，但會引入陰影懸浮（陰影未連接到其障礙物）。即時 Light3D 陰影不受該 bias 屬性的影響。

float bounce_indirect_energy = 1.0 🔗

  • void set_bounce_indirect_energy(value: float)

  • float get_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.

int bounces = 3 🔗

  • void set_bounces(value: int)

  • int get_bounces()

烘焙過程中考慮的光反彈次數。較高的值會產生更明亮、更逼真的光線，但代價是更長的烘焙時間。如果設定為 0，則僅烘焙環境光線、直接光線和自發光光線。

CameraAttributes camera_attributes 🔗

CameraAttributes 資源，指定要烘焙的曝光級別。自動曝光和非曝光屬性將被忽略。應該使用曝光設定來減少烘焙時出現的動態範圍。如果曝光度太高，LightmapGI 將出現帶狀偽影，或可能出現過度曝光偽影。

int denoiser_range = 10 🔗

  • void set_denoiser_range(value: int)

  • int get_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 ProjectSettings.rendering/lightmapping/denoising/denoiser is set to JNLM.

float denoiser_strength = 0.1 🔗

  • void set_denoiser_strength(value: float)

  • float get_denoiser_strength()

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

bool directional = false 🔗

  • void set_directional(value: bool)

  • bool 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 and with Light3D.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.

Color environment_custom_color = Color(1, 1, 1, 1) 🔗

  • void set_environment_custom_color(value: Color)

  • Color get_environment_custom_color()

用於環境照明的顏色。僅在 environment_mode 為 ENVIRONMENT_MODE_CUSTOM_COLOR 時有效。

float environment_custom_energy = 1.0 🔗

  • void set_environment_custom_energy(value: float)

  • float get_environment_custom_energy()

用於環境照明的顏色倍數。僅在 environment_mode 為 ENVIRONMENT_MODE_CUSTOM_COLOR 時有效。

Sky environment_custom_sky 🔗

  • void set_environment_custom_sky(value: Sky)

  • Sky get_environment_custom_sky()

用作環境照明光源的天空。僅在 environment_mode 為 ENVIRONMENT_MODE_CUSTOM_SKY 時有效。

EnvironmentMode environment_mode = 1 🔗

烘焙光照貼圖時使用的環境模式。

GenerateProbes generate_probes_subdiv = 2 🔗

為動態物件照明自動生成 LightmapProbe 時使用的細分級別。較高的值會在動態物件上產生更準確的間接照明，但代價是更長的烘焙時間和更大的檔大小。

注意：自動生成的 LightmapProbe，不作為在場景樹停靠面板中的節點可見，並且生成後無法通過這種方式修改。

注意：不管 generate_probes_subdiv，動態物件上的直接光照，總是使用 Light3D 節點即時套用。

bool interior = false 🔗

  • void set_interior(value: bool)

  • bool is_interior()

如果為 true，則會在烘焙光照貼圖時忽略環境光照。

LightmapGIData light_data 🔗

與該 LightmapGI 節點關聯的 LightmapGIData。該資源是在烘焙後自動建立的，並不意味著要手動建立。

int max_texture_size = 16384 🔗

  • void set_max_texture_size(value: int)

  • int get_max_texture_size()

生成的紋理合集的最大紋理大小。更高的值將導致生成的切片更少，但由於硬體對紋理大小的限制，可能無法在所有硬體上工作。如果不確定，請將 max_texture_size 保留為其預設值 16384。

BakeQuality quality = 1 🔗

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.

ShadowmaskMode shadowmask_mode = 0 🔗

實驗性： 此屬性可能在未來版本中變更或移除。

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 DirectionalLight3D.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.

bool supersampling = false 🔗

  • void set_supersampling_enabled(value: bool)

  • bool is_supersampling_enabled()

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.

float supersampling_factor = 2.0 🔗

  • void set_supersampling_factor(value: float)

  • float get_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.

float texel_scale = 1.0 🔗

  • void set_texel_scale(value: float)

  • float get_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.

bool use_denoiser = true 🔗

  • void set_use_denoiser(value: bool)

  • bool is_using_denoiser()

如果為 true，則在生成的光照貼圖上，使用基於 CPU 的降噪演算法。這以更長的烘焙時間為代價，消除了生成的光照貼圖中的大部分噪點。儘管無失真壓縮在壓縮降噪圖像方面可能做得更好，但使用降噪器通常不會顯著影響檔大小。

注意：在大場景中對光照貼圖進行降噪時，內建降噪器（OpenImageDenoise）可能會當機。如果在光照貼圖烘焙結束時遇到當機，請嘗試禁用 use_denoiser。

bool use_texture_for_bounces = true 🔗

  • void set_use_texture_for_bounces(value: bool)

  • bool is_using_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.