lecodes-sdk 2.4.6 → 2.4.8

package/src/gl/Lightmap.ts

@@ -3,8 +3,9 @@
 // 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 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:
+// `lecodes lightmap bake` (the bake tool lecodes-bake — the windowless host with the bake built in —
+// describes the live scene to creator-bake, which traces it on the GPU 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
@@ -67,6 +68,11 @@ export type LightmapLoadOptions = {
    *  `{ 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>
+  /** FOR THE BAKE: CUBES BY NAME — regular expressions (ECMAScript, case-sensitive) searched in every record's key
+   *  (`<node key>@<ordinal>`: `"SM_pipe"` takes every pipe node, `"@1$"` the second mesh of each): a record that matches
+   *  leaves the atlas like a small or thin one — an occluder lit by ambient cubes baked where it stands — whatever its size
+   *  or charts. Added to the CLI's `--cube` patterns (both apply). */
+  cube?: string[]
 }
 
 /** one `transmit` entry (LightmapLoadOptions.transmit): the straight share, or both shares */
@@ -98,11 +104,17 @@ export type LightmapFiles = {
   /** 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
+  /** 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. */
+  uv1?: string
 }
 
 /** 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 TRACERS = { auto: 0, optix: 1, vulkan: 2 } as const       // CBAKE_TRACER_*
+const DENOISERS = { auto: 0, optix: 1, oidn: 2 } as const       // CBAKE_DENOISER_*
 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" }
 
@@ -125,15 +137,32 @@ export type LightmapProbe = {
   distance: number
 }
 
-/** `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 }
+/** `ground` = a terrain node (built with `Material.terrainLightmap()`): one rect, bound to its chunks by the host;
+ *  `cube` = every record of it bakes as ambient cubes (`LightmapAddOptions.cube`, a scene node's `lightmap: 'cube'`) */
+type Entry = { key: string, model?: Model, mesh?: Mesh, ground?: Node, cube?: boolean }
+
+/** `Lightmap.add`'s options */
+export type LightmapAddOptions = {
+  /** Bake it as AMBIENT CUBES instead of atlas texels: an occluder (its shadow and bounce stay in the atlas) whose own
+   *  light is baked where it stands — the way the bake treats small and thin objects (`--min-texels`, `--thin-texels`),
+   *  here by hand: a pipe run, a fence, a prop whose charts show their seams. A long one takes a slab of cubes per metre
+   *  (`--object-slab`). Default false. */
+  cube?: boolean
+}
 
 type BakeConfig = {
   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"`. */
+  /** 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"`. */
   denoise?: "none" | "indirect" | "no-sun" | "all",
+  /** Which GPU API traces: `"auto"` (the default) = OptiX where an NVIDIA driver with OptiX opens, else Vulkan ray query — any card
+   *  with hardware ray tracing (RTX, Radeon RX 6000+, Arc) with its driver alone; `"optix"` / `"vulkan"` by name (the bake fails
+   *  when it cannot open). */
+  tracer?: "auto" | "optix" | "vulkan",
+  /** Which AI denoiser `denoise` runs: `"auto"` (the default) = OptiX's on an NVIDIA card, else Intel Open Image Denoise (its CUDA /
+   *  HIP / CPU device); `"optix"` / `"oidn"` by name. Independent of the tracer. One that cannot open is a warning: the pages stay as traced. */
+  denoiser?: "auto" | "optix" | "oidn",
   /** 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). */
@@ -153,6 +182,19 @@ type BakeConfig = {
    *  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,
+  /** ROUND AND NARROW objects leave the atlas the same way: an instance none of whose lightmap charts is wider than this
+   *  many texels across its short side (at `texel`) — a railing's tubes, a cable, a pipe run, blinds. A strip of 1-3 texels
+   *  around a tube cannot hold the light's change around it and its uv seam shows as a step; the ambient cube baked where
+   *  it stands is smooth. A flat object has a wide chart somewhere and stays. 0 = off. Default 4 (20 cm at 5 cm texels). */
+  thinTexels?: number,
+  /** A LONG object the atlas left out takes its light in SLABS of this many metres along the longest axis of its bounds
+   *  (round(length / objectSlab), 16 at most) — a 6 m pipe run, a railing along a wall: one end under a lamp, the other in
+   *  the dark, where one cube gave all of it the mean. The shader blends the two slabs around each pixel along that axis.
+   *  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. */
+  cube?: string[],
   /** 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
@@ -170,9 +212,12 @@ type BakeConfig = {
   debugDir?: string,
 }
 
-/** 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[] }
+/** a small static's light where it stands (creator-bake objects.h): its SLABS along `axis` (0 x, 1 y, 2 z; its bounds run
+ *  from `from` to `to` along it) — one for a small one, round(length / objectSlab) for a long one — and per slab per side
+ *  of its box (+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[], axis: number, from: number, to: number, cubes: number[][][], probes: number[] }
+/** a RECORD of the .bake: a registered node's key, or `<key>@<ordinal>` for one mesh of a model (creator-bake atlas.h) */
 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[],
@@ -189,6 +234,8 @@ type BakeData = {
   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,
+  /** the packed lightmap uv1 the rects map (creator-bake atlas.h), null = the models' own */
+  uv1?: string | null,
   sun?: { direction: number[], color: number[], lux: number } | null, sunMap?: boolean, sunMapLevels?: number, mips?: number, emissiveNits?: number,
   instances: BakeInstance[],
 }
@@ -225,16 +272,17 @@ export class Lightmap {
    *  both receivers and occluders in the bake (a model without lightmap UVs, or with materials the lightmap shader
    *  declines — alpha cards — is an occluder alone; a terrain is ONE rect, built with `Material.terrainLightmap()`).
    *  `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 {
+   *  names are not stable. `{ cube: true }` bakes it as ambient cubes instead of atlas texels (`LightmapAddOptions`). */
+  static add(node: Node, key?: string, options: LightmapAddOptions = {}): Node {
     const base = key ?? `${node.name || "node"}#${Lightmap.next(node.name || "node")}`
+    const cube = options.cube === true
     const found: Entry[] = []
     const walk = (n: Node): void => {
       // the node `Terrain.create` returned carries its terrain (Terrain.of reads the same field): the host keeps the
       // terrain's triangles under this node's id for the bake and binds the rect to its chunks
-      if ((n as unknown as { _terrain?: unknown })._terrain) { found.push({ key: base, ground: n }); return }
-      if (n instanceof Model) { found.push({ key: base, model: n }); return }
-      if (n instanceof Mesh) { found.push({ key: base, mesh: n }); return }
+      if ((n as unknown as { _terrain?: unknown })._terrain) { found.push({ key: base, ground: n, cube }); return }
+      if (n instanceof Model) { found.push({ key: base, model: n, cube }); return }
+      if (n instanceof Mesh) { found.push({ key: base, mesh: n, cube }); return }
       for (const c of n.children) walk(c)
     }
     walk(node)
@@ -244,13 +292,13 @@ export class Lightmap {
     return node
   }
 
-  /** @internal Scene-file runtime: one model/mesh node under its path key (no subtree walk). */
-  static _register(node: Model | Mesh, key: string): void {
-    Lightmap.entries.push(node instanceof Model ? { key, model: node } : { key, mesh: node })
+  /** @internal Scene-file runtime: one model/mesh node under its path key (no subtree walk); `cube` = `lightmap: 'cube'`. */
+  static _register(node: Model | Mesh, key: string, cube = false): void {
+    Lightmap.entries.push(node instanceof Model ? { key, model: node, cube } : { key, mesh: node, cube })
   }
   /** @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 })
+  static _registerGround(node: Node, key: string, cube = false): void {
+    Lightmap.entries.push({ key, ground: node, cube })
   }
 
   private static next(name: string): number {
@@ -308,12 +356,31 @@ export class Lightmap {
     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)`)
   }
 
+  /** THE PACKED UV1 the bake's rects map (the .bake's `uv1`), into the host BEFORE any rect is applied: the host swaps it
+   *  into the models' TEXCOORD_1 as their rects go on. A bake without one clears the last (the models' own uv1 back).
+   *  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 }
+    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 })
+      if (resp.status >= 400) { console.warn(`Lightmap: no packed uv1 at ${files.uv1} (HTTP ${resp.status}) — the bake is not applied`); return false }
+      if (!_creator.lightmapUv1Load((resp as unknown as { _h: Handle })._h.id)) { console.warn(`Lightmap: ${files.uv1} is not a packed uv1 — rebake`); return false }
+    } catch (e) {
+      console.warn(`Lightmap: could not read ${files.uv1}: ${String(e)}`)
+      return false
+    }
+    return true
+  }
+
   /** 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?.()
+    _creator.lightmapUv1Clear?.()
     Lightmap.entries = []
     Lightmap.ordinals.clear()
     Lightmap.bound = null
@@ -350,7 +417,7 @@ export class Lightmap {
   static async load(scene: Scene, files: LightmapFiles, options: LightmapLoadOptions = {}): Promise<LightmapInfo | null> {
     Lightmap.scene = scene
     const bake = bakeConfig()
-    if (bake) { Lightmap.bake(bake, options.emissiveNits, options.emissiveBake ?? true, options.transmit); return null }
+    if (bake) { Lightmap.bake(bake, options.emissiveNits, options.emissiveBake ?? true, options.transmit, options.cube); 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
@@ -369,6 +436,7 @@ export class Lightmap {
       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 }
@@ -410,9 +478,15 @@ export class Lightmap {
     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)
+    // lightmapObjectApply's numbers: axis, from, to, n, then n slabs x six sides x (rgb, sky), then probe a, probe b, a's weight
+    const objectData = (l: BakeObjectLight) =>
+      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\``)
+    // 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)
     let smallLit = 0
     const byEntity = new Map<number, Entry>()
     let applied = 0
@@ -420,19 +494,20 @@ export class Lightmap {
     for (const e of Lightmap.entries) {
       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]._h.id, aux[0]._h.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]._h.id, aux[inst.page]._h.id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
+      const records = parts.get(e.key)
+      if (records) {
+        let took = 0, receivers = 0
+        for (const [ k, inst ] of records) {
+          if (inst.small) {
+            if (lit(inst.light) && _creator.lightmapObjectApply && n > 0 && _creator.lightmapObjectApply(node.id, light[0]._h.id, aux[0]._h.id, objectData(inst.light), k) > 0) { took++; smallLit++ }
+          } else if (inst.receiver) {
+            receivers++
+            if (!inst.st || inst.page === undefined || inst.page >= n) { missing.push(inst.key); continue }
+            if (_creator.lightmapApply(node.id, light[inst.page]._h.id, aux[inst.page]._h.id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k) > 0) took++
           }
         }
-        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++
+        if (took > 0) applied++
+        else if (receivers > 0) console.warn(`Lightmap: ${e.key} (${records.size} mesh record(s)) took no rect — not loaded lightmapped (Model.load { lightmap: true }), or the host binds no records (rebuild it)`)
         continue
       }
       const r = rects.get(e.key)
@@ -440,10 +515,9 @@ export class Lightmap {
       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 (!lit(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]._h.id, aux[0]._h.id, d) > 0) smallLit++
+        if (_creator.lightmapObjectApply(node.id, light[0]._h.id, aux[0]._h.id, objectData(l)) > 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)
@@ -455,19 +529,19 @@ export class Lightmap {
       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`)
+    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)
     return { size: data.size, texel: data.texel, pages: n, applied, total: rects.size, missing }
   }
 
-  /** 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>> {
+  /** The bake's `<key>@k` records by their node key: a model's meshes (k = the primitive's ordinal in its file). */
+  private static recordsOf(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)
+      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) }
@@ -502,7 +576,7 @@ export class Lightmap {
       b[kind] = tex
     }
     b.showing = kind
-    const parts = Lightmap.groupsOf(b.data.instances)
+    const parts = Lightmap.recordsOf(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]._h.id, b.aux[inst.page]._h.id, inst.st[0], inst.st[1], inst.st[2], inst.st[3], k)
@@ -553,7 +627,7 @@ export class Lightmap {
   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, number], lightmapGroup?: number }
+    type Hit = { entity: number, nodeName: string, material: string, point: number[], distance: number, uv1?: [number, number], lightmapOrdinal?: 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
@@ -564,7 +638,7 @@ export class Lightmap {
     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 hitKey = hit.lightmapOrdinal !== undefined && b.rects.has(`${entry.key}@${hit.lightmapOrdinal}`) ? `${entry.key}@${hit.lightmapOrdinal}` : 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 }
@@ -593,10 +667,14 @@ export class Lightmap {
     return m
   }
 
-  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))
+  private static bake(cfg: BakeConfig, levelNits?: number, emissiveBake = true, transmit?: Record<string, LightmapTransmit>, levelCube?: string[]): void {
+    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
+    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 }
     // 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
@@ -609,7 +687,8 @@ export class Lightmap {
       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(";"))
+      Object.entries(transmit ?? {}).map(([name, share]) => typeof share === "number" ? `${name}=${share}` : `${name}=${share.through ?? 0},${share.diffuse ?? 0}`).join(";"),
+      TRACERS[cfg.tracer ?? "auto"] ?? 0, DENOISERS[cfg.denoiser ?? "auto"] ?? 0, cfg.thinTexels ?? 4, cfg.objectSlab ?? 1, cubeKeys, cubeIds)
     for (const l of live) _creator.setLightIntensity?.(l.id, l.intensity)
   }
 }

package/src/gl/Model.ts

@@ -20,8 +20,8 @@ export interface TrianglePick {
   mesh: string
   primitive: number
   material: string
-  /** the node's lightmap group (scene-file extras), when it has one */
-  lightmapGroup?: number
+  /** the primitive's index over its file's meshes: the lightmap bake's record `<key>@<ordinal>` */
+  lightmapOrdinal: number
   /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
   triangle: number
   backface: boolean
@@ -130,8 +130,8 @@ export class Model extends Node {
       culling?: boolean
       onProgress?: (p: { loaded: number, total?: number }) => void
       /** Baked lighting (engines/bake). `true` = a STATIC: loads through the lightmap material so
-       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
-       *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
+       *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 —
+       *  `lecodes assets unwrap`, which `lightmap bake` runs itself on raw GLBs) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
        *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */
       lightmap?: boolean
       /** Vegetation: load through the FOLIAGE tier (see `Foliage`) — wind, touch bending, distance fade,

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/ReflectionProbe.ts

@@ -0,0 +1,141 @@
+// A reflection probe: a cube of the scene's light drawn around a point, live (creator-gl renderview.cpp: a render view of
+// six faces into an HDR cube render texture; with PREFILTER, Filament's libs/iblprefilter filter after each completed
+// cube). A Node, placed and parented like any; its view starts once the node is in a scene (Node.ts awaitScene) — or at
+// `scene.environment = probe` while it is in none. RenderTexture.ts holds the half it shares with a secondary Camera.
+
+import { Node, awaitScene } from "./Node"
+import { CAMERA_DEFAULTS } from "./Camera"
+import {
+  RenderTexture, RT_FLAG_CUBEMAP, RT_FLAG_HDR, RT_FLAG_PREFILTER, RT_MAX_SIDE, makeRenderTexture, requireRenderTextures, startRenderView,
+} from "./RenderTexture"
+
+/** `new ReflectionProbe(options)`: the cube, what its view draws, and how often. */
+export type ReflectionProbeOptions = {
+  /** The cube's edge, texels per face side (default 128): a power of two, 16..4096, when prefiltered; 1..4096 otherwise.
+   *  A probe is light, not a picture — 64..128 is plenty for a car's reflections. */
+  size?: number
+  /** The layers its view draws, a bit mask over `Node.layer` (default 0xff = everything): leave out the probe's own
+   *  carrier, or the cube is the inside of the car it rides on. Fixed. */
+  layers?: number
+  /** Shadows in its view (default `false`): with them, a full cube renders its own shadow maps six times. Fixed. */
+  shadows?: boolean
+  /** Faces drawn per render, 1..6, round-robin (default 6 = the whole cube) — `probe.facesPerFrame`. */
+  facesPerFrame?: number
+  /** Render once every N frames drawn (default 1 = every frame) — `probe.everyNth`. */
+  everyNth?: number
+  /** Filter the cube for ROUGHNESS (default `true`; `size` a power of two then). Without it the cube has one sharp level:
+   *  under `scene.environment` only mirror-like surfaces (roughness near 0) are right, and the diffuse ambient stays the
+   *  scene's own probe's. With it the GPU filters every completed cube into five roughness levels — a brushed or painted
+   *  body shows its surroundings blurred as much as its roughness says — and the roughest level becomes the diffuse
+   *  ambient: what the probe sees lights matte surfaces too (a red wall tints them red).
+   *
+   *  COST: one filtering per completed cube (every render at `facesPerFrame` 6, every third at 2), on the frame after:
+   *  the cube's mip chain plus a pass per level whose taps are the level's texels × `samples` — for a 64 cube at the
+   *  default 256 samples about 2 million cube taps — and ten small driver submissions on the CPU. `everyNth` /
+   *  `facesPerFrame` space the filterings out. Fixed. */
+  prefilter?: boolean
+  /** The filter's samples per texel, 1..2048 (default 256 — a quarter of Filament's offline default: each sample reads
+   *  the mip that matches its footprint, which keeps a low count smooth; raise it if a mid-roughness surface reads
+   *  blotchy). Smoothness for time; read with `prefilter` only. */
+  samples?: number
+  /** Near clip plane in metres (default 0.01). Fixed. */
+  near?: number
+  /** Far clip plane in metres (default 1000). Fixed. */
+  far?: number
+}
+
+/**
+ * A REFLECTION PROBE: a cube of the scene's light drawn around a point, live — chrome and glass show what is actually
+ * around them, moving objects included. A Node: place it, or parent it (`car.add(probe)` — it rides along); the six faces
+ * look along the world axes from its WORLD position (its rotation and scale are ignored). It draws once it is in a scene
+ * (added to one, or under a node that is), every frame that scene is on show — after the frame's update passes, before
+ * the scene's own picture — in linear HDR light (no tone mapping) at the scene camera's exposure. It sees the scene's
+ * renderables, lights, environment and sky, not its overlays.
+ *
+ * Two ways to use it:
+ *  - `scene.environment = probe`: the scene's reflections come from the cube instead of the scene's own probe
+ *    (`SceneOptions.ibl`) — and, prefiltered (the default), its diffuse ambient too. A probe in no scene yet starts in
+ *    that one.
+ *  - `probe.texture` in a material that samples a cube itself (a custom shader's samplerCubemap): the same cube as a
+ *    `RenderTexture` — when prefiltered, the filtered one, five roughness levels.
+ *
+ * COST: a full render is six passes over the scene, plus (prefiltered) a GPU filtering per completed cube (`prefilter`
+ * says what one costs). Keep `size` small (128 is a lot), spread the cube over frames (`facesPerFrame: 2` = a whole cube
+ * every 3 frames, a third of the cost each), render less often (`everyNth`), leave out what it need not see (`layers` —
+ * its carrier first), keep `shadows` off, and turn it off once a static surrounding is drawn (`enabled = false` keeps the
+ * last cube).
+ *
+ * LIFETIME: the cube and its view live as long as the probe — keep a reference (`scene.environment` holds it too).
+ * Destroying the probe's node stops the view (the cube keeps its last light); moving it to another scene later does not
+ * move the view. Throws on a host without render textures (`createRenderTexture` — the web hosts, for now).
+ */
+export class ReflectionProbe extends Node {
+  /** The cube the probe draws (`cubemap`, linear HDR light) — the filtered one, five roughness levels, when `prefilter`. */
+  readonly texture: RenderTexture
+  /** Filtered for roughness (the `prefilter` option). */
+  readonly prefilter: boolean
+  /** @internal The render view's owned handle (`_view.id` = the engine's view id), null until the view starts: it lives
+   *  exactly as long as this probe holds it. */
+  _view: Handle | null = null
+  private readonly _layers: number
+  private readonly _shadows: boolean
+  private readonly _near: number
+  private readonly _far: number
+  private _enabled = true
+  private _everyNth: number
+  private _facesPerFrame: number
+
+  constructor(options: ReflectionProbeOptions = {}) {
+    requireRenderTextures("new ReflectionProbe")
+    const size = Math.max(1, Math.floor(options.size ?? 128))
+    const prefilter = options.prefilter !== false
+    if (prefilter && (size < 16 || size > RT_MAX_SIDE || (size & (size - 1)) !== 0)) {
+      throw new Error(`new ReflectionProbe: a prefiltered probe's size is a power of two, 16..${RT_MAX_SIDE} (got ${size}) — or prefilter: false`)
+    }
+    super()
+    const samples = prefilter ? Math.max(0, Math.floor(options.samples ?? 0)) : 0
+    this.texture = makeRenderTexture("new ReflectionProbe", size, size, RT_FLAG_CUBEMAP | RT_FLAG_HDR | (prefilter ? RT_FLAG_PREFILTER : 0), samples)
+    this.prefilter = prefilter
+    this._layers = (options.layers ?? 0xff) & 0xff
+    this._shadows = options.shadows === true
+    this._near = options.near ?? CAMERA_DEFAULTS.near
+    this._far = options.far ?? CAMERA_DEFAULTS.far
+    this._everyNth = Math.max(1, Math.floor(options.everyNth ?? 1))
+    this._facesPerFrame = Math.min(6, Math.max(1, Math.floor(options.facesPerFrame ?? 6)))
+    awaitScene(this)
+  }
+
+  /** @internal Node.ts awaitScene / Scene.environment: the probe is in scene `sceneId` — start its view into its cube. */
+  _bindView(sceneId: number): void {
+    if (this._view) return
+    this._view = startRenderView("ReflectionProbe", sceneId, this.texture, this.id, this._layers, 90, this._near, this._far, this._shadows)
+    if (this._view && (!this._enabled || this._everyNth !== 1 || this._facesPerFrame !== 6)) this._sendSchedule()
+  }
+
+  /** Whether the probe draws (default `true`). Off keeps the last cube and costs nothing — a probe that has drawn its
+   *  static surroundings once; back on, it renders on the next frame drawn. */
+  get enabled(): boolean { return this._enabled }
+  set enabled(on: boolean) {
+    this._enabled = on
+    this._sendSchedule()
+  }
+  /** Render once every N frames DRAWN (default 1 = every frame). The count restarts with each change: the next frame
+   *  drawn renders, then one in every N. */
+  get everyNth(): number { return this._everyNth }
+  set everyNth(n: number) {
+    this._everyNth = Math.max(1, Math.floor(n))
+    this._sendSchedule()
+  }
+  /** The cube's faces drawn per render, 1..6 (default 6), round-robin from where the last render stopped: 2 spreads a
+   *  whole cube over 3 renders at a third of the cost each. A prefiltered cube is filtered each time it completes. */
+  get facesPerFrame(): number { return this._facesPerFrame }
+  set facesPerFrame(n: number) {
+    this._facesPerFrame = Math.min(6, Math.max(1, Math.floor(n)))
+    this._sendSchedule()
+  }
+
+  /** @internal Send the whole schedule (`setRenderViewOptions` restarts the count, so the next frame drawn renders). */
+  private _sendSchedule(): void {
+    if (this._view) _creator.setRenderViewOptions?.(this._view.id, this._enabled, this._everyNth, this._facesPerFrame)
+  }
+}