baking

Bake a scene's lighting so it stops being recomputed every frame. This is the optimization surface: turn static lighting into baked lightmaps, place irradiance light probes for the movers, place reflection probes for shiny surfaces, and detect what still needs baking — each in one call, with automatic placement and sane defaults.

The whole point is to reach optimized content without hand-placing anything. You do not scatter probes one by one or attach a component to every surface. You name a scope (or the whole scene) and the tool resolves the set, places what is needed, and bakes it.

Mobility decides who bakes

Model.mobility ("auto" | "static" | "movable") is the single selection axis. Static geometry receives lightmaps and occludes baked light; movable geometry (and every player) samples probe volumes. "auto" derives the answer from the entity's components (physics bodies, skinned meshes, animation, movers). baking.mobility shows every derivation and batch-overrides the field where the derivation is wrong.

Static surfaces whose UVs tile or overlap cannot hold a per-texel lightmap; the lightmap pass binds them to the covering probe volume automatically and reports them as probeLit.

The flow

1. Build the scene and set up its lighting (the lighting toolbox).
2. baking.detect — see what is unbaked and why (static surfaces with no lightmap, shadow-casting lights re-rendering every frame, movers with no probe coverage, no reflection probe).
3. baking.all — the whole GI pass in one call: an auto-placed irradiance probe volume, static lightmaps (tiled-UV surfaces routed to that probe field), and auto-placed reflection probes.
4. Verify: baking.detect again should come back clean.

When to reach for each

• baking.all — the finish move. Run it once a static scene is dressed.
• baking.mobility — inspect or batch-set geometry mobility (the exclusion switch when a derivation is wrong).
• baking.lightmaps — bake static surfaces in a scope to per-surface lightmaps (full irradiance: direct + multi-bounce indirect).
• baking.probes — auto-place irradiance probe volumes where the lights are (point/spot lights are clustered and one volume is placed per cluster, up to maxVolumes), so moving entities pick up baked indirect light.
• baking.reflections — auto-place reflection probes across the scene so metallic/reflective surfaces mirror their surroundings.
• baking.showProbes — visualize the baked irradiance field with color-coded markers.
• baking.detect — the coverage check. What needs baking / re-baking and why.
• baking.clear — tear baked GI down to re-bake from a clean slate.

Placement is automatic — do not hand-place

Light probes are placed from where light actually is: the tool gathers the scene's point/spot lights, clusters them by overlapping influence, and places one volume per cluster (capped by maxVolumes, merging the nearest clusters). Each volume's probe density comes from spacing, with a per-volume cap of maxProbes. Reflection probes are spread across the scene's geometry bounds. You steer with typed knobs (spacing, maxProbes, maxVolumes, padding, samples for light probes; count and radius for reflection probes), not coordinates. Placing probes by hand, one at a time, is the pattern this toolbox exists to replace — a scene full of hand-dropped probes is unoptimized content that took more effort to make.

Baking is a static-content step: bake once the geometry and static lights are settled, and re-bake (or baking.detect) when they change. Things that genuinely move every frame stay realtime; everything else should end up baked.