lecodes-cli 0.18.2 → 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/Trigger.ts

@@ -1,45 +1,45 @@
-// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
-// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
-// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
-//
-//   const goal = new Mesh(box(), material)
-//     .aspect(Shape, { box: [1, 2, 1] })
-//     .aspect(Trigger)
-//   goal.addEventListener('enter', other => win(other))
-//   goal.addEventListener('exit',  other => …)
-
-import { Aspect } from "../core/Aspect"
-import { Shape } from "./Shape"
-import { ensurePhysicsEvents } from "./physicsEvents"
-import type { Node } from "./Node"
-
-export class Trigger extends Aspect<"trigger", Node> {
-  static readonly aspect = "trigger"
-
-  private _bodyId = 0
-  /** Native body id (0 if no physics support). */
-  get id(): number { return this._bodyId }
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
-    if (!shape) {
-      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
-    }
-    const shapeId = shape._claim()
-    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
-    shape._ownBody(this._bodyId)
-    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
-  }
-
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    const shape = this.node.get(Shape)
-    if (shape) {
-      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
-      shape._recreatePickBody()
-    }
-  }
-
-  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
-}
+// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
+//
+//   const goal = new Mesh(box(), material)
+//     .aspect(Shape, { box: [1, 2, 1] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => …)
+
+import { Aspect } from "../core/Aspect"
+import { Shape } from "./Shape"
+import { ensurePhysicsEvents } from "./physicsEvents"
+import type { Node } from "./Node"
+
+export class Trigger extends Aspect<"trigger", Node> {
+  static readonly aspect = "trigger"
+
+  private _bodyId = 0
+  /** Native body id (0 if no physics support). */
+  get id(): number { return this._bodyId }
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    const shapeId = shape._claim()
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
+    shape._ownBody(this._bodyId)
+    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()
+    }
+  }
+
+  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
+}

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) }