lecodes-sdk 2.4.7 → 2.4.9

package/src/gl/Lightmap.ts

@@ -1,5 +1,5 @@
 // Baked lighting for static 3D geometry (engines/bake). A scene FILE does all of this by
-// itself: `env: { lightmap: { data, light, aux } }` marks the level as baked, every model/mesh node
+// itself: `env: { lightmap: bake('./assets/lightmap/level.bake') }` 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
@@ -10,20 +10,22 @@
 //   const crate = await Model.load(asset('./assets/props/crate.glb'), { lightmap: true })
 //   Lightmap.add(holder)                    // a Model, a Mesh, or a node holding them
 //   ...
-//   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') })
+//   await Lightmap.load(scene, bake('./assets/lightmap/level.bake', { emissiveBake: false }))
 //
-// `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.
+// `bake()` is a COMPILE-TIME macro (compile/bakeMacro.ts), the one reference to a bake: the `.bake` is a JSON
+// MANIFEST that names every file the bake wrote next to it (the atlas pages, the aux pages, the reflection probes, the
+// light grid, the packed uv1, a `--split` bake's page sets). The compiler reads it, stages each file the way asset()
+// does and writes the list in place (`LightmapDef`), the options (its second argument) beside it. Before the first bake
+// there is no manifest: the def is `{ data: null, path }` — the level runs unbaked and says so, and under `lecodes
+// lightmap bake` that path is where the bake writes. (The data file is JSON with a .bake extension: a .json would be
+// scanned as a code module.)
 //
-// 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".
+// `probes` (when the bake placed some) 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 them a static's specular reflects the sky's SH alone.
+//
+// `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".
 //
 // 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
@@ -35,7 +37,7 @@
 // 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
+// halves: a bake made with `--split` writes them as page sets of their own, its manifest names 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.
@@ -50,16 +52,22 @@ import { Node, nodes } from "./Node"
 import { Light } from "./Light"
 import type { Scene } from "./Scene"
 
-export type LightmapLoadOptions = {
+/** The level's bake / load options: `bake()`'s second argument (an object literal, copied into the def as written). */
+export type LightmapOptions = {
   /** 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. */
+  /** FOR THE BAKE: the radiance in cd / m² of emission 1.0 on this level (emissive factor x strength x map) - every lit
+   *  region of an emissive surface bakes as a rectangle lamp. An imported pack's emission is a LOOK, tuned for the eye;
+   *  this is where the level says what its panels really give: a 1.3 m ceiling panel of ~8000 lm is ~1600 nits. Default:
+   *  what the camera makes of 1.0 (`1.2 x 2^EV100`). 0 = emissive surfaces light nothing. The CLI's `--emissive-nits`
+   *  wins over it. A `Material.lit` glow with `emissiveNits` of its own emits those instead. */
   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. */
+  /** `false` = the emissive surfaces light NOTHING in the bake - the level is lit by its lamps (a `kind: 'point'` light
+   *  with a `bakeArea` next to every panel, the Unity packs' way) and the panels are decoration; `emissiveNits` then only
+   *  says how bright their glow is DRAWN (scene-referred: nits through the camera's exposure). Default true. The
+   *  OVERRIDE over every surface's own switch (`Material.lit`'s `emissiveBake`, a GLB material's extras
+   *  `{"lecodes":{"emissiveBake":false}}`), which vetoes one material while the rest still light the level. */
   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
@@ -75,7 +83,7 @@ export type LightmapLoadOptions = {
   cube?: string[]
 }
 
-/** one `transmit` entry (LightmapLoadOptions.transmit): the straight share, or both shares */
+/** one `transmit` entry (LightmapOptions.transmit): the straight share, or both shares */
 export type LightmapTransmit = number | { through?: number, diffuse?: number }
 
 export type LightmapInfo = {
@@ -89,27 +97,36 @@ export type LightmapInfo = {
   missing: string[]
 }
 
+/** The bake's files as `bake()` reads them off the `.bake` manifest at compile time — each one staged like an asset()
+ *  (every name in the manifest is relative to the `.bake`'s folder). Written by the macro, never by hand. */
 export type LightmapFiles = {
-  data: 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[]
+  /** The `.bake` (the manifest) — null until `lecodes lightmap bake` has written it: the level then runs unbaked. */
+  data: string | null
+  /** Project-relative path of the `.bake`, always set: what the messages name, and where `lecodes lightmap bake` writes. */
+  path: string
+  /** The irradiance atlas (`<stem>-light[_n].ktx2`), every page in order. */
+  light: string[]
+  /** The aux atlas (`<stem>-aux[_n].ktx2`: sun / sky visibility + light direction), pages like `light`. */
+  aux: string[]
   /** DEBUG: the direct-light-only pages a `--split` bake wrote (`<stem>-direct[_n].ktx2`), for the "direct" view. */
-  direct?: string | string[]
+  direct?: string[]
   /** DEBUG: the bounce-only pages of a `--split` bake (`<stem>-indirect[_n].ktx2`), for the "indirect" view. */
-  indirect?: string | string[]
+  indirect?: 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. */
+  /** THE LIGHT GRID for movers (`<stem>.lgrid`, `lecodes lightmap bake --volume`): every node a Physics aspect or a
+   *  CharacterController moves (and what code marks with `Lightmap.track`) takes its ambient light from the bake at the
+   *  place it is at, whatever its shader. Absent = movers keep the scene's IBL. */
   volume?: string
-  /** THE PACKED LIGHTMAP UV1 (`<stem>-uv1.bin`, the .bake's `uv1`): the bake packs every mesh's lightmap charts into a
-   *  square of their own and its rects map that uv1 — the engine swaps it into the models' TEXCOORD_1 first. Required
-   *  when the bake names one. */
+  /** THE PACKED LIGHTMAP UV1 (`<stem>-uv1.bin`): the bake packs every mesh's lightmap charts into a square of their own
+   *  and its rects map that uv1 — the engine swaps it into the models' TEXCOORD_1 before the rects go on. */
   uv1?: string
 }
 
+/** What `bake('<path>.bake', options)` compiles to — the files of the bake and the level's options in one literal:
+ *  `env.lightmap` in a scene file, `Lightmap.load`'s argument in a hand-built scene. */
+export type LightmapDef = LightmapFiles & LightmapOptions
+
 /** 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
@@ -151,7 +168,13 @@ export type LightmapAddOptions = {
 }
 
 type BakeConfig = {
-  outDir: string, stem: string, size?: number, texel?: number, pages?: number,
+  /** The project root (forward slashes): the bake writes `<root>/<the def's path>` — where the level's `bake()` points. */
+  root: string,
+  /** `--out`: write the files into this folder instead (absolute) — a second seed for `lecodes lightmap diff`. */
+  outDir?: string,
+  /** `--name`: only the level whose `.bake` has this stem bakes (a bundle that reaches several bake() calls). */
+  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,
   /** The AI denoiser (see `denoiser`) over: `"no-sun"` (the default) the bounce, the sky and the lamps, `"indirect"` the bounce alone, `"all"` + the sun (its shadow edges too), `"none"`. */
@@ -193,7 +216,7 @@ type BakeConfig = {
    *  0 = one cube an object. Default 1. */
   objectSlab?: number,
   /** CUBES BY NAME (the CLI's `--cube`): regular expressions over the records' keys, joined with the level's own
-   *  (`LightmapLoadOptions.cube`) into one — each wrapped in `(?: )`, `|` between. */
+   *  (`LightmapOptions.cube`) into one — each wrapped in `(?: )`, `|` between. */
   cube?: string[],
   /** THE LIGHT GRID for movers: the cell size in metres (0.75 of it tall); 0 = none. Default 1. */
   volumeSpacing?: number,
@@ -251,11 +274,9 @@ type Bound = {
 
 const bakeConfig = (): BakeConfig | null => {
   const g = (globalThis as unknown as { __lecodesLightmap?: BakeConfig }).__lecodesLightmap
-  return g && typeof g.outDir === "string" ? g : null
+  return g && typeof g.root === "string" ? g : null
 }
 
-const list = (v: string | string[] | undefined): string[] => v === undefined ? [] : Array.isArray(v) ? v : [ v ]
-
 const NONE = 0xFFFFFFFF
 
 export class Lightmap {
@@ -311,7 +332,7 @@ export class Lightmap {
   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,
+  /** A MOVER takes its ambient light from the level's baked LIGHT GRID (the bake's `.lgrid`) 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
@@ -333,10 +354,7 @@ export class Lightmap {
 
   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
-    }
+    if (!files.volume || !data.volume || !_creator.lightVolumeLoad) 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 }
@@ -361,7 +379,8 @@ export class Lightmap {
    *  False = the bake needs it and it cannot be had - its rects would read the wrong texels. */
   private static async loadUv1(data: BakeData, files: LightmapFiles): Promise<boolean> {
     if (!data.uv1) { _creator.lightmapUv1Clear?.(); return true }
-    if (!files.uv1) { console.warn(`Lightmap: the bake packed the models' lightmap charts (${data.uv1}) but the scene does not list it — add uv1: asset('…/${data.uv1}') to env.lightmap; the bake is not applied until then`); return false }
+    // bake() lists every file the manifest names: only a def written by hand can miss it
+    if (!files.uv1) { console.warn(`Lightmap: ${files.path} maps a packed uv1 (${data.uv1}) the def does not carry — the bake is not applied`); return false }
     if (!_creator.lightmapUv1Load) { console.warn("Lightmap: this host cannot take the bake's packed lightmap uv1 (rebuild it) — the bake is not applied"); return false }
     try {
       const resp = await fetch(files.uv1, { useOnce: true })
@@ -411,43 +430,40 @@ export class Lightmap {
     else _creator.lightmapSunSet?.(0, 1, 0, 0, 0, 0, false)
   }
 
-  /** 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). */
+  /** Apply a bake — or, under `lecodes lightmap bake`, run it. `def` is what `bake('<path>.bake', options)` compiled
+   *  to (a scene file's `env.lightmap`). 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> {
+  static async load(scene: Scene, def: LightmapDef): Promise<LightmapInfo | null> {
     Lightmap.scene = scene
     const bake = bakeConfig()
-    if (bake) { Lightmap.bake(bake, options.emissiveNits, options.emissiveBake ?? true, options.transmit, options.cube); return null }
+    if (bake) { Lightmap.bake(bake, def); 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
     }
+    if (def.data === null) { console.warn(`Lightmap: no bake at ${def.path} yet — run \`lecodes lightmap bake\``); return null }
     let data: BakeData
     try {
-      const resp = await fetch(files.data, { useOnce: true })
-      if (resp.status >= 400) { console.warn(`Lightmap: no bake at ${files.data} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
+      const resp = await fetch(def.data, { useOnce: true })
+      if (resp.status >= 400) { console.warn(`Lightmap: no bake at ${def.path} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
       data = resp.json()
     } catch (e) {
-      console.warn(`Lightmap: could not read ${files.data}: ${String(e)}`)
+      console.warn(`Lightmap: could not read ${def.path}: ${String(e)}`)
       return null
     }
     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\``)
+      console.warn(`Lightmap: ${def.path} is not a creator-bake file (version ${String(data.version)}) — rebake with \`lecodes lightmap bake\``)
       return null
     }
-    if (!data.pages || !(data.lightScale > 0)) return null   // the CLI's placeholder: nothing baked yet
-    if (!(await Lightmap.loadUv1(data, files))) return null   // the rects map the packed uv1: it goes in first
-    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`)
-    }
-    // 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)
+    if (!(await Lightmap.loadUv1(data, def))) return null   // the rects map the packed uv1: it goes in first
+    // the pages the manifest names, in order (bake() listed them off it); both atlases are DATA and exempt from
+    // Texture.maxSize (a capped atlas blurs every shadow edge)
+    const n = Math.min(data.pages, def.light.length, def.aux.length)
+    if (!(n > 0)) { console.warn(`Lightmap: ${def.path} names no atlas page — rebake with \`lecodes lightmap bake\``); return null }
+    const light = await Promise.all(def.light.slice(0, n).map((f) => Texture.load(f, { fullSize: true, srgb: false })))
+    const aux = await Promise.all(def.aux.slice(0, n).map((f) => Texture.load(f, { fullSize: true, srgb: false })))
+    const lightScale = data.lightScale * (def.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
@@ -457,19 +473,18 @@ export class Lightmap {
     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")
+    if (pb && pb.count > 0 && def.probes) {
+      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 })
+        probeAtlas = await Texture.load(def.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._h.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`)
       }
     }
-    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)` : ""}`)
+    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}${(def.lightScale ?? 1) !== 1 ? ` (bake ${data.lightScale} x ${def.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
@@ -483,7 +498,7 @@ export class Lightmap {
       Float32Array.from([ l.axis, l.from, l.to, l.cubes.length, ...l.cubes.flat(2), probeId(l.probes[0]), probeId(l.probes[1]), l.probes[2] ])
     // a bake from before the slabs (`light.cube`, one cube): not read — its small statics stay unlit until it is rebaked
     const lit = (l?: BakeObjectLight): l is BakeObjectLight => !!l && Array.isArray(l.cubes)
-    if (data.instances.some((i) => i.small && i.light && !lit(i.light))) console.warn(`Lightmap: ${files.data} has small statics without \`light.cubes\` (baked before the slabbed object light) — they stay unlit; rebake with \`lecodes lightmap bake\``)
+    if (data.instances.some((i) => i.small && i.light && !lit(i.light))) console.warn(`Lightmap: ${def.path} has small statics without \`light.cubes\` (baked before the slabbed object light) — they stay unlit; rebake with \`lecodes lightmap bake\``)
     // THE BAKE'S UNIT IS THE MESH: a model's primitives are records of their own, `<key>@<ordinal>` (ordinal = the primitive's
     // index over the file's meshes) - a rect, or a small static's light, each; the host binds record k to that primitive
     const parts = Lightmap.recordsOf(data.instances)
@@ -531,8 +546,8 @@ export class Lightmap {
     }
     if (small.size) console.log(`[lightmap] ${small.size} small, thin or cube-marked record(s) are not in the atlas (the bake's minTexels / thinTexels / cube): ${smallLit} lit by the light baked where they stand`)
     if (missing.length) console.warn(`Lightmap: ${missing.length} static(s) or mesh record(s) have no rect in the bake (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "…" : ""}) — rebake`)
-    Lightmap.bound = { data, rects, byEntity, files, pages: n, aux, light, probes, probeAtlas, showing: "light" }
-    await Lightmap.loadVolume(data, files)
+    Lightmap.bound = { data, rects, byEntity, files: def, pages: n, aux, light, probes, probeAtlas, showing: "light" }
+    await Lightmap.loadVolume(data, def)
     return { size: data.size, texel: data.texel, pages: n, applied, total: rects.size, missing }
   }
 
@@ -551,7 +566,7 @@ export class Lightmap {
   }
 
   /** 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). */
+   *  except "direct" / "indirect", which load that page set the first time (a bake made with `--split`). */
   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 ]
@@ -566,9 +581,9 @@ export class Lightmap {
     if (!b || b.showing === kind || !_creator.lightmapApply) return
     let tex = b[kind]
     if (!tex) {
-      const files = list(b.files[kind])
+      const files = 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`)
+        console.warn(`Lightmap: ${b.files.path} has no "${kind}" pages — rebake with \`lecodes lightmap bake --split\``)
         return
       }
       tex = await Promise.all(files.slice(0, b.pages).map((f) => Texture.load(f, { fullSize: true, srgb: false })))
@@ -656,7 +671,12 @@ export class Lightmap {
     return typeof c === "string" ? Color.toHexString(c) : "#ffffffff"
   }
 
-  /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic). */
+  /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic)
+   *  — and its GLOW, so a glowing Mesh looks the same before and after the bake applies: `emissive` (linear) becomes the
+   *  lightmap material's `emissiveFactor` at strength 1; its own `emissiveNits` go over with `emissiveOwn` 1, which the
+   *  level-wide write (`lightmapSetOptions`) leaves alone. A glow without nits takes the level's, like a GLB panel:
+   *  screen-referred under a level of 0 nits, else emission x the level's nits through the exposure — the same as
+   *  before the bake when the level's nits are the camera's (the default). */
   private static meshMaterial(mesh: Mesh): Material {
     const u = mesh.material?.uniforms ?? {}
     const m = Material.lightmap()
@@ -664,15 +684,28 @@ export class Lightmap {
     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)
+    // linear [r, g, b] as Material.lit writes it, or a colour string a later `.set('emissive', '#…')` left (the engine
+    // converts that one like any colour uniform)
+    const e = u.emissive
+    if ((Array.isArray(e) && e.length === 3 && e[0] + e[1] + e[2] > 0) || typeof e === "string") {
+      m.set("emissiveFactor", Array.isArray(e) ? [ e[0], e[1], e[2] ] : e as string).set("emissiveStrength", 1)
+      if (typeof u.emissiveNits === "number" && u.emissiveNits > 0) m.set("emissiveNits", u.emissiveNits).set("emissiveOwn", 1)
+    }
     return m
   }
 
-  private static bake(cfg: BakeConfig, levelNits?: number, emissiveBake = true, transmit?: Record<string, LightmapTransmit>, levelCube?: string[]): void {
+  private static bake(cfg: BakeConfig, def: LightmapDef): void {
+    // the target is where the level's bake() points (`<root>/<path>`): the files land next to the `.bake` it names
+    const slash = def.path.lastIndexOf("/")
+    const stem = def.path.slice(slash + 1).replace(/\.bake$/i, "")
+    if (cfg.stem !== undefined && cfg.stem !== stem) { console.log(`[lightmap] ${def.path} is not the level being baked (--name ${cfg.stem}): skipped`); return }
+    const outDir = cfg.outDir ?? (slash > 0 ? `${cfg.root}/${def.path.slice(0, slash)}` : cfg.root)
+    const levelNits = def.emissiveNits, emissiveBake = def.emissiveBake ?? true, transmit = def.transmit, levelCube = def.cube
     if (!_creator.lightmapBake) { console.error("[lightmap] error: this host has no bake module (the bake runs in lecodes-bake: LECODES_BAKE_EXE names a host without it)"); return }
     const idOf = (e: Entry): number => (e.model ?? e.mesh ?? e.ground!).id
     const ids = Uint32Array.from(Lightmap.entries.map(idOf))
     const keys = Lightmap.entries.map((e) => e.key).join("\n")
-    // the statics baked as cubes: by hand per node (`cube`), and by key - the CLI's --cube and the level's env.lightmap.cube, one regex
+    // the statics baked as cubes: by hand per node (`cube`), and by key - the CLI's --cube and the level's `cube` option, one regex
     const cubeIds = Uint32Array.from(Lightmap.entries.filter((e) => e.cube).map(idOf))
     const cubeKeys = [ ...(cfg.cube ?? []), ...(levelCube ?? []) ].filter((p) => p !== "").map((p) => `(?:${p})`).join("|")
     if (ids.length === 0) { console.error("[lightmap] error: nothing registered — call Lightmap.add on the static props before Lightmap.load"); return }
@@ -682,8 +715,8 @@ export class Lightmap {
     for (const l of live) _creator.setLightIntensity?.(l.id, 0)
     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,
+    if (emissiveNits > 0) console.log(`[lightmap] emission 1.0 = ${Math.round(emissiveNits)} nits${emissiveBake ? "" : ", DRAWN only (the level's emissiveBake: false - the emissive surfaces light nothing)"} (${cfg.emissiveNits !== undefined ? "--emissive-nits" : levelNits !== undefined ? "the level's emissiveNits" : `the camera's EV100 ${ev100.toFixed(1)}`})`)
+    _creator.lightmapBake(outDir, 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 ?? "",

package/src/gl/Material.ts

@@ -162,12 +162,36 @@ export const _sheetColsRows = (sheet: number | [number, number] | undefined): [n
   return [ Math.max(1, Math.floor(c) || 1), Math.max(1, Math.floor(r) || 1) ]
 }
 
-/** `Material.lit` options — PBR scalars on top of the color/map pair. */
+/** `Material.lit` options — PBR scalars on top of the color/map pair, and the surface's own glow. */
 export type LitMaterialOptions = MaterialColorOptions & MaterialStateOptions & {
   /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
   roughness?: number
   /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
   metallic?: number
+  /** The surface's GLOW, added on top of its lit colour: a ceiling panel, a screen, a sign. Any colour (sRGB, like
+   *  `color`); an `[r, g, b]` array may go past 1 — an HDR colour, its hue in sRGB and the excess a linear multiplier
+   *  (`[4, 3.6, 3]` = `[1, 0.9, 0.75]` four times as bright). Unset = no glow. */
+  emissive?: ColorInput
+  /** The glow's luminance in cd / m² (nits) for `emissive` 1.0 — `#ffffff` at 1600 is a typical ceiling panel. Set,
+   *  the glow is drawn SCENE-referred: through the camera's exposure, as bright as the light it gives the room in a
+   *  bake. Unset (or 0) = SCREEN-referred: the colour is drawn as it is whatever the exposure, and a bake counts it at
+   *  the level's `emissiveNits` (what the camera makes of 1.0 unless the level says otherwise). */
+  emissiveNits?: number
+  /** `false` = decoration: the glow is drawn, but a lightmap bake does not light the level with it (Unity's "Global
+   *  Illumination: None") — the level's lamps do. Default true: a glowing static lights the level like a lamp. The
+   *  level-wide `bake('…', { emissiveBake: false })` overrides it for every surface. */
+  emissiveBake?: boolean
+}
+
+// sRGB → linear, one channel (the exact curve: IEC 61966-2-1)
+const srgbToLinear = (v: number): number => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4)
+
+/** @internal `emissive` as lit.mat takes it: LINEAR rgb. An HDR array keeps its excess over 1 as a linear multiplier
+ *  on the sRGB hue (`peak` = its brightest channel). */
+export const _emissiveLinear = (c: ColorInput): [number, number, number] => {
+  const [ r, g, b ] = Color.toRgb01(c)
+  const peak = Math.max(r, g, b, 1)
+  return [ srgbToLinear(Math.max(0, r) / peak) * peak, srgbToLinear(Math.max(0, g) / peak) * peak, srgbToLinear(Math.max(0, b) / peak) * peak ]
 }
 
 
@@ -179,6 +203,9 @@ export class Material {
   readonly uniforms: Record<string, UniformValue>
 
   private _colorKey: string | null = null
+  /** @internal lit: whether the glow lights the level in a bake (`LitMaterialOptions.emissiveBake`); lit.mat carries
+   *  the same as its `emissiveBake` parameter, which is what the bake reads off a Mesh's instance */
+  _emissiveBake = true
 
   constructor(shader: FetchResponse | Handle | number) {
     if (typeof shader === "number") {
@@ -265,7 +292,8 @@ export class Material {
     return new Material(h)
   }
 
-  /** PBR lit material. */
+  /** PBR lit material. `emissive` / `emissiveNits` / `emissiveBake` are its glow (`LitMaterialOptions`); the uniforms
+   *  are written only for a material that asks for a glow, so a plain lit material never names them. */
   static lit(options: LitMaterialOptions = {}): Material {
     const m = Material._builtin(_creator.builtinMaterial("lit"), "lit")
     m._colorKey = "baseColor"
@@ -273,6 +301,12 @@ export class Material {
     if (options.map) m.map = options.map
     if (options.roughness !== undefined) m.uniforms.roughness = options.roughness
     if (options.metallic !== undefined) m.uniforms.metallic = options.metallic
+    if (options.emissiveBake === false) m._emissiveBake = false
+    if (options.emissive !== undefined) {
+      m.uniforms.emissive = _emissiveLinear(options.emissive)
+      if (options.emissiveNits !== undefined) m.uniforms.emissiveNits = Math.max(0, options.emissiveNits)
+      m.uniforms.emissiveBake = m._emissiveBake ? 1 : 0
+    }
     applyDepth(m, options)
     return m
   }

package/src/gl/Node.ts

@@ -94,6 +94,43 @@ const findNodeByWalk = (rootId: number, name: string): number => {
 // Scratch for the world-position read-back in _setOwnedPosition (one per module, never handed out).
 const worldScratch = new Float32Array(3)
 
+/** @internal The scene a node is in: the one `scene.add` put it or its nearest such ancestor in (`_inScene`), -1 = none
+ *  yet. A scene's nodes are pinned, so the walk meets the very wrappers `scene.add` stamped. */
+export const sceneIdOf = (node: Node): number => {
+  if (node._inScene >= 0) return node._inScene
+  for (let id = _creator.getParent(node.id); id !== 0; id = _creator.getParent(id)) {
+    const n = nodes.get(id)
+    if (n && n._inScene >= 0) return n._inScene
+  }
+  return -1
+}
+
+/** @internal A node whose render view starts once the node is in a scene (a secondary Camera's `renderToTexture`, a
+ *  ReflectionProbe): `_bindView(sceneId)` starts it if it has none. */
+export type ViewBinder = Node & { _bindView(sceneId: number): void }
+// The binders waiting for a scene, WEAKLY: a view never placed must not pin its node. Tried whenever the scene graph
+// grows (bindPendingViews) — an empty set costs that call one size check.
+const pendingViews = new Set<WeakRef<ViewBinder>>()
+/** @internal Start `binder`'s view now if its node is in a scene, else at the scene.add / node.add that puts it in one.
+ *  One try per placement: a view the host refuses (an overlay scene) warns and is not retried. */
+export const awaitScene = (binder: ViewBinder): void => {
+  const sceneId = sceneIdOf(binder)
+  if (sceneId >= 0) binder._bindView(sceneId)
+  else pendingViews.add(new WeakRef(binder))
+}
+/** @internal The scene graph grew (scene.add, node.add, setParent): start the waiting views whose node is in a scene now. */
+export const bindPendingViews = (): void => {
+  if (pendingViews.size === 0) return
+  for (const ref of pendingViews) {
+    const binder = ref.deref()
+    if (!binder) { pendingViews.delete(ref); continue }
+    const sceneId = sceneIdOf(binder)
+    if (sceneId < 0) continue
+    pendingViews.delete(ref)
+    binder._bindView(sceneId)
+  }
+}
+
 export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** @internal The entity's owned handle (`_h.id` = the entity id; DEAD_HANDLE once destroyed). An
    *  engine-created entity (a glTF part, an anchor) is wrapped from its number and pinned as the
@@ -101,6 +138,9 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   _h: Handle
   /** Native entity id. */
   get id(): number { return this._h.id }
+  /** @internal The id of the scene `scene.add` put this node in (-1 = none; `scene.remove` clears it) — how a render
+   *  view finds its scene (sceneIdOf). */
+  _inScene = -1
 
   private _matrix?: Float32Array
   private _worldMatrix?: Float32Array
@@ -132,6 +172,25 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   set name(value: string) { _creator.setName(this.id, value) }
   get visible(): boolean { return _creator.isVisible(this.id) }
   set visible(value: boolean) { _creator.setVisible(this.id, value) }
+  /**
+   * The node's visibility LAYERS, a bit mask 1..255. The scene's own view draws every layer; a render
+   * view (a secondary `Camera`'s or a `ReflectionProbe`'s, their `layers` option) draws only the
+   * renderables whose layers share a bit with its mask — which is what layers are for: leaving a subtree
+   * out of a second camera (the car out of the reflection probe riding on it, the player's own body out
+   * of a mirror). A node without a layer
+   * of its own takes its nearest ancestor's, else 1, so a car's layer covers everything parented under
+   * it; `0` clears the node's own (inherit again). `visible = false` wins over any layer. Reads the
+   * effective bits. A host without layers draws everything everywhere (reads 1, a write warns once).
+   */
+  get layer(): number { return _creator.getLayer ? _creator.getLayer(this.id) : 1 }
+  set layer(mask: number) {
+    if (_creator.setLayer) _creator.setLayer(this.id, mask & 0xff)
+    else if (!Node._warnedLayer) {
+      Node._warnedLayer = true
+      console.warn("[node] this host has no setLayer — node layers are ignored, every view draws everything")
+    }
+  }
+  private static _warnedLayer = false
 
   // --- local transform ---
   // Native owns the authoritative matrix. `_sync()` reads it into a per-node scratch buffer on EVERY
@@ -317,6 +376,7 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
   /** Parent the given nodes under this one. */
   add(...children: Node[]): this {
     for (const c of children) { _creator.setParent(c.id, this.id, false); nodes.pin(c) }
+    bindPendingViews()
     return this
   }
   setParent(parent: Node | null, worldPositionStays = false): this {
@@ -326,6 +386,7 @@ export class Node extends AspectHost<NodeEvents> implements CompWriter {
     } else {
       _creator.setParent(this.id, parent.id, worldPositionStays)
       nodes.pin(this)
+      bindPendingViews()
     }
     return this
   }

package/src/gl/Particles.ts

@@ -306,7 +306,7 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
    *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
   order?: number
-  /** Sprites take the light of the PLACE each one is in — the level's baked light grid (`env.lightmap.volume`).
+  /** Sprites take the light of the PLACE each one is in — the level's baked light grid (the bake's `.lgrid`).
    *  A sprite is unlit: its colour is the picture, which is right for fire and wrong for dust — a puff kicked up
    *  under an awning glows as if it stood in the sun. With `lit` every particle's colour is multiplied by the light
    *  where it is, relative to the level's OPEN ground: exactly the authored colour out in the sun, the ambient's