lecodes-sdk 0.20.2 → 1.1.0

package/src/gl/DecalSet.ts

@@ -35,6 +35,14 @@ export type DecalOptions = {
   fadeIn?: number
   /** Seconds of fade at the end of `life` (ignored with life 0). Default 0. */
   fadeOut?: number
+  /** Opacity multipliers at the image's BOTTOM and TOP edge (−Y / +Y), interpolated along it — a
+   *  tire mark that darkens as the slide deepens. Default `[1, 1]`. */
+  gradient?: [number, number]
+  /** Tilt of the image's bottom and top edge, as a unit-space slope (Δy per Δx across the box):
+   *  the edge pivots on the corner of the side it keeps and cuts INTO the box on the other, so two
+   *  boxes can meet on one shared line — what `DecalTrail` uses to mitre its joints. `0` = square.
+   *  Default `[0, 0]`. */
+  caps?: [number, number]
 }
 
 export type DecalSetOptions = DecalOptions & {
@@ -63,8 +71,10 @@ export type DecalSetOptions = DecalOptions & {
   /** HDR boost of the image (0 = none). Default material only. */
   emissive?: number
   name?: string
-  /** Coarse draw order, 0 (first) … 7 (last); default 4 — see `Mesh.renderPriority`. Decals are
-   *  blended and sort with the other blended draws of their priority. */
+  /** Coarse draw order, 0 (first) … 7 (last) — see `Mesh.renderPriority`. Default 3: a decal is
+   *  part of the surface it sits on, so it draws before every other blended thing (meshes 4,
+   *  particles 5) — the engine's depth sort compares object centres, and a set spread over the
+   *  level has no useful centre. */
   renderPriority?: number
 }
 
@@ -86,7 +96,7 @@ export type DecalPlacement = DecalOptions & {
   rotation?: QuatLike | Vec3Like
 }
 
-const RECORD = 23
+const RECORD = 27
 const NO_SLOT = 0xFFFFFFFF
 
 export class DecalSet extends Node {
@@ -116,7 +126,7 @@ export class DecalSet extends Node {
     }
     if (_creator.createDecalSet) {
       _creator.createDecalSet(this.id, Material.idOf(this._material), this._max)
-      if (options.renderPriority !== undefined) this.renderPriority = options.renderPriority
+      this.renderPriority = options.renderPriority ?? 3
     } else if (!DecalSet._warned) {
       DecalSet._warned = true
       console.warn("[decals] this host has no createDecalSet — decals are not drawn")
@@ -200,7 +210,8 @@ export class DecalSet extends Node {
     return this._write(slot, right, up, normal, new Vec3(p.position), p)
   }
 
-  private _write(slot: number, right: Vec3, up: Vec3, normal: Vec3, centre: Vec3, o: DecalOptions): number {
+  /** @internal One decal's frame → record → host (`DecalTrail` writes its segments through here). */
+  _write(slot: number, right: Vec3, up: Vec3, normal: Vec3, centre: Vec3, o: DecalOptions): number {
     const d = this._defaults
     const size = o.size ?? d.size!
     const w = typeof size === "number" ? size : size[0]
@@ -222,6 +233,10 @@ export class DecalSet extends Node {
     const opacity = o.opacity ?? d.opacity!
     r[16] = tr; r[17] = tg; r[18] = tb; r[19] = ta * opacity
     r[20] = o.life ?? d.life!; r[21] = o.fadeIn ?? d.fadeIn!; r[22] = o.fadeOut ?? d.fadeOut!
+    const caps = o.caps ?? d.caps
+    r[23] = caps ? caps[0] : 0; r[24] = caps ? caps[1] : 0
+    const gradient = o.gradient ?? d.gradient
+    r[25] = gradient ? gradient[0] : 1; r[26] = gradient ? gradient[1] : 1
     if (slot === NO_SLOT) {
       if (!_creator.addDecal) return -1
       const s = _creator.addDecal(this.id, r)
@@ -231,3 +246,115 @@ export class DecalSet extends Node {
     return slot
   }
 }
+
+/** A `DecalTrail`'s look: the strip's width, and what every segment carries. */
+export type DecalTrailOptions = Omit<DecalOptions, "size" | "caps" | "gradient"> & {
+  /** Width of the strip on the surface, world units. */
+  width: number
+}
+
+// The mitre stops making sense past this turn between two segments (a sharp reversal would need a
+// box longer than the strip is wide); the trail breaks there and starts afresh.
+const TRAIL_MAX_SLOPE = 1.75   // tan 60°
+
+/**
+ * A continuous strip of decals along a path — a tire's skid mark, a dragged body, a tread track.
+ * Feed it points (`add`) as the thing moves; every new point becomes one box-decal SEGMENT from the
+ * previous point, its image's up along the travel, and the joints between segments are MITRED: each
+ * box is cut along the bisector it shares with its neighbour (`caps`), so the strip has no overlaps
+ * darkening the outside of a bend and no wedges of gap on the inside. The opacity given with each
+ * point is interpolated along the segment (`gradient`), so a mark can darken as a slide deepens and
+ * fade as it ends. Segments are the set's decals — same ring, same `max` budget: a set of 900 holds
+ * 900 segments across every trail drawn from it.
+ *
+ * The previous segment is REWRITTEN when the next point arrives (its far cap becomes the shared
+ * mitre), through `DecalSet.update`'s path — a recycled slot is simply left alone by the engine.
+ */
+export class DecalTrail {
+  private _prev: { point: Vec3, opacity: number } | null = null
+  private _seg: {
+    slot: number, start: Vec3, end: Vec3, dir: Vec3, right: Vec3, normal: Vec3,
+    slopeStart: number, a0: number, a1: number,
+  } | null = null
+
+  readonly set: DecalSet
+  readonly options: DecalTrailOptions
+
+  constructor(set: DecalSet, options: DecalTrailOptions) {
+    this.set = set
+    this.options = options
+  }
+
+  /** Extend the strip to `point` on a surface with `normal`, `opacity` (0..1) at that point. The
+   *  first call after a start / `end()` only anchors the strip. Returns the new segment's slot, or
+   *  −1 when nothing was drawn (the anchor, a point that did not move, no host support). */
+  add(point: Vec3Like, normal: Vec3Like, opacity = 1): number {
+    const p = new Vec3(point)
+    const n = new Vec3(normal).normalize()
+    const prev = this._prev
+    this._prev = { point: p, opacity }
+    if (!prev) return -1
+    // The segment, flattened onto the surface plane.
+    let d = p.sub(prev.point)
+    d = d.sub(n.scale(d.dot(n)))
+    const len = d.length()
+    if (len < 1e-3) { this._prev = prev; return -1 }   // not moved: wait for a real step
+    const dir = d.scale(1 / len)
+    const right = dir.cross(n)   // DecalSet.spawn's frame: right × up = normal, image unmirrored from the normal's side
+    const w = this.options.width
+
+    // Mitre with the previous segment: the joint's bisector is the sum of the two right normals,
+    // and each box takes it as a cap — the previous one at its END (rewritten now), this one at its
+    // START — with the slopes measured in each box's own frame. A trail's first segment, or one
+    // after a break, starts square.
+    let slopeStart = 0
+    const last = this._seg
+    if (last) {
+      const lastDir = last.dir.sub(n.scale(last.dir.dot(n))).normalize()
+      const lastRight = lastDir.cross(n)
+      const m = lastRight.add(right)
+      const denom = m.dot(right)
+      const slopeEnd = Math.abs(denom) > 1e-4 ? m.dot(lastDir) / denom : Infinity
+      if (Math.abs(slopeEnd) <= TRAIL_MAX_SLOPE) {
+        this._rewrite(last, slopeEnd)
+        slopeStart = -slopeEnd
+      } else {
+        this._rewrite(last, 0)   // too sharp to mitre: leave the last one square, start afresh
+      }
+    }
+    const seg = { slot: -1, start: prev.point, end: p, dir, right, normal: n, slopeStart, a0: prev.opacity, a1: opacity }
+    seg.slot = this._box(seg, 0, -1)
+    this._seg = seg
+    return seg.slot
+  }
+
+  /** Finish the strip. With a `point`, one last segment runs out to it at opacity 0 — a mark that
+   *  tapers away instead of stopping dead. The next `add` anchors a new strip. */
+  end(point?: Vec3Like, normal: Vec3Like = Vec3.up): this {
+    if (point && this._prev) this.add(point, normal, 0)
+    this._prev = null
+    this._seg = null
+    return this
+  }
+
+  private _rewrite(seg: NonNullable<DecalTrail["_seg"]>, slopeEnd: number): void {
+    if (seg.slot >= 0) this._box(seg, slopeEnd, seg.slot)
+  }
+
+  /** Write one segment's box: the strip between its joints, extended past each mitred joint by the
+   *  mitre's reach (w/2 · |slope|) so the tilted cap still passes through the joint's centre. */
+  private _box(seg: NonNullable<DecalTrail["_seg"]>, slopeEnd: number, slot: number): number {
+    const w = this.options.width
+    const L = seg.end.sub(seg.start).length()
+    const extStart = 0.5 * w * Math.abs(seg.slopeStart)
+    const extEnd = 0.5 * w * Math.abs(slopeEnd)
+    const boxLen = L + extStart + extEnd
+    const centre = seg.start.add(seg.dir.scale(0.5 * boxLen - extStart))
+    // World slopes → unit-space slopes: x is measured in widths, y in box lengths.
+    const caps: [number, number] = [ seg.slopeStart * (w / boxLen), slopeEnd * (w / boxLen) ]
+    const { width: _w, ...rest } = this.options
+    const s = this.set._write(slot < 0 ? NO_SLOT : slot, seg.right, seg.dir, seg.normal, centre,
+      { ...rest, size: [ w, boxLen ], caps, gradient: [ seg.a0, seg.a1 ] })
+    return slot < 0 ? s : slot
+  }
+}

package/src/gl/Foliage.ts

@@ -0,0 +1,102 @@
+// Foliage — the vegetation tier of the lightmap material family (creator-gl materials/src/foliage.mat).
+//
+// A model loaded with `Model.load(src, { foliage: true })` (scene files: `foliage: true` on a `model`
+// node) takes a shader whose vertices sway in the wind, bend away from BENDERS (the hero, enemies —
+// any node registered with `Foliage.bend`) and thin out over a distance range, and whose fragment
+// tints every copy a little differently. All of it is level-wide state the engine keeps: the wind
+// and the sway options apply to every foliage model, present and future; benders are read from
+// their live world transforms each frame (the 8 nearest the camera reach the shader); a fade is per
+// ASSET — every copy of that model, present and future.
+//
+// Hosts without the tier (no `foliageSet*` bridge) ignore every call; the models then load through
+// the ordinary lightmap tier where that exists, else the standard shader.
+import { Model } from "./Model"
+import { Node } from "./Node"
+
+export type FoliageWind = {
+  /** Direction on the ground (x, z); normalised by the engine. Default [1, 0.3]. */
+  direction?: [number, number]
+  /** Metres of sway at `bendHeight` (taller parts sway more). Default 0.07. 0 = still. */
+  strength?: number
+  /** Radians per second of the main sway. Default 1.2. */
+  speed?: number
+  /** 0..1: how much the strength breathes over a slow envelope. Default 0.6. */
+  gust?: number
+}
+
+export type FoliageOptions = {
+  /** The wind, or `false` for none. */
+  wind?: FoliageWind | false
+  /** Height above the instance origin (m) where the full sway / touch applies; the base never moves.
+   *  Default 1.5. */
+  bendHeight?: number
+  /** Metres the TOP of a small plant leans away from a bender standing at its centre; the whole plant leans
+   *  as one, rooted at its base. Plants over ~2 m react less, trees over ~5 m not at all (the engine
+   *  measures each asset). Default 0.6. 0 = no touch reaction. */
+  touch?: number
+  /** 0..1: how far each copy's tint drifts from the texture (warmer/darker to cooler/lighter, by a hash
+   *  of its position). Default 0.35. */
+  variation?: number
+  /** 0..1: wrapped sun lighting — thin leaves let light through. Default 0.5. */
+  sunWrap?: number
+}
+
+const state: Required<Omit<FoliageOptions, "wind">> & { wind: Required<FoliageWind> | false } = {
+  wind: { direction: [ 1, 0.3 ], strength: 0.07, speed: 1.2, gust: 0.6 },
+  bendHeight: 1.5,
+  touch: 0.6,
+  variation: 0.35,
+  sunWrap: 0.5,
+}
+
+const pushWind = (): void => {
+  const w = state.wind
+  if (w === false) _creator.foliageSetWind?.(1, 0, 0, 1, 0)
+  else _creator.foliageSetWind?.(w.direction[0], w.direction[1], w.strength, w.speed, w.gust)
+}
+
+export const Foliage = {
+  /** Level-wide options; each field given replaces the current value (a scene file's `env.foliage`
+   *  goes through here). */
+  configure(options: FoliageOptions): void {
+    if (options.wind !== undefined) Foliage.wind(options.wind)
+    let sway = false
+    if (options.bendHeight !== undefined) { state.bendHeight = options.bendHeight; sway = true }
+    if (options.touch !== undefined) { state.touch = options.touch; sway = true }
+    if (options.variation !== undefined) { state.variation = options.variation; sway = true }
+    if (options.sunWrap !== undefined) { state.sunWrap = options.sunWrap; sway = true }
+    if (sway) _creator.foliageSetOptions?.(state.bendHeight, state.touch, state.variation, state.sunWrap)
+  },
+
+  /** The wind: fields given replace the current ones; `false` = calm. Live. */
+  wind(wind: FoliageWind | false): void {
+    if (wind === false) state.wind = false
+    else {
+      const cur = state.wind === false ? { direction: [ 1, 0.3 ] as [number, number], strength: 0.07, speed: 1.2, gust: 0.6 } : state.wind
+      state.wind = { direction: wind.direction ?? cur.direction, strength: wind.strength ?? cur.strength, speed: wind.speed ?? cur.speed, gust: wind.gust ?? cur.gust }
+    }
+    pushWind()
+  },
+
+  /** A node whose live position pushes the vegetation within `radius` metres (the hero: ~0.7; a
+   *  boulder: its size). Any number may be registered; the 8 nearest the camera act each frame. The
+   *  engine also tracks the node's velocity (smoothed over ~0.2 s): a plant you run through is brushed
+   *  forward and settles behind you instead of flipping as you cross its centre.
+   *  Returns the unregister function; a destroyed node drops out on its own. */
+  bend(node: Node, radius = 0.7): () => void {
+    _creator.foliageSetBender?.(node.id, radius > 0 ? radius : 0.01)
+    return () => Foliage.unbend(node)
+  },
+
+  /** Stop a node from bending the vegetation. */
+  unbend(node: Node): void {
+    _creator.foliageSetBender?.(node.id, 0)
+  },
+
+  /** Distance fade for EVERY copy of this model's asset (present and future): the cards thin out
+   *  from `start` to `end` metres from the camera and past `end` the copy leaves the frame entirely.
+   *  Small ground cover (grass, clover, flowers) is the target; `end` 0 = no fade. */
+  fade(model: Model, start: number, end: number): void {
+    _creator.foliageSetFade?.(model.id, start, end)
+  },
+}

package/src/gl/Geometry.ts

@@ -3,9 +3,25 @@
 // worker/src/primitives/*.
 
 import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import { fetch } from "../runtime/fetch"
 
 export type MeshKind = "triangles" | "vertices" | "edges"
 
+/** A geometry file — what `lecodes assets geometry <model.glb>` writes (`<model>.geometry.json`):
+ *  one merged, world-space triangle buffer. `Geometry.load(asset('./casing.geometry.json'))`. */
+export type GeometryData = {
+  format?: "lecodes-geometry"
+  version?: number
+  /** xyz per vertex. */
+  vertices: ArrayLike<number>
+  /** xyz per vertex (unit length). */
+  normals: ArrayLike<number>
+  /** uv per vertex. */
+  uv: ArrayLike<number>
+  /** Triangle list, ≤ 65535 vertices addressed. */
+  indices: ArrayLike<number>
+}
+
 // local tuple helpers — geometry building works on raw Float32Array buffers, so it stays out of the
 // Vec3 wrapper (no per-vertex allocation).
 type Tup3 = [number, number, number]
@@ -65,7 +81,39 @@ export class Geometry {
   static box(size: Vec3Like | number = 1): Geometry { return createCube(size) }
   static sphere(options?: SphereOptions): Geometry { return createSphere(options) }
   static cylinder(options?: CylinderOptions): Geometry { return createCylinder(options) }
+  /** A capsule along Y, centred at the origin: a cylinder `length` long (between the two cap centres)
+   *  with a hemisphere of `radius` on each end — one closed surface, smooth across the seams. */
+  static capsule(options?: CapsuleOptions): Geometry { return createCapsule(options) }
   static plane(options?: PlaneOptions): Geometry { return createPlane(options) }
+
+  /** A Geometry from a geometry file's contents (`GeometryData` — see `Geometry.load`). The arrays
+   *  are copied into typed buffers, so the source object can be dropped. */
+  static fromData(data: GeometryData): Geometry {
+    if (!data || !data.vertices || !data.indices) throw new Error("Geometry.fromData: not a geometry file (no vertices/indices)")
+    if (data.format !== undefined && data.format !== "lecodes-geometry") throw new Error(`Geometry.fromData: unknown format "${data.format}"`)
+    const nv = data.vertices.length / 3
+    if (nv > 65535) throw new Error(`Geometry.fromData: ${nv} vertices — at most 65535 (uint16 indices)`)
+    const vertices = Float32Array.from(data.vertices)
+    const normals = data.normals && data.normals.length === vertices.length ? Float32Array.from(data.normals) : new Float32Array(vertices.length)
+    const uv = data.uv && data.uv.length === nv * 2 ? Float32Array.from(data.uv) : new Float32Array(nv * 2)
+    return new Geometry(vertices, normals, Uint16Array.from(data.indices), uv)
+  }
+
+  /** Load a geometry file: `lecodes assets geometry casing.glb` → `casing.geometry.json` →
+   *  `await Geometry.load(asset('./casing.geometry.json'))`. A GLB's triangles as a plain buffer,
+   *  for `Particles({ mesh })` debris (shell casings, rubble) and `Mesh.from`.
+   *  A `.json` project file is INLINED by the compiler — `asset('./x.json')` is the parsed data, not
+   *  a URL — so that form (and `import data from './x.json'`) is read directly, no fetch; a string
+   *  (a URL, a non-`.json` asset such as `.geo`) is fetched. */
+  static async load(source: string | GeometryData): Promise<Geometry> {
+    if (typeof source !== "string") return Geometry.fromData(source)
+    const url = source
+    const resp = await fetch(url, { useOnce: true })
+    if (resp.status >= 400) { resp.dispose(); throw new Error(`Geometry.load: ${url} → HTTP ${resp.status}`) }
+    const data = resp.json<GeometryData>()
+    resp.dispose()
+    return Geometry.fromData(data)
+  }
 }
 
 // Gutter between lightmap charts (fraction of the chart square): the bake dilates each rect by a
@@ -193,6 +241,67 @@ const createSphere = (options: SphereOptions = {}): Geometry => {
   return new Geometry(vertices, normals, indices, uvs)
 }
 
+// --- capsule ---
+export type CapsuleOptions = {
+  radius?: number
+  /** Distance between the two cap centres (the straight part); 0 = a sphere. Default 1. */
+  length?: number
+  /** Segments around the axis. */
+  widthSegments?: number
+  /** Rings per hemisphere (pole to equator). */
+  capSegments?: number
+}
+const createCapsule = (options: CapsuleOptions = {}): Geometry => {
+  const { radius = 0.5, length = 1, widthSegments = 32, capSegments = 8 } = options
+  const W = widthSegments, half = length / 2
+  // rings from the top cap's first ring down to the bottom cap's last: the equator appears twice (once per
+  // cap, `length` apart) — the band between those two rings is the cylinder; the poles are fans, like the sphere
+  const R = capSegments * 2
+  const verticesCount = (W + 1) * R + W * 2
+  const vertices = new Float32Array(verticesCount * 3)
+  const normals = new Float32Array(verticesCount * 3)
+  const uvs = new Float32Array(verticesCount * 2)
+  const indices = new Uint16Array(W * (R - 1) * 6 + W * 3 * 2)
+  const total = Math.PI * radius + length   // arc from pole to pole, for v
+  let vertexCnt = 0, indicesCnt = 0
+  for (let j = 0; j < R; j++) {
+    const top = j < capSegments
+    const theta = (top ? j + 1 : j) / capSegments * (Math.PI / 2)   // 0 = the top pole, π = the bottom
+    const yOff = top ? half : -half
+    const sinT = Math.sin(theta), cosT = Math.cos(theta)
+    const v = ((Math.PI - theta) * radius + (top ? length : 0)) / total
+    for (let ix = 0; ix <= W; ix++) {
+      const u = ix / W
+      const nx = -Math.cos(u * Math.PI * 2) * sinT, nz = Math.sin(u * Math.PI * 2) * sinT
+      vertices.set([ nx * radius, cosT * radius + yOff, nz * radius ], vertexCnt * 3)
+      normals.set([ nx, cosT, nz ], vertexCnt * 3)
+      uvs.set([ u, v ], vertexCnt * 2)
+      if (j > 0 && ix > 0) {
+        const s = vertexCnt - 1, s1 = vertexCnt - (W + 1) - 1
+        indices.set([ s + 1, s1, s, s1, s + 1, s1 + 1 ], indicesCnt)
+        indicesCnt += 6
+      }
+      vertexCnt++
+    }
+  }
+  const lastRing = vertexCnt - (W + 1)
+  for (const side of [ 1, -1 ]) {
+    const circleStart = side > 0 ? 0 : lastRing
+    for (let ix = 0; ix < W; ix++) {
+      const u = (ix + 0.5) / W
+      vertices.set([ 0, side * (radius + half), 0 ], vertexCnt * 3)
+      normals.set([ 0, side, 0 ], vertexCnt * 3)
+      uvs.set([ u, side > 0 ? 1 : 0 ], vertexCnt * 2)
+      const s = circleStart + ix
+      if (side > 0) indices.set([ s, s + 1, vertexCnt ], indicesCnt)
+      else indices.set([ vertexCnt, s + 1, s ], indicesCnt)
+      indicesCnt += 3
+      vertexCnt++
+    }
+  }
+  return new Geometry(vertices, normals, indices, uvs)
+}
+
 // --- cylinder ---
 export type CylinderOptions = { radius?: number, radiusTop?: number, radiusBottom?: number, edges?: number, smooth?: boolean }
 const createCylinder = (options: CylinderOptions = {}): Geometry => {

package/src/gl/Light.ts

@@ -3,7 +3,15 @@
 
 import { Color, type ColorInput } from "../core/color"
 import type { Vec3Like } from "../math/vec"
-import { Node } from "./Node"
+import { Node, type NodeTweenProps } from "./Node"
+import { DOM_GL_LIGHT, colorValue, floatValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
+import type { Animation } from "../animate/tween/Animation"
+
+/** Animatable light props on top of the node transform. */
+export type LightTweenProps = NodeTweenProps & {
+  intensity?: number | number[],
+  color?: ColorInput | ColorInput[],
+}
 
 export type SunOptions = {
   /** Light direction (points where the light travels). Defaults to a typical key-light angle. */
@@ -46,26 +54,42 @@ export type PointOptions = {
   /** 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.
+   * Whether `lecodes lightmap bake` bakes this light into the level's lightmap. A baked lamp lights the statics
+   * from the atlas and the MOVERS from the level's light grid, and is held dark in real time while that grid is
+   * loaded (without a grid it keeps lighting the movers live); a light
+   * that must reach the statics live too — a flicker, a lamp the player can shoot out, a muzzle flash —
+   * says `baked: false`: it is kept out of the bake and put on the statics' light channel. Default true.
    */
   baked?: boolean
+  /**
+   * THE BAKE'S SHAPE of this lamp: `[width, height]` in metres = an AREA light - a rectangle in the light's local XZ
+   * plane, emitting along its local -Y (down, for an unrotated node) with the same lumens: a ceiling panel. The bake
+   * lights from the whole rectangle (soft shadows, light from where the panel is and not from a point inside the
+   * fixture). Real time it is still the point light above. Ignored with `baked: false`.
+   */
+  bakeArea?: readonly [number, number]
 }
 
 export class Light extends Node {
   private _intensity = 0
+
+  /** Tween `intensity` / `color` (a flash, a sunrise) and the transform — see {@link Node.animateTo}. */
+  override animateTo(props: LightTweenProps & TweenMeta): Animation { return super.animateTo(props) }
+  override animateFrom(props: LightTweenProps & TweenMeta): Animation { return super.animateFrom(props) }
+  /** @internal */
+  override _tweenChannel(prop: string): TweenChannel | null {
+    const id = () => this.id
+    if (prop === "intensity") return { domain: DOM_GL_LIGHT, id, value: floatValue, commit: (v) => { this._intensity = v as number } }
+    if (prop === "color") return { domain: DOM_GL_LIGHT, id, value: (v) => colorValue(v, Color.toRgba01) }
+    return super._tweenChannel(prop)
+  }
   /** @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). */
+  /** @internal sun direction as created (the engine keeps it). */
   _direction: [number, number, number] = [ 0, -1, 0 ]
-  /** The most recently created sun — what `Lightmap.load` uses unless told otherwise. */
+  /** The most recently created sun. */
   static lastSun: Light | null = null
   /** @internal the colour as created / last set (a settings menu recreates a sun from these). */
   _color: ColorInput = 0xffffff
@@ -113,6 +137,9 @@ export class Light extends Node {
       options.range ?? 10,
       options.castShadows ?? false,
     )
+    if (options.bakeArea && light._baked) _creator.setLightBakeArea?.(light.id, options.bakeArea[0], options.bakeArea[1])
+    // an unbaked lamp lights the baked statics live: Filament channel 1 (see Lightmap)
+    if (!light._baked) _creator.setLightChannel?.(light.id, 1, true)
     return light
   }
 
@@ -123,14 +150,17 @@ export class Light extends Node {
   get intensity(): number { return this._intensity }
   set intensity(value: number) {
     this._intensity = value
-    _creator.setLightIntensity?.(this.id, this._bakedOff ? 0 : value)
+    if (!this._heldDark) _creator.setLightIntensity?.(this.id, 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)
+  /** @internal A BAKED lamp is held dark while the level's LIGHT GRID is loaded (Lightmap): the statics have it in the
+   *  atlas and the movers in the grid's ambient cubes - left burning it lit every mover and unbaked prop a second time,
+   *  without a shadow (through walls), and put a hot spot on its own fixture. `intensity` keeps the authored value. */
+  _heldDark = false
+  _holdDark(dark: boolean): void {
+    if (this._heldDark === dark) return
+    this._heldDark = dark
+    _creator.setLightIntensity?.(this.id, dark ? 0 : this._intensity)
   }
 
   destroy(): void {