t1k:unity:rendering:light-baking
| Field | Value |
|---|---|
| Module | rendering |
| Version | 5.39.1 |
| Effort | high |
| Tools | — |
Keywords: global illumination, light baking, lightmap
How to invoke
Section titled “How to invoke”/t1k:unity:rendering:light-bakingUnity Light Baking Skill (DOTS-Safe)
Section titled “Unity Light Baking Skill (DOTS-Safe)”Triggers
Section titled “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
Section titled “Reusable Module”Package: Packages/[your-package]/Editor/LightBakeUtility.cs
Namespace: [YourPackage].Editor
Menu Items
Section titled “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 | Rename Library/EntityScenes/ aside. Close the Editor first; rename, never delete (the Editor may hold files open) |
Tools/[YourPackage]/Revert Light to Realtime | Emergency revert + cache clear |
// Full safe bake (sets Mixed, configures, bakes, auto-clears cache on completion)LightBakeUtility.ConfigureAndBake(LightingSettings.Lightmapper.ProgressiveGPU);
// Individual stepsLightBakeUtility.SetDirectionalLightToMixed();LightBakeUtility.ClearEntitySceneCache();LightBakeUtility.RevertDirectionalLightToRealtime();DOTS-Safe Bake Workflow
Section titled “DOTS-Safe Bake Workflow”The Problem
Section titled “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
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.
Correct Bake Workflow
Section titled “Correct Bake Workflow”- Open SubScene for editing (click “Edit SubScene” or double-click in Hierarchy)
- Set directional light to
LightmapBakeType.Mixed - Configure lightmapper (Progressive GPU preferred, CPU fallback)
- Bake asynchronously (with SubScene still open)
- On completion: Close SubScene — lightmaps auto-convert into SubScene data
- Rename
Library/EntityScenes/aside with the Editor closed (rename, not delete; auto-done by LightBakeUtility) - Re-enter Play mode to verify entities visible in Game view
- If broken: Run
Tools/[YourPackage]/Revert Light to Realtime
LightBakeUtility Workflow (automated)
Section titled “LightBakeUtility Workflow (automated)”- Call
LightBakeUtility.ConfigureAndBake()— sets Mixed, configures, bakes, auto-clears cache - User must manually: Open SubScene before baking, close after completion
- Re-enter Play mode to verify
→ See references/lightmapper-config.md for default settings, prerequisites, and troubleshooting.
Companion Module: MeshLightmapHelper
Section titled “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.
Hard rules
Section titled “Hard rules”- ⚠️ 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
ChunkWorldRenderBoundswith NaN values in the SCENE FILE itself. ClearingLibrary/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 rawgit 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 popif you need to recover non-bake edits. If the file is also dirty in another collaborator’s worktree (rare), confirm with them before anygit checkout. - 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 unityfacade has no screenshot verb: capture manually, or viat1k unity evalcallingScreenCapture.CaptureScreenshot(path)in Play mode (unverified live) - Shadowmask NOT supported by Entities Graphics — use
MixedLightingMode.IndirectOnlyonly - GPU lightmapper needs OpenCL — Falls back to CPU if unavailable (much slower)
- SubScene = 1 lightmap per SubScene — fine for single SubScene setups
- Forward+ has no GBuffer — doesn’t affect lightmap baking, only impostor baking
- Bake with scene saved — Always save scene before baking to prevent data loss on crash
t1k unity Integration
Section titled “t1k unity Integration”# Trigger baket1k unity menu 'Tools/[YourPackage]/Bake Lighting (GPU)'
# Check progresst1k unity console --grep LightBakeUtility
# Emergency revertt1k unity menu 'Tools/[YourPackage]/Revert Light to Realtime'
# Verify entity visibility after baket1k unity play enter # Enter play modet1k 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.
Visual change notice
Section titled “Visual change notice”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:
ScreenCapturein Play mode pert1k-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.