lecodes-sdk 2.4.5 → 2.4.7

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.5",
+  "version": "2.4.7",
   "files": [
     "src",
     "dist",

package/src/bridges/app.d.ts

@@ -11,7 +11,7 @@
 // `?` on a method = an optional slot: a host that leaves it null gets no such JS method, so the SDK's
 // `typeof` feature-detects stay honest. The `HostApp` interface below adds the slots the runtime
 // calls that JS never sees (notifications to the host).
-import type { bytes, i32 } from "./types"
+import type { bytes, f64, i32 } from "./types"
 
 declare global {
   // ---- World control (run/restart/quit — the platform's `location` analog) ----------------------
@@ -58,6 +58,13 @@ declare global {
     /** Collect garbage, drain the release queue and report the live owned records per kind
      *  (`{"live":{"tree":n,…},"pending":n}`) — the read behind checks/owned. @custom */
     ownedStats(): string
+    /** Collect garbage and drain the release queue now, logging `[gc] app.gc: <ms>, heap …, next at
+     *  …, <n> owned resources freed`. `headroomMB` (> 0) puts the next automatic pass at least that
+     *  many megabytes above the heap the pass left (QuickJS; until that pass). On JavaScriptCore a
+     *  request (the engine collects on its own schedule, the drain follows: on iOS the line says 0;
+     *  no headroom); the wasm arm collects only under Bun, in a browser page it is the drain alone.
+     *  Web Lite has no such member. Backs app.gc. @custom */
+    gc?(headroomMB?: f64): void
     /** Current lifecycle state: "active" | "background". Surfaced as app.state. */
     state?(): string
     /** Current connectivity (navigator.onLine semantics — best-effort: false only when the platform

package/src/bridges/gl.d.ts

@@ -14,9 +14,11 @@ export type PickBone = { name: string, weight: f32 }
  *  `bones` = its JOINTS_0 / WEIGHTS_0 pairs with weight > 0 (empty = unweighted). */
 export type PickVertex = { index: u32, bind: [f32, f32, f32], world: [f32, f32, f32], bones: PickBone[] }
 /** The closest triangle under a screen point (`pickTriangle`). `node` = the mesh node's own entity (0
- *  when the host has none), `lightmapGroup` / `uv1` only when the node / primitive carry them. */
+ *  when the host has none), `lightmapOrdinal` = the primitive's index over the file's meshes (the bake's record
+ *  `<key>@<ordinal>`), `uv1` (the lightmap uv the GPU reads: the bake's packed one when loaded) only when the primitive
+ *  carries one. */
 export type TrianglePick = {
-  entity: u32, node: u32, nodeName: string, lightmapGroup?: i32,
+  entity: u32, node: u32, nodeName: string, lightmapOrdinal: u32,
   mesh: string, primitive: u32, material: string,
   triangle: u32, backface: boolean, distance: f32,
   point: [f32, f32, f32], bary: [f32, f32, f32], uv1?: [f32, f32],
@@ -671,23 +673,31 @@ declare global {
     // JoltPhysics. motionType: 0 static / 1 kinematic / 2 dynamic.
     /** @c creatorHasPhysics */
     physicsHasSupport(): boolean
-    /** Lightmap bake (engines/bake) — a dev-time tool compiled into the desktop host only; `lightmapBake` exists
+    /** Lightmap bake (engines/bake) — a dev-time tool compiled into the bake tool lecodes-bake only; `lightmapBake` exists
      *  only where `lightmapHasSupport()` is true. Describes the given static instances (GLB roots / Mesh entities;
      *  `keysJoined` = one key per id, '
 '-joined), the scene's brightest sun, its point lights (spherical emitters of
-     *  `lightRadius` metres) and its IBL to the bake, which traces them on the NVIDIA card — direct light plus
+     *  `lightRadius` metres) and its IBL to the bake, which traces them on the GPU (`tracer`: 0 auto = OptiX where an NVIDIA driver
+     *  with OptiX opens, else Vulkan ray query on any card with hardware ray tracing; 1 OptiX, 2 Vulkan by name) — direct light plus
      *  `bounceRays` Lambertian paths of `bounces` vertices per texel (0 / 0 = direct only) with `patchSamples` next-event
      *  samples over the bright patches of a first direct pass — and writes
      *  `<outDir>/<stem>.bake` + `<stem>-light[_n].ktx2` (irradiance in lux / lightScale, BC6H) + `<stem>-aux[_n].ktx2`
      *  (sun / sky visibility + light direction); `split` adds `<stem>-direct[_n]` / `-indirect[_n]` page sets for the
-     *  SDK's two views; `denoise` runs OptiX's AI denoiser over 0 nothing, 1 the indirect part, 2 + the sky and the lamps, 3 + the sun; `filter` = the texel's reconstruction filter radius in texels (1 = ±1 texel tent, 0.5 = within the texel, 0 = the centre alone);
+     *  SDK's two views; `denoise` runs the AI denoiser (`denoiser`: 0 auto = OptiX's on an NVIDIA card, else Intel Open Image Denoise; 1 OptiX, 2 OIDN by name —
+     *  independent of the tracer) over 0 nothing, 1 the indirect part, 2 + the sky and the lamps, 3 + the sun; `filter` = the texel's reconstruction filter radius in texels (1 = ±1 texel tent, 0.5 = within the texel, 0 = the centre alone);
      *  `probeSpacing` > 0 places REFLECTION PROBES on a grid of that many metres and writes `<stem>-probes.ktx2` (a BC6H atlas of octahedral
      *  maps: one column of roughness-level tiles per probe, captured with `probeSize`² cube faces and `probeRays` paths per texel; the scene's
      *  IBL cubemap is what an escaping ray sees; `probeIndoor` keeps only the probes under a roof (an open share of the sphere of at most 15 %) — the
      *  outdoors reflects the sky through the texel's baked sky visibility instead; `volumeSpacing` (metres, 0 = none) bakes THE LIGHT GRID for movers — `<name>.lgrid`, named in the .bake's `volume`: per cell
      *  in free space an ambient cube without the direct sun, links between neighbours a ray connects (what `setAmbientCube`
-     *  is fed from); `minSize` (metres, 0 = off) leaves every instance smaller than that along every axis out of the atlas — an occluder
-     *  only, `"small": true` + its `light` (an ambient cube baked where it stands) in the .bake, applied by lightmapObjectApply; `probeLayout` 0 = ROOMS (indoor points slide to their
+     *  is fed from); `minSize` (metres, 0 = off) leaves every record (a mesh of an instance) smaller than that along every axis out of the atlas — an occluder
+     *  only, `"small": true` + its `light` (an ambient cube baked where it stands) in the .bake, applied by lightmapObjectApply; `thinTexels` (0 = off) does the same to every
+     *  record none of whose lightmap charts is wider than that many texels across its short side — a railing's tubes, a cable, a pipe run: 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; `objectSlab` (metres, 0 = one cube an object) gives a long one of
+     *  those round(length / objectSlab) cubes along the longest axis of its bounds (16 at most), blended per pixel along it; BY HAND, the same way out of
+     *  the atlas: every record whose key (`<node key>@<ordinal>`) `cubeKeys` matches — an ECMAScript regular expression, searched, case-sensitive ("" = off; one
+     *  that does not compile fails the bake: "error: bad --cube pattern") — and every record of the entities in `cubeIds` (of `entityIds`: a node's
+     *  `lightmap: 'cube'`), whatever their size or charts; `probeLayout` 0 = ROOMS (indoor points slide to their
      *  room's middle and merge: one probe per room), 1 = GRID; `probeBox` = 6 floats, min xyz + max xyz, keeps the grid inside that box — null = the
      *  receivers' bounds) and the grid into the .bake; `debugDir` (optional) gets the float layers per page. Synchronous; progress on stdout as
      *  "[lightmap] …" lines, "[lightmap] done" on success. @c creatorHasLightmapBake */
@@ -697,7 +707,7 @@ declare global {
                   sunRays: u32, skyRays: u32, lightRays: u32, lightRadius: f32, sunAngleDeg: f32, bias: f32, seed: u32,
                   bounceRays: u32, bounces: u32, patchSamples: u32, split: boolean, denoise: u32, filter: f32,
                   probeSpacing: f32, probeSize: u32, probeRays: u32, probeIndoor: boolean, probeLayout: u32, probeBox: Float32Array | null, minSize: f32, volumeSpacing: f32, emissiveNits: f32, detailTexels: u32, debugDir?: string,
-                  transmit?: string): boolean
+                  transmit?: string, tracer?: u32, denoiser?: u32, thinTexels?: f32, objectSlab?: f32, cubeKeys?: string, cubeIds?: Uint32Array): boolean
     /** Lightmap consumption: the next createGlb takes lightmap.filamat (the material behind that instance id) for its
      *  OPAQUE materials and the masked twin for its MASK materials instead of the ubershader, and keeps TEXCOORD_1;
      *  BLEND (glass) materials always keep the ubershader. 0xFFFFFFFF clears. The same call arms the foliage tier. @custom */
@@ -724,17 +734,22 @@ declare global {
      *  Returns the probe count; an invalid texture id clears. */
     lightmapProbesSet?(atlasTextureId: u32, oct: u32, levels: u32, perRow: u32, count: u32,
                        lox: f32, loy: f32, loz: f32, sx: f32, sy: f32, sz: f32): u32
-    /** Bind the light page + the aux page + this instance's rect (uv1 * [sx, sy] + [ox, oy]) on every lightmap-material
-     *  instance of the entity (a GLB instance's renderables, or a Mesh entity's own) and move those renderables to light
-     *  channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). Returns how many
+    /** Bind the light page + the aux page + a RECORD's rect (uv1 * [sx, sy] + [ox, oy]) and move the renderables it went on
+     *  to light channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). The bake's
+     *  unit is the mesh: a GLB instance is one record per primitive (`<key>@<ordinal>` in the .bake); `ordinal` >= 0 binds
+     *  that primitive (its index over the file's meshes) of every node that draws it, on a material instance of its own;
+     *  -1 (the default) = every lightmap-material primitive of the entity (a Mesh entity, a terrain). Returns how many
      *  material instances took it (0 = not loaded lightmapped). */
-    lightmapApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, sx: f32, sy: f32, ox: f32, oy: f32, group?: i32): u32
+    lightmapApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, sx: f32, sy: f32, ox: f32, oy: f32, ordinal?: i32): u32
     /** A SMALL STATIC the atlas left out (the bake's `minSize`: `small` + `light` in the .bake): no rect — the light
-     *  baked where it stands goes into its material parameters. `data` = 27 floats: the ambient cube — per side of its
-     *  bounds (+x -x +y -y +z -z) the irradiance rgb in lux and the sky visibility — then probe a, probe b, a's weight
-     *  (65535 = no probe, 65534 = the sky). The textures = any page of the level (the probes' records sit under every
-     *  aux page). Returns the material instances that took it (0 = not loaded lightmapped). @count count=data */
-    lightmapObjectApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, data: Float32Array, group?: i32): u32
+     *  baked where it stands goes into its material parameters. `data` = 7 + 24 n floats: axis (0 x, 1 y, 2 z), from, to
+     *  (its bounds along the axis), n (slabs, 1..16); then n AMBIENT CUBES, slab by slab from `from` — per side of the slab's
+     *  box (+x -x +y -y +z -z) the irradiance rgb in lux and the sky visibility; then probe a, probe b, a's weight (65535 =
+     *  no probe, 65534 = the sky). Any other count is refused. The shader blends the two slabs around a pixel along the
+     *  axis. The textures = any page of the level (the probes' records sit under every aux page). `ordinal` as
+     *  `lightmapApply` (a small record of a GLB is one primitive). Returns the material instances that took it (0 = not
+     *  loaded lightmapped). @count count=data */
+    lightmapObjectApply?(entityId: u32, lightTextureId: u32, auxTextureId: u32, data: Float32Array, ordinal?: i32): u32
     /** BAKED AMBIENT LIGHT for a mover, or anything on a standard or custom LIT shader: every renderable of the GLB
      *  instance (or the Mesh entity) takes its diffuse indirect light from `data`'s ambient cube instead of the scene's
      *  IBL, and the IBL's reflections through the sky visibility. `data` = 25 or 26 floats: six sides (+x -x +y -y +z -z) of
@@ -751,6 +766,12 @@ declare global {
      *  `lightVolumeSample(x, y, z)` = that cube at a point (26 floats, null = no grid or no valid cell near), for tools;
      *  `lightVolumeClear()` drops the grid and every mover's cube. */
     lightVolumeLoad?(fetchId: bytes): boolean
+    /** THE PACKED LIGHTMAP UV1 (`<name>-uv1.bin`, the .bake's `uv1`): the bake packs every file's lightmap charts into a
+     *  square of their own and its rects map THAT uv1. `lightmapUv1Load(fetchId)` hands the engine the fetched sidecar
+     *  (false = not one); every GLB a rect is applied to then takes its file's packed uv1 into TEXCOORD_1, once per asset
+     *  (assets bound before the call are applied again). `lightmapUv1Clear()` drops it: the models get their own uv1 back. */
+    lightmapUv1Load?(fetchId: bytes): boolean
+    lightmapUv1Clear?(): void
     lightVolumeTrack?(entityId: u32, on: boolean, fixed?: boolean): void
     lightVolumeClear?(): void
     /** @out 26 @out 26 */

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/math/vec.ts

@@ -1,6 +1,6 @@
 // Fluent 2D / 3D vectors — the SDK's user-facing vector math (no gl-matrix, no out-params, no imports).
 //
-// Design (see PLAN.md): a vector is a *mutable little struct* — `v.x = 3`, `v.set(x, y, z)` mutate in
+// Design: a vector is a *mutable little struct* — `v.x = 3`, `v.set(x, y, z)` mutate in
 // place — but every *method* is PURE: `a.add(b)` returns a NEW vector and never touches `a`. So chains
 // (`dir.normalize().scale(s)`) can't clobber their source, and the immutable-method style is the most
 // amenable to a future escape-analysis / scalar-replacement compiler pass. Backing is plain number

package/src/runtime/app.ts

@@ -113,6 +113,20 @@ export const app = {
   quit(): void {
     _creatorApp.quit?.()
   },
+  /** Collect garbage now: what the app no longer references — a finished level's nodes, its
+   *  textures and materials — is freed before this returns, not whenever the collector next runs.
+   *  Call it where a pause is invisible (a loading screen, between levels), after dropping the
+   *  references; never during play — a collection walks the whole heap. It also puts the next
+   *  automatic collection at half again the heap it leaves: the room the next stretch of play has.
+   *  `headroomMB` asks for more room when the play ahead allocates more than that — a drive that
+   *  streams in hundreds of megabytes of terrain buffers: `app.gc({ headroomMB: 512 })` keeps the
+   *  next collection at least 512 MB away (until it comes; then the engine's rule again). The log's
+   *  `[gc]` line says what it took, what it freed and where the next one is. On iOS a request the
+   *  engine serves on its own schedule, without the headroom; a no-op in the browser, where a page
+   *  cannot ask for a collection. */
+  gc(options?: { headroomMB?: number }): void {
+    _creatorApp.gc?.(options?.headroomMB)
+  },
   /** Global back-press fallback (Android back button/gesture — iOS has no system back). Fires
    *  only when nothing else consumed the press: no open widget/modal claimed it, the current
    *  screen has no `onBack`, every pager is at its tab root and the router is at its