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

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

說明

LightmapGI 節點用於計算和儲存烘焙的光照貼圖。光照貼圖用於提供高品質的間接照明，並且漏光很少。如果啟用 directional，LightmapGI 還可以使用球諧函式，以提供粗略的反射。由於光照探針，動態物體可以接收間接光照，可以通過將 generate_probes_subdiv 設定為 GENERATE_PROBES_DISABLED 以外的值，來自動放置光照探針。也可以通過建立 LightmapProbe 節點，來新增額外的光照貼圖探針。缺點是光照貼圖是完全靜態的，不能在匯出的專案中烘焙。與 VoxelGI 相比，烘焙 LightmapGI 節點也更慢。

程式生成：光照貼圖烘焙功能僅在編輯器中可用。這意味著 LightmapGI 不適合程式生成或使用者建置的關卡。對於程式生成或使用者建置的關卡，請改用 VoxelGI 或 SDFGI（請參閱 Environment.sdfgi_enabled）。

效能：LightmapGI 為全域照明提供最佳的執行時效能。它適用於包括集成顯卡和行動裝置在內的低端硬體。

注意：由於光照貼圖的工作方式，大多數屬性只有在光照貼圖被再次烘焙後，才會產生可見效果。

注意：不支援在 CSGShape3D 和 PrimitiveMesh 上烘焙光照貼圖，因為它們無法儲存烘焙所需的 UV2 資料。

注意：如果沒有安裝自訂光照貼圖器，則只能從支援 Forward+ 或 Mobile 渲染器的裝置烘焙 LightmapGI。

注意：LightmapGI 節點只會為其父節點的子節點烘焙光照資料。不會烘焙場景中更上層的節點。

教學

屬性

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/ultra_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

由於光照貼圖太小，光照貼圖烘焙失敗。

BakeError BAKE_ERROR_ATLAS_TOO_SMALL = 11

由於光照貼圖無法放入圖集，因此光照貼圖烘焙失敗。

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()

每次反彈的能量乘數。較高的值將使間接照明更亮。值 1.0 代表物理上準確的行為，但較高的值可用於在使用少量反彈時使間接照明傳播更明顯。這可以通過減少 bounces 數量，然後增加 bounce_indirect_energy 來加速烘焙時間。

注意：bounce_indirect_energy 僅在 bounces 被設定為大於或等於 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()

降噪器取樣的像素距離。較低的值會保留更多細節，但如果光照貼圖品質不夠高，則可能會產生斑點結果。僅當 use_denoiser 為 true 且 ProjectSettings.rendering/lightmapping/denoising/denoiser 被設定為 JNLM 時有效。

float denoiser_strength = 0.1 🔗

  • void set_denoiser_strength(value: float)

  • float get_denoiser_strength()

套用至生成的光照貼圖的去噪步驟的強度。僅當 use_denoiser 為 true 且 ProjectSettings.rendering/lightmapping/denoising/denoiser 被設定為 JNLM 時有效。

bool directional = false 🔗

  • void set_directional(value: bool)

  • bool is_directional()

如果為 true，烘焙光照貼圖以包含作為球諧函式的方向資訊。這會產生更逼真的光照外觀，尤其是使用法線貼圖材質和烘焙了直射光的燈光（Light3D.light_bake_mode 設定為 Light3D.BAKE_STATIC 並將 Light3D.editor_only 設定為 false）。方向資訊還用於為靜態和動態物件提供粗略的反射。這有一個小的執行時效能成本，因為著色器必須執行更多的工作，來解釋來自光照貼圖的方向資訊。定向光照貼圖也需要更長的時間來烘焙並產生更大的檔案大小。

注意：屬性的名稱與 DirectionalLight3D 沒有關係。directional 適用於所有燈光型別。

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 🔗

烘焙光照貼圖時使用的品質預設。會影響烘焙時間，但輸出檔案的大小在所有品質層級上基本相同。

要進一步加快烘焙時間，請在減小 bounces、停用 use_denoiser 並/或減小 texel_scale。

要進一步提升品質，請啟用 supersampling 並/或增大 texel_scale。

ShadowmaskMode shadowmask_mode = 0 🔗

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

陰影遮罩策略，用於該 LightmapGI 實例烘焙的靜態物體的方向陰影。

使用陰影遮罩的 DirectionalLight3D 節點即便超出了 DirectionalLight3D.directional_shadow_max_distance 所定義的範圍也能夠投射陰影。原理是為平行光烘焙包含陰影貼圖的紋理，然後根據目前的陰影遮罩模式使用這張紋理。

注意：shadowmask_mode 非 LightmapGIData.SHADOWMASK_MODE_NONE 時才會建立陰影遮罩紋理。要看到區別，請將 LightmapGIData.SHADOWMASK_MODE_NONE 改為其他模式，然後重新烘焙光照貼圖。

bool supersampling = false 🔗

  • void set_supersampling_enabled(value: bool)

  • bool is_supersampling_enabled()

如果為 true，則光照貼圖在烘焙時會將紋素縮放值與 supersampling_factor 相乘，並在儲存光照貼圖之前進行下取樣（因此有效的紋素密度與停用超取樣時相同）。

超取樣可以提高光照貼圖的品質、減少噪聲、提供更平滑的陰影、更好地陰影化物體中的小規模特徵。不過也可能會導致在烘焙光照貼圖時顯著增加烘焙時間和記憶體使用。會自動調整填充，避免增加光洩漏。

float supersampling_factor = 2.0 🔗

  • void set_supersampling_factor(value: float)

  • float get_supersampling_factor()

超取樣時與紋素密度相乘的係數。為了獲得最佳效果，建議使用整數值。雖然允許使用分數值，但可能會導致光洩漏增加、光照貼圖模糊。

較高的值可能會帶來更好的品質，但在烘焙時也會增加烘焙時間和記憶體使用。

詳見 supersampling。

float texel_scale = 1.0 🔗

  • void set_texel_scale(value: float)

  • float get_texel_scale()

縮放目前烘焙的所有網格的光照貼圖紋素密度。這是一個乘數，基於匯入的各個 3D 場景中定義的已有光照貼圖紋素大小，以及各個網格的密度乘數（設計用於在不同縮放使用相同網格時使用）。值越低，烘焙時間越快。

例如，將 texel_scale 翻倍會讓物體的光照貼圖紋理在每個方向上的解析度都翻倍，導致紋素數量變為原來的四倍。

bool use_denoiser = true 🔗

  • void set_use_denoiser(value: bool)

  • bool is_using_denoiser()

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

bool use_texture_for_bounces = true 🔗

  • void set_use_texture_for_bounces(value: bool)

  • bool is_using_texture_for_bounces()

如果為 true，將生成帶有照明資訊的紋理，以加快間接照明的生成速度，但會犧牲一定的精度。當使用低解析度光照貼圖或在表面上顯著拉伸光照貼圖的 UV 時，幾何體可能會出現額外的漏光偽影。如果不確定，請將 use_texture_for_bounces 保留為其預設值 true。

注意：use_texture_for_bounces 僅在 bounces 被設定為大於或等於 1 的值時才有效。