lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/gl/IK.ts

@@ -1,174 +1,193 @@
-// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
-// They run after the animation wrote the pose (base anim or Animator) and before the skin is
-// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
-// walked up through parents — one instance per end effector, any Node hierarchy works.
-//
-//   const foot = hero.bone('LeftFoot')!
-//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
-//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
-//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
-//
-// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
-// slot in later behind the same API.
-
-import { Aspect } from "../core/Aspect"
-import { Vec3, type Vec3Like } from "../math/vec"
-import { Quat } from "../math/quat"
-import type { Node } from "./Node"
-
-type Target = Node | Vec3Like
-
-const targetPos = (t: Target | undefined): Vec3 | null => {
-  if (t === undefined || t === null) return null
-  const n = t as Node
-  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
-  return new Vec3(t as Vec3Like)
-}
-
-/** World rotation of a node (parent chain composed natively). */
-const worldRot = (n: Node): Quat => n.worldMatrix.rotation
-
-/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
-const setWorldRot = (n: Node, q: Quat): void => {
-  const p = n.parent
-  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
-}
-
-const clampAngle = (q: Quat, maxRad: number): Quat => {
-  // angle of a unit quaternion = 2·acos(|w|)
-  const w = Math.min(1, Math.abs(q.w))
-  const ang = 2 * Math.acos(w)
-  if (ang <= maxRad || ang < 1e-6) return q
-  const s = Math.sqrt(1 - w * w)
-  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
-  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
-}
-
-/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
- *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
- *  (knee/elbow) — a Node or world point. */
-class TwoBone extends Aspect<"ik", Node> {
-  static readonly aspect = "ik"
-
-  /** Where the end bone should be (Node or world position). */
-  target?: Target
-  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
-  pole?: Target
-  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
-  weight = 1
-  /** Solve every frame (default). Set false to drive `solve()` yourself. */
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const end = this.node
-    const mid = end.parent
-    const root = mid?.parent
-    if (!mid || !root) return
-
-    const w = Math.min(1, this.weight)
-    const midLocal0 = mid.quaternion
-    const rootLocal0 = root.quaternion
-
-    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
-    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
-    if (l1 < 1e-6 || l2 < 1e-6) return
-    const eps = 1e-4
-    const toT = t.sub(a)
-    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
-
-    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
-    const ba = a.sub(b), bc = c.sub(b)
-    const cur = ba.angle(bc)
-    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
-    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
-    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
-    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
-    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
-    let axis = ba.cross(bc)
-    if (axis.lengthSq() < 1e-10) {
-      // straight limb: bend toward the pole (or any perpendicular)
-      const p = targetPos(this.pole)
-      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
-      axis = ba.cross(ref)
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
-    }
-    axis = axis.normalize()
-    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
-    const midWorld = worldRot(mid)
-    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
-
-    // 2. swing the root so the end lands on the target direction
-    const c2 = end.worldPosition
-    const rootWorld = worldRot(root)
-    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
-
-    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
-    const p = targetPos(this.pole)
-    if (p) {
-      const dir = toT.normalize()
-      const b2 = mid.worldPosition
-      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
-      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
-      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
-        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
-      }
-    }
-
-    // 4. weight: blend from the animated pose to the solved one
-    if (w < 1) {
-      root.quaternion = rootLocal0.slerp(root.quaternion, w)
-      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
-    }
-  }
-}
-
-/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
- *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
- *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
- *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
-class LookAt extends Aspect<"lookAt", Node> {
-  static readonly aspect = "lookAt"
-
-  target?: Target
-  /** The bone's local axis that should point at the target. */
-  axis: Vec3Like = [ 0, 0, -1 ]
-  /** Max deflection from the animated direction, in degrees (default 80). */
-  limit = 80
-  /** 0–1 contribution. */
-  weight = 1
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const bone = this.node
-    const w = Math.min(1, this.weight)
-    const local0 = bone.quaternion
-    const from = bone.worldPosition
-    const dir = t.sub(from)
-    if (dir.lengthSq() < 1e-10) return
-    const rot = worldRot(bone)
-    const current = new Vec3(this.axis).rotate(rot)
-    let delta = Quat.fromTo(current, dir)
-    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
-    setWorldRot(bone, delta.mul(rot))
-    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
-  }
-}
-
-/** Inverse kinematics aspects — attach to bones (see file header). */
-export const IK = { TwoBone, LookAt }
-export type IKTwoBone = TwoBone
-export type IKLookAt = LookAt
+// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
+// They run after the animation wrote the pose (base anim or Animator) and before the skin is
+// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
+// walked up through parents — one instance per end effector, any Node hierarchy works.
+//
+//   const foot = hero.bone('LeftFoot')!
+//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
+//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
+//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
+//
+// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
+// slot in later behind the same API.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, type Vec3Like } from "../math/vec"
+import { Quat } from "../math/quat"
+import type { Node } from "./Node"
+
+type Target = Node | Vec3Like
+
+const targetPos = (t: Target | undefined): Vec3 | null => {
+  if (t === undefined || t === null) return null
+  const n = t as Node
+  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
+  return new Vec3(t as Vec3Like)
+}
+
+/** World rotation of a node (parent chain composed natively). */
+const worldRot = (n: Node): Quat => n.worldMatrix.rotation
+
+/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
+const setWorldRot = (n: Node, q: Quat): void => {
+  const p = n.parent
+  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
+}
+
+const clampAngle = (q: Quat, maxRad: number): Quat => {
+  // angle of a unit quaternion = 2·acos(|w|)
+  const w = Math.min(1, Math.abs(q.w))
+  const ang = 2 * Math.acos(w)
+  if (ang <= maxRad || ang < 1e-6) return q
+  const s = Math.sqrt(1 - w * w)
+  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
+  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
+}
+
+/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
+ *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
+ *  (knee/elbow) — a Node or world point. */
+class TwoBone extends Aspect<"ik", Node> {
+  static readonly aspect = "ik"
+
+  /** Where the end bone should be (Node or world position). */
+  target?: Target
+  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
+  pole?: Target
+  /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat.
+   *  Unset = the end bone keeps its animated local rotation (a hand on a grip, a foot on a slope
+   *  want it set). Blended by `weight · rotationWeight`. */
+  rotation?: Node | Quat
+  /** 0–1 contribution of `rotation` (on top of `weight`). */
+  rotationWeight = 1
+  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+  weight = 1
+  /** Solve every frame (default). Set false to drive `solve()` yourself. */
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const end = this.node
+    const mid = end.parent
+    const root = mid?.parent
+    if (!mid || !root) return
+
+    const w = Math.min(1, this.weight)
+    const midLocal0 = mid.quaternion
+    const rootLocal0 = root.quaternion
+
+    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
+    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
+    if (l1 < 1e-6 || l2 < 1e-6) return
+    const eps = 1e-4
+    const toT = t.sub(a)
+    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
+
+    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
+    const ba = a.sub(b), bc = c.sub(b)
+    const cur = ba.angle(bc)
+    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
+    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
+    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
+    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
+    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
+    let axis = ba.cross(bc)
+    if (axis.lengthSq() < 1e-10) {
+      // straight limb: bend toward the pole (or any perpendicular)
+      const p = targetPos(this.pole)
+      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
+      axis = ba.cross(ref)
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
+    }
+    axis = axis.normalize()
+    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
+    const midWorld = worldRot(mid)
+    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
+
+    // 2. swing the root so the end lands on the target direction
+    const c2 = end.worldPosition
+    const rootWorld = worldRot(root)
+    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
+
+    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
+    const p = targetPos(this.pole)
+    if (p) {
+      const dir = toT.normalize()
+      const b2 = mid.worldPosition
+      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
+      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
+      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
+        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
+      }
+    }
+
+    // 4. weight: blend from the animated pose to the solved one
+    if (w < 1) {
+      root.quaternion = rootLocal0.slerp(root.quaternion, w)
+      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
+    }
+
+    // 5. end-bone rotation: take the target's world rotation (a hand stays on its grip, a foot
+    // flat on the slope) — the solve above only placed the end's ORIGIN
+    const r = this.rotation
+    if (r !== undefined && r !== null) {
+      const rw = w * Math.min(1, Math.max(0, this.rotationWeight))
+      if (rw > 0) {
+        const want = (r as Node).id !== undefined && typeof (r as Node).worldMatrix === "object" ? worldRot(r as Node) : (r as Quat)
+        const endLocal0 = end.quaternion
+        setWorldRot(end, want)
+        if (rw < 1) end.quaternion = endLocal0.slerp(end.quaternion, rw)
+      }
+    }
+  }
+}
+
+/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
+ *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
+ *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
+ *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
+class LookAt extends Aspect<"lookAt", Node> {
+  static readonly aspect = "lookAt"
+
+  target?: Target
+  /** The bone's local axis that should point at the target. */
+  axis: Vec3Like = [ 0, 0, -1 ]
+  /** Max deflection from the animated direction, in degrees (default 80). */
+  limit = 80
+  /** 0–1 contribution. */
+  weight = 1
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const bone = this.node
+    const w = Math.min(1, this.weight)
+    const local0 = bone.quaternion
+    const from = bone.worldPosition
+    const dir = t.sub(from)
+    if (dir.lengthSq() < 1e-10) return
+    const rot = worldRot(bone)
+    const current = new Vec3(this.axis).rotate(rot)
+    let delta = Quat.fromTo(current, dir)
+    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
+    setWorldRot(bone, delta.mul(rot))
+    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
+  }
+}
+
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export const IK = { TwoBone, LookAt }
+export type IKTwoBone = TwoBone
+export type IKLookAt = LookAt

package/runtime/sdk/gl/Light.ts

@@ -1,4 +1,5 @@
-// Lights. Currently a directional sun (the engine's primary light). Add it to a scene like any node.
+// 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"
@@ -21,17 +22,78 @@ export type SunOptions = {
   shadowsQuality?: 0 | 1 | 2 | 3
 }
 
+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
+}
+
 export class Light extends Node {
+  private _intensity = 0
+  /** @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,
-      options.intensity ?? 100000,
+      light._intensity,
       Color.toPackedRgb(options.color ?? 0xffffff),
       options.shadowsQuality ?? 1,
     )
     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
+    _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, value)
+  }
+
+  set color(value: ColorInput) {
+    _creator.setLightColor?.(this.id, Color.toPackedRgb(value))
+  }
 }

package/runtime/sdk/gl/Lightmap.ts

@@ -0,0 +1,179 @@
+// Baked shadows 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.
+
+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 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
+}
+
+export type LightmapInfo = {
+  size: number
+  texel: number
+  /** keys applied / keys in the file / registered statics without a rect */
+  applied: number
+  total: number
+  missing: string[]
+}
+
+type Entry = { key: string, model?: Model, mesh?: Mesh }
+
+type BakeConfig = {
+  outDir: string, size?: number, texel?: number, sunRays?: number, aoRays?: number,
+  aoDistance?: number, bias?: number, sunAngle?: 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
+}
+
+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 ordinals = new Map<string, number>()
+  private static warned = false
+
+  /** 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 => {
+      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 })
+  }
+
+  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). */
+  static clear(): void {
+    Lightmap.entries = []
+    Lightmap.ordinals.clear()
+  }
+
+  /** 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: { data: string, texture: string }, 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: { size: number, texel: number, sun?: number[] | null, instances: { key: string, receiver: boolean, st?: number[] }[] }
+    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
+    }
+    const texture = await Texture.load(files.texture)
+    const ambientScale = options.ambientScale ?? 1
+    const strength = options.sunStrength ?? 1
+    const rects = new Map<string, number[]>()
+    for (const inst of data.instances) if (inst.receiver && inst.st) rects.set(inst.key, inst.st)
+    let applied = 0
+    const missing: string[] = []
+    for (const e of Lightmap.entries) {
+      const st = rects.get(e.key)
+      if (!st) { missing.push(e.key); continue }
+      if (e.model) {
+        const n = _creator.lightmapApply(e.model.id, texture._id, st[0], st[1], st[2], st[3], ambientScale, strength)
+        if (n === 0) { console.warn(`Lightmap: ${e.key} was not loaded with { lightmap: true } — skipped`); continue }
+        _creator.setGlbShadows?.(e.model.id, false, true)
+      } else if (e.mesh) {
+        Lightmap.swapMeshMaterial(e.mesh, texture, st, ambientScale, strength)
+        e.mesh.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`)
+    return { size: data.size, texel: data.texel, applied, total: rects.size, missing }
+  }
+
+  /** A Mesh keeps its look (colour / map / roughness / metallic) but moves to the lightmap material. */
+  private static swapMeshMaterial(mesh: Mesh, texture: Texture, st: number[], ambientScale: number, strength: number): void {
+    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("lightmap", texture)
+    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
+    m.set("ambientScale", ambientScale)
+    m.set("sunStrength", strength)
+    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)!.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 }
+    _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)
+  }
+}