lecodes-cli 0.18.1 → 0.19.0

package/runtime/sdk/core/StateMachine.ts

@@ -0,0 +1,308 @@
+// A hierarchical state machine over a plain context object — the one place a game keeps "what am I
+// doing right now": an enemy brain, a weapon (ready → fire → cooldown → reload), a game mode
+// (warmup → round → over), a door. Declarative: the whole machine is ONE table you can read top
+// to bottom, log, and later show in an inspector; the machine knows nothing about aspects, nodes
+// or the network, so it runs wherever its owner ticks it (an `updateFixed` for anything that must
+// match another machine's, `update` for presentation).
+//
+//   const Guard = defineStates<Bot>({
+//     initial: 'patrol',
+//     on: { hit: 'flinch' },                                    // from ANY state
+//     to: { dead: (b) => b.hp <= 0 },                           // checked in every state, first
+//     states: {
+//       patrol: { update: (b, dt) => b.walk(dt), to: { combat: (b) => b.target !== null } },
+//       combat: {
+//         initial: 'engage',
+//         to: { search: (b) => b.lostFor > 4 },                 // leaves whichever child is active
+//         states: {
+//           engage: { update: (b) => b.approach(), to: { shoot: (b) => b.visible && b.dist < 12 } },
+//           shoot:  { enter: (b) => b.fire = true, exit: (b) => b.fire = false, to: { engage: (b) => !b.visible } },
+//         },
+//       },
+//       search: { after: [6, 'patrol'] },                       // a timed transition
+//       flinch: { after: [0.2, '$back'] },                      // '$back' = the state we came from
+//       dead:   { enter: (b) => b.die() },
+//     },
+//   })
+//   const fsm = new StateMachine(Guard, bot)
+//   fsm.step(dt)                    // once per tick: guards (outer states first), then updates
+//   fsm.send('hit')                 // an event: the innermost state that handles it wins
+//   fsm.state                       // 'combat.shoot'   fsm.is('combat') → true
+//   fsm.on('change', (to, from) => console.log(`[fsm] ${from} → ${to}`))
+//
+// Semantics, in order, per `step(dt)`:
+//   1. every active state's clock advances (`t` = seconds in that state);
+//   2. transitions are tested OUTERMOST first — the root's `to` (any-state guards), then each
+//      active state's `to` guards (first true wins) and its `after` timer; a taken transition is
+//      re-tested from the new state (a pass-through state chains), at most 8 hops per step;
+//   3. `update` runs outermost → innermost; an update that RETURNS a state name transitions
+//      there and ends the pass (the states it entered update next step).
+// A transition exits states innermost-first up to the common ancestor and enters the new branch
+// outermost-first, descending into `initial` children; the target state's own name (or an
+// ancestor's) re-enters it. Names resolve relative to the declaring state (siblings, then each
+// ancestor's siblings), or as a dotted path from the root; unknown names throw when the machine is
+// built, so a typo is a startup error, not a silent no-op. `send` looks innermost → outermost
+// (the root's `on` = any state) and returns whether someone handled it.
+
+export type StateGuard<C> = (ctx: C, t: number) => boolean
+export type StateHandler<C> = (ctx: C, ...args: any[]) => string | void
+
+export interface StateDef<C> {
+  /** The child entered by default when this (compound) state is entered. */
+  initial?: string
+  /** Child states — this becomes a compound state; only a leaf is ever "the" state. */
+  states?: Record<string, StateDef<C>>
+  /** Entered (from = the previous leaf's path, '' at start). */
+  enter?: (ctx: C, from: string) => void
+  /** Left (to = the next leaf's path). */
+  exit?: (ctx: C, to: string) => void
+  /** Every step while active, outer states first; `t` = seconds in this state. Return a state name
+   *  to transition. */
+  update?: (ctx: C, dt: number, t: number) => string | void
+  /** Guarded transitions, tested every step before `update` — key = target, first true wins. */
+  to?: Record<string, StateGuard<C>>
+  /** Leave for `target` after `seconds` in this state. */
+  after?: [seconds: number, target: string]
+  /** Event handlers for `send(name, …args)`: a target name, or a function returning one (or nothing). */
+  on?: Record<string, string | StateHandler<C>>
+}
+
+export interface StatesDef<C> {
+  initial: string
+  states: Record<string, StateDef<C>>
+  /** Any-state guards — tested first, in every state. */
+  to?: Record<string, StateGuard<C>>
+  /** Any-state event handlers — the fallback when no active state handles the event. */
+  on?: Record<string, string | StateHandler<C>>
+  /** Any-state update, runs before the active states' own. */
+  update?: (ctx: C, dt: number, t: number) => string | void
+}
+
+export type StateMachineEvents = {
+  /** After a transition completed (both are leaf paths; `from` = '' for the initial entry). */
+  change: (to: string, from: string) => void
+}
+
+/** Identity helper — names the context type once so every callback is typed. */
+export const defineStates = <C>(def: StatesDef<C>): StatesDef<C> => def
+
+const BACK = "$back"
+const MAX_HOPS = 8
+
+interface SNode<C> {
+  name: string
+  path: string
+  def: StateDef<C>
+  parent: SNode<C> | null
+  children: Map<string, SNode<C>>
+  initial: SNode<C> | null
+  depth: number
+  /** seconds in this state (valid while active) */
+  t: number
+  /** resolved `to` targets in declaration order */
+  guards: Array<[SNode<C>, StateGuard<C>]>
+  after: [number, SNode<C> | typeof BACK] | null
+  /** resolution cache for names returned at runtime */
+  resolved: Map<string, SNode<C> | typeof BACK>
+}
+
+export class StateMachine<C> {
+  readonly ctx: C
+  private readonly root: SNode<C>
+  private readonly byPath = new Map<string, SNode<C>>()
+  /** the active branch, root's child (index 0) → leaf */
+  private chain: SNode<C>[] = []
+  private prev: SNode<C> | null = null
+  private listeners: Array<(to: string, from: string) => void> = []
+  private changed = 0
+
+  constructor(def: StatesDef<C>, ctx: C) {
+    this.ctx = ctx
+    this.root = this.build("", "", def as StateDef<C>, null, 0)
+    // second pass: resolve names (every state exists now)
+    for (const n of this.byPath.values()) this.link(n)
+    this.link(this.root)
+    if (!this.root.initial) throw new Error("StateMachine: `initial` is required")
+    this.enterBranch([], this.leafOf(this.root.initial), "")
+  }
+
+  /** The active leaf's path ('combat.shoot'). */
+  get state(): string { return this.chain[this.chain.length - 1]?.path ?? "" }
+  /** The leaf we came from ('' before the first transition). */
+  get previous(): string { return this.prev?.path ?? "" }
+  /** Seconds in the active leaf. */
+  get time(): number { return this.chain[this.chain.length - 1]?.t ?? 0 }
+  /** Every active state's path, outermost first. */
+  get branch(): string[] { return this.chain.map((n) => n.path) }
+
+  /** Is `name` (a state name or dotted path) active — as the leaf OR as one of its ancestors? */
+  is(name: string): boolean {
+    for (const n of this.chain) if (n.name === name || n.path === name) return true
+    return false
+  }
+  /** Seconds in the named active state (0 when it is not active). */
+  timeIn(name: string): number {
+    for (const n of this.chain) if (n.name === name || n.path === name) return n.t
+    return 0
+  }
+
+  /** Force a transition (a spawn, a reset from outside the table). */
+  go(name: string): void {
+    const leaf = this.chain[this.chain.length - 1] ?? this.root
+    this.transition(this.resolve(leaf, name))
+  }
+
+  /** Deliver an event. Innermost active state first, the root's `on` last. True if handled. */
+  send(event: string, ...args: unknown[]): boolean {
+    for (let i = this.chain.length - 1; i >= 0; i--) {
+      const n = this.chain[i]!
+      const h = n.def.on?.[event]
+      if (h === undefined) continue
+      const target = typeof h === "string" ? h : h(this.ctx, ...args)
+      if (typeof target === "string") this.transition(this.resolve(n, target))
+      return true
+    }
+    const h = this.root.def.on?.[event]
+    if (h === undefined) return false
+    const target = typeof h === "string" ? h : h(this.ctx, ...args)
+    if (typeof target === "string") this.transition(this.resolve(this.chain[this.chain.length - 1] ?? this.root, target))
+    return true
+  }
+
+  /** One tick: clocks, guards (outer first, chained), then updates (outer first). */
+  step(dt: number): void {
+    for (const n of this.chain) n.t += dt
+    this.root.t += dt
+    for (let hop = 0; hop < MAX_HOPS; hop++) {
+      const target = this.findTransition()
+      if (target === null) break
+      this.transition(target)
+    }
+    const mark = this.changed
+    const r0 = this.root.def.update?.(this.ctx, dt, this.root.t)
+    if (typeof r0 === "string") { this.transition(this.resolve(this.chain[this.chain.length - 1]!, r0)); return }
+    if (this.changed !== mark) return
+    const chain = this.chain.slice()
+    for (const n of chain) {
+      const r = n.def.update?.(this.ctx, dt, n.t)
+      if (typeof r === "string") { this.transition(this.resolve(n, r)); return }
+      if (this.changed !== mark) return   // an update transitioned through send()/go()
+    }
+  }
+
+  /** Listen for transitions. */
+  on(event: "change", fn: StateMachineEvents["change"]): this { this.listeners.push(fn); return this }
+  off(event: "change", fn: StateMachineEvents["change"]): this {
+    const i = this.listeners.indexOf(fn)
+    if (i >= 0) this.listeners.splice(i, 1)
+    return this
+  }
+
+  // ---- building ----
+  private build(name: string, path: string, def: StateDef<C>, parent: SNode<C> | null, depth: number): SNode<C> {
+    const node: SNode<C> = { name, path, def, parent, children: new Map(), initial: null, depth, t: 0, guards: [], after: null, resolved: new Map() }
+    if (path) this.byPath.set(path, node)
+    if (def.states) {
+      for (const [childName, childDef] of Object.entries(def.states)) {
+        if (childName.includes(".") || childName.startsWith("$")) throw new Error(`StateMachine: bad state name '${childName}'`)
+        node.children.set(childName, this.build(childName, path ? `${path}.${childName}` : childName, childDef, node, depth + 1))
+      }
+      const initial = def.initial ?? Object.keys(def.states)[0]!
+      const child = node.children.get(initial)
+      if (!child) throw new Error(`StateMachine: '${path || "root"}' has no child '${initial}' for initial`)
+      node.initial = child
+    } else if (def.initial) {
+      throw new Error(`StateMachine: '${path}' names an initial child but has no states`)
+    }
+    return node
+  }
+
+  private link(n: SNode<C>): void {
+    if (n.def.to) for (const [target, guard] of Object.entries(n.def.to)) n.guards.push([this.resolveStrict(n, target), guard])
+    if (n.def.after) n.after = [n.def.after[0], this.resolve(n, n.def.after[1])]
+    if (n.def.on) for (const h of Object.values(n.def.on)) if (typeof h === "string") this.resolve(n, h)
+  }
+
+  private resolveStrict(from: SNode<C>, name: string): SNode<C> {
+    const r = this.resolve(from, name)
+    if (r === BACK) throw new Error(`StateMachine: '${BACK}' is not allowed as a guard target of '${from.path}'`)
+    return r
+  }
+
+  /** Relative first (siblings of `from`, then of each ancestor), then a dotted path from the root. */
+  private resolve(from: SNode<C>, name: string): SNode<C> | typeof BACK {
+    const cached = from.resolved.get(name)
+    if (cached) return cached
+    let found: SNode<C> | typeof BACK | undefined
+    if (name === BACK) found = BACK
+    else {
+      for (let n: SNode<C> | null = from; n && !found; n = n.parent) {
+        const scope = n.parent ?? this.root
+        found = scope.children.get(name)
+        if (!found && n === from) found = n.children.get(name)   // a compound state naming its own child
+      }
+      if (!found) found = this.byPath.get(name)
+    }
+    if (!found) throw new Error(`StateMachine: unknown state '${name}' (from '${from.path || "root"}')`)
+    from.resolved.set(name, found)
+    return found
+  }
+
+  // ---- running ----
+  /** Guards never re-enter a state that is already active (a `dead` guard staying true does not
+   *  re-enter `dead` every step) — only an explicit `go()` / event does that. */
+  private findTransition(): SNode<C> | typeof BACK | null {
+    const ctx = this.ctx
+    for (const [target, guard] of this.root.guards) if (!this.active(target) && guard(ctx, this.root.t)) return target
+    for (const n of this.chain) {
+      for (const [target, guard] of n.guards) if (!this.active(target) && guard(ctx, n.t)) return target
+      if (n.after && n.t >= n.after[0] && (n.after[1] === BACK || !this.active(n.after[1]))) return n.after[1]
+    }
+    return null
+  }
+
+  private active(n: SNode<C>): boolean { return this.chain[n.depth - 1] === n }
+
+  private leafOf(n: SNode<C>): SNode<C> {
+    while (n.initial) n = n.initial
+    return n
+  }
+
+  private transition(target: SNode<C> | typeof BACK): void {
+    const current = this.chain[this.chain.length - 1] ?? null
+    let node: SNode<C>
+    if (target === BACK) {
+      if (!this.prev) return
+      node = this.prev
+    } else node = target
+    const leaf = this.leafOf(node)
+    // the new branch (root excluded)
+    const next: SNode<C>[] = []
+    for (let n: SNode<C> | null = leaf; n && n !== this.root; n = n.parent) next.unshift(n)
+    // common prefix; a target that is the current leaf or one of its ancestors re-enters itself
+    let common = 0
+    while (common < this.chain.length && common < next.length && this.chain[common] === next[common]) common++
+    if (node !== this.root && common >= node.depth && this.chain[node.depth - 1] === node) common = node.depth - 1
+    const from = current?.path ?? ""
+    const to = leaf.path
+    for (let i = this.chain.length - 1; i >= common; i--) this.chain[i]!.def.exit?.(this.ctx, to)
+    this.prev = current
+    this.enterBranch(this.chain.slice(0, common), leaf, from, next)
+  }
+
+  private enterBranch(kept: SNode<C>[], leaf: SNode<C>, from: string, next?: SNode<C>[]): void {
+    if (!next) {
+      next = []
+      for (let n: SNode<C> | null = leaf; n && n !== this.root; n = n.parent) next.unshift(n)
+    }
+    this.chain = kept.slice()
+    this.changed++
+    for (let i = kept.length; i < next.length; i++) {
+      const n = next[i]!
+      n.t = 0
+      this.chain.push(n)
+      n.def.enter?.(this.ctx, from)
+    }
+    for (const fn of this.listeners.slice()) fn(leaf.path, from)
+  }
+}

package/runtime/sdk/core/time.ts

@@ -15,6 +15,9 @@ const sinks: ScaleSink[] = []
 class TimeClock {
   private _scale = 1
   private _paused = false
+  /** The fixed step: what `updateFixed(dt)` receives, every time, on every machine (1/60). Under
+   *  `scale` the NUMBER of fixed steps per frame changes, never this value. */
+  readonly fixedDt = 1 / 60
   /** Seconds of GAME time since the app started (scaled; stops while paused). */
   now = 0
   /** Seconds of wall-clock time since the app started (never stops). */

package/runtime/sdk/gl/Camera.ts

@@ -36,6 +36,12 @@ export class Camera extends Node {
    *  defaults (the headless core takes a `fov` option) and a blind push would overwrite them. */
   private _projSet = false
 
+  // Exposure the app asked for (filament's physical defaults until it does): f/16, 1/125 s, ISO 100 =
+  // EV100 15, bright sunlight — what every light intensity in the docs is tuned against.
+  private _exposure = { aperture: 16, shutterSpeed: 1 / 125, iso: 100 }
+  private _ev = 0
+  private _exposureSet = false
+
   /** @internal — Scene wires the camera to its native scene id + projection callback. */
   _attach(sceneId: number): void {
     this._sceneId = sceneId
@@ -43,6 +49,39 @@ export class Camera extends Node {
       for (let i = 0; i < 16; i++) this.projectionMatrix[i] = mat[i]
     })
     if (this._projSet) this._applyProjection()
+    if (this._exposureSet) this._applyExposure()
+  }
+
+  /** Exposure compensation in stops (default 0): +1 doubles how bright the scene renders, −2
+   *  quarters it. The one exposure knob most games need — a dark interior, a flash of white, or eye
+   *  adaptation when the sun swings into view (drop it, and the sun stays at the display's peak
+   *  while everything else darkens). Scene light follows it; particle `emissive` is post-exposure
+   *  and does not, so a fireball keeps its on-screen brightness. Cheap to animate every frame. */
+  get exposureCompensation(): number { return this._ev }
+  set exposureCompensation(stops: number) {
+    this._ev = Number.isFinite(stops) ? stops : 0
+    this._exposureSet = true
+    this._applyExposure()
+  }
+
+  /** The physical camera: `aperture` in f-stops, `shutterSpeed` in seconds, `iso`, plus the same
+   *  `compensation` in stops — any subset, one call. `camera.setExposure({ iso: 400 })` is two stops
+   *  brighter than the default f/16 · 1/125 · ISO 100. */
+  setExposure(exposure: { aperture?: number, shutterSpeed?: number, iso?: number, compensation?: number }): this {
+    if (exposure.aperture !== undefined) this._exposure.aperture = exposure.aperture
+    if (exposure.shutterSpeed !== undefined) this._exposure.shutterSpeed = exposure.shutterSpeed
+    if (exposure.iso !== undefined) this._exposure.iso = exposure.iso
+    if (exposure.compensation !== undefined) this._ev = exposure.compensation
+    this._exposureSet = true
+    this._applyExposure()
+    return this
+  }
+
+  /** Hosts that predate the call keep the fixed default (older wasm / native builds). */
+  private _applyExposure(): void {
+    if (this._sceneId < 0) return
+    const e = this._exposure
+    _creator.setCameraExposure?.(this._sceneId, e.aperture, e.shutterSpeed, e.iso * 2 ** this._ev)
   }
 
   /** Vertical field of view in degrees (default 60) — a smaller angle is a longer lens. */

package/runtime/sdk/gl/Light.ts

@@ -14,12 +14,19 @@ export type SunOptions = {
   /**
    * Shadow quality (default 1):
    *   0 - no shadows
-   *   1 - standard (1024 shadow map, hard PCF edges)
-   *   2 - high (2048 + stable, soft contact-hardening edges)
-   *   3 - best (4096 + stable, PCSS soft shadows)
-   * Higher values cost more GPU/memory.
+   *   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 = {
@@ -59,6 +66,7 @@ export class Light extends Node {
       light._intensity,
       Color.toPackedRgb(options.color ?? 0xffffff),
       options.shadowsQuality ?? 1,
+      options.shadowDistance ?? 100,
     )
     return light
   }

package/runtime/sdk/gl/Lightmap.ts

@@ -19,6 +19,12 @@
 // 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.
+//
+// DYNAMIC objects (docs/lightmap-plan.md §9): the bake also writes lightmap.volume — the same two
+// 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"
@@ -40,19 +46,27 @@ export type LightmapLoadOptions = {
 export type LightmapInfo = {
   size: number
   texel: number
+  /** The light volume, when one was loaded: grid dims + cell size in metres. */
+  volume?: { dims: number[], cell: 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 }
+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,
+  aoDistance?: number, bias?: number, sunAngle?: number, volumeCell?: number,
 }
 
+type VolumeHeader = { texture: number, dims: number[], min: number[], cell: number }
+
 const bakeConfig = (): BakeConfig | null => {
   const g = (globalThis as unknown as { __lecodesLightmap?: BakeConfig }).__lecodesLightmap
   return g && typeof g.outDir === "string" ? g : null
@@ -71,9 +85,11 @@ export class Lightmap {
   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
 
+
   /** 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. */
@@ -81,6 +97,8 @@ export class Lightmap {
     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)
@@ -97,6 +115,17 @@ export class Lightmap {
     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)
@@ -106,12 +135,15 @@ export class Lightmap {
   /** Forget every registration (a scene rebuild). */
   static clear(): void {
     Lightmap.entries = []
+    Lightmap.dynamics = []
     Lightmap.ordinals.clear()
+    Model._lightmapDefault = false
+    _creator.lightmapVolumeSet?.(0xFFFFFFFF, 0, 0, 0, 0, 0, 0, 0, 1, 1)
   }
 
   /** 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> {
+  static async load(scene: Scene, files: { data: string, texture: string, volume?: string }, options: LightmapLoadOptions = {}): Promise<LightmapInfo | null> {
     const bake = bakeConfig()
     if (bake) { Lightmap.bake(bake); return null }
     if (!_creator.lightmapApply) {
@@ -131,6 +163,8 @@ export class Lightmap {
     const texture = await Texture.load(files.texture)
     const ambientScale = options.ambientScale ?? 1
     const strength = options.sunStrength ?? 1
+    // the light volume first: it claims every lightmap-material instance, the atlas rects below win back the statics
+    const volume = files.volume ? await Lightmap.loadVolume(files.volume, strength, ambientScale) : null
     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
@@ -141,19 +175,57 @@ export class Lightmap {
       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)
+        e.model.castShadows = false
       } else if (e.mesh) {
         Lightmap.swapMeshMaterial(e.mesh, texture, st, ambientScale, strength)
         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
+        e.terrain.material.set("lightmap", texture).set("lightmapST", [ st[0], st[1], st[2], st[3] ])
+          .set("ambientScale", ambientScale).set("sunStrength", strength)
+        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`)
-    return { size: data.size, texel: data.texel, applied, total: rects.size, missing }
+    const info: LightmapInfo = { size: data.size, texel: data.texel, applied, total: rects.size, missing }
+    if (volume) info.volume = { dims: volume.dims, cell: volume.cell }
+    return info
+  }
+
+  /** lightmap.volume → the engine's 3D texture → 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, strength: number, ambientScale: 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)
+    _creator.lightmapVolumeSet(header.texture, header.min[0], header.min[1], header.min[2], size[0], size[1], size[2], header.cell, strength, ambientScale)
+    for (const mesh of Lightmap.dynamics) {
+      const m = Lightmap.meshMaterial(mesh, ambientScale, strength)
+      m.set("probeVolume", texture)
+      m.set("probeMin", [ header.min[0], header.min[1], header.min[2], header.cell * 0.5 ])
+      m.set("probeInvSize", [ 1 / size[0], 1 / size[1], 1 / size[2], 1 ])
+      mesh.setMaterial(m)
+    }
+    return header
   }
 
   /** 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 {
+  private static meshMaterial(mesh: Mesh, ambientScale: number, strength: number): Material {
     const src = mesh.material
     const u = src?.uniforms ?? {}
     const m = Material.lightmap()
@@ -161,19 +233,24 @@ export class Lightmap {
     if (u.baseColorMap instanceof Texture) m.set("baseColorMap", u.baseColorMap)
     if (typeof u.roughness === "number") m.set("roughnessFactor", u.roughness)
     if (typeof u.metallic === "number") m.set("metallicFactor", u.metallic)
-    m.set("lightmap", texture)
-    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
     m.set("ambientScale", ambientScale)
     m.set("sunStrength", strength)
+    return m
+  }
+
+  private static swapMeshMaterial(mesh: Mesh, texture: Texture, st: number[], ambientScale: number, strength: number): void {
+    const m = Lightmap.meshMaterial(mesh, ambientScale, strength)
+    m.set("lightmap", texture)
+    m.set("lightmapST", [ st[0], st[1], st[2], st[3] ])
     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 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 }
     _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.aoDistance ?? 2, cfg.bias ?? 0.02, cfg.sunAngle ?? 0.5, cfg.volumeCell ?? 0.5)
   }
 }

package/runtime/sdk/gl/Material.ts

@@ -205,6 +205,21 @@ export class Material {
     const m = new Material({ _id: _creatorUtils.fetchLocal("lightmap.filamat") } as any)
     m.set("baseColorFactor", "#ffffffff").set("roughnessFactor", 1).set("metallicFactor", 0)
     m.set("lightmapST", [ 1, 1, 0, 0 ]).set("ambientScale", 1).set("sunStrength", 1).set("hasNormalMap", 0)
+    m.set("probeMin", [ 0, 0, 0, 0 ]).set("probeInvSize", [ 0, 0, 0, 0 ])
+    return m
+  }
+
+  /** The terrain splat material (docs/terrain-plan.md §1.5): four albedo (+ normal-map) layers blended by
+   *  a control map on the terrain's own grid, per-layer `tiling` (metres per repeat) / `roughness` /
+   *  `normalScale` / `triplanar`, lightmap-aware (the same `lightmap` / `lightmapST` block as
+   *  `Material.lightmap`). `Terrain` builds and owns one per terrain; the uniforms are primed here so an
+   *  unset layer is white and an unbaked terrain is fully lit. */
+  static terrain(): Material {
+    // Inline literal: the compiler's preload header captures the shader name from it.
+    const m = new Material({ _id: _creatorUtils.fetchLocal("terrain.filamat") } as any)
+    m.set("tiling", [ 8, 8, 8, 8 ]).set("roughness", [ 1, 1, 1, 1 ]).set("normalScale", [ 0, 0, 0, 0 ]).set("triplanar", [ 0, 0, 0, 0 ])
+    m.set("gridSize", [ 2, 2 ]).set("cellSize", 1).set("tint", "#ffffff")
+    m.set("lightmapST", [ 1, 1, 0, 0 ]).set("ambientScale", 1).set("sunStrength", 1)
     return m
   }