lecodes-sdk 1.0.0 → 1.2.0

package/src/gl/Lightmap.ts

@@ -1,145 +1,204 @@
-// Baked lighting for static 3D geometry (docs/lightmap-plan.md). A scene FILE does all of this by
-// itself: `env: { lightmap: { data, texture } }` marks the level as baked, every model/mesh node
+// Baked lighting for static 3D geometry (packages/creator-bake). A scene FILE does all of this by
+// itself: `env: { lightmap: { data, light, aux } }` marks the level as baked, every model/mesh node
 // that no Physics aspect moves is a static (keys = node paths, `lightmap: true|false` overrides),
 // and the runtime applies the bake when the level finishes loading (scene/defineScene.ts).
 // Hand-built scenes register what never moves with `Lightmap.add`, bake once with
-// `lecodes lightmap bake` (the desktop host traces the live scene and writes lightmap.ktx2 +
-// lightmap.bake), and `Lightmap.load` applies the atlas at runtime:
+// `lecodes lightmap bake` (the desktop host describes the live scene to creator-bake, which traces it
+// on the NVIDIA card and writes the atlas), and `Lightmap.load` applies it at runtime:
 //
 //   const crate = await Model.load(asset('./assets/props/crate.glb'), { lightmap: true })
 //   Lightmap.add(holder)                    // a Model, a Mesh, or a node holding them
-//   Lightmap.add(ground)                    // Mesh.plane works too
 //   ...
-//   await Lightmap.load(scene, { data: asset('./assets/lightmap/lightmap.bake'),
-//                                texture: asset('./assets/lightmap/lightmap.ktx2') })
+//   await Lightmap.load(scene, { data: asset('./assets/lightmap/level.bake'),
+//                                light: asset('./assets/lightmap/level-light.ktx2'),
+//                                aux: asset('./assets/lightmap/level-aux.ktx2'),
+//                                probes: asset('./assets/lightmap/level-probes.ktx2') })
 //
-// Both files are asset() handles because the compiler stages exactly the files it sees (the data
-// file is JSON with a .bake extension — a .json would be scanned as a code module). `load` is a
-// no-op when the bake is missing or the host predates the feature, so the project stays runnable —
-// and in BAKE mode (`lecodes lightmap bake`) it is where the bake fires: the same call marks "the
-// scene is complete". Atlas channels: R = sun visibility, G = ambient occlusion; the shader keeps
-// the real-time sun for dynamic casters and multiplies the baked mask in with an ambient floor.
+// `probes` (optional) is the bake's REFLECTION PROBES — the level's radiance traced by the same bake from a grid of
+// points, prefiltered per roughness, one octahedral tile column per probe in one atlas; every pixel of a static
+// blends the probes around it (the .bake carries the grid). Without the file a static's specular reflects the
+// sky's SH alone.
 //
-// PAGES: a large level takes more than one atlas (`--pages`); `texture` is then every page in order.
+// The files are asset() handles because the compiler stages exactly the files it sees (the data file
+// is JSON with a .bake extension — a .json would be scanned as a code module). `load` is a no-op when
+// the bake is missing or the host predates the feature, so the project stays runnable — and in BAKE
+// mode (`lecodes lightmap bake`) it is where the bake fires: the same call marks "the scene is complete".
 //
-// POINT LIGHTS: the bake traces the scene's point lights too (filament's own candela / falloff
-// math, shadow rays) into a second RGB atlas — pass it as `light` — and lists them in the .bake;
-// once that atlas applies, the real-time lights it carries are switched off (`Light.point({ baked:
-// false })` keeps one live and out of the bake). Statics read the lamps from the atlas, movers from
-// the volume's light block — for the price of nothing per frame.
+// What a static gets: its whole DIFFUSE light from the atlas — the sun, the sky and the lamps that the
+// bake traced onto it, in lux — and nothing from the real-time sun or lamps (the engine keeps those
+// off baked renderables through light channels). Movers, glass and anything loaded without
+// `lightmap: true` stay real-time. A lamp that must light statics live too (`Light.point({ baked:
+// false })`) is put on the statics' channel and kept out of the bake.
 //
-// DYNAMIC objects (docs/lightmap-plan.md §9): the bake also writes lightmap.volume — the same
-// channels on a 3D grid over the level. Pass it as `volume` and every model loaded with
-// `{ lightmap: 'dynamic' }` (the default while a scene file with `env.lightmap.volume` runs) plus
-// every dynamic Mesh a scene file registers samples it per pixel: a crate rolled under the roof
-// loses the sun like the floor does, a character near a wall picks up its ambient occlusion.
+// Debugging: `Lightmap.debug(mode)` switches every lightmapped surface to a DATA view (irradiance,
+// albedo, normals, visibilities, the atlas checker, the light direction, false-colour lux) and
+// `Lightmap.probe(x, y)` names the texel under a screen point. View 1 ("irradiance") is the lighting alone:
+// a white diffuse material under the camera's exposure. Views "direct" / "indirect" show the bake's two
+// halves: a bake made with `--split` writes them as page sets of their own, the scene lists them as
+// `direct` / `indirect` next to `light`, and the view binds those pages in place of `light` (the shading
+// is untouched — it is the same material reading other pages). The bake's `--debug-dir` keeps the
+// float layers `lecodes lightmap inspect` reads.
 
 import { fetch } from "../runtime/fetch"
 import { Texture } from "./Texture"
 import { Material } from "./Material"
 import { Mesh } from "./Mesh"
 import { Model } from "./Model"
-import { Node } from "./Node"
+import { Node, nodeRegistry } from "./Node"
 import { Light } from "./Light"
-import { cx, cy, cz } from "../math/vec"
 import type { Scene } from "./Scene"
 
 export type LightmapLoadOptions = {
-  /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
-  sunStrength?: number
-  /** Multiplier on the ambient (IBL) share in the shadow math — how bright a fully shadowed texel
-   *  stays. 1 reproduces filament's own real-time shadow darkness (the shader reads the scene's sun
-   *  and IBL from filament's per-frame uniforms); raise it for lighter shadows, lower for deeper. Default 1. */
-  ambientScale?: number
-  /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by
-   *  its ambient probe alone can want less than the geometric truth. Default 1. */
-  aoStrength?: number
-  /** Multiplier on the baked point lights' irradiance (default 1). Purely ARTISTIC: the bake is
-   *  physical (verified against the analytic 1/d^2 sum over the level's lamps - where line of sight
-   *  is clear the two agree within ~17 %), and a room lit to its real illuminance simply reads dim
-   *  against an ambient fill. This dials the lamps up without a re-bake, since their irradiance is
-   *  IN the atlas and `--lamp-gain` would cost a full one.
-   *  It scales the atlas AND the light volume together, so statics and movers stay consistent - but
-   *  note they are NOT equally forgiving: a static surface carries the bake's own cosine and
-   *  shadowing, while a mover reads the volume through a flat half-cosine, so a large boost blows
-   *  movers out long before it blows out the level. Past ~x100 expect to light the movers
-   *  separately. */
-  lightBoost?: number
-  /** Multiplier on the light VOLUME's irradiance alone — the movers' own `lightBoost`. Default =
-   *  `lightBoost`, and since 2026-08-31 that default is the right one: the volume is an ambient cube
-   *  (irradiance per axis face, blended by the pixel's normal), so a mover's top takes a lamp above it
-   *  and its underside does not — the same shading the atlas gives the statics. Before that the volume
-   *  was one flat 0.5·E on every face and this knob was the workaround. Kept as a trim. */
-  volumeBoost?: number
-  /** What an OCCLUDER-only static (a prop without lightmap UVs — traced into the receivers' atlas but
-   *  carrying no rect of its own) does in real time. `"baked"` (default): its shadow is in the bake, so
-   *  it stops casting and the shadow pass draws only the movers — on a level of thousands of foliage
-   *  cards that is a third of the GPU frame. `"realtime"`: it keeps casting, which is the only way its
-   *  shadow reaches OTHER non-receiver props (a rock under a tree); the honest fix for that is lightmap
-   *  UVs on the props (`lecodes assets doctor --lightmap-uv`), which makes them receivers. */
-  occluderShadows?: "baked" | "realtime"
+  /** A DEBUG multiplier on the atlas' lux (default 1): the atlas is physical, so this is a knob for looking,
+   *  not a look. */
+  lightScale?: number
+  /** The level's own radiance of emission 1.0 for the BAKE (cd / m², `BakeConfig.emissiveNits`): an imported pack's
+   *  emissive values are tuned for a look, not for light - this is where the level says how much its panels really give.
+   *  The CLI's `--emissive-nits` wins over it; without either the camera's exposure decides. */
+  emissiveNits?: number
+  /** `false` = the emissive surfaces light NOTHING in the bake (the level is lit by its lamps, the panels are decoration)
+   *  while `emissiveNits` still says how bright their glow is drawn. Default true. */
+  emissiveBake?: boolean
+  /** FOR THE BAKE: materials that let light THROUGH them, by their glTF name (`"name*"` = every name with that start):
+   *  the share of a shadow ray that passes, tinted by the material's base colour x map - an awning's warm, patterned light
+   *  on the sand. The surface itself stays opaque: baked, drawn as before, a real-time shadow caster.
+   *  A number = the share that goes STRAIGHT through (the gaps of a weave: it draws the map's picture on the ground);
+   *  `{ through, diffuse }` adds the share the fibres SCATTER - the cloth's underside glows like a matte panel and lights
+   *  what is under it by the solid angle it fills, with no picture. Dense canvas: `{ through: 0.08, diffuse: 0.25 }`. */
+  transmit?: Record<string, LightmapTransmit>
 }
 
+/** one `transmit` entry (LightmapLoadOptions.transmit): the straight share, or both shares */
+export type LightmapTransmit = number | { through?: number, diffuse?: number }
+
 export type LightmapInfo = {
   size: number
   texel: number
-  /** Atlas pages the bake took (`texture` lists them in order). */
+  /** Atlas pages the bake took (`light` / `aux` list them in order). */
   pages: number
-  /** The light volume, when one was loaded: grid dims + cell size in metres. */
-  volume?: { dims: number[], cell: number }
-  /** Point lights the bake carries and this load switched off (statics read them from the atlas,
-   *  movers from the volume); 0 without a `light` atlas. */
-  lights: number
   /** keys applied / keys in the file / registered statics without a rect */
   applied: number
   total: number
   missing: string[]
-  /** Occluder-only statics whose real-time shadow was switched off (`occluderShadows: "baked"`). */
-  occluders: number
 }
 
 export type LightmapFiles = {
   data: string
-  /** The atlas — one page, or every page in order for a bake that took several. */
-  texture: string | string[]
-  /** The point lights' baked irradiance (pages like `texture`). */
-  light?: string | string[]
+  /** The irradiance atlas — one page, or every page in order for a bake that took several. */
+  light: string | string[]
+  /** The aux atlas (sun / sky visibility + light direction), pages like `light`. */
+  aux: string | string[]
+  /** DEBUG: the direct-light-only pages a `--split` bake wrote (`<stem>-direct[_n].ktx2`), for the "direct" view. */
+  direct?: string | string[]
+  /** DEBUG: the bounce-only pages of a `--split` bake (`<stem>-indirect[_n].ktx2`), for the "indirect" view. */
+  indirect?: string | string[]
+  /** The reflection probes (`<stem>-probes.ktx2`), when the bake placed some (`lecodes lightmap bake --probe-spacing`). */
+  probes?: string
+  /** THE LIGHT GRID for movers (`<stem>.lgrid`, `lecodes lightmap bake --volume`): the baked ambient light of every
+   *  place a mover can be. Absent = movers keep the scene's IBL. */
   volume?: string
 }
 
-import type { Terrain } from "./terrain/Terrain"
+/** The lightmap material's data views (`Lightmap.debug`); "direct" / "indirect" bind a `--split` bake's pages instead. */
+export type LightmapDebugMode = "off" | "irradiance" | "albedo" | "normal" | "shadingNormal" | "share" | "skyVis" | "atlas" | "direction" | "lux" | "relief" | "direct" | "indirect" | "probe" | "probeMap" | "skyPath" | "probePath"
+const DENOISE_LEVELS = { none: 0, indirect: 1, "no-sun": 2, all: 3 } as const
+const DEBUG_MODES: LightmapDebugMode[] = [ "off", "irradiance", "albedo", "normal", "shadingNormal", "share", "skyVis", "atlas", "direction", "lux", "relief", "direct", "indirect", "probe", "probeMap", "skyPath", "probePath" ]
+const PAGE_VIEWS: Record<number, "direct" | "indirect"> = { 11: "direct", 12: "indirect" }
+
+export type LightmapDebugParams = {
+  /** `lux`: the false-colour ramp's log10 range (default 0..5, i.e. 1 lux .. 100 000). */
+  luxRange?: [number, number]
+}
 
-type Entry = { key: string, model?: Model, mesh?: Mesh, terrain?: Terrain }
+/** What `Lightmap.probe` answers: the baked texel under a screen point. */
+export type LightmapProbe = {
+  key: string
+  entity: number
+  node: string
+  material: string
+  page: number
+  /** The texel's column / row on its page. */
+  texel: [number, number]
+  uv1: [number, number]
+  world: [number, number, number]
+  distance: number
+}
 
-const terrainOf = (n: Node): Terrain | null => (n as unknown as { _terrain?: Terrain })._terrain ?? null
+/** `ground` = a terrain node (built with `Material.terrainLightmap()`): one rect, bound to its chunks by the host */
+type Entry = { key: string, model?: Model, mesh?: Mesh, ground?: Node }
 
 type BakeConfig = {
-  outDir: string, size?: number, texel?: number, sunRays?: number, aoRays?: number,
-  aoDistance?: number, bias?: number, sunAngle?: number, volumeCell?: number,
-  pages?: number, lightRays?: number, lightRadius?: number,
-  /** One bounce of indirect light from the point lights, gathered on the AO rays. The value is the
-   *  ALBEDO the bounce assumes for every surface it hits (0 = off; ~0.35 is concrete). A bake with
-   *  no bounce lights only what a lamp sees directly - in an interior that leaves the walls between
-   *  the fixtures black, and a cast shadow invisible for want of light to be missing from. */
-  bounce?: number, bounceDistance?: number, bounceRays?: number,
-  /** Metres within which an occluder PARALLEL to the surface being lit is ignored (default 0.05).
-   *  A modular kit stacks two wall pieces in the same place; to the bake they are coincident and
-   *  the AO goes black in hard-edged patches. Real contact shadows are unaffected - they come off
-   *  surfaces at an angle. 0 turns it off. */
-  coplanarSkip?: number,
-  /** Radius (px) of the geometry-aware denoise over the traced texels (default 2, 0 = off): the
-   *  Monte-Carlo grain goes, edges of geometry stay. */
-  denoise?: number,
+  outDir: string, stem: string, size?: number, texel?: number, pages?: number,
+  sunRays?: number, skyRays?: number, lightRays?: number, lightRadius?: number, sunAngle?: number, bias?: number, seed?: number,
+  bounceRays?: number, bounces?: number, patchSamples?: number, split?: boolean,
+  /** OptiX's AI denoiser: `"no-sun"` (the default) the bounce, the sky and the lamps, `"indirect"` the bounce alone, `"all"` + the sun (its shadow edges too), `"none"`. */
+  denoise?: "none" | "indirect" | "no-sun" | "all",
+  /** The texel's reconstruction filter radius in texels: 1 (the default) = a ±1 texel tent, 0.5 = within the texel, 0 = the centre alone. */
+  filter?: number,
+  /** Reflection probes: the grid spacing in metres (4; 0 = none), a probe face's edge in texels (32) and the paths per probe texel (128). */
+  probeSpacing?: number, probeSize?: number, probeRays?: number,
+  /** Keep only the probes under a roof (a closed top, fewer than three open sides). Outdoor statics then reflect the sky through
+   *  their baked sky visibility, like an environment map without the ground; no outdoor probe can reach indoors and the
+   *  atlas shrinks. Default false. */
+  probeIndoor?: boolean,
+  /** Where the probes go. "rooms" (the default): every indoor point of the grid slides to the middle of its room and the
+   *  points of one room merge — one probe per room, far from the walls, its box the room (stations every ~8 m along a
+   *  room over 12 m); outdoor points stay on the grid. "grid": everything stays on the grid. Either way the bake records, per block of atlas
+   *  texels, the two probes those texels SEE (rays), so no probe reflects through a wall. */
+  probeLayout?: "rooms" | "grid",
+  /** Instances smaller than this many ATLAS TEXELS along every axis (x `texel` metres: 12 at 5 cm = 0.6 m) get no place
+   *  in the atlas: they still cast their baked shadow and bounce - the wall keeps their shadow - and take their own light
+   *  from an ambient cube baked where they stand. In texels and not metres: what cannot hold a lightmap is a matter of
+   *  how many texels it gets (a fire extinguisher of 0.55 m: 300 charts, the largest 29 texels - every chart edge a step).
+   *  0 = everything bakes. Default 12. */
+  minTexels?: number,
+  /** THE LIGHT GRID for movers: the cell size in metres (0.75 of it tall); 0 = none. Default 1. */
+  volumeSpacing?: number,
+  /** A SMALL SURFACE GETS A FINER TEXEL: an instance whose surface is under this many atlas texels (area / texel²) is laid
+   *  out denser by sqrt(detailTexels / its texels), 3x at most - a pipe of 1 m is ~300 texels at 5 cm, its charts a few
+   *  texels wide and every chart edge a step. Default 2000; 0 = off. */
+  detailTexels?: number,
+  /** EMISSIVE SURFACES LIGHT THE LEVEL: the radiance in cd / m² of emission 1.0 (a material's emissive factor x strength x
+   *  map) - every lit region of an emissive surface becomes a rectangle lamp in the bake (a ceiling panel drawn in the
+   *  ceiling's texture, a screen, a sign). Default: what the level's CAMERA makes of emission 1.0, `1.2 x 2^ev100` - the
+   *  engine draws emission screen-referred, so a panel then lights the room as brightly as it looks. 0 = they light nothing. */
+  emissiveNits?: number,
+  /** Only grid cells whose centre lies inside this world box get a probe (min xyz, max xyz) — keeps probes off a roof top the
+   *  player never sees. Default: the receivers' bounds. */
+  probeBox?: [number, number, number, number, number, number],
+  debugDir?: string,
 }
 
-type VolumeHeader = { texture: number, dims: number[], min: number[], cell: number, light?: number, faces?: number }
-
+/** a small static's light where it stands (creator-bake objects.h): per side of its bounds (+x -x +y -y +z -z) the
+ *  irradiance rgb in lux + the sky visibility; probes = a, b, a's weight (-1 = none, -2 = the sky) */
+type BakeObjectLight = { at: number[], cube: number[][], probes: number[] }
+type BakeInstance = { key: string, receiver: boolean, small?: boolean, light?: BakeObjectLight, page?: number, rect?: number[], st?: number[] }
+type BakeProbes = {
+  file: string, size: number, levels: number, count: number, oct: number, tile: number[], perRow: number, atlas: number[],
+  spacing: number, layout: "rooms" | "grid",
+  /** the block size of the pages' probe maps (atlas texels) and the range their records decode with: lo xyz, size xyz */
+  map: number, encode: number[],
+  positions: number[][], boxes: number[][],
+  /** per probe: its open share of the sphere (0 = a room, over 0.15 = under the sky) */
+  sky: number[],
+}
 type BakeData = {
-  version?: number, size: number, texel: number, pages?: number, textures?: string[],
-  lightTextures?: string[], lightScale?: number, lightGamma?: number,
-  lights?: { p: number[], color: number[], cd: number, range: number }[],
-  sun?: number[] | null,
-  instances: { key: string, receiver: boolean, st?: number[], page?: number }[],
+  version: number, size: number, pages: number, texel: number, lightScale: number,
+  light: string[], aux: string[], direct?: string[], indirect?: string[],
+  probes?: BakeProbes | null,
+  /** the light grid (creator-bake volume.h): its file and lattice */
+  volume?: { file: string, n: number[], origin: number[], cell: number[], valid: number } | null,
+  sun?: { direction: number[], color: number[], lux: number } | null, sunMap?: boolean, sunMapLevels?: number, mips?: number, emissiveNits?: number,
+  instances: BakeInstance[],
+}
+type PageKind = "light" | "direct" | "indirect"
+type Bound = {
+  data: BakeData, rects: Map<string, BakeInstance>, byEntity: Map<number, Entry>, files: LightmapFiles, pages: number,
+  aux: Texture[], light: Texture[], direct?: Texture[], indirect?: Texture[],
+  /** how many reflection probes the host holds (0 = none loaded), and their atlas */
+  probes: number, probeAtlas?: Texture,
+  /** which page set the surfaces read right now */
+  showing: PageKind,
 }
 
 const bakeConfig = (): BakeConfig | null => {
@@ -147,14 +206,6 @@ const bakeConfig = (): BakeConfig | null => {
   return g && typeof g.outDir === "string" ? g : null
 }
 
-/** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
-const hex8 = (c: unknown): string => {
-  if (typeof c !== "string") return "#ffffffff"
-  if (c.length === 7) return c + "ff"
-  if (c.length === 4) return "#" + c[1] + c[1] + c[2] + c[2] + c[3] + c[3] + "ff"
-  return c
-}
-
 const list = (v: string | string[] | undefined): string[] => v === undefined ? [] : Array.isArray(v) ? v : [ v ]
 
 const NONE = 0xFFFFFFFF
@@ -164,21 +215,18 @@ export class Lightmap {
   static get baking(): boolean { return bakeConfig() !== null }
 
   private static entries: Entry[] = []
-  private static dynamics: Mesh[] = []
   private static ordinals = new Map<string, number>()
   private static warned = false
-  private static switchedOff: Light[] = []
-
+  /** The bake bound last (`load`): what `probe` reads rects from. */
+  private static bound: Bound | null = null
 
   /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
-   *  both receivers and occluders in the bake. `key` names the entry in lightmap.bake (default:
+   *  both receivers and occluders in the bake. `key` names the entry in the .bake (default:
    *  the node's name + a running number, `container#3`); pass one when names are not stable. */
   static add(node: Node, key?: string): Node {
     const base = key ?? `${node.name || "node"}#${Lightmap.next(node.name || "node")}`
     const found: Entry[] = []
     const walk = (n: Node): void => {
-      const t = terrainOf(n)
-      if (t) { found.push({ key: base, terrain: t }); return }   // one receiver, its chunks are internal
       if (n instanceof Model) { found.push({ key: base, model: n }); return }
       if (n instanceof Mesh) { found.push({ key: base, mesh: n }); return }
       for (const c of n.children) walk(c)
@@ -194,16 +242,9 @@ export class Lightmap {
   static _register(node: Model | Mesh, key: string): void {
     Lightmap.entries.push(node instanceof Model ? { key, model: node } : { key, mesh: node })
   }
-
-  /** @internal Scene-file runtime: a terrain node (its own material carries the atlas, no swap). */
-  static _registerTerrain(terrain: Terrain, key: string): void {
-    Lightmap.entries.push({ key, terrain })
-  }
-
-  /** @internal Scene-file runtime: a dynamic Mesh — swapped to the lightmap material on the volume
-   *  when `load` runs (dynamic Models need nothing here: the engine binds the volume itself). */
-  static _registerDynamic(mesh: Mesh): void {
-    Lightmap.dynamics.push(mesh)
+  /** @internal Scene-file runtime: a terrain node - a receiver with one rect (the host keeps its triangles for the bake). */
+  static _registerGround(node: Node, key: string): void {
+    Lightmap.entries.push({ key, ground: node })
   }
 
   private static next(name: string): number {
@@ -212,23 +253,77 @@ export class Lightmap {
     return n
   }
 
-  /** Forget every registration (a scene rebuild); baked-off lights come back to the real-time path. */
+  // ---- movers: the light grid ------------------------------------------------------------------------
+  private static movers = new Set<Model | Mesh>()
+  private static volumeOn = false
+
+  /** A MOVER takes its ambient light from the level's baked LIGHT GRID (`env.lightmap.volume`) at the place it is at,
+   *  every frame — whatever its shader: the standard glTF one or a custom lit material. Every Model / Mesh under `node`
+   *  is marked (a character, a weapon with its parts). A scene file does this itself for every node a Physics aspect or
+   *  a CharacterController moves; call it for what CODE spawns — an enemy, a pickup, a projectile. `on = false` hands
+   *  the subtree back to the scene's IBL. Safe before the level's bake has loaded. */
+  static track(node: Node, on = true): void {
+    // by entity id through the bridge, not `node.children`: the bundler drops that accessor from a build where
+    // nothing else reads it (the leash in lightcheck, 2026-09-18: "children" was undefined on a Mesh)
+    const walk = (id: number): void => {
+      const n = nodeRegistry.get(id)
+      if (n instanceof Model || n instanceof Mesh) {
+        if (on) Lightmap.movers.add(n); else Lightmap.movers.delete(n)
+        if (Lightmap.volumeOn || !on) _creator.lightVolumeTrack?.(id, on)
+      }
+      for (const c of _creator.getChildren(id)) walk(c)
+    }
+    walk(node.id)
+  }
+
+  private static async loadVolume(data: BakeData, files: LightmapFiles): Promise<void> {
+    Lightmap.volumeOn = false
+    if (!files.volume || !data.volume || !_creator.lightVolumeLoad) {
+      if (data.volume && !files.volume) console.warn(`Lightmap: the bake wrote a light grid (${data.volume.file}) but the scene does not list it — add volume: asset('…/${data.volume.file}') to env.lightmap, movers keep the IBL until then`)
+      return
+    }
+    try {
+      const resp = await fetch(files.volume, { useOnce: true })
+      if (resp.status >= 400) { console.warn(`Lightmap: no light grid at ${files.volume} (HTTP ${resp.status})`); return }
+      const ok = _creator.lightVolumeLoad((resp as unknown as { _id: number })._id)
+      resp.dispose()
+      if (!ok) { console.warn(`Lightmap: ${files.volume} is not a light grid — rebake`); return }
+    } catch (e) {
+      console.warn(`Lightmap: could not read ${files.volume}: ${String(e)}`)
+      return
+    }
+    Lightmap.volumeOn = true
+    // the baked lamps are in the grid's cubes now: burning on, they would light every mover twice (Light._holdDark)
+    for (const l of Light._points) if (l._baked) l._holdDark(true)
+    for (const m of Lightmap.movers) _creator.lightVolumeTrack?.(m.id, true)
+    // the statics the atlas left out (glass, a material the lightmap shader declines) take the grid's light once; the
+    // host ignores a static whose every primitive is baked
+    for (const e of Lightmap.entries) if (!e.ground) _creator.lightVolumeTrack?.((e.model ?? e.mesh!).id, true, true)
+    console.log(`[lightmap] light grid ${data.volume.n.join(" x ")} cells of ${data.volume.cell.map((v) => v.toFixed(2)).join(" x ")} m, ${Lightmap.movers.size} mover(s)`)
+  }
+
+  /** Forget every registration (a scene rebuild). */
   static clear(): void {
+    for (const l of Light._points) l._holdDark(false)
+    Lightmap.movers.clear()
+    Lightmap.volumeOn = false
+    _creator.lightVolumeClear?.()
     Lightmap.entries = []
-    Lightmap.dynamics = []
     Lightmap.ordinals.clear()
-    Model._lightmapDefault = false
-    for (const l of Lightmap.switchedOff) l._setBakedOff(false)
-    Lightmap.switchedOff = []
-    _creator.lightmapSetOptions?.(1, 1, 1, 0)
-    _creator.lightmapVolumeSet?.(NONE, NONE, 0, 0, 0, 0, 0, 0, 0)
+    Lightmap.bound = null
+    if (Lightmap.balls) { Lightmap.balls.destroy(); Lightmap.balls = null }
+    _creator.lightmapSetOptions?.(1, 0)
+    _creator.lightmapSunSet?.(0, 1, 0, 0, 0, 0, false)
+    _creator.lightmapDebug?.(0)
   }
 
   /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
    *  applied (no bake yet, a host without the feature, bake mode). */
+  private static scene: Scene | null = null
   static async load(scene: Scene, files: LightmapFiles, options: LightmapLoadOptions = {}): Promise<LightmapInfo | null> {
+    Lightmap.scene = scene
     const bake = bakeConfig()
-    if (bake) { Lightmap.bake(bake); return null }
+    if (bake) { Lightmap.bake(bake, options.emissiveNits, options.emissiveBake ?? true, options.transmit); return null }
     if (!_creator.lightmapApply) {
       if (!Lightmap.warned) { Lightmap.warned = true; console.warn("Lightmap: this host has no lightmap support — rendering without the bake") }
       return null
@@ -243,188 +338,257 @@ export class Lightmap {
       console.warn(`Lightmap: could not read ${files.data}: ${String(e)}`)
       return null
     }
-    // the atlas pages: a bake that took more pages than the scene lists applies what it can and says so
-    const pages = Math.max(1, data.pages ?? 1)
-    const pageFiles = list(files.texture)
-    if (pageFiles.length === 0) { console.warn("Lightmap: no atlas texture given"); return null }
-    if (pageFiles.length < pages) {
-      console.warn(`Lightmap: the bake took ${pages} atlas pages but the scene lists ${pageFiles.length} — add the other page files (${(data.textures ?? []).slice(pageFiles.length).join(", ")}) to env.lightmap.texture`)
+    if (data.version !== 4 || !Array.isArray(data.instances)) {
+      console.warn(`Lightmap: ${files.data} is not a creator-bake file (version ${String(data.version)}) — rebake with \`lecodes lightmap bake\``)
+      return null
     }
-    // baked lighting is exempt from Texture.maxSize: a capped atlas blurs every shadow edge
-    const textures = await Promise.all(pageFiles.slice(0, pages).map((f) => Texture.load(f, { fullSize: true })))
-    // the light atlas: the bake carries the point lights only when the scene passes their atlas
-    const lightFiles = list(files.light)
-    let lightTextures: Texture[] = []
-    let lightScale = 0
-    let volumeScale = 0
-    if (data.lightTextures?.length && (data.lightScale ?? 0) > 0) {
-      if (lightFiles.length === 0) {
-        console.warn(`Lightmap: the bake carries ${data.lights?.length ?? 0} baked point light(s) but the scene passes no \`light\` atlas (${data.lightTextures[0]}) — the lamps stay real-time`)
-      } else {
-        if (lightFiles.length < pages) console.warn(`Lightmap: the light atlas has ${pages} pages but the scene lists ${lightFiles.length}`)
-        lightTextures = await Promise.all(lightFiles.slice(0, pages).map((f) => Texture.load(f, { fullSize: true })))
-        lightScale = (data.lightScale ?? 0) * (options.lightBoost ?? 1)
-        volumeScale = (data.lightScale ?? 0) * (options.volumeBoost ?? options.lightBoost ?? 1)
-      }
+    if (!data.pages || !(data.lightScale > 0)) return null   // the CLI's placeholder: nothing baked yet
+    const pages = Math.max(1, data.pages)
+    const lightFiles = list(files.light), auxFiles = list(files.aux)
+    if (lightFiles.length === 0 || auxFiles.length === 0) { console.warn("Lightmap: the scene passes no `light` / `aux` atlas"); return null }
+    if (lightFiles.length < pages || auxFiles.length < pages) {
+      console.warn(`Lightmap: the bake took ${pages} page(s) but the scene lists ${Math.min(lightFiles.length, auxFiles.length)} — add ${data.light.slice(lightFiles.length).join(", ")} / ${data.aux.slice(auxFiles.length).join(", ")} to env.lightmap`)
     }
-    const ambientScale = options.ambientScale ?? 1
-    const strength = options.sunStrength ?? 1
-    const aoStrength = options.aoStrength ?? 1
-    // the light store's curve: sRGB(pow(E / lightScale, 1 / lightGamma)); bakes before 2026-08-31 are linear (1)
-    const lightGamma = data.lightGamma ?? 1
-    // level-wide knobs first: the volume and every rect below inherit them
-    _creator.lightmapSetOptions?.(ambientScale, strength, aoStrength, lightScale, volumeScale, lightGamma)
-    // what the bake actually BOUND, so a level can be debugged without guessing (FEEDBACK 95): the
-    // scale is the one number standing between the atlas' physical irradiance and the pixel
-    console.log(`[lightmap] bound ${textures.length} page(s)${lightTextures.length ? ` + ${lightTextures.length} light page(s)` : ""}`
-      + ` lightScale ${lightScale.toFixed(2)}${(options.lightBoost ?? 1) !== 1 ? ` (bake ${(data.lightScale ?? 0).toFixed(2)} x boost ${options.lightBoost})` : ""}`
-      + `${volumeScale !== lightScale ? ` volumeScale ${volumeScale.toFixed(2)}` : ""}`
-      + ` gamma ${lightGamma} ao ${aoStrength} ambient ${ambientScale} sun ${strength}`)
-    // the light volume next: it claims every lightmap-material instance, the atlas rects below win back the statics
-    const volume = files.volume ? await Lightmap.loadVolume(files.volume, volumeScale, lightGamma, ambientScale, strength, aoStrength) : null
-    const rects = new Map<string, { st: number[], page: number }>()
-    // an OCCLUDER-only static (no lightmap UVs): the bake traced its shadow onto every receiver, so it
-    // has nothing left to cast in real time — the shadow pass then draws only the movers. Twig & Twine's
-    // 9 441 props (5 M alpha-masked spruce cards) cost the GPU a third of the frame as live casters.
-    const occluders = new Set<string>()
-    for (const inst of data.instances) {
-      if (inst.receiver && inst.st) rects.set(inst.key, { st: inst.st, page: inst.page ?? 0 })
-      else if (!inst.receiver) occluders.add(inst.key)
+    // both atlases are DATA and exempt from Texture.maxSize (a capped atlas blurs every shadow edge)
+    const n = Math.min(pages, lightFiles.length, auxFiles.length)
+    const light = await Promise.all(lightFiles.slice(0, n).map((f) => Texture.load(f, { fullSize: true, srgb: false })))
+    const aux = await Promise.all(auxFiles.slice(0, n).map((f) => Texture.load(f, { fullSize: true, srgb: false })))
+    const lightScale = data.lightScale * (options.lightScale ?? 1)
+    _creator.lightmapSetOptions?.(lightScale, data.emissiveNits ?? 0)
+    // a mover's sun shadow on the statics: only a bake that wrote the sun map under its aux pages
+    const sun = data.sunMap ? data.sun : null
+    if (sun) _creator.lightmapSunSet?.(-sun.direction[0], -sun.direction[1], -sun.direction[2], sun.color[0] * sun.lux, sun.color[1] * sun.lux, sun.color[2] * sun.lux, true, data.sunMapLevels ?? 1)
+    else _creator.lightmapSunSet?.(0, 1, 0, 0, 0, 0, false)
+    // the reflection probes: the atlas loads like a page, the grid travels as numbers; level-wide on the host
+    let probes = 0
+    let probeAtlas: Texture | undefined
+    const pb = data.probes
+    if (pb && pb.count > 0) {
+      if (!files.probes) console.warn(`Lightmap: the bake has ${pb.count} reflection probe(s) but the scene lists no \`probes\` file — add probes: asset('<dir>/${pb.file}') to env.lightmap`)
+      else if (!_creator.lightmapProbesSet) console.warn("Lightmap: this host has no reflection probes — statics reflect the sky alone")
+      else if (!Array.isArray(pb.encode) || pb.encode.length < 6) console.warn("Lightmap: the bake's probes are in an older format — rebake (statics reflect the sky alone until then)")
+      else {
+        probeAtlas = await Texture.load(files.probes, { fullSize: true, srgb: false })
+        // which probes a pixel reflects is in the aux pages (their probe maps); the host needs the atlas and the records' range
+        probes = _creator.lightmapProbesSet(probeAtlas._id, pb.oct, pb.levels, pb.perRow, pb.count,
+                                            pb.encode[0], pb.encode[1], pb.encode[2], pb.encode[3], pb.encode[4], pb.encode[5])
+        if (probes !== pb.count) console.warn(`Lightmap: the host took ${probes} of ${pb.count} probe(s) — rebake`)
+      }
     }
-    const bakedOccluders = (options.occluderShadows ?? "baked") === "baked"
-    let applied = 0, shadowless = 0
+    console.log(`[lightmap] bound ${n} page(s) of ${data.size} at ${(data.texel * 100).toFixed(2)} cm (${data.mips ?? 1} level(s), sun map ${data.sunMapLevels ?? (data.sunMap ? 1 : 0)}), lightScale ${lightScale}${(options.lightScale ?? 1) !== 1 ? ` (bake ${data.lightScale} x ${options.lightScale})` : ""}${probes > 0 ? `, ${probes} reflection probe(s)` : ""}`)
+    const rects = new Map<string, BakeInstance>()
+    for (const inst of data.instances) if (inst.receiver && inst.st && inst.page !== undefined) rects.set(inst.key, inst)
+    // the ones the bake left out for their size: occluders there, movers here — not a rect gone missing
+    const small = new Map<string, BakeInstance>()
+    for (const inst of data.instances) if (inst.small) small.set(inst.key, inst)
+    const declined = new Set<string>()
+    for (const inst of data.instances) if (!inst.receiver && !inst.small) declined.add(inst.key)
+    const probeId = (k: number) => k === -2 ? 65534 : k < 0 ? 65535 : k
+    // A GLB UNWRAPPED IN GROUPS (`assets doctor --lightmap-uv --lightmap-groups n`): the bake keys its parts `<key>#k`, a rect
+    // (or a small static's cube) each, and the host binds part k to the nodes that carry extras.lightmapGroup = k
+    const parts = Lightmap.groupsOf(data.instances)
+    let smallLit = 0
+    const byEntity = new Map<number, Entry>()
+    let applied = 0
     const missing: string[] = []
     for (const e of Lightmap.entries) {
-      const r = rects.get(e.key)
-      if (!r || r.page >= textures.length) {
-        if (occluders.has(e.key)) {
-          if (bakedOccluders) {
-            if (e.model) e.model.castShadows = false
-            else if (e.mesh) e.mesh.castShadows = false
-            shadowless++
+      const node = e.model ?? e.mesh ?? e.ground!
+      byEntity.set(node.id, e)
+      const groups = parts.get(e.key)
+      if (groups) {
+        let took = 0
+        for (const [ k, inst ] of groups) {
+          if (inst.small && inst.light && _creator.lightmapObjectApply && n > 0) {
+            const l = inst.light
+            took += _creator.lightmapObjectApply(node.id, light[0]._id, aux[0]._id, Float32Array.from([ ...l.cube.flat(), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ]), k)
+          } else if (inst.receiver && inst.st && inst.page !== undefined && inst.page < n) {
+            took += _creator.lightmapApply(node.id, light[inst.page]._id, aux[inst.page]._id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
           }
-        } else missing.push(e.key)
+        }
+        if (took === 0) console.warn(`Lightmap: ${e.key} (${groups.size} groups) was not loaded lightmapped, or the host binds no groups (rebuild it)`)
+        else applied++
         continue
       }
-      const st = r.st
-      const texture = textures[r.page]
-      const light = r.page < lightTextures.length ? lightTextures[r.page] : null
-      if (e.model) {
-        const n = _creator.lightmapApply(e.model.id, texture._id, st[0], st[1], st[2], st[3], light ? light._id : NONE)
-        if (n === 0) { console.warn(`Lightmap: ${e.key} was not loaded with { lightmap: true } — skipped`); continue }
-        e.model.castShadows = false
-      } else if (e.mesh) {
-        Lightmap.swapMeshMaterial(e.mesh, texture, light, light ? lightScale : 0, lightGamma, st, ambientScale, strength, aoStrength)
-        e.mesh.castShadows = false
-      } else if (e.terrain) {
-        // terrain.mat carries lightmap.mat's atlas block: bind the rect on the terrain's own material
-        const m = e.terrain.material.set("lightmap", texture).set("lightmapST", [ st[0], st[1], st[2], st[3] ])
-          .set("ambientScale", ambientScale).set("sunStrength", strength).set("bakedAo", aoStrength).set("lightGamma", lightGamma)
-        if (light) m.set("lightmapLight", light).set("lightScale", lightScale)
-        else m.set("lightScale", 0)
-        e.terrain.castShadows = false
+      const r = rects.get(e.key)
+      const tiny = small.get(e.key)
+      if (tiny) {
+        // no rect: the light baked where it stands (any page's samplers — the probes' records sit under every aux page)
+        const l = tiny.light
+        if (!l || !_creator.lightmapObjectApply || n === 0) continue
+        if (e.mesh) e.mesh.material = Lightmap.meshMaterial(e.mesh)
+        const d = Float32Array.from([ ...l.cube.flat(), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ])
+        if (_creator.lightmapObjectApply(node.id, light[0]._id, aux[0]._id, d) > 0) smallLit++
+        continue
       }
+      if (!r && declined.has(e.key)) continue   // glass / a declined material: the bake knows it as an occluder - the light grid lights it (loadVolume)
+      if (!r || r.page! >= n) { missing.push(e.key); continue }
+      const st = r.st!
+      // a Mesh receiver: its lit material becomes a lightmap material carrying the same colour / map / factors
+      if (e.mesh) e.mesh.material = Lightmap.meshMaterial(e.mesh)
+      const took = _creator.lightmapApply(node.id, light[r.page!]._id, aux[r.page!]._id, st[0], st[1], st[2], st[3])
+      if (took === 0) { console.warn(`Lightmap: ${e.key} was not loaded lightmapped (Model.load { lightmap: true } / Material.lightmap())`); continue }
       applied++
     }
+    if (small.size) console.log(`[lightmap] ${small.size} small static(s) are not in the atlas (the bake's minTexels): ${smallLit} lit by the light baked where they stand`)
     if (missing.length) console.warn(`Lightmap: ${missing.length} static(s) have no rect in the bake (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "…" : ""}) — rebake`)
-    // the lights the bake carries go dark: the atlas holds them for the statics, the volume for the movers
-    let lights = 0
-    if (lightTextures.length > 0 && data.lights?.length) lights = Lightmap.switchOffBaked(data.lights)
-    if (shadowless > 0) console.log(`[lightmap] ${shadowless} occluder-only static(s) cast no real-time shadow (baked); the shadow pass draws the movers only`)
-    const info: LightmapInfo = { size: data.size, texel: data.texel, pages, applied, total: rects.size, missing, lights, occluders: shadowless }
-    if (volume) info.volume = { dims: volume.dims, cell: volume.cell }
-    return info
+    Lightmap.bound = { data, rects, byEntity, files, pages: n, aux, light, probes, probeAtlas, showing: "light" }
+    await Lightmap.loadVolume(data, files)
+    return { size: data.size, texel: data.texel, pages: n, applied, total: rects.size, missing }
   }
 
-  /** Every live point light within 5 cm of a baked one is held dark (a moved lamp keeps lighting live
-   *  — and double, until the next bake, which is the honest state of a stale bake). */
-  private static switchOffBaked(baked: { p: number[] }[]): number {
+  /** The bake's `<key>#k` instances by their base key: the parts of a GLB unwrapped in groups (k = extras.lightmapGroup). */
+  private static groupsOf(instances: BakeInstance[]): Map<string, Map<number, BakeInstance>> {
+    const out = new Map<string, Map<number, BakeInstance>>()
+    const registered = new Set(Lightmap.entries.map((e) => e.key))
+    for (const inst of instances) {
+      const m = /^(.*)#(\d+)$/.exec(inst.key)
+      if (!m || !registered.has(m[1])) continue
+      let g = out.get(m[1])
+      if (!g) { g = new Map(); out.set(m[1], g) }
+      g.set(Number(m[2]), inst)
+    }
+    return out
+  }
+
+  /** Switch every lightmapped surface to a DATA view (or back with `"off"` / 0). Level-wide, instant —
+   *  except "direct" / "indirect", which load that page set the first time (a `--split` bake listed in the scene). */
+  static debug(mode: LightmapDebugMode | number, params: LightmapDebugParams = {}): void {
+    const m = typeof mode === "number" ? mode : Math.max(0, DEBUG_MODES.indexOf(mode))
+    const [ lo, hi ] = params.luxRange ?? [ 0, 5 ]
+    const pages = PAGE_VIEWS[m]
+    void Lightmap.show(pages ?? "light")
+    _creator.lightmapDebug?.(pages ? 0 : m, 0, lo, hi, 0)
+  }
+
+  /** Bind another page set of the bound bake to every surface (the "direct" / "indirect" views). */
+  private static async show(kind: PageKind): Promise<void> {
+    const b = Lightmap.bound
+    if (!b || b.showing === kind || !_creator.lightmapApply) return
+    let tex = b[kind]
+    if (!tex) {
+      const files = list(b.files[kind])
+      if (files.length < b.pages) {
+        console.warn(`Lightmap: the scene lists ${files.length ? "only " + files.length : "no"} "${kind}" page(s) — bake with \`lecodes lightmap bake --split\` and add its ${kind} pages to env.lightmap`)
+        return
+      }
+      tex = await Promise.all(files.slice(0, b.pages).map((f) => Texture.load(f, { fullSize: true, srgb: false })))
+      if (Lightmap.bound !== b) return   // rebuilt meanwhile
+      b[kind] = tex
+    }
+    b.showing = kind
+    const parts = Lightmap.groupsOf(b.data.instances)
+    for (const [ id, e ] of b.byEntity) {
+      for (const [ k, inst ] of parts.get(e.key) ?? []) {
+        if (inst.receiver && inst.st && inst.page !== undefined && inst.page < b.pages) _creator.lightmapApply(id, tex[inst.page]._id, b.aux[inst.page]._id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
+      }
+      const r = b.rects.get(e.key)
+      if (!r || r.page! >= b.pages) continue
+      const st = r.st!
+      _creator.lightmapApply(id, tex[r.page!]._id, b.aux[r.page!]._id, st[0], st[1], st[2], st[3])
+    }
+    console.log(`[lightmap] showing the ${kind} pages`)
+  }
+  private static balls: Node | null = null
+  /** DEBUG: a mirror ball at every reflection probe of the bound bake (`on`), or none (`off`) — a ball reflects the
+   *  probes around its point unoccluded (at a probe's own position that is the probe itself), so a probe inside a
+   *  wall, a black one or a leak across a wall shows at a glance. Metallic, roughness 0; view "probe" shows the
+   *  probes alone. */
+  static debugProbes(on: boolean, radius = 0.2): number {
+    if (Lightmap.balls) { Lightmap.balls.destroy(); Lightmap.balls = null }
+    const b = Lightmap.bound
+    if (!on || !b || b.probes === 0 || !b.data.probes || !_creator.lightmapApply) return 0
+    const holder = new Node()
+    holder.name = "lightmap-probes"
     let n = 0
-    for (const light of Light._points) {
-      if (!light._baked) continue
-      const wp = light.worldPosition
-      const x = cx(wp), y = cy(wp), z = cz(wp)
-      const hit = baked.some((b) => Math.abs(b.p[0] - x) < 0.05 && Math.abs(b.p[1] - y) < 0.05 && Math.abs(b.p[2] - z) < 0.05)
-      if (!hit) continue
-      light._setBakedOff(true)
-      Lightmap.switchedOff.push(light)
+    for (let k = 0; k < Math.min(b.probes, b.data.probes.positions.length); k++) {
+      const [ x, y, z ] = b.data.probes.positions[k]
+      const m = Material.lightmap()
+      m.set("baseColorFactor", "#ffffffff").set("metallicFactor", 1).set("roughnessFactor", 0).set("hasNormalMap", 0)
+      const ball = Mesh.sphere({ radius, material: m })
+      ball.name = `probe#${k}`
+      ball.position = [ x, y, z ]
+      holder.add(ball)
+      _creator.lightmapApply(ball.id, b.light[0]._id, b.aux[0]._id, 0, 0, 0, 0)
+      m.set("probeBall", k + 1)   // probe k alone, unoccluded
       n++
     }
+    Lightmap.scene?.add(holder)
+    Lightmap.balls = holder
+    console.log(`[lightmap] ${n} probe ball(s)`)
     return n
   }
 
-  /** lightmap.volume → the engine's 3D textures → THE volume for every dynamic lightmap-material instance,
-   *  plus the registered dynamic Meshes. Null when the file is a placeholder or the host lacks the feature. */
-  private static async loadVolume(url: string, lightScale: number, lightGamma: number, ambientScale: number, strength: number, aoStrength: number): Promise<VolumeHeader | null> {
-    if (!_creator.lightmapVolumeLoad || !_creator.lightmapVolumeSet) return null
-    let header: VolumeHeader
-    try {
-      const resp = await fetch(url, { useOnce: true })
-      if (resp.status >= 400) { console.warn(`Lightmap: no volume at ${url} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
-      const json = _creator.lightmapVolumeLoad((resp as unknown as { _id: number })._id)
-      resp.dispose()
-      if (!json) { console.warn(`Lightmap: ${url} is not a light volume — rebake`); return null }
-      header = JSON.parse(json) as VolumeHeader
-    } catch (e) {
-      console.warn(`Lightmap: could not read ${url}: ${String(e)}`)
-      return null
+  /** The view names in `lightmapDebug`'s order — for a knob that cycles them. */
+  static get debugModes(): readonly LightmapDebugMode[] { return DEBUG_MODES }
+
+  /** The baked texel under a screen point (logical px): its instance key, page and texel column / row,
+   *  so the value can be looked up in the bake's debug layers (`lecodes lightmap inspect`). null when
+   *  nothing baked is under the point or the host has no triangle pick. */
+  static probe(screenX: number, screenY: number): LightmapProbe | null {
+    const b = Lightmap.bound
+    if (!b || !_creator.pickTriangle) return null
+    type Hit = { entity: number, nodeName: string, material: string, point: number[], distance: number, uv1?: number[], lightmapGroup?: number }
+    // the nearest hit over the registered statics: one pick per entry (the all-instances pick, entity 0, walks
+    // every GLB instance including the off-scene templates and is what a scene file's clones confuse)
+    let hit: Hit | null = null
+    for (const id of b.byEntity.keys()) {
+      const j = _creator.pickTriangle(id, screenX, screenY)
+      if (!j) continue
+      const h = JSON.parse(j) as Hit
+      if (!hit || h.distance < hit.distance) hit = h
     }
-    const [ nx, ny, nz ] = header.dims
-    if (nx * ny * nz <= 1) return null   // the CLI's placeholder: nothing baked yet
-    const size = [ nx * header.cell, ny * header.cell, nz * header.cell ]
-    const texture = new Texture(nx, ny, header.texture)
-    const hasLight = header.light !== undefined && lightScale > 0
-    const light = hasLight ? new Texture(nx, ny, header.light!) : null
-    if (hasLight && (header.faces ?? 1) < 6) console.warn("Lightmap: the light volume predates the ambient cube (one directionless value per cell) — rebake")
-    _creator.lightmapVolumeSet(header.texture, hasLight ? header.light! : NONE, header.min[0], header.min[1], header.min[2], size[0], size[1], size[2], header.cell)
-    for (const mesh of Lightmap.dynamics) {
-      const m = Lightmap.meshMaterial(mesh, ambientScale, strength, aoStrength, lightGamma)
-      m.set("probeVolume", texture)
-      if (light) m.set("probeLight", light).set("lightScale", lightScale)
-      m.set("probeMin", [ header.min[0], header.min[1], header.min[2], header.cell * 0.5 ])
-      // .w = the grid's depth: the shader keeps its fetch inside one face slab of the light texture
-      m.set("probeInvSize", [ 1 / size[0], 1 / size[1], 1 / size[2], nz ])
-      mesh.setMaterial(m)
+    if (!hit) { console.log(`[probe] nothing baked under ${screenX.toFixed(0)},${screenY.toFixed(0)}`); return null }
+    const entry = b.byEntity.get(hit.entity)
+    if (!entry) { console.log(`[probe] hit entity ${hit.entity} node "${hit.nodeName}" at ${hit.point.map((c) => c.toFixed(2)).join(",")} is not a registered static`); return null }
+    const hitKey = hit.lightmapGroup !== undefined && b.rects.has(`${entry.key}#${hit.lightmapGroup}`) ? `${entry.key}#${hit.lightmapGroup}` : entry.key
+    const inst = b.rects.get(hitKey)
+    if (!inst || !inst.st) { console.log(`[probe] ${hitKey}: no rect in the bake`); return null }
+    if (!hit.uv1) { console.log(`[probe] ${entry.key}: the hit primitive carries no TEXCOORD_1`); return null }
+    const st = inst.st
+    const u = hit.uv1[0] * st[0] + st[2], v = hit.uv1[1] * st[1] + st[3]
+    return {
+      key: hitKey, entity: hit.entity, node: hit.nodeName, material: hit.material, page: inst.page ?? 0,
+      texel: [ Math.floor(u * b.data.size), Math.floor(v * b.data.size) ],
+      uv1: [ hit.uv1[0], hit.uv1[1] ], world: [ hit.point[0], hit.point[1], hit.point[2] ], distance: hit.distance,
     }
-    return header
   }
 
-  /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
-  private static meshMaterial(mesh: Mesh, ambientScale: number, strength: number, aoStrength: number, lightGamma = 1): Material {
-    const src = mesh.material
-    const u = src?.uniforms ?? {}
+  /** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
+  private static hex8(c: unknown): string {
+    if (typeof c !== "string") return "#ffffffff"
+    if (c.length === 7) return c + "ff"
+    if (c.length === 4) return "#" + c[1] + c[1] + c[2] + c[2] + c[3] + c[3] + "ff"
+    return c
+  }
+
+  /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic). */
+  private static meshMaterial(mesh: Mesh): Material {
+    const u = mesh.material?.uniforms ?? {}
     const m = Material.lightmap()
-    m.set("baseColorFactor", hex8(u.baseColor))
+    m.set("baseColorFactor", Lightmap.hex8(u.baseColor ?? u.color))
     if (u.baseColorMap instanceof Texture) m.set("baseColorMap", u.baseColorMap)
     if (typeof u.roughness === "number") m.set("roughnessFactor", u.roughness)
     if (typeof u.metallic === "number") m.set("metallicFactor", u.metallic)
-    m.set("ambientScale", ambientScale)
-    m.set("sunStrength", strength)
-    m.set("bakedAo", aoStrength)
-    m.set("lightGamma", lightGamma)
     return m
   }
 
-  private static swapMeshMaterial(mesh: Mesh, texture: Texture, light: Texture | null, lightScale: number, lightGamma: number, st: number[],
-                                  ambientScale: number, strength: number, aoStrength: number): void {
-    const m = Lightmap.meshMaterial(mesh, ambientScale, strength, aoStrength, lightGamma)
-    m.set("lightmap", texture)
-    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
-    if (light) m.set("lightmapLight", light).set("lightScale", lightScale)
-    mesh.setMaterial(m)
-  }
-
-  private static bake(cfg: BakeConfig): void {
-    if (!_creator.lightmapBake) { console.error("[lightmap] error: this host has no bake module (build the desktop host with CREATOR_GL_LIGHTMAP, or update lecodes desktop)"); return }
-    const ids = Uint32Array.from(Lightmap.entries.map((e) => (e.model ?? e.mesh ?? e.terrain!.node).id))
+  private static bake(cfg: BakeConfig, levelNits?: number, emissiveBake = true, transmit?: Record<string, LightmapTransmit>): void {
+    if (!_creator.lightmapBake) { console.error("[lightmap] error: this host has no bake module (build the desktop host with the CUDA toolkit, or update lecodes desktop)"); return }
+    const ids = Uint32Array.from(Lightmap.entries.map((e) => (e.model ?? e.mesh ?? e.ground!).id))
     const keys = Lightmap.entries.map((e) => e.key).join("\n")
     if (ids.length === 0) { console.error("[lightmap] error: nothing registered — call Lightmap.add on the static props before Lightmap.load"); return }
     // a `baked: false` light is held dark for the bake — the engine bakes every lit point light it finds
+    for (const l of Light._points) l._holdDark(false)   // a bake started over a loaded level
     const live = [ ...Light._points ].filter((l) => !l._baked)
     for (const l of live) _creator.setLightIntensity?.(l.id, 0)
-    _creator.lightmapBake(cfg.outDir, ids, keys, cfg.size ?? 4096, cfg.texel ?? 0.02, cfg.sunRays ?? 32, cfg.aoRays ?? 64,
-      cfg.aoDistance ?? 2, cfg.bias ?? 0.02, cfg.sunAngle ?? 0.5, cfg.volumeCell ?? 0.5, cfg.pages ?? 1, cfg.lightRays ?? 8, cfg.lightRadius ?? 0.1,
-      cfg.bounce ?? 0, cfg.bounceDistance ?? 8, cfg.bounceRays ?? 1, cfg.coplanarSkip ?? 0.05, cfg.denoise ?? 2)
+    const ev100 = Lightmap.scene?.camera.ev100 ?? 15
+    const emissiveNits = cfg.emissiveNits ?? levelNits ?? 1.2 * 2 ** ev100
+    if (emissiveNits > 0) console.log(`[lightmap] emission 1.0 = ${Math.round(emissiveNits)} nits${emissiveBake ? "" : ", DRAWN only (env.lightmap.emissiveBake: false - the emissive surfaces light nothing)"} (${cfg.emissiveNits !== undefined ? "--emissive-nits" : levelNits !== undefined ? "the level's env.lightmap.emissiveNits" : `the camera's EV100 ${ev100.toFixed(1)}`})`)
+    _creator.lightmapBake(cfg.outDir, cfg.stem, ids, keys, cfg.size ?? 4096, cfg.texel ?? 0.05, cfg.pages ?? 4,
+      cfg.sunRays ?? 64, cfg.skyRays ?? 2048, cfg.lightRays ?? 64, cfg.lightRadius ?? 0.05, cfg.sunAngle ?? 0.53, cfg.bias ?? 0.01, cfg.seed ?? 1,
+      cfg.bounceRays ?? 128, cfg.bounces ?? 3, cfg.patchSamples ?? 64, cfg.split ?? false, DENOISE_LEVELS[cfg.denoise ?? "no-sun"], cfg.filter ?? 1,
+      cfg.probeSpacing ?? 4, cfg.probeSize ?? 32, cfg.probeRays ?? 128, cfg.probeIndoor ?? false, cfg.probeLayout === "grid" ? 1 : 0, cfg.probeBox ? Float32Array.from(cfg.probeBox) : null, (cfg.minTexels ?? 12) * (cfg.texel ?? 0.05), cfg.volumeSpacing ?? 1, emissiveBake ? emissiveNits : -emissiveNits, cfg.detailTexels ?? 2000, cfg.debugDir ?? "",
+      Object.entries(transmit ?? {}).map(([name, share]) => typeof share === "number" ? `${name}=${share}` : `${name}=${share.through ?? 0},${share.diffuse ?? 0}`).join(";"))
     for (const l of live) _creator.setLightIntensity?.(l.id, l.intensity)
   }
 }