lecodes-cli 0.18.1 → 0.19.0

package/runtime/sdk/gl/Texture.ts

@@ -30,6 +30,23 @@ export class Texture {
     return new Texture(Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio), canvas._tex3dId)
   }
 
+  /** A texture from raw pixels: `channels` (1–4, default 4) UBYTE per pixel, row-major, `width ×
+   *  height × channels` bytes; `srgb` (default true for colour) picks the sRGB internal format —
+   *  pass false for data (a heightmap, a mask). No mips. Throws on a host without the call. */
+  static fromPixels(width: number, height: number, data: Uint8Array, opts: { channels?: 1 | 2 | 3 | 4, srgb?: boolean } = {}): Texture {
+    if (!_creator.createTexturePixels) throw new Error("Texture.fromPixels needs a newer host")
+    const channels = opts.channels ?? 4
+    if (data.length < width * height * channels) throw new Error(`Texture.fromPixels: ${data.length} bytes for ${width}×${height}×${channels}`)
+    const id = _creator.createTexturePixels(width, height, channels, data, opts.srgb ?? true)
+    if (id === 0xFFFFFFFF) throw new Error("Texture.fromPixels: the host refused the texture")
+    return new Texture(width, height, id)
+  }
+
+  /** Re-upload a rectangle of a `fromPixels` texture (same channel count). */
+  update(x: number, y: number, width: number, height: number, data: Uint8Array): void {
+    _creator.updateTexturePixels?.(this._id, x, y, width, height, data)
+  }
+
   static load(source: string | FetchResponse | File): Promise<Texture> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {

package/runtime/sdk/gl/animation/Animator.ts

@@ -21,15 +21,38 @@
 import { Aspect } from "../../core/Aspect"
 import type { Node } from "../Node"
 import type { AnimationClip } from "./AnimationClip"
-import { Core, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
+import { Core, type ActiveClip, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
 import type { Loop } from "./Loop"
 import type { Layer } from "./Layer"
 import type { Playback } from "./Playback"
 
+/** Level of detail for a GLB instance (docs/lod-plan.md): `'auto'` = the engine's pick by screen size and
+ *  visibility, or a fixed level 0 (full) … 3 (coarsest mesh, animation every 4th frame without fingers). */
+export type LodMode = "auto" | 0 | 1 | 2 | 3
+
+/** @internal Push a node's LOD override to the host: the Model's mesh level and the Animator's rate
+ *  (an Animator set to 'full' wins over a model level — the pose stays exact, the mesh may still coarsen). */
+export const _pushLod = (node: Node): void => {
+  if (!_creator.setLod) return
+  const mesh = (node as { _lodMesh?: number })._lodMesh ?? -1
+  const anim = node.get(Animator)
+  _creator.setLod(node.id, mesh, anim?._lod === "full" ? 0 : mesh)
+}
+
 export class Animator extends Aspect<"anim", Node> {
   static readonly aspect = "anim"
   private _c!: Core
   private _rootMotion = false
+  private _rootRotation = false
+  /** @internal */
+  _lod: "auto" | "full" = "auto"
+
+  /** Animation level of detail. `'auto'` (default): a character small on screen or out of view is
+   *  evaluated every 2nd / 4th frame and stops sampling its finger, toe and twist joints; `'full'`:
+   *  every frame, every joint, whatever the distance — a hero seen through a scope, a cutscene actor.
+   *  Independent of `Model.lod` (the mesh level). No-op on hosts without the LOD pass. */
+  get lod(): "auto" | "full" { return this._lod }
+  set lod(v: "auto" | "full") { this._lod = v; _pushLod(this.node) }
 
   onAttach(): void { this._c = new Core(this.node) }
   onDetach(): void { this._c.destroy() }
@@ -66,6 +89,8 @@ export class Animator extends Aspect<"anim", Node> {
   get loop(): Loop | undefined { return this._c.layers[0].loop?.view }
   /** A one-shot on the base layer hasn't handed over yet. */
   get busy(): boolean { return this._c.busy(this._c.layers[0]) }
+  /** Every clip shown this frame, all layers, with its weight — the crossfades' state (a debug overlay's list). */
+  get active(): ActiveClip[] { return this._c.layers.flatMap((L) => this._c.active(L)) }
 
   // ---- layers ----
   /** A new layer on top (masked override / additive). The returned object is its handle. */
@@ -83,5 +108,13 @@ export class Animator extends Aspect<"anim", Node> {
    *  or its CharacterController (on this node or an ancestor) as a velocity, so it collides. For
    *  clips whose hips actually travel (Mixamo without "In Place", lunges, rolls). */
   get rootMotion(): boolean { return this._rootMotion }
-  set rootMotion(on: boolean) { this._rootMotion = on; this._c.setRootMotion(on) }
+  set rootMotion(on: boolean) { this._rootMotion = on; this._c.setRootMotion(on, this._rootRotation) }
+  /** With `rootMotion`, the root bone's TURN (its yaw about the node's up, since the clip's first
+   *  frame) is root motion too: it comes off the pose and turns the node the travel lands on — the
+   *  character (or the model) faces where a turn-start / turn-in-place / arc clip took it, and the
+   *  crossfade into the next clip keeps that heading instead of swinging back. Off by default: a
+   *  walk cycle's hip sway is a turn too, and most rigs want it in the pose; turn it on for a rig
+   *  whose root bone carries the heading (`lecodes assets retarget --root-rotation yaw`). */
+  get rootRotation(): boolean { return this._rootRotation }
+  set rootRotation(on: boolean) { this._rootRotation = on; if (this._rootMotion) this._c.setRootMotion(true, on) }
 }

package/runtime/sdk/gl/animation/Layer.ts

@@ -2,7 +2,7 @@
 // `{ additive: true }` for deltas stacked on top). The Animator's own play/stop/playLoop ARE its base
 // layer; extra layers composite over it in creation order. The object is the layer's only handle.
 
-import type { Core, LayerRec, LoopDef, LoopOptions, PlayOptions, StopOptions } from "./core"
+import type { ActiveClip, Core, LayerRec, LoopDef, LoopOptions, PlayOptions, StopOptions } from "./core"
 import type { Loop } from "./Loop"
 import type { Playback } from "./Playback"
 
@@ -26,4 +26,6 @@ export class Layer {
   set weight(v: number) { this._r.weight = v; this._c.pushLayer(this._r) }
   /** A one-shot on this layer hasn't handed over yet. */
   get busy(): boolean { return this._c.busy(this._r) }
+  /** Every clip this layer shows this frame with its weight — the crossfades' state, for a debug overlay. */
+  get active(): ActiveClip[] { return this._c.active(this._r) }
 }

package/runtime/sdk/gl/animation/Loop.ts

@@ -16,6 +16,11 @@ export class Loop {
    *  even while a one-shot plays (the loop returns at the new mix). */
   get value(): BlendPosition { return this._r.value }
   set value(v: BlendPosition) { this._c.setLoopValue(this._r, v) }
+  /** Where the loop is in its cycle, 0–1 — one clock for every member (a blend cycles over its
+   *  weighted period). Set it to jump the cycle: `playLoop(def, { phase })` on the way in, or here
+   *  to re-sync with something else (a clip whose pose matches the cycle at that phase). */
+  get phase(): number { return this._c.loopPhase(this._r) }
+  set phase(v: number) { this._c.setLoopPhase(this._r, v) }
   /** Each member's current contribution, 0–1 (fades included). */
   get weights(): Record<string, number> {
     const out: Record<string, number> = {}

package/runtime/sdk/gl/animation/Playback.ts

@@ -21,13 +21,14 @@ export class Playback implements PromiseLike<boolean> {
   /** The layer it plays on. */
   get layer(): Layer { return this._r.slot.layer.view }
   /** Clock (s). */
-  get time(): number { return this._c.slotTime(this._r.slot) }
+  get time(): number { return this._r.slot.last === this._r ? this._c.slotTime(this._r.slot) : 0 }
   /** 0–1 through the clip (the current cycle, when looping). */
   get progress(): number { const d = this.clip.duration; return d > 0 ? this.time / d : 0 }
   /** Not handed over yet (the clip still owns the layer). */
   get playing(): boolean { return this._r.playing }
-  /** Current contribution to the pose, 0–1 — moves during crossfades. */
-  get weight(): number { return this._r.slot.playback === this._r ? this._c.slotWeight(this._r.slot) : 0 }
+  /** Current contribution to the pose, 0–1 — moves during crossfades, still falling after the
+   *  hand-over while the clip fades beneath what took over. */
+  get weight(): number { return this._r.slot.last === this._r ? this._c.slotWeight(this._r.slot) : 0 }
   /** Resolves at the hand-over (`true`) or when cut short (`false`) — the promise `await playback`
    *  uses; the one to return from async functions or put in `Promise.all`. */
   get done(): Promise<boolean> { return this._r.done }

package/runtime/sdk/gl/animation/core.ts

@@ -36,10 +36,25 @@ export type LoopOptions = {
   fade?: number
   /** Playback rate of the loop's clips (default 1). */
   speed?: number
+  /** Where in the cycle to start, 0–1 (default 0): a blend's members share one clock, so this is the
+   *  phase of every member — e.g. the phase whose pose matches the clip the loop takes over from. */
+  phase?: number
 }
 /** What a layer loops: one clip (name / index), or a blend space `{ name: position }`. */
 export type LoopDef = string | number | Record<string, BlendPosition>
 
+/** One clip the layer shows this frame — `layer.active` / `anim.active` (a debug overlay's list). */
+export type ActiveClip = {
+  name: string
+  clip: AnimationClip
+  /** contribution to the pose, 0–1 — the crossfades' state */
+  weight: number
+  /** clock (s) */
+  time: number
+  /** a member of the layer's loop (else a one-shot — playing, or fading after its hand-over) */
+  loop: boolean
+}
+
 export type LayerOptions = {
   /** Bone name(s): the layer drives only these subtrees (`'Spine1'` = upper body). Default: the whole rig. */
   mask?: string | string[]
@@ -54,9 +69,13 @@ export type ClipEventHandler = (clip: string, layer: Layer) => void
 
 // ---- records -------------------------------------------------------------------------------------
 
-export type SlotRec = { name: string, clip: AnimationClip, slot: number, layer: LayerRec, inBlend: boolean, playback?: PlaybackRec }
+/** One INSTANCE of a clip on a layer (an engine slot). A clip has as many as it needs at once: a
+ *  clip started again while its last instance still fades gets another slot — the old one keeps
+ *  fading beneath (a rewind in place would snap the pose). `playback` = the one-shot that owns it
+ *  until its hand-over; `last` = the one that took it most recently (its weight / time after that). */
+export type SlotRec = { name: string, clip: AnimationClip, slot: number, layer: LayerRec, inBlend: boolean, playback?: PlaybackRec, last?: PlaybackRec }
 export type PlaybackRec = { slot: SlotRec, playing: boolean, done: Promise<boolean>, resolve: (natural: boolean) => void }
-export type LayerRec = { index: number, view: Layer, slots: SlotRec[], byName: Map<string, SlotRec>, loop?: LoopRec, weight: number, mask: string, additive: boolean }
+export type LayerRec = { index: number, view: Layer, slots: SlotRec[], loop?: LoopRec, weight: number, mask: string, additive: boolean }
 export type LoopRec = { layer: LayerRec, members: { name: string, slot: SlotRec }[], value: BlendPosition, view: Loop, dead: boolean }
 
 const handlers = new Map<number, (slot: number, type: number) => void>()
@@ -145,12 +164,12 @@ export class Core {
   destroy(): void {
     for (const L of this.layers) for (const s of L.slots) if (s.playback) this.settle(s.playback, false)
     if (this.id) { _creator.animatorDestroy(this.id); handlers.delete(this.id); this.id = 0 }
-    for (const L of this.layers) { L.slots = []; L.byName.clear(); if (L.loop) { L.loop.dead = true; L.loop = undefined } }
+    for (const L of this.layers) { L.slots = []; if (L.loop) { L.loop.dead = true; L.loop = undefined } }
   }
 
   // ---- layers ----
   newLayer(options?: LayerOptions): LayerRec {
-    const rec: LayerRec = { index: this.layers.length, view: undefined as unknown as Layer, slots: [], byName: new Map(), weight: options?.weight ?? 1, mask: "", additive: options?.additive ?? false }
+    const rec: LayerRec = { index: this.layers.length, view: undefined as unknown as Layer, slots: [], weight: options?.weight ?? 1, mask: "", additive: options?.additive ?? false }
     if (options?.mask !== undefined) rec.mask = Array.isArray(options.mask) ? options.mask.join("\n") : options.mask
     rec.view = new Layer(rec, this)
     return rec
@@ -169,10 +188,11 @@ export class Core {
   }
 
   // ---- slots ----
-  /** Bind a clip on a layer (once per name). */
+  /** A slot for the clip on the layer: one of its own that is silent now (never shown, or faded
+   *  out), else a new binding — so a clip still fading can start again OVER itself. */
   slotFor(L: LayerRec, name: string, clip: AnimationClip): SlotRec | undefined {
-    const have = L.byName.get(name)
-    if (have && have.clip === clip) return have
+    const have = L.slots.find((s) => s.name === name && s.clip === clip && !s.inBlend && !s.playback && this.slotWeight(s) <= 0)
+    if (have) return have
     const slot = _creator.animatorBind(this.id, clip._set, clip._index, L.index)
     if (slot < 0) { console.warn(`Animator: could not bind clip '${name}'`); return undefined }
     const bound = _creator.animatorBoundTracks(this.id, slot)
@@ -180,7 +200,6 @@ export class Core {
     else if (bound < clip.trackCount) console.warn(`Animator: '${name}' — ${clip.trackCount - bound}/${clip.trackCount} tracks unbound (bone names not found)`)
     const rec: SlotRec = { name, clip, slot, layer: L, inBlend: false }
     L.slots.push(rec)
-    L.byName.set(name, rec)
     return rec
   }
 
@@ -203,7 +222,7 @@ export class Core {
     let resolve = (_n: boolean): void => {}
     const done = new Promise<boolean>((r) => { resolve = r })
     const rec: PlaybackRec = { slot: s, playing: true, done, resolve }
-    s.playback = rec
+    s.playback = rec; s.last = rec
     _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
     return new Playback(rec, this)
   }
@@ -255,8 +274,21 @@ export class Core {
     }
     L.loop = rec
     _creator.animatorSetBlend(this.id, L.index, is2D ? 2 : 1, new Uint16Array(slots), new Float32Array(positions), fade, o.speed ?? 1)
+    if (o.phase !== undefined) this.setLoopPhase(rec, o.phase)
     return rec.view
   }
+  /** The loop's phase through its cycle, 0–1 (the members share one clock). */
+  loopPhase(b: LoopRec): number {
+    const m = b.members[0]
+    if (!m || b.dead) return 0
+    const d = m.slot.clip.duration
+    return d > 0 ? this.slotTime(m.slot) / d : 0
+  }
+  setLoopPhase(b: LoopRec, phase: number): void {
+    const m = b.members[0]
+    if (!m || b.dead) return
+    this.seek(m.slot, (((phase % 1) + 1) % 1) * m.slot.clip.duration)   // seeking one member moves the group
+  }
   setLoopValue(b: LoopRec, v: BlendPosition): void {
     if (b.dead) { console.warn("Animator: this loop was replaced — use the object the latest playLoop() returned"); return }
     b.value = v
@@ -264,13 +296,23 @@ export class Core {
     const [x, y] = typeof v === "number" ? [ v, 0 ] : [ v[0], v[1] ]
     _creator.animatorSetBlendValue(this.id, b.layer.index, x, y)
   }
+  /** What the layer shows this frame: every instance with a weight, in binding order (stable rows). */
+  active(L: LayerRec): ActiveClip[] {
+    const out: ActiveClip[] = []
+    for (const s of L.slots) {
+      const weight = this.slotWeight(s)
+      if (weight <= 0) continue
+      out.push({ name: s.name, clip: s.clip, weight, time: this.slotTime(s), loop: s.inBlend })
+    }
+    return out
+  }
   slotWeight(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotWeight(this.id, s.slot) : 0 }
   slotTime(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotTime(this.id, s.slot) : 0 }
   seek(s: SlotRec, time: number): void { if (this.id && s.slot >= 0) _creator.animatorSeek(this.id, s.slot, time) }
 
   // ---- props ----
   setSpeed(v: number): void { this.speed = v; if (this.id) _creator.animatorSetGlobal(this.id, v, false) }
-  setRootMotion(on: boolean): void { if (this.ensure()) _creator.animatorSetRootMotion(this.id, on ? "*" : "", on ? 2 : 0) }
+  setRootMotion(on: boolean, rotation = false): void { if (this.ensure()) _creator.animatorSetRootMotion(this.id, on ? "*" : "", (on ? 2 : 0) | (on && rotation ? 4 : 0)) }
 
   // ---- events ----
   on(event: string, cb: ClipEventHandler): void { (this._listeners.get(event) ?? this._listeners.set(event, new Set()).get(event)!).add(cb) }

package/runtime/sdk/gl/terrainMesh.ts

@@ -0,0 +1,219 @@
+// The terrain grid as geometry, in TypeScript — used two ways (docs/terrain-plan.md §1.3, §3.5):
+//   • `heightAt` / `normalAt` — the SDK's own queries, identical on every host (bilinear on the SAME
+//     triangle split the engines draw and collide);
+//   • `buildTerrainChunk` — chunk meshes for hosts WITHOUT `_creator.terrainCreate` (web-lite, headless,
+//     a wasm/AAR/Apple build predating the feature): the same grid → chunk → triangles rule
+//     creator-gl/src/terrain.cpp applies (the i00–i11 diagonal, CCW seen from +Y, a triangle only when
+//     its three samples are valid), as plain Geometry for setMesh. Normals use central differences over
+//     the FULL grid (seamless chunks); the tangent frame is then the host's arbitrary one, so normal maps
+//     read wrong on those hosts — the accepted fallback cost.
+// Keep the hole / split rule in step with terrain.cpp buildChunk and Jolt's HeightFieldShape.
+
+import { Geometry } from "./Geometry"
+
+export type TerrainGrid = {
+  sizeX: number
+  sizeZ: number
+  cellSize: number
+  /** sizeX × sizeZ heights, row-major (z rows). */
+  heights: Float32Array
+  /** One byte per sample, 1 = hole; null = no holes. */
+  holes: Uint8Array | null
+}
+
+const clampI = (v: number, hi: number): number => (v < 0 ? 0 : v > hi ? hi : v)
+
+/** The sample at integer (x, z), clamped to the grid. */
+export const sampleAt = (g: TerrainGrid, x: number, z: number): number =>
+  g.heights[clampI(z, g.sizeZ - 1) * g.sizeX + clampI(x, g.sizeX - 1)]
+
+export const isHole = (g: TerrainGrid, x: number, z: number): boolean =>
+  g.holes !== null && g.holes[z * g.sizeX + x] !== 0
+
+/** Surface normal at a sample from central differences (one-sided at the borders). Writes `out` (xyz). */
+export const normalAt = (g: TerrainGrid, x: number, z: number, out: Float32Array | number[] = [ 0, 0, 0 ]): typeof out => {
+  const x0 = x > 0 ? x - 1 : x, x1 = x + 1 < g.sizeX ? x + 1 : x
+  const z0 = z > 0 ? z - 1 : z, z1 = z + 1 < g.sizeZ ? z + 1 : z
+  const dx = (sampleAt(g, x1, z) - sampleAt(g, x0, z)) / ((x1 - x0) * g.cellSize)
+  const dz = (sampleAt(g, x, z1) - sampleAt(g, x, z0)) / ((z1 - z0) * g.cellSize)
+  const len = Math.hypot(dx, 1, dz)
+  out[0] = -dx / len; out[1] = 1 / len; out[2] = -dz / len
+  return out
+}
+
+/**
+ * Height at a LOCAL (x, z) in metres, interpolated on the drawn triangles (the i00–i11 diagonal), so a
+ * character's feet and a raycast agree with what is rendered to the millimetre. NaN inside a hole
+ * triangle or outside the grid.
+ */
+export const heightAt = (g: TerrainGrid, x: number, z: number): number => {
+  const fx = x / g.cellSize, fz = z / g.cellSize
+  if (!(fx >= 0 && fz >= 0 && fx <= g.sizeX - 1 && fz <= g.sizeZ - 1)) return NaN
+  let ix = Math.floor(fx), iz = Math.floor(fz)
+  if (ix >= g.sizeX - 1) ix = g.sizeX - 2
+  if (iz >= g.sizeZ - 1) iz = g.sizeZ - 2
+  const u = fx - ix, v = fz - iz
+  const i00 = iz * g.sizeX + ix
+  const h00 = g.heights[i00], h10 = g.heights[i00 + 1], h01 = g.heights[i00 + g.sizeX], h11 = g.heights[i00 + g.sizeX + 1]
+  if (g.holes !== null) {
+    const holes = g.holes
+    if (holes[i00] || holes[i00 + g.sizeX + 1]) return NaN
+    // lower-left triangle (i00, i01, i11) when v >= u, else upper-right (i00, i11, i10)
+    if (v >= u ? holes[i00 + g.sizeX] !== 0 : holes[i00 + 1] !== 0) return NaN
+  }
+  // plane of the triangle the point falls in
+  return v >= u
+    ? h00 + (h11 - h01) * u + (h01 - h00) * v
+    : h00 + (h10 - h00) * u + (h11 - h10) * v
+}
+
+/** The geometric normal at a LOCAL (x, z): the drawn triangle's normal (not the smoothed vertex one). */
+export const faceNormalAt = (g: TerrainGrid, x: number, z: number, out: Float32Array | number[] = [ 0, 0, 0 ]): typeof out => {
+  const fx = x / g.cellSize, fz = z / g.cellSize
+  let ix = Math.floor(fx), iz = Math.floor(fz)
+  ix = clampI(ix, g.sizeX - 2); iz = clampI(iz, g.sizeZ - 2)
+  const u = fx - ix, v = fz - iz
+  const i00 = iz * g.sizeX + ix
+  const h00 = g.heights[i00], h10 = g.heights[i00 + 1], h01 = g.heights[i00 + g.sizeX], h11 = g.heights[i00 + g.sizeX + 1]
+  const c = g.cellSize
+  // gradients of the two planes (see heightAt)
+  const dx = (v >= u ? h11 - h01 : h10 - h00) / c
+  const dz = (v >= u ? h01 - h00 : h11 - h10) / c
+  const len = Math.hypot(dx, 1, dz)
+  out[0] = -dx / len; out[1] = 1 / len; out[2] = -dz / len
+  return out
+}
+
+/** Chunks along X and Z for a grid: a chunk covers `chunk` cells (chunk + 1 samples). */
+export const chunkCounts = (g: TerrainGrid, chunk: number): [number, number] =>
+  [ Math.floor((g.sizeX - 2) / chunk) + 1, Math.floor((g.sizeZ - 2) / chunk) + 1 ]
+
+/**
+ * One chunk as a Geometry (positions, smooth normals, UV0 = local XZ metres, UV1 = the terrain's unit
+ * square, u16 indices), or null when every cell of it is a hole.
+ */
+export const buildTerrainChunk = (g: TerrainGrid, cx: number, cz: number, chunk: number): Geometry | null => {
+  const x0 = cx * chunk, z0 = cz * chunk
+  const x1 = Math.min(x0 + chunk, g.sizeX - 1), z1 = Math.min(z0 + chunk, g.sizeZ - 1)
+  const nx = x1 - x0 + 1, nz = z1 - z0 + 1
+  const idx: number[] = []
+  for (let z = z0; z < z1; z++) {
+    for (let x = x0; x < x1; x++) {
+      const i00 = (z - z0) * nx + (x - x0), i10 = i00 + 1, i01 = i00 + nx, i11 = i01 + 1
+      const v00 = !isHole(g, x, z), v10 = !isHole(g, x + 1, z), v01 = !isHole(g, x, z + 1), v11 = !isHole(g, x + 1, z + 1)
+      if (!(v00 && v11)) continue
+      if (v01) idx.push(i00, i01, i11)
+      if (v10) idx.push(i00, i11, i10)
+    }
+  }
+  if (idx.length === 0) return null
+  const count = nx * nz
+  const vertices = new Float32Array(count * 3)
+  const normals = new Float32Array(count * 3)
+  const uv = new Float32Array(count * 2)
+  const uv1 = new Float32Array(count * 2)
+  const n = [ 0, 0, 0 ]
+  const invX = 1 / (g.sizeX - 1), invZ = 1 / (g.sizeZ - 1)
+  for (let z = z0; z <= z1; z++) {
+    for (let x = x0; x <= x1; x++) {
+      const i = (z - z0) * nx + (x - x0)
+      vertices[i * 3] = x * g.cellSize
+      vertices[i * 3 + 1] = g.heights[z * g.sizeX + x]
+      vertices[i * 3 + 2] = z * g.cellSize
+      normalAt(g, x, z, n)
+      normals[i * 3] = n[0]; normals[i * 3 + 1] = n[1]; normals[i * 3 + 2] = n[2]
+      uv[i * 2] = x * g.cellSize; uv[i * 2 + 1] = z * g.cellSize
+      uv1[i * 2] = x * invX; uv1[i * 2 + 1] = z * invZ
+    }
+  }
+  const geom = new Geometry(vertices, normals, Uint16Array.from(idx), uv)
+  geom.uv1 = uv1
+  return geom
+}
+
+// ---- ray queries ---------------------------------------------------------------------------------
+
+export type GridHit = { x: number, y: number, z: number, distance: number, nx: number, ny: number, nz: number }
+
+/** Möller–Trumbore against one triangle; the distance along the ray, or -1. */
+const rayTriangle = (
+  ox: number, oy: number, oz: number, dx: number, dy: number, dz: number,
+  ax: number, ay: number, az: number, bx: number, by: number, bz: number, qx: number, qy: number, qz: number,
+): number => {
+  const e1x = bx - ax, e1y = by - ay, e1z = bz - az
+  const e2x = qx - ax, e2y = qy - ay, e2z = qz - az
+  const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x
+  const det = e1x * px + e1y * py + e1z * pz
+  if (Math.abs(det) < 1e-12) return -1
+  const inv = 1 / det
+  const tx = ox - ax, ty = oy - ay, tz = oz - az
+  const u = (tx * px + ty * py + tz * pz) * inv
+  if (u < -1e-6 || u > 1 + 1e-6) return -1
+  const qxx = ty * e1z - tz * e1y, qyy = tz * e1x - tx * e1z, qzz = tx * e1y - ty * e1x
+  const v = (dx * qxx + dy * qyy + dz * qzz) * inv
+  if (v < -1e-6 || u + v > 1 + 1e-6) return -1
+  const t = (e2x * qxx + e2y * qyy + e2z * qzz) * inv
+  return t >= 0 ? t : -1
+}
+
+/**
+ * Nearest hit of a LOCAL ray (origin + direction, metres) on the drawn triangles — the same
+ * i00–i11 split and hole rule as `heightAt`, so a pick lands on what is rendered. Walks the cells
+ * the ray crosses (2D DDA on XZ), testing each cell's two triangles; holes let the ray through.
+ * Null when it misses (or never enters the grid within `maxDistance`).
+ */
+export const gridRaycast = (g: TerrainGrid, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance = 1e5): GridHit | null => {
+  const c = g.cellSize, W = (g.sizeX - 1) * c, D = (g.sizeZ - 1) * c
+  let t0 = 0, t1 = maxDistance
+  const clip = (o: number, d: number, hi: number): boolean => {
+    if (Math.abs(d) < 1e-12) return o >= 0 && o <= hi
+    let a = -o / d, b = (hi - o) / d
+    if (a > b) { const s = a; a = b; b = s }
+    if (a > t0) t0 = a
+    if (b < t1) t1 = b
+    return t0 <= t1
+  }
+  if (!clip(ox, dx, W) || !clip(oz, dz, D)) return null
+  const sx = ox + dx * t0, sz = oz + dz * t0
+  let ix = Math.min(g.sizeX - 2, Math.max(0, Math.floor(sx / c)))
+  let iz = Math.min(g.sizeZ - 2, Math.max(0, Math.floor(sz / c)))
+  const stepX = dx > 1e-12 ? 1 : dx < -1e-12 ? -1 : 0
+  const stepZ = dz > 1e-12 ? 1 : dz < -1e-12 ? -1 : 0
+  const tDeltaX = stepX ? Math.abs(c / dx) : Infinity, tDeltaZ = stepZ ? Math.abs(c / dz) : Infinity
+  let tMaxX = stepX > 0 ? t0 + ((ix + 1) * c - sx) / dx : stepX < 0 ? t0 + (ix * c - sx) / dx : Infinity
+  let tMaxZ = stepZ > 0 ? t0 + ((iz + 1) * c - sz) / dz : stepZ < 0 ? t0 + (iz * c - sz) / dz : Infinity
+  const holes = g.holes
+  let t = t0
+  for (let guard = 0; guard < g.sizeX + g.sizeZ + 2 && t <= t1 + 1e-9; guard++) {
+    const i00 = iz * g.sizeX + ix, i10 = i00 + 1, i01 = i00 + g.sizeX, i11 = i01 + 1
+    const x0 = ix * c, x1 = x0 + c, z0 = iz * c, z1 = z0 + c
+    const h00 = g.heights[i00], h10 = g.heights[i10], h01 = g.heights[i01], h11 = g.heights[i11]
+    const ok00 = !holes || holes[i00] === 0, ok11 = !holes || holes[i11] === 0
+    let best = -1, tri = 0
+    if (ok00 && ok11) {
+      // lower-left (i00, i01, i11) and upper-right (i00, i11, i10) — both CCW seen from +Y
+      if (!holes || holes[i01] === 0) {
+        const d = rayTriangle(ox, oy, oz, dx, dy, dz, x0, h00, z0, x0, h01, z1, x1, h11, z1)
+        if (d >= 0 && (best < 0 || d < best)) { best = d; tri = 0 }
+      }
+      if (!holes || holes[i10] === 0) {
+        const d = rayTriangle(ox, oy, oz, dx, dy, dz, x0, h00, z0, x1, h11, z1, x1, h10, z0)
+        if (d >= 0 && (best < 0 || d < best)) { best = d; tri = 1 }
+      }
+    }
+    if (best >= 0 && best <= t1 + 1e-6) {
+      // the hit triangle's normal
+      let ax: number, ay: number, az: number, bx: number, by: number, bz: number
+      if (tri === 0) { ax = 0; ay = h01 - h00; az = c; bx = c; by = h11 - h00; bz = c }
+      else { ax = c; ay = h11 - h00; az = c; bx = c; by = h10 - h00; bz = 0 }
+      let nx = ay * bz - az * by, ny = az * bx - ax * bz, nz = ax * by - ay * bx
+      const l = Math.hypot(nx, ny, nz) || 1
+      nx /= l; ny /= l; nz /= l
+      return { x: ox + dx * best, y: oy + dy * best, z: oz + dz * best, distance: best, nx, ny, nz }
+    }
+    if (tMaxX < tMaxZ) { t = tMaxX; ix += stepX; tMaxX += tDeltaX }
+    else { t = tMaxZ; iz += stepZ; tMaxZ += tDeltaZ }
+    if (ix < 0 || iz < 0 || ix > g.sizeX - 2 || iz > g.sizeZ - 2) break
+  }
+  return null
+}

package/runtime/sdk/inject.ts

@@ -18,6 +18,7 @@ export { Color } from "./core/color"
 export { Aspect, System, type With, type SystemHost } from "./core/Aspect"
 export { type EventMap } from "./core/events"
 export { Time } from "./core/time"
+export { StateMachine, defineStates, type StateDef, type StatesDef, type StateGuard, type StateHandler, type StateMachineEvents } from "./core/StateMachine"
 export { InspectorUI } from "./core/InspectorUI"
 
 // ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
@@ -37,6 +38,8 @@ export { localStorage } from "./runtime/storage"
 export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
 export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
+// Multiplayer (docs/multiplayer-plan.md): roles, players, JSON messages over the _creatorNet transport.
+export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform } from "./net"
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
 // only ever imports its server functions (docs/backend-plan.md §4).
 export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
@@ -161,6 +164,8 @@ export { CharacterController } from "./gl/CharacterController"
 export { Vehicle } from "./gl/Vehicle"
 export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle"
 export { Wheel } from "./gl/Wheel"
+export { Ragdoll } from "./gl/Ragdoll"
+export type { RagdollPart, RagdollHinge } from "./gl/Ragdoll"
 export type { TireCurve, WheelSuspension, WheelTire, WheelVisual } from "./gl/Wheel"
 export { Gearbox } from "./gl/Gearbox"
 export { AnimationClip } from "./gl/animation/AnimationClip"
@@ -169,11 +174,17 @@ export { Animator } from "./gl/animation/Animator"
 export { Playback } from "./gl/animation/Playback"
 export { Loop } from "./gl/animation/Loop"
 export { Layer } from "./gl/animation/Layer"
-export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition } from "./gl/animation/core"
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, ActiveClip } from "./gl/animation/core"
 export { IK } from "./gl/IK"
 export type { IKTwoBone, IKLookAt } from "./gl/IK"
 export { Light } from "./gl/Light"
 export { Lightmap } from "./gl/Lightmap"
+export { Terrain } from "./gl/Terrain"
+export type { TerrainOptions, TerrainLayer, TerrainRegion, ConformOptions, RibbonOptions, AutoPaintRules, SculptOptions, TerrainHit, TerrainSnapshot } from "./gl/Terrain"
+export { NavMesh, NavCrowd } from "./gl/NavMesh"
+export type { NavMeshLoadOptions, NavMeshInfo, NavPath, NavQueryOptions, NavRaycastHit, NavAgentSize } from "./gl/NavMesh"
+export { NavAgent } from "./gl/NavAgent"
+export type { NavAgentState, NavAgentAvoidance, NavAgentDrive, NavAgentEvents } from "./gl/NavAgent"
 export { Material } from "./gl/Material"
 export { Geometry } from "./gl/Geometry"
 export { InstancedMesh } from "./gl/InstancedMesh"

package/runtime/sdk/net/codec.ts

@@ -0,0 +1,119 @@
+// Defaults → wire layout (docs/multiplayer-plan.md §4 "input: defaults object = layout"). The hot
+// stream — inputs and snapshot states — is binary and its shape comes from a plain defaults object:
+//   number    → f32
+//   boolean   → 1 bit (packed after the floats)
+//   number[]  → f32 × length, fixed
+// Nothing else: no strings, no nesting, no optionals — snapshot fields are flat and fixed-size by
+// design. Both sides run the same bundle, so the layout is derived, never transmitted; the `sig`
+// feeds the schema hash the handshake compares.
+
+export type FieldKind = 0 | 1 | 2   // f32 · bool · f32[]
+export type Field = { key: string; kind: FieldKind; len: number }
+export type Layout = { fields: Field[]; floats: number; bools: number; bytes: number; sig: string }
+
+const describe = (v: unknown): string => Array.isArray(v) ? `array of ${v.length}` : v === null ? "null" : typeof v
+
+export const makeLayout = (defaults: Record<string, unknown>, what: string): Layout => {
+  const fields: Field[] = []
+  let floats = 0
+  let bools = 0
+  for (const key of Object.keys(defaults)) {
+    const v = defaults[key]
+    if (typeof v === "number") { fields.push({ key, kind: 0, len: 1 }); floats++ }
+    else if (typeof v === "boolean") { fields.push({ key, kind: 1, len: 1 }); bools++ }
+    else if (Array.isArray(v) && v.length > 0 && v.length <= 64 && v.every((n) => typeof n === "number")) {
+      fields.push({ key, kind: 2, len: v.length }); floats += v.length
+    } else {
+      throw new Error(`${what}: field '${key}' must be a number, a boolean or a fixed-length number[] (got ${describe(v)})`)
+    }
+  }
+  const sig = fields.map((f) => `${f.key}:${f.kind}${f.len > 1 ? f.len : ""}`).join(",")
+  return { fields, floats, bools, bytes: floats * 4 + Math.ceil(bools / 8), sig }
+}
+
+/** A fresh state object shaped like the defaults (arrays copied, never shared). */
+export const cloneDefaults = <T extends object>(defaults: T): T => {
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(defaults)) {
+    const v = (defaults as Record<string, unknown>)[key]
+    out[key] = Array.isArray(v) ? v.slice() : v
+  }
+  return out as T
+}
+
+/** Copy the layout's fields from `from` into `into` (array elements copied in place; unknown keys
+ *  ignored — a JSON spawn state or a partial `setInput`). */
+export const assignState = (layout: Layout, into: any, from: any): void => {
+  if (!from) return
+  for (const f of layout.fields) {
+    const v = from[f.key]
+    if (v === undefined) continue
+    if (f.kind === 2) {
+      const a = into[f.key] as number[]
+      for (let i = 0; i < f.len; i++) a[i] = +(v[i] ?? 0)
+    } else if (f.kind === 1) into[f.key] = !!v
+    else into[f.key] = +v
+  }
+}
+
+export const packInto = (view: DataView, offset: number, layout: Layout, s: any): number => {
+  let o = offset
+  for (const f of layout.fields) {
+    if (f.kind === 0) { view.setFloat32(o, s[f.key], true); o += 4 }
+    else if (f.kind === 2) {
+      const a = s[f.key] as number[]
+      for (let i = 0; i < f.len; i++) { view.setFloat32(o, a[i] ?? 0, true); o += 4 }
+    }
+  }
+  let bits = 0
+  let n = 0
+  for (const f of layout.fields) {
+    if (f.kind !== 1) continue
+    if (s[f.key]) bits |= 1 << (n & 7)
+    n++
+    if ((n & 7) === 0) { view.setUint8(o++, bits); bits = 0 }
+  }
+  if (n & 7) view.setUint8(o++, bits)
+  return o
+}
+
+export const unpackFrom = (view: DataView, offset: number, layout: Layout, into: any): number => {
+  let o = offset
+  for (const f of layout.fields) {
+    if (f.kind === 0) { into[f.key] = view.getFloat32(o, true); o += 4 }
+    else if (f.kind === 2) {
+      const a = into[f.key] as number[]
+      for (let i = 0; i < f.len; i++) { a[i] = view.getFloat32(o, true); o += 4 }
+    }
+  }
+  let bits = 0
+  let n = 0
+  for (const f of layout.fields) {
+    if (f.kind !== 1) continue
+    if ((n & 7) === 0) bits = view.getUint8(o++)
+    into[f.key] = (bits & (1 << (n & 7))) !== 0
+    n++
+  }
+  return o
+}
+
+/** `out = a + (b − a) · t` for the numeric fields; booleans take `b`'s. */
+export const lerpState = (layout: Layout, a: any, b: any, t: number, out: any): void => {
+  for (const f of layout.fields) {
+    if (f.kind === 0) out[f.key] = a[f.key] + (b[f.key] - a[f.key]) * t
+    else if (f.kind === 2) {
+      const pa = a[f.key] as number[], pb = b[f.key] as number[], po = out[f.key] as number[]
+      for (let i = 0; i < f.len; i++) po[i] = pa[i] + (pb[i] - pa[i]) * t
+    } else out[f.key] = b[f.key]
+  }
+}
+
+/** FNV-1a over a string → 8 hex chars. Enough to tell two bundles' schemas apart. */
+export const hashString = (s: string): string => {
+  let h = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(16).padStart(8, "0")
+}