LightmapGI: UV2, baking and result checks — documentation

LightmapGI

LightmapGI calculates static-geometry lighting ahead of time and stores it in texture atlases. The game reads those atlases instead of recalculating the same indirect light. This saves computation but uses memory and does not make moving-geometry lighting fully dynamic.

Baking requires a build with lightmapper_rd and a GPU supporting RenderingDevice. This pass used the installed Forward+/Vulkan editor. Rendering prepared maps and baking them are different capabilities: existing maps can be rendered where GPU baking is unavailable.

Prepare meshes

Save the .rscene level. Put LightmapGI under a common root with the geometry. The native action traverses the LightmapGI parent and descendants; when LightmapGI is the level root it traverses its descendants.
Set baked MeshInstance3D objects to GIMode = Static. You need a visible mesh with triangle surfaces, normals and a second UV channel.
Prepare nonoverlapping UV2 islands with adequate separation. Ordinary repeating-texture UVs do not replace UV2: distinct faces need distinct atlas space.
Check object scale, normals and wall thickness before baking. More rays will not repair a bad unwrap or a ceiling hole.

Mesh source	Preparation
Imported 3D model	Select Static Lightmaps preparation during import and reimport. Check UV2 and map size on the resulting mesh.
Authored UV2 from a 3D editor	Check overlap and sufficient Lightmap Size Hint; a second channel existing does not establish suitability.
BoxMesh and other PrimitiveMesh resources	Enable `AddUV2` on the mesh resource. Adjust `UV2Padding` if needed.
Procedural geometry	Prepare UV2, normals, map size and level ownership. Helper Entities not owned by the saved level may be skipped during traversal.

Manual changes to an imported mesh can be lost on the next import. Put persistent preparation into import settings or the source model.

Distinguish density from atlas size

Import Lightmap Texel Size: a smaller world distance per texel means higher density.
LightmapGI.TexelScale: scales mesh map dimensions; a larger value increases required texture area.
GeometryInstance3D.GILightmapTexelScale: changes density for an individual instance.
MaxTextureSize: caps one atlas texture rather than choosing every object's detail. The current setter accepts 2048…16384. The actual atlas can be smaller than that cap.

Start with suitable UV2 and reasonable density on important surfaces, then adjust atlas limits and quality.

Choose light modes

Light BakeMode	Baked contribution
`Disabled`	Excludes the light from baking. Use for lighting that should operate only at runtime.
`Dynamic`	Bakes indirect contribution; direct light and its shadows remain dynamic. Runtime light changes do not recalculate the saved indirect contribution.
`Static`	Bakes direct and indirect contribution for static receivers. Light changes do not update saved maps.

Hiding Light3D does not replace BakeMode = Disabled: the current collector selects lights by BakeMode without checking Visible. Change the mode to exclude a light, then rebake.

If a light will move or switch off, decide whether its old baked contribution is acceptable. Dynamic does not mean dynamic lightmap rewriting.

Bake and save

Select LightmapGI and invoke Bake Lightmaps in the 3D editor. The current C# SDK does not expose LightmapGI.Bake(); do not substitute an invented method call for the editor action.
Choose a .lmbake data path for the first bake. This differs from the .rbin destination in the VoxelGI workflow.
Wait for completion. Inspect assigned LightData, mesh users and generated atlases. A completion message or empty data file alone does not prove lighting was calculated.
Save the level. Keep .lmbake, generated source atlases and their import settings together; the data file alone does not replace its dependencies.
Reopen the saved level and run it. For final acceptance also run an exported game on the target platform.

Renaming or moving baked meshes may break receiver-path matches. Rebake and inspect warnings about missing receivers.

Adjust quality

Setting	What to inspect
Quality and bounce count	Noise and light coverage. More work does not repair UV2 or incorrect geometry.
UseDenoiser	Noise reduction versus fine-shadow preservation. Inspect smoothing artifacts as well as the overall view.
Directional	Additional directional information for normal-mapped materials. Changes stored data, cost and result size.
Supersampling	Higher calculation resolution followed by downsampling. Increases memory and time requirements.
EnvironmentMode	Whether environment contribution belongs in the bake. Start with Disabled for a closed diagnostic room if appropriate.
Bias	Self-occlusion artifacts and leaks. Increasing bias does not replace wall thickness or correct normals.

Inspect bake-affecting settings after rebaking. Changing an option without recalculation does not update saved textures.

Moving objects do not obtain a newly baked UV2 map from an old bake. Configure lightmap probes and direct lighting for them separately; this does not let them arbitrarily change static-level baked shadows or indirect lighting. Reflections and reflected light stored in a texture are also distinct: check sky, reflection probes and materials.

Diagnose a wrong result

No meshes with lightmapping support: check Static, visibility, triangle surfaces, normals, UV2 and traversal scope.
No save path: save the level and select .lmbake data. ResourceSaver saving a new Resource does not itself guarantee ResourcePath assignment.
Map too small: check Lightmap Size Hint and TexelScale. A larger atlas cap does not fix a zero final map dimension.
Seams, bright edges or splotches: check UV2, padding, density, normals and compression, then ray count and denoising.
Light remains after switching off a lamp: check whether direct or indirect contribution was baked. Change the lighting approach or rebake.
Geometry changes leave old shadows: the data is static; recalculate and save the updated level.

For this article an isolated project exercised native GPU baking through the current editor plugin, nonzero atlas light, saving, independent .lmbake loading and saved-level rendering with the direct light disabled. Editor shutdown retained Scan thread aborted: the run is not marked completely clean. Export, dynamic probes, directional/shadowmask and every material's quality were not tested here.

Compare VoxelGI, SDFGI and the GI overview.