t1k:unity:rendering:light-baking

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	rendering
Version	3.1.7
Effort	high
Tools	—

Keywords: global illumination, light baking, lightmap, unity

How to invoke

/t1k:unity:rendering:light-baking

---

Unity Light Baking Skill (DOTS-Safe)

Triggers

• 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

Reusable Module

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

Menu Items

Menu Path	Action
Tools/[YourPackage]/Bake Lighting (GPU)	Progressive GPU bake with DOTS-safe workflow
Tools/[YourPackage]/Bake Lighting (CPU)	Progressive CPU fallback
Tools/[YourPackage]/Cancel Lighting Bake	Cancel in-progress bake
Tools/[YourPackage]/Clear Entity Scene Cache	Delete Library/EntityScenes/
Tools/[YourPackage]/Revert Light to Realtime	Emergency revert + cache clear

API

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

DOTS-Safe Bake Workflow

The Problem

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

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.

Correct Bake Workflow

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. Clear Library/EntityScenes/ cache (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

LightBakeUtility Workflow (automated)

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.

Companion Module: MeshLightmapHelper

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.

Gotchas

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. MCP temp camera bypasses culling — manage_scene(screenshot) creates a temp camera that doesn’t respect frustum culling. Always verify in Game view, not MCP screenshots
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

MCP Integration

# Trigger bake via MCP
execute_menu_item("Tools/[YourPackage]/Bake Lighting (GPU)")

# Check progress
read_console(filter_text="LightBakeUtility")

# Emergency revert
execute_menu_item("Tools/[YourPackage]/Revert Light to Realtime")

# Verify entity visibility after bake
manage_editor(action="play")  # Enter play mode
rendering_stats(action="get_stats")  # Check draw calls

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