Skip to content

t1k:unity:rendering:light-baking

FieldValue
Modulerendering
Version5.39.1
Efforthigh
Tools—

Keywords: global illumination, light baking, lightmap

/t1k:unity:rendering:light-baking

  • lightmap, lightmap bake, bake lighting, generate lighting
  • Progressive GPU, Progressive CPU, lightmapper
  • mixed lighting, baked indirect, IndirectOnly
  • light probe baking, lightmap resolution
  • ChunkWorldRenderBounds, NaN corruption, invisible entities after baking

Package: Packages/[your-package]/Editor/LightBakeUtility.cs Namespace: [YourPackage].Editor

Menu PathAction
Tools/[YourPackage]/Bake Lighting (GPU)Progressive GPU bake with DOTS-safe workflow
Tools/[YourPackage]/Bake Lighting (CPU)Progressive CPU fallback
Tools/[YourPackage]/Cancel Lighting BakeCancel in-progress bake
Tools/[YourPackage]/Clear Entity Scene CacheRename Library/EntityScenes/ aside. Close the Editor first; rename, never delete (the Editor may hold files open)
Tools/[YourPackage]/Revert Light to RealtimeEmergency revert + cache clear
// Full safe bake (sets Mixed, configures, bakes, auto-clears cache on completion)
LightBakeUtility.ConfigureAndBake(LightingSettings.Lightmapper.ProgressiveGPU);
// Individual steps
LightBakeUtility.SetDirectionalLightToMixed();
LightBakeUtility.ClearEntitySceneCache();
LightBakeUtility.RevertDirectionalLightToRealtime();

Unity Entities Graphics stores ChunkWorldRenderBounds as chunk components. When lightmaps are baked with SubScenes closed, the lightmap data cannot be properly converted into SubScene entity data, corrupting bounds with NaN values. NaN propagates through bounds aggregation — entire chunk gets frustum-culled — ALL entities in that chunk become invisible.

⚠️ CRITICAL: SubScene Must Be OPEN During Bake

Section titled “⚠️ CRITICAL: SubScene Must Be OPEN During Bake”

Per official Entities Graphics 1.4 docs:

“You will need to bake with subscenes open, upon closing the lightmaps will be converted into the subscene.”

Baking with SubScene closed = NaN corruption in ChunkWorldRenderBounds.

  1. Open SubScene for editing (click “Edit SubScene” or double-click in Hierarchy)
  2. Set directional light to LightmapBakeType.Mixed
  3. Configure lightmapper (Progressive GPU preferred, CPU fallback)
  4. Bake asynchronously (with SubScene still open)
  5. On completion: Close SubScene — lightmaps auto-convert into SubScene data
  6. Rename Library/EntityScenes/ aside with the Editor closed (rename, not delete; auto-done by LightBakeUtility)
  7. Re-enter Play mode to verify entities visible in Game view
  8. If broken: Run Tools/[YourPackage]/Revert Light to Realtime
  1. Call LightBakeUtility.ConfigureAndBake() — sets Mixed, configures, bakes, auto-clears cache
  2. User must manually: Open SubScene before baking, close after completion
  3. Re-enter Play mode to verify

→ See references/lightmapper-config.md for default settings, prerequisites, and troubleshooting.

File: Packages/[your-package]/Editor/MeshLightmapHelper.cs

Reusable UV2 generation for lightmap baking:

// Planar XZ projection for procedural terrain meshes (no UV0)
MeshLightmapHelper.GeneratePlanarUV2(mesh);
// Unity Unwrapping for imported meshes (FBX/OBJ with UV0)
MeshLightmapHelper.GenerateSecondaryUVs(mesh);
// Auto-process all static children (copies mesh, generates UV2)
MeshLightmapHelper.EnsureUV2ForStaticChildren(rootGameObject);

LightBakeUtility.EnsureSceneUV2() auto-calls this for ALL static root objects before baking.

  1. ⚠️ CRITICAL: SubScene MUST be OPEN during lightmap bake — Per official docs: “You will need to bake with subscenes open, upon closing the lightmaps will be converted into the subscene.” Baking with SubScene closed corrupts ChunkWorldRenderBounds with NaN values in the SCENE FILE itself. Clearing Library/EntityScenes/ is NOT sufficient — the scene file itself is corrupted. Always open SubScene before baking, close after completion. Recovery (Blocker — destructive op safety): if you hit the corruption, do NOT raw git checkout -- <scene>.unity — that silently discards any unrelated in-progress work in the same file. Correct sequence: (a) git stash push -m "pre-recover" -- <scene>.unity (preserves your uncommitted work), (b) git checkout HEAD -- <scene>.unity (restores known-good), (c) verify scene loads cleanly in Unity, (d) git stash pop if you need to recover non-bake edits. If the file is also dirty in another collaborator’s worktree (rare), confirm with them before any git checkout.
  2. A temp-camera screenshot bypasses culling — a screenshot from a temporary or Scene-view camera does not respect frustum culling. Always verify in the Game view. The t1k unity facade has no screenshot verb: capture manually, or via t1k unity eval calling ScreenCapture.CaptureScreenshot(path) in Play mode (unverified live)
  3. Shadowmask NOT supported by Entities Graphics — use MixedLightingMode.IndirectOnly only
  4. GPU lightmapper needs OpenCL — Falls back to CPU if unavailable (much slower)
  5. SubScene = 1 lightmap per SubScene — fine for single SubScene setups
  6. Forward+ has no GBuffer — doesn’t affect lightmap baking, only impostor baking
  7. Bake with scene saved — Always save scene before baking to prevent data loss on crash
# Trigger bake
t1k unity menu 'Tools/[YourPackage]/Bake Lighting (GPU)'
# Check progress
t1k unity console --grep LightBakeUtility
# Emergency revert
t1k unity menu 'Tools/[YourPackage]/Revert Light to Realtime'
# Verify entity visibility after bake
t1k unity play enter # Enter play mode
t1k unity dots get_render_stats # DOTS render stats (draw-call counters need the Profiler: no facade verb)

→ See references/lightmapper-config.md for troubleshooting steps.

A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:

  • Capture OLD before the first edit and NEW after the last (screen: ScreenCapture in Play mode per t1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file).
  • Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending: ”, never a fake image.