lecodes-sdk 0.19.0

package/src/gl/InstancedMesh.ts

@@ -0,0 +1,132 @@
+// One geometry drawn many times — grass tufts, crates, debris, coins, a crowd of identical props —
+// with a transform per instance and a handful of draw calls. Hardware instancing (Filament's
+// InstanceBuffer): the engine applies each instance's local matrix, so any regular material works.
+//
+// Transforms live in a CPU-side Float32Array (16 floats per instance, column-major, local to this
+// node). `setAt` / `hideAt` / `setMatrixAt` edit it and track the dirty range; `commit()` uploads
+// that range in one bridge call — call it once per frame after your edits, not per instance.
+// The native side splits the instances into chunks of the platform's per-draw cap (64 native,
+// 8 on WebGL) on child entities, and keeps a bounding box per chunk so frustum culling stays on.
+
+import { Mat4, type Mat4Like } from "../math/mat4"
+import { Quat, type QuatLike } from "../math/quat"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import type { Geometry } from "./Geometry"
+import { Material } from "./Material"
+import type { MeshOptions } from "./Mesh"
+import { Node } from "./Node"
+
+/** One instance's placement, local to the InstancedMesh node. Omitted fields mean identity. */
+export type InstanceTransform = {
+  position?: Vec3Like
+  /** Quaternion; wins over `eulerAngles`. */
+  rotation?: QuatLike
+  /** Degrees (YXZ), like `Node.eulerAngles`. */
+  eulerAngles?: Vec3Like
+  scale?: Vec3Like | number
+}
+
+const DEG = Math.PI / 180
+
+export class InstancedMesh extends Node {
+  /** Instance capacity, fixed at construction. Unset instances are hidden. */
+  readonly count: number
+  private _geometry: Geometry
+  private _material: Material
+  private _data: Float32Array
+  private _lo = Infinity
+  private _hi = -1
+
+  constructor(geometry: Geometry, count: number, options: MeshOptions = {}) {
+    super()
+    if (!(count >= 1)) throw new Error("InstancedMesh: count must be ≥ 1")
+    this.count = Math.floor(count)
+    this._geometry = geometry
+    this._material = options.material ?? Material.unlit()
+    this._data = new Float32Array(16 * this.count)
+    _creator.createInstancedMesh(this.id, Material.idOf(this._material), geometry.vertices, geometry.normals, geometry.indices, geometry.uv, this.count)
+    if (options.position) this.position = options.position
+    if (options.eulerAngles) this.eulerAngles = options.eulerAngles
+    if (options.scale !== undefined) this.scale = typeof options.scale === "number" ? [ options.scale, options.scale, options.scale ] : options.scale
+    if (options.name !== undefined) this.name = options.name
+    if (options.castShadows !== undefined || options.receiveShadows !== undefined) {
+      _creator.setInstancedMeshShadows(this.id, options.castShadows ?? true, options.receiveShadows ?? true)
+    }
+  }
+
+  override get geometry(): Geometry { return this._geometry }
+
+  get material(): Material { return this._material }
+  set material(m: Material) {
+    this._material = m
+    _creator.setInstancedMeshMaterial(this.id, Material.idOf(m))
+  }
+
+  /** Shadow flags for all instances (both at once — the engine sets them per draw). */
+  setShadows(cast: boolean, receive = cast): this {
+    _creator.setInstancedMeshShadows(this.id, cast, receive)
+    return this
+  }
+
+  private _touch(i: number): void {
+    if (i < this._lo) this._lo = i
+    if (i > this._hi) this._hi = i
+  }
+
+  /** Place instance `i`. Pending until `commit()`. */
+  setAt(i: number, t: InstanceTransform): this {
+    if (i < 0 || i >= this.count) throw new RangeError(`InstancedMesh: index ${i} out of 0..${this.count - 1}`)
+    const rot = t.rotation ?? (t.eulerAngles
+      ? Quat.fromEuler(cx(t.eulerAngles) * DEG, cy(t.eulerAngles) * DEG, cz(t.eulerAngles) * DEG)
+      : Quat.identity)
+    const m = Mat4.compose(t.position ?? [ 0, 0, 0 ], rot, t.scale ?? 1).toArray()
+    this._data.set(m, i * 16)
+    this._touch(i)
+    return this
+  }
+
+  /** Place instance `i` from a 4×4 column-major matrix (local to this node). */
+  setMatrixAt(i: number, m: Mat4Like): this {
+    if (i < 0 || i >= this.count) throw new RangeError(`InstancedMesh: index ${i} out of 0..${this.count - 1}`)
+    const a = m instanceof Mat4 ? m.toArray() : m
+    for (let k = 0; k < 16; k++) this._data[i * 16 + k] = a[k]
+    this._touch(i)
+    return this
+  }
+
+  /** Hide instance `i` (a zero matrix — no geometry is emitted for it). */
+  hideAt(i: number): this {
+    if (i < 0 || i >= this.count) throw new RangeError(`InstancedMesh: index ${i} out of 0..${this.count - 1}`)
+    this._data.fill(0, i * 16, i * 16 + 16)
+    this._touch(i)
+    return this
+  }
+
+  /** Bulk write: `matrices` holds 16 floats per instance, starting at instance `offset`. */
+  setMatrices(matrices: ArrayLike<number>, offset = 0): this {
+    const n = Math.min(Math.floor(matrices.length / 16), this.count - offset)
+    if (n <= 0) return this
+    this._data.set(Array.prototype.slice.call(matrices, 0, n * 16), offset * 16)
+    this._touch(offset)
+    this._touch(offset + n - 1)
+    return this
+  }
+
+  /** The 4×4 of instance `i` as stored (a copy). */
+  matrixAt(i: number): Mat4 {
+    return Mat4.from(this._data.subarray(i * 16, i * 16 + 16))
+  }
+
+  /** Upload every change since the last commit (one bridge call covering the dirty range). */
+  commit(): this {
+    if (this._hi < this._lo) return this
+    const lo = this._lo, hi = this._hi
+    this._lo = Infinity
+    this._hi = -1
+    _creator.setInstanceTransforms(this.id, this._data.subarray(lo * 16, (hi + 1) * 16), lo)
+    return this
+  }
+
+  /** Whether edits are waiting for `commit()`. */
+  get dirty(): boolean { return this._hi >= this._lo }
+}

package/src/gl/Light.ts

@@ -0,0 +1,135 @@
+// Lights. A directional sun (the engine's primary light) and punctual point lights. Add one to a
+// scene like any node; `intensity` and `color` stay writable so a light can be animated.
+
+import { Color, type ColorInput } from "../core/color"
+import type { Vec3Like } from "../math/vec"
+import { Node } from "./Node"
+
+export type SunOptions = {
+  /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
+  direction?: Vec3Like
+  /** Luminous intensity. */
+  intensity?: number
+  color?: ColorInput
+  /**
+   * Shadow quality (default 1):
+   *   0 - no shadows
+   *   1 - 1024 map, hard edges (one filtered tap; the cheap level, ~3 % of a frame on an iGPU)
+   *   2 - 1024 map, soft edges (variance shadows + blur; ~+15 % of a frame on an iGPU)
+   *   3 - 2048 map, contact-hardening soft edges (PCSS: sharp where the caster touches, softer
+   *       away; discrete-GPU territory, ~+60 % of a frame on an iGPU)
+   * A lightmapped level already carries every static shadow, so 0 is a legitimate choice there.
+   */
+  shadowsQuality?: 0 | 1 | 2 | 3
+  /**
+   * Metres from the camera within which the sun casts shadows (default 100). Shadows fade out by
+   * this distance and the shadow map covers only this range, so a shorter distance is crisper for
+   * the same quality and puts fewer casters in the shadow pass. 30-40 is plenty in first person.
+   */
+  shadowDistance?: number
+}
+
+export type PointOptions = {
+  /**
+   * Luminous POWER in lumens — the same physical scale as the sun's lux and `environmentIntensity`,
+   * so a light keeps its look when the scene's exposure changes. A candle is ~12 lm, a bare 60 W
+   * bulb ~800, a car headlight ~1500, a fireball millions. Default 1000.
+   */
+  intensity?: number
+  color?: ColorInput
+  /**
+   * Metres of influence — past it the light contributes nothing. This is the performance knob:
+   * overlapping point lights are the expensive case, so keep it as small as the look allows.
+   * Default 10.
+   */
+  range?: number
+  /** Point-light shadows are a cubemap render per light; off by default. */
+  castShadows?: boolean
+  /**
+   * Whether `lecodes lightmap bake` bakes this light into the level's lightmap (docs/lightmap-plan.md).
+   * A baked light is switched OFF at runtime once the bake applies — statics read it from the atlas,
+   * movers from the light volume — so it costs nothing per frame; a light that must stay live (a
+   * flicker, a lamp the player can shoot out) says `baked: false` and is kept out of the bake.
+   * Lights created after the level loads (a muzzle flash) are never in a bake. Default true.
+   */
+  baked?: boolean
+}
+
+export class Light extends Node {
+  private _intensity = 0
+  /** @internal PointOptions.baked — a candidate for the lightmap bake (default true). */
+  _baked = true
+  /** @internal the bake carries this light: the real-time one is held dark (Lightmap.load). */
+  _bakedOff = false
+  /** @internal every live point light, for the bake / the switch-off; a destroyed one leaves. */
+  static _points = new Set<Light>()
+  /** @internal sun direction as created (the engine keeps it; Lightmap.load reads it back). */
+  _direction: [number, number, number] = [ 0, -1, 0 ]
+  /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
+  static lastSun: Light | null = null
+
+  /** A directional sun light. */
+  static sun(options: SunOptions = {}): Light {
+    const light = new Light()
+    const [ dx, dy, dz ] = options.direction ?? [ 0.548267, -0.473983, -0.689016 ]
+    light._direction = [ dx, dy, dz ]
+    light._intensity = options.intensity ?? 100000
+    Light.lastSun = light
+    _creator.createSunLight(
+      light.id, dx, dy, dz,
+      light._intensity,
+      Color.toPackedRgb(options.color ?? 0xffffff),
+      options.shadowsQuality ?? 1,
+      options.shadowDistance ?? 100,
+    )
+    return light
+  }
+
+  /**
+   * A point light — a lamp, a muzzle flash, a fireball. Position it like any node.
+   *
+   * Feature-detected: hosts that predate it create the node and light nothing, which keeps a scene
+   * that adds atmosphere on top of its sun renderable everywhere. Check `Light.supportsPoint`
+   * before making one carry the scene.
+   */
+  static point(options: PointOptions = {}): Light {
+    const light = new Light()
+    light._intensity = options.intensity ?? 1000
+    light._baked = options.baked ?? true
+    Light._points.add(light)
+    _creator.createPointLight?.(
+      light.id,
+      light._intensity,
+      Color.toPackedRgb(options.color ?? 0xffffff),
+      options.range ?? 10,
+      options.castShadows ?? false,
+    )
+    return light
+  }
+
+  /** Whether this host can create point lights at all. */
+  static get supportsPoint(): boolean { return _creator.createPointLight !== undefined }
+
+  /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
+  get intensity(): number { return this._intensity }
+  set intensity(value: number) {
+    this._intensity = value
+    _creator.setLightIntensity?.(this.id, this._bakedOff ? 0 : value)
+  }
+
+  /** @internal Hold a baked point light dark (the atlas / volume carries it) or hand it back to the real-time path. */
+  _setBakedOff(off: boolean): void {
+    if (this._bakedOff === off) return
+    this._bakedOff = off
+    _creator.setLightIntensity?.(this.id, off ? 0 : this._intensity)
+  }
+
+  destroy(): void {
+    Light._points.delete(this)
+    super.destroy()
+  }
+
+  set color(value: ColorInput) {
+    _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
+  }
+}

package/src/gl/Lightmap.ts

@@ -0,0 +1,402 @@
+// Baked lighting for static 3D geometry (docs/lightmap-plan.md). A scene FILE does all of this by
+// itself: `env: { lightmap: { data, texture } }` marks the level as baked, every model/mesh node
+// that no Physics aspect moves is a static (keys = node paths, `lightmap: true|false` overrides),
+// and the runtime applies the bake when the level finishes loading (scene/defineScene.ts).
+// Hand-built scenes register what never moves with `Lightmap.add`, bake once with
+// `lecodes lightmap bake` (the desktop host traces the live scene and writes lightmap.ktx2 +
+// lightmap.bake), and `Lightmap.load` applies the atlas at runtime:
+//
+//   const crate = await Model.load(asset('./assets/props/crate.glb'), { lightmap: true })
+//   Lightmap.add(holder)                    // a Model, a Mesh, or a node holding them
+//   Lightmap.add(ground)                    // Mesh.plane works too
+//   ...
+//   await Lightmap.load(scene, { data: asset('./assets/lightmap/lightmap.bake'),
+//                                texture: asset('./assets/lightmap/lightmap.ktx2') })
+//
+// Both files are asset() handles because the compiler stages exactly the files it sees (the data
+// file is JSON with a .bake extension — a .json would be scanned as a code module). `load` is a
+// no-op when the bake is missing or the host predates the feature, so the project stays runnable —
+// and in BAKE mode (`lecodes lightmap bake`) it is where the bake fires: the same call marks "the
+// scene is complete". Atlas channels: R = sun visibility, G = ambient occlusion; the shader keeps
+// the real-time sun for dynamic casters and multiplies the baked mask in with an ambient floor.
+//
+// PAGES: a large level takes more than one atlas (`--pages`); `texture` is then every page in order.
+//
+// POINT LIGHTS: the bake traces the scene's point lights too (filament's own candela / falloff
+// math, shadow rays) into a second RGB atlas — pass it as `light` — and lists them in the .bake;
+// once that atlas applies, the real-time lights it carries are switched off (`Light.point({ baked:
+// false })` keeps one live and out of the bake). Statics read the lamps from the atlas, movers from
+// the volume's light block — for the price of nothing per frame.
+//
+// DYNAMIC objects (docs/lightmap-plan.md §9): the bake also writes lightmap.volume — the same
+// channels on a 3D grid over the level. Pass it as `volume` and every model loaded with
+// `{ lightmap: 'dynamic' }` (the default while a scene file with `env.lightmap.volume` runs) plus
+// every dynamic Mesh a scene file registers samples it per pixel: a crate rolled under the roof
+// loses the sun like the floor does, a character near a wall picks up its ambient occlusion.
+
+import { fetch } from "../runtime/fetch"
+import { Texture } from "./Texture"
+import { Material } from "./Material"
+import { Mesh } from "./Mesh"
+import { Model } from "./Model"
+import { Node } from "./Node"
+import { Light } from "./Light"
+import { cx, cy, cz } from "../math/vec"
+import type { Scene } from "./Scene"
+
+export type LightmapLoadOptions = {
+  /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
+  sunStrength?: number
+  /** Multiplier on the ambient (IBL) share in the shadow math — how bright a fully shadowed texel
+   *  stays. 1 reproduces filament's own real-time shadow darkness (the shader reads the scene's sun
+   *  and IBL from filament's per-frame uniforms); raise it for lighter shadows, lower for deeper. Default 1. */
+  ambientScale?: number
+  /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by
+   *  its ambient probe alone can want less than the geometric truth. Default 1. */
+  aoStrength?: number
+  /** Multiplier on the baked point lights' irradiance (default 1). Purely ARTISTIC: the bake is
+   *  physical (verified against the analytic 1/d^2 sum over the level's lamps - where line of sight
+   *  is clear the two agree within ~17 %), and a room lit to its real illuminance simply reads dim
+   *  against an ambient fill. This dials the lamps up without a re-bake, since their irradiance is
+   *  IN the atlas and `--lamp-gain` would cost a full one.
+   *  It scales the atlas AND the light volume together, so statics and movers stay consistent - but
+   *  note they are NOT equally forgiving: a static surface carries the bake's own cosine and
+   *  shadowing, while a mover reads the volume through a flat half-cosine, so a large boost blows
+   *  movers out long before it blows out the level. Past ~x100 expect to light the movers
+   *  separately. */
+  lightBoost?: number
+  /** Multiplier on the light VOLUME's irradiance alone — the movers' own `lightBoost`. Default =
+   *  `lightBoost`, and since 2026-08-31 that default is the right one: the volume is an ambient cube
+   *  (irradiance per axis face, blended by the pixel's normal), so a mover's top takes a lamp above it
+   *  and its underside does not — the same shading the atlas gives the statics. Before that the volume
+   *  was one flat 0.5·E on every face and this knob was the workaround. Kept as a trim. */
+  volumeBoost?: number
+}
+
+export type LightmapInfo = {
+  size: number
+  texel: number
+  /** Atlas pages the bake took (`texture` lists them in order). */
+  pages: number
+  /** The light volume, when one was loaded: grid dims + cell size in metres. */
+  volume?: { dims: number[], cell: number }
+  /** Point lights the bake carries and this load switched off (statics read them from the atlas,
+   *  movers from the volume); 0 without a `light` atlas. */
+  lights: number
+  /** keys applied / keys in the file / registered statics without a rect */
+  applied: number
+  total: number
+  missing: string[]
+}
+
+export type LightmapFiles = {
+  data: string
+  /** The atlas — one page, or every page in order for a bake that took several. */
+  texture: string | string[]
+  /** The point lights' baked irradiance (pages like `texture`). */
+  light?: string | string[]
+  volume?: string
+}
+
+import type { Terrain } from "./Terrain"
+
+type Entry = { key: string, model?: Model, mesh?: Mesh, terrain?: Terrain }
+
+const terrainOf = (n: Node): Terrain | null => (n as unknown as { _terrain?: Terrain })._terrain ?? null
+
+type BakeConfig = {
+  outDir: string, size?: number, texel?: number, sunRays?: number, aoRays?: number,
+  aoDistance?: number, bias?: number, sunAngle?: number, volumeCell?: number,
+  pages?: number, lightRays?: number, lightRadius?: number,
+  /** One bounce of indirect light from the point lights, gathered on the AO rays. The value is the
+   *  ALBEDO the bounce assumes for every surface it hits (0 = off; ~0.35 is concrete). A bake with
+   *  no bounce lights only what a lamp sees directly - in an interior that leaves the walls between
+   *  the fixtures black, and a cast shadow invisible for want of light to be missing from. */
+  bounce?: number, bounceDistance?: number, bounceRays?: number,
+  /** Metres within which an occluder PARALLEL to the surface being lit is ignored (default 0.05).
+   *  A modular kit stacks two wall pieces in the same place; to the bake they are coincident and
+   *  the AO goes black in hard-edged patches. Real contact shadows are unaffected - they come off
+   *  surfaces at an angle. 0 turns it off. */
+  coplanarSkip?: number,
+  /** Radius (px) of the geometry-aware denoise over the traced texels (default 2, 0 = off): the
+   *  Monte-Carlo grain goes, edges of geometry stay. */
+  denoise?: number,
+}
+
+type VolumeHeader = { texture: number, dims: number[], min: number[], cell: number, light?: number, faces?: number }
+
+type BakeData = {
+  version?: number, size: number, texel: number, pages?: number, textures?: string[],
+  lightTextures?: string[], lightScale?: number, lightGamma?: number,
+  lights?: { p: number[], color: number[], cd: number, range: number }[],
+  sun?: number[] | null,
+  instances: { key: string, receiver: boolean, st?: number[], page?: number }[],
+}
+
+const bakeConfig = (): BakeConfig | null => {
+  const g = (globalThis as unknown as { __lecodesLightmap?: BakeConfig }).__lecodesLightmap
+  return g && typeof g.outDir === "string" ? g : null
+}
+
+/** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
+const hex8 = (c: unknown): string => {
+  if (typeof c !== "string") return "#ffffffff"
+  if (c.length === 7) return c + "ff"
+  if (c.length === 4) return "#" + c[1] + c[1] + c[2] + c[2] + c[3] + c[3] + "ff"
+  return c
+}
+
+const list = (v: string | string[] | undefined): string[] => v === undefined ? [] : Array.isArray(v) ? v : [ v ]
+
+const NONE = 0xFFFFFFFF
+
+export class Lightmap {
+  /** True while `lecodes lightmap bake` runs the app — skip menus and build the scene straight away. */
+  static get baking(): boolean { return bakeConfig() !== null }
+
+  private static entries: Entry[] = []
+  private static dynamics: Mesh[] = []
+  private static ordinals = new Map<string, number>()
+  private static warned = false
+  private static switchedOff: Light[] = []
+
+
+  /** Register static geometry — a Model, a Mesh, or any node whose subtree holds them. Statics are
+   *  both receivers and occluders in the bake. `key` names the entry in lightmap.bake (default:
+   *  the node's name + a running number, `container#3`); pass one when names are not stable. */
+  static add(node: Node, key?: string): Node {
+    const base = key ?? `${node.name || "node"}#${Lightmap.next(node.name || "node")}`
+    const found: Entry[] = []
+    const walk = (n: Node): void => {
+      const t = terrainOf(n)
+      if (t) { found.push({ key: base, terrain: t }); return }   // one receiver, its chunks are internal
+      if (n instanceof Model) { found.push({ key: base, model: n }); return }
+      if (n instanceof Mesh) { found.push({ key: base, mesh: n }); return }
+      for (const c of n.children) walk(c)
+    }
+    walk(node)
+    if (found.length === 0) { console.warn(`Lightmap.add: ${base} holds no Model or Mesh`); return node }
+    if (found.length > 1) found.forEach((e, i) => { e.key = `${base}/${i}` })
+    Lightmap.entries.push(...found)
+    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: a terrain node (its own material carries the atlas, no swap). */
+  static _registerTerrain(terrain: Terrain, key: string): void {
+    Lightmap.entries.push({ key, terrain })
+  }
+
+  /** @internal Scene-file runtime: a dynamic Mesh — swapped to the lightmap material on the volume
+   *  when `load` runs (dynamic Models need nothing here: the engine binds the volume itself). */
+  static _registerDynamic(mesh: Mesh): void {
+    Lightmap.dynamics.push(mesh)
+  }
+
+  private static next(name: string): number {
+    const n = Lightmap.ordinals.get(name) ?? 0
+    Lightmap.ordinals.set(name, n + 1)
+    return n
+  }
+
+  /** Forget every registration (a scene rebuild); baked-off lights come back to the real-time path. */
+  static clear(): void {
+    Lightmap.entries = []
+    Lightmap.dynamics = []
+    Lightmap.ordinals.clear()
+    Model._lightmapDefault = false
+    for (const l of Lightmap.switchedOff) l._setBakedOff(false)
+    Lightmap.switchedOff = []
+    _creator.lightmapSetOptions?.(1, 1, 1, 0)
+    _creator.lightmapVolumeSet?.(NONE, NONE, 0, 0, 0, 0, 0, 0, 0)
+  }
+
+  /** 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). */
+  static async load(scene: Scene, files: LightmapFiles, options: LightmapLoadOptions = {}): Promise<LightmapInfo | null> {
+    const bake = bakeConfig()
+    if (bake) { Lightmap.bake(bake); 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
+    }
+    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 }
+      data = resp.json()
+      resp.dispose()
+    } catch (e) {
+      console.warn(`Lightmap: could not read ${files.data}: ${String(e)}`)
+      return null
+    }
+    // the atlas pages: a bake that took more pages than the scene lists applies what it can and says so
+    const pages = Math.max(1, data.pages ?? 1)
+    const pageFiles = list(files.texture)
+    if (pageFiles.length === 0) { console.warn("Lightmap: no atlas texture given"); return null }
+    if (pageFiles.length < pages) {
+      console.warn(`Lightmap: the bake took ${pages} atlas pages but the scene lists ${pageFiles.length} — add the other page files (${(data.textures ?? []).slice(pageFiles.length).join(", ")}) to env.lightmap.texture`)
+    }
+    const textures = await Promise.all(pageFiles.slice(0, pages).map((f) => Texture.load(f)))
+    // the light atlas: the bake carries the point lights only when the scene passes their atlas
+    const lightFiles = list(files.light)
+    let lightTextures: Texture[] = []
+    let lightScale = 0
+    let volumeScale = 0
+    if (data.lightTextures?.length && (data.lightScale ?? 0) > 0) {
+      if (lightFiles.length === 0) {
+        console.warn(`Lightmap: the bake carries ${data.lights?.length ?? 0} baked point light(s) but the scene passes no \`light\` atlas (${data.lightTextures[0]}) — the lamps stay real-time`)
+      } else {
+        if (lightFiles.length < pages) console.warn(`Lightmap: the light atlas has ${pages} pages but the scene lists ${lightFiles.length}`)
+        lightTextures = await Promise.all(lightFiles.slice(0, pages).map((f) => Texture.load(f)))
+        lightScale = (data.lightScale ?? 0) * (options.lightBoost ?? 1)
+        volumeScale = (data.lightScale ?? 0) * (options.volumeBoost ?? options.lightBoost ?? 1)
+      }
+    }
+    const ambientScale = options.ambientScale ?? 1
+    const strength = options.sunStrength ?? 1
+    const aoStrength = options.aoStrength ?? 1
+    // the light store's curve: sRGB(pow(E / lightScale, 1 / lightGamma)); bakes before 2026-08-31 are linear (1)
+    const lightGamma = data.lightGamma ?? 1
+    // level-wide knobs first: the volume and every rect below inherit them
+    _creator.lightmapSetOptions?.(ambientScale, strength, aoStrength, lightScale, volumeScale, lightGamma)
+    // what the bake actually BOUND, so a level can be debugged without guessing (FEEDBACK 95): the
+    // scale is the one number standing between the atlas' physical irradiance and the pixel
+    console.log(`[lightmap] bound ${textures.length} page(s)${lightTextures.length ? ` + ${lightTextures.length} light page(s)` : ""}`
+      + ` lightScale ${lightScale.toFixed(2)}${(options.lightBoost ?? 1) !== 1 ? ` (bake ${(data.lightScale ?? 0).toFixed(2)} x boost ${options.lightBoost})` : ""}`
+      + `${volumeScale !== lightScale ? ` volumeScale ${volumeScale.toFixed(2)}` : ""}`
+      + ` gamma ${lightGamma} ao ${aoStrength} ambient ${ambientScale} sun ${strength}`)
+    // the light volume next: it claims every lightmap-material instance, the atlas rects below win back the statics
+    const volume = files.volume ? await Lightmap.loadVolume(files.volume, volumeScale, lightGamma, ambientScale, strength, aoStrength) : null
+    const rects = new Map<string, { st: number[], page: number }>()
+    for (const inst of data.instances) if (inst.receiver && inst.st) rects.set(inst.key, { st: inst.st, page: inst.page ?? 0 })
+    let applied = 0
+    const missing: string[] = []
+    for (const e of Lightmap.entries) {
+      const r = rects.get(e.key)
+      if (!r || r.page >= textures.length) { missing.push(e.key); continue }
+      const st = r.st
+      const texture = textures[r.page]
+      const light = r.page < lightTextures.length ? lightTextures[r.page] : null
+      if (e.model) {
+        const n = _creator.lightmapApply(e.model.id, texture._id, st[0], st[1], st[2], st[3], light ? light._id : NONE)
+        if (n === 0) { console.warn(`Lightmap: ${e.key} was not loaded with { lightmap: true } — skipped`); continue }
+        e.model.castShadows = false
+      } else if (e.mesh) {
+        Lightmap.swapMeshMaterial(e.mesh, texture, light, light ? lightScale : 0, lightGamma, st, ambientScale, strength, aoStrength)
+        e.mesh.castShadows = false
+      } else if (e.terrain) {
+        // terrain.mat carries lightmap.mat's atlas block: bind the rect on the terrain's own material
+        const m = e.terrain.material.set("lightmap", texture).set("lightmapST", [ st[0], st[1], st[2], st[3] ])
+          .set("ambientScale", ambientScale).set("sunStrength", strength).set("bakedAo", aoStrength).set("lightGamma", lightGamma)
+        if (light) m.set("lightmapLight", light).set("lightScale", lightScale)
+        else m.set("lightScale", 0)
+        e.terrain.castShadows = false
+      }
+      applied++
+    }
+    if (missing.length) console.warn(`Lightmap: ${missing.length} static(s) have no rect in the bake (${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "…" : ""}) — rebake`)
+    // the lights the bake carries go dark: the atlas holds them for the statics, the volume for the movers
+    let lights = 0
+    if (lightTextures.length > 0 && data.lights?.length) lights = Lightmap.switchOffBaked(data.lights)
+    const info: LightmapInfo = { size: data.size, texel: data.texel, pages, applied, total: rects.size, missing, lights }
+    if (volume) info.volume = { dims: volume.dims, cell: volume.cell }
+    return info
+  }
+
+  /** Every live point light within 5 cm of a baked one is held dark (a moved lamp keeps lighting live
+   *  — and double, until the next bake, which is the honest state of a stale bake). */
+  private static switchOffBaked(baked: { p: number[] }[]): number {
+    let n = 0
+    for (const light of Light._points) {
+      if (!light._baked) continue
+      const wp = light.worldPosition
+      const x = cx(wp), y = cy(wp), z = cz(wp)
+      const hit = baked.some((b) => Math.abs(b.p[0] - x) < 0.05 && Math.abs(b.p[1] - y) < 0.05 && Math.abs(b.p[2] - z) < 0.05)
+      if (!hit) continue
+      light._setBakedOff(true)
+      Lightmap.switchedOff.push(light)
+      n++
+    }
+    return n
+  }
+
+  /** lightmap.volume → the engine's 3D textures → THE volume for every dynamic lightmap-material instance,
+   *  plus the registered dynamic Meshes. Null when the file is a placeholder or the host lacks the feature. */
+  private static async loadVolume(url: string, lightScale: number, lightGamma: number, ambientScale: number, strength: number, aoStrength: number): Promise<VolumeHeader | null> {
+    if (!_creator.lightmapVolumeLoad || !_creator.lightmapVolumeSet) return null
+    let header: VolumeHeader
+    try {
+      const resp = await fetch(url, { useOnce: true })
+      if (resp.status >= 400) { console.warn(`Lightmap: no volume at ${url} (HTTP ${resp.status}) — run \`lecodes lightmap bake\``); return null }
+      const json = _creator.lightmapVolumeLoad((resp as unknown as { _id: number })._id)
+      resp.dispose()
+      if (!json) { console.warn(`Lightmap: ${url} is not a light volume — rebake`); return null }
+      header = JSON.parse(json) as VolumeHeader
+    } catch (e) {
+      console.warn(`Lightmap: could not read ${url}: ${String(e)}`)
+      return null
+    }
+    const [ nx, ny, nz ] = header.dims
+    if (nx * ny * nz <= 1) return null   // the CLI's placeholder: nothing baked yet
+    const size = [ nx * header.cell, ny * header.cell, nz * header.cell ]
+    const texture = new Texture(nx, ny, header.texture)
+    const hasLight = header.light !== undefined && lightScale > 0
+    const light = hasLight ? new Texture(nx, ny, header.light!) : null
+    if (hasLight && (header.faces ?? 1) < 6) console.warn("Lightmap: the light volume predates the ambient cube (one directionless value per cell) — rebake")
+    _creator.lightmapVolumeSet(header.texture, hasLight ? header.light! : NONE, header.min[0], header.min[1], header.min[2], size[0], size[1], size[2], header.cell)
+    for (const mesh of Lightmap.dynamics) {
+      const m = Lightmap.meshMaterial(mesh, ambientScale, strength, aoStrength, lightGamma)
+      m.set("probeVolume", texture)
+      if (light) m.set("probeLight", light).set("lightScale", lightScale)
+      m.set("probeMin", [ header.min[0], header.min[1], header.min[2], header.cell * 0.5 ])
+      // .w = the grid's depth: the shader keeps its fetch inside one face slab of the light texture
+      m.set("probeInvSize", [ 1 / size[0], 1 / size[1], 1 / size[2], nz ])
+      mesh.setMaterial(m)
+    }
+    return header
+  }
+
+  /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
+  private static meshMaterial(mesh: Mesh, ambientScale: number, strength: number, aoStrength: number, lightGamma = 1): Material {
+    const src = mesh.material
+    const u = src?.uniforms ?? {}
+    const m = Material.lightmap()
+    m.set("baseColorFactor", hex8(u.baseColor))
+    if (u.baseColorMap instanceof Texture) m.set("baseColorMap", u.baseColorMap)
+    if (typeof u.roughness === "number") m.set("roughnessFactor", u.roughness)
+    if (typeof u.metallic === "number") m.set("metallicFactor", u.metallic)
+    m.set("ambientScale", ambientScale)
+    m.set("sunStrength", strength)
+    m.set("bakedAo", aoStrength)
+    m.set("lightGamma", lightGamma)
+    return m
+  }
+
+  private static swapMeshMaterial(mesh: Mesh, texture: Texture, light: Texture | null, lightScale: number, lightGamma: number, st: number[],
+                                  ambientScale: number, strength: number, aoStrength: number): void {
+    const m = Lightmap.meshMaterial(mesh, ambientScale, strength, aoStrength, lightGamma)
+    m.set("lightmap", texture)
+    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
+    if (light) m.set("lightmapLight", light).set("lightScale", lightScale)
+    mesh.setMaterial(m)
+  }
+
+  private static bake(cfg: BakeConfig): void {
+    if (!_creator.lightmapBake) { console.error("[lightmap] error: this host has no bake module (build the desktop host with CREATOR_GL_LIGHTMAP, or update lecodes desktop)"); return }
+    const ids = Uint32Array.from(Lightmap.entries.map((e) => (e.model ?? e.mesh ?? e.terrain!.node).id))
+    const keys = Lightmap.entries.map((e) => e.key).join("\n")
+    if (ids.length === 0) { console.error("[lightmap] error: nothing registered — call Lightmap.add on the static props before Lightmap.load"); return }
+    // a `baked: false` light is held dark for the bake — the engine bakes every lit point light it finds
+    const live = [ ...Light._points ].filter((l) => !l._baked)
+    for (const l of live) _creator.setLightIntensity?.(l.id, 0)
+    _creator.lightmapBake(cfg.outDir, ids, keys, cfg.size ?? 4096, cfg.texel ?? 0.02, cfg.sunRays ?? 32, cfg.aoRays ?? 64,
+      cfg.aoDistance ?? 2, cfg.bias ?? 0.02, cfg.sunAngle ?? 0.5, cfg.volumeCell ?? 0.5, cfg.pages ?? 1, cfg.lightRays ?? 8, cfg.lightRadius ?? 0.1,
+      cfg.bounce ?? 0, cfg.bounceDistance ?? 8, cfg.bounceRays ?? 1, cfg.coplanarSkip ?? 0.05, cfg.denoise ?? 2)
+    for (const l of live) _creator.setLightIntensity?.(l.id, l.intensity)
+  }
+}