lecodes-sdk 0.19.2 → 0.20.0

package/src/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/src/gl/animation/Animator.ts

@@ -1,329 +1,137 @@
-// Animator — THE animation system, reached as `node.anim`. Every Model carries one pre-attached (its
-// clip list = the GLB's embedded clips; nothing native exists until the first play()). The whole
-// per-frame loop — transitions, blend spaces, one-shot hand-over, root motion — runs in the engine;
-// the SDK only issues calls. See docs/animation-v2-plan.md.
-//
-// A layer shows ONE source at a time (its one-shot, its loop, or nothing) and every switch is an
-// INERTIALIZED transition: the pose the layer showed does not fade away, its difference to the new
-// source decays over `fade` (default 0.2 s; `fade: 0` = cut). Nothing stacks, so a clip may be
-// replaced however far along it is, as often as you like — a planted foot the two clips share stays
-// planted through the transition.
-//
-//   const hero = await Model.load(asset('./hero.glb'))
-//   hero.anim.playLoop('Idle')                             // the layer's LOOP: what it rests on
-//   await hero.anim.play('Jump', { fadeIn: 0.1, fadeOut: 0.2 })   // a one-shot over it, back to the loop after
-//
-//   hero.anim.addClip('slash', slash)                      // clips from other files / procedural / sliced
-//   const loco = hero.anim.playLoop({ Idle: 0, Walking: 2, 'Fast Run': 6 })   // a blend as the loop
-//   loco.value = hero.controller.velocity.length           // where we are on the blend axis
-//   const kick = hero.anim.play('slash', { fadeIn: 0.1, fadeOut: 0.3 })   // resolves at its hand-over
-//   kick.clip.addEvent(0.4, 'hit'); hero.anim.on('hit', () => …)
-//   if (await kick) hero.anim.playLoop('Crouch', { fade: 0.3 })   // resolved at the hand-over: what you start now is what it fades into
-//   const upper = hero.anim.addLayer({ mask: 'Spine1' })
-//   upper.playLoop('Aim', { fade: 0.3 })                   // arms aim, legs keep walking
-//
-// Any Node hierarchy works, not just Models: tracks bind to child names (a robot arm of meshes).
-
-import { Aspect } from "../../core/Aspect"
-import { Vec3 } from "../../math/vec"
-import type { Node } from "../Node"
-import type { AnimationClip } from "./AnimationClip"
-import { Core, type ActiveClip, type ClipCurves, type ClipEventHandler, type KneeAxisReport, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StepHandler, 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)
-}
-
-/** What `Animator.warp` turns on. Speeds are m/s, angles degrees, distances metres. */
-export type WarpOptions = {
-  /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale
-   *  (default 0.85…1.2). It is a CORRECTION: a pack whose takes already read right at the speeds it
-   *  is played at wants none of this, and a wide range only lets the legs be stretched into shapes
-   *  nobody recorded. Open it for a pack that must cover speeds it was never recorded at. */
-  stride?: boolean | [number, number]
-  /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
-   *  (default 20). The spine counter-turns, so the chest keeps facing where it faced — the whole twist
-   *  lives in one joint, which is why a few degrees read as a lean and a lot reads as a broken back.
-   *  Only applied while the gait LOOP shows: a start, a turn or a stop walks a path of its own. */
-  orientation?: boolean | number
-  /** Below this speed — the game's or the clip's — both warps are off (default 0.2). */
-  minSpeed?: number
-  /** How far the pelvis may drop to keep a stretched leg from locking straight (default 0.25). */
-  pelvis?: number
-  /** The stride scale's own spring, seconds (default 0.15). The body's speed is continuous but the
-   *  shown clip's recorded one steps at every switch, so the scale is smoothed rather than followed. */
-  strideTime?: number
-}
-
-const WARP = { STRIDE: 0, STRIDE_MIN: 1, STRIDE_MAX: 2, ORIENT: 3, ORIENT_MAX: 4, ORIENT_TIME: 5, MIN_SPEED: 6, PELVIS: 7, STRIDE_TIME: 8, COUNT: 9 }
-
-/** What `Animator.feet` sets: which bones the feet are, and what the engine does with them. Distances
- *  are metres, times seconds. Every key is optional and only the keys given change — set the bones
- *  once, switch the lock on somewhere else. */
-export type FeetOptions = {
-  /** The contact bones per side — `'LeftFoot'`, or with a toe / ball `['LeftFoot', 'LeftToeBase']`.
-   *  Default: classified from the bone names (Mixamo / Unity / Blender / UE). Set them for a rig the
-   *  classifier misses; it re-bakes every clip's contacts and phase. */
-  left?: string | string[]
-  right?: string | string[]
-  /** FOOT LOCK: a foot the shown clip calls planted (its baked contacts, else a runtime detector) is
-   *  pinned where it landed — heel to ball, rolling as the clip rolls — and the leg re-solved to keep it
-   *  there while the body moves on. What hides the last of a transition's slide: the pose the new clip
-   *  starts from is not the one the old clip ended in, and the difference used to be dragged out of
-   *  the standing foot over the blend. Off by default; a `Locomotion` turns it on. */
-  lock?: boolean
-  /** GROUND IK: each foot is put on the ground the engine probes under it (stairs, a slope, a kerb),
-   *  aligned to its normal, and the pelvis lowered so the lower leg can reach — the feet stop hanging
-   *  in the air on a step down and sinking into a step up. Needs a physics world to probe; without
-   *  one the ground is the node's own plane. Off by default. */
-  ik?: boolean
-  /** How far the pelvis may drop for the ground (default 0.35). */
-  pelvis?: number
-  /** The anchor's leash: a locked foot never absorbs more residual than this — beyond it the anchor
-   *  follows the animation instead of fighting it (default 0.10). */
-  unlockDistance?: number
-  /** The lock's ease in / out, seconds (default 0.08 / 0.12). */
-  lockIn?: number
-  lockOut?: number
-  /** 0..1: how much the foot tilts onto the ground normal (default 1). */
-  align?: number
-  /** The probe ray's reach above and below the ankle (default 0.6) — a step taller than this is a
-   *  hole to the probe. */
-  probe?: number
-  /** The lock plants only once the animated ankle moves slower than this, m/s (default 0.2: a foot
-   *  the take itself holds still). Raise it to pin a foot a transition is still dragging — a run
-   *  entered from standing lands its first foot while the offset from the idle still decays. */
-  plantSpeed?: number
-}
-
-/** One foot after this frame's evaluation (`Animator.foot`): whether the lock holds it, the lock's
- *  weight (eased 0…1), where it was pinned and where the leg was asked to put the ankle — all world. */
-export type FootState = { locked: boolean, weight: number, anchor: Vec3, target: Vec3 }
-
-const FEET = { IK: 0, LOCK: 1, PELVIS: 2, UNLOCK_DIST: 3, LOCK_IN: 4, LOCK_OUT: 5, PELVIS_TIME: 6, ALIGN: 7, PROBE: 8, DETECT_SPEED: 9, DETECT_HEIGHT: 10, PLANT_SPEED: 11, COUNT: 12 }
-const footBuf = new Float32Array(8)
-
-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() }
-
-  // ---- clips ----
-  /** The clip list, in order: the GLB's embedded clips (file order), then the clips you added. An
-   *  added clip with an embedded clip's name takes its place. */
-  get clips(): readonly AnimationClip[] { return this._c.clips() }
-  /** One clip by name, or by index into `clips` — e.g. to `slice()` it. `undefined` if there is none. */
-  clip(ref: string | number): AnimationClip | undefined { return this._c.resolveClip(ref)?.[1] }
-  /** Add a clip under a name (default: its own `name`) — from another file, procedural, or sliced.
-   *  Overrides an embedded clip of the same name. Chainable. */
-  addClip(name: string | AnimationClip, clip?: AnimationClip): this {
-    const c = typeof name === "string" ? clip : name
-    const n = typeof name === "string" ? name : name.name
-    if (!c) { console.warn(`Animator.addClip('${n}'): no clip`); return this }
-    this._c.addClip(n, c)
-    return this
-  }
-
-  // ---- playing (the base layer) ----
-  /** Play a one-shot on the base layer — by name, index, or the first clip with no argument. It
-   *  takes the layer over from whatever it showed, transitioned over `fade` (default 0.2 s).
-   *  Returns a Playback: `await` it — it resolves at the clip's hand-over (`true`; `false` if cut
-   *  short), and what you start right after is what the clip hands the layer to (another one-shot,
-   *  `playLoop(next)`; nothing = back to the loop). */
-  play(clip?: string | number, options: PlayOptions = {}): Playback { return this._c.play(this._c.layers[0], clip, options) }
-  /** Set the base layer's LOOP — what it shows when no one-shot plays: a clip (`playLoop('Idle')`) or
-   *  a blend space (`playLoop({ Idle: 0, Run: 6 })`, drive the returned object's `value`). Takes the
-   *  layer over from whatever plays — a one-shot included (it is cut short) — transitioned over
-   *  `fade`. `stop()` removes it. */
-  playLoop(def: LoopDef, options: LoopOptions = {}): Loop | undefined { return this._c.loop(this._c.layers[0], def, options) }
-  /** Fade everything out, on every layer (loops included) → rest pose. */
-  stop(options: StopOptions = {}): this { this._c.stopAll(options.fade ?? 0); return this }
-  /** The base layer's current loop (the object the last `playLoop()` returned), if any. */
-  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]) }
-  /** What every layer shows this frame with its weight: one one-shot, or a loop's members with their
-   *  blend shares (a debug overlay's list). */
-  get active(): ActiveClip[] { return this._c.layers.flatMap((L) => this._c.active(L)) }
-
-  /** Where the base layer is in the GAIT CYCLE: 0 at a left-foot-down, 0.5 at a right-foot-down,
-   *  whether a loop or a one-shot shows it. -1 when what plays has no cycle (an idle, a hit reaction).
-   *  This is the number `play(clip, { phase: 'match' })` matches against. */
-  get phase(): number { return this._c.layerPhase(this._c.layers[0]) }
-
-  /** The native animator's id — 0 until something is played or bound. Engine-facing code only. */
-  get _id(): number { return this._c.id }
-  /** Bind a clip to the base layer without playing it and return its native slot (-1 = no such clip);
-   *  creates the native animator on first use. What a Locomotion registers its set with. */
-  _slot(clip: string | number): number { return this._c.slotIndex(clip) }
-
-  /** What the engine measured on a clip once it was bound to this skeleton: foot contacts, the gait
-   *  phase φ(t), and the root's travel / yaw / speed — a controller reads these instead of shipping
-   *  measured tables. Binds the clip on first ask. `undefined` if there is no such clip. */
-  curves(clip: string | number): ClipCurves | undefined { return this._c.curves(clip) }
-
-  /** The skeleton's calibrated KNEE HINGE AXIS for a side (thigh-local, unit) with its confidence
-   *  report — measured once over every bound clip's knee rotation track; the ground truth
-   *  `curves(clip).kneePoleAt` predicts bend planes from. Undefined = no leg chain, or no knee
-   *  motion bound to calibrate from. */
-  kneeAxis(side: "left" | "right"): KneeAxisReport | undefined { return this._c.kneeAxis(side) }
-
-  /** STEP WARP v2 knobs (the warp rewrite): `stride` scales each foot's travel-direction offset
-   *  from its hip (the step shortens / lengthens), `lift` = metres ADDED to its height
-   *  (swing-gated; 0 = neutral, negative = a shuffle; half of what it adds raises the pelvis —
-   *  the body steps higher with the foot), `pitch` (degrees, + = toes up) rotates each foot about
-   *  its lateral axis, `slope` (degrees, + = ascending) the invisible staircase — feet on the
-   *  incline + auto pitch; raise the character by tan(slope) × the stride-scaled clip travel to
-   *  hold each planted foot on its tread. Solved in the calibrated knee hinge plane.
-   *  Omit / null = off. A tuning bench's dial — locomotion will drive this itself later. */
-  setStepWarp(options?: { stride?: number, lift?: number, pitch?: number, slope?: number } | null): void { this._c.setStepWarp(options) }
-
-  /** Scrub: set `clip`'s playhead directly, seconds — for inspectors and debug boards (pair with
-   *  `speed = 0`). The clip should be the one showing; nothing is faded or re-picked. */
-  seek(clip: string | number, time: number): void { this._c.seekTime(clip, time) }
-  /** `clip`'s current playhead, seconds (-1 = not bound). */
-  time(clip: string | number): number { return this._c.timeOf(clip) }
-  /** Re-aim a playing turn clip's warp (`play({ turn })`) to `deg` for the whole clip — the scale lands on what is
-   *  still to come; `undefined` = off. */
-  setTurn(clip: string | number, deg: number | undefined): void { this._c.setTurnOf(clip, deg) }
-
-  /** THE FEET (docs/animation-v2-plan.md §2.9): which bones they are, and what the engine does with
-   *  them after the clips are composited — the foot LOCK (a planted foot stays where it landed while the
-   *  body moves on) and GROUND IK (each foot on the ground probed under it, the pelvis lowered). Only
-   *  the keys given change, so the bones and the behaviour can be set from different places:
-   *
-   *      model.anim.feet = { left: 'LeftFoot', right: 'RightFoot' }   // a rig the classifier misses
-   *      model.anim.feet = { lock: true }                              // (a Locomotion does this itself)
-   *      model.anim.feet = { lock: true, ik: true, pelvis: 0.3 }       // stairs and slopes
-   *
-   *  The engine probes the ground itself (against what a character can stand on) and reads the
-   *  CharacterController's ground state; nothing is fed per frame. See `FeetOptions`. */
-  set feet(f: FeetOptions) {
-    const o = this._feetOpts
-    Object.assign(o, f)
-    if (f.left !== undefined || f.right !== undefined) {
-      const join = (v: string | string[] | undefined): string => v === undefined ? "" : Array.isArray(v) ? v.join("\n") : v
-      this._c.setFeet(join(o.left), join(o.right))
-    }
-    const p = new Float32Array(FEET.COUNT)
-    // the engine's own defaults (canimAnimatorFeetDefaults)
-    p[FEET.PELVIS] = 0.35; p[FEET.UNLOCK_DIST] = 0.10; p[FEET.LOCK_IN] = 0.08; p[FEET.LOCK_OUT] = 0.12
-    p[FEET.PELVIS_TIME] = 0.15; p[FEET.ALIGN] = 1; p[FEET.PROBE] = 0.6; p[FEET.DETECT_SPEED] = 0.35; p[FEET.DETECT_HEIGHT] = 0.12
-    p[FEET.PLANT_SPEED] = 0.2
-    if (o.ik) p[FEET.IK] = 1
-    if (o.lock) p[FEET.LOCK] = 1
-    if (o.pelvis !== undefined) p[FEET.PELVIS] = o.pelvis
-    if (o.unlockDistance !== undefined) p[FEET.UNLOCK_DIST] = o.unlockDistance
-    if (o.lockIn !== undefined) p[FEET.LOCK_IN] = o.lockIn
-    if (o.lockOut !== undefined) p[FEET.LOCK_OUT] = o.lockOut
-    if (o.align !== undefined) p[FEET.ALIGN] = o.align
-    if (o.probe !== undefined) p[FEET.PROBE] = o.probe
-    if (o.plantSpeed !== undefined) p[FEET.PLANT_SPEED] = o.plantSpeed
-    this._c.setFeetParams(p)
-  }
-  private readonly _feetOpts: FeetOptions = {}
-
-  /** One foot's state after this frame's evaluation — where the lock holds it and with what weight
-   *  (a debug beam under the foot). `undefined` on a host without the feet stage, or before anything
-   *  played. */
-  foot(side: "left" | "right"): FootState | undefined {
-    if (!this._c.footState(side === "left" ? 0 : 1, footBuf)) return undefined
-    return { locked: footBuf[0] > 0.5, weight: footBuf[1], anchor: new Vec3(footBuf[2], footBuf[3], footBuf[4]), target: new Vec3(footBuf[5], footBuf[6], footBuf[7]) }
-  }
-
-  /** WARPING (docs/animation-v2-plan.md §2.7) — the pose is fitted to what the body actually does,
-   *  after the clips are composited and before the feet:
-   *
-   *  `stride` — each leg's hip→foot vector is scaled ALONG the travel direction by the ratio of the
-   *    game speed to the shown clip's own (clamped, default 0.6…1.5), the foot height kept, and the
-   *    pelvis lowered when that would overextend a leg. A walk played at 1.9 m/s stops skating; a
-   *    speed between two gaits becomes continuous instead of "two clips and a crossfade".
-   *  `orientation` — the lower body turns from the clip's travel direction toward the one the body
-   *    really travels in (capped, default 60°) and the spine counter-turns, so the chest keeps its
-   *    facing. Arcs and strafing stop needing a clip per angle.
-   *
-   *  Both need to know the body's motion, which a `Locomotion` feeds every frame; without one, set
-   *  `_creator.animatorSetMotion` yourself or leave warping off. Off by default.
-   *
-   *      model.anim.warp = true                                  // both, with the defaults
-   *      model.anim.warp = { stride: [0.7, 1.4], orientation: 45 }
-   */
-  set warp(w: WarpOptions | boolean) {
-    const o: WarpOptions = w === true ? { stride: true, orientation: true } : w === false ? {} : w
-    const p = new Float32Array(WARP.COUNT)
-    // the engine's own defaults (canimAnimatorWarpDefaults): what is not asked for stays neutral
-    p[WARP.STRIDE_MIN] = 0.85; p[WARP.STRIDE_MAX] = 1.2; p[WARP.ORIENT_MAX] = 20
-    p[WARP.ORIENT_TIME] = 0.15; p[WARP.MIN_SPEED] = 0.2; p[WARP.PELVIS] = 0.25
-    p[WARP.STRIDE_TIME] = 0.15
-    if (o.stride) {
-      p[WARP.STRIDE] = 1
-      if (Array.isArray(o.stride)) { p[WARP.STRIDE_MIN] = o.stride[0]; p[WARP.STRIDE_MAX] = o.stride[1] }
-    }
-    if (o.orientation) {
-      p[WARP.ORIENT] = 1
-      if (typeof o.orientation === "number") p[WARP.ORIENT_MAX] = o.orientation
-    }
-    if (o.minSpeed !== undefined) p[WARP.MIN_SPEED] = o.minSpeed
-    if (o.pelvis !== undefined) p[WARP.PELVIS] = o.pelvis
-    if (o.strideTime !== undefined) p[WARP.STRIDE_TIME] = o.strideTime
-    this._c.setWarp(p)
-  }
-
-  // ---- footsteps ----
-  /** A foot planted (world position) — audio, dust, decals. Fires for what the BASE layer shows,
-   *  from the clip's own contacts; a clip with no contacts fires nothing. */
-  onStep(cb: StepHandler): this { this._c.onStepHandler(cb); return this }
-  offStep(cb: StepHandler): this { this._c.offStepHandler(cb); return this }
-
-  // ---- layers ----
-  /** A new layer on top (masked override / additive). The returned object is its handle. */
-  addLayer(options: LayerOptions = {}): Layer { return this._c.addLayer(options) }
-
-  // ---- clip events (`clip.addEvent(0.4, 'hit')`) ----
-  on(event: string, cb: ClipEventHandler): this { this._c.on(event, cb); return this }
-  off(event: string, cb: ClipEventHandler): this { this._c.off(event, cb); return this }
-
-  // ---- props ----
-  /** Global playback rate: 0.3 = slow-mo, 0 = pause. */
-  get speed(): number { return this._c.speed }
-  set speed(v: number) { this._c.setSpeed(v) }
-  /** Root motion: the root bone's horizontal travel comes OFF the pose and moves the node instead —
-   *  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). A character that
-   *  moves under a `Locomotion` gets this from its displacement mode instead. */
-  get rootMotion(): boolean { return this._rootMotion }
-  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) }
-}
+// Animator — the animation system, reached as `node.anim`. Every Model carries one (its clip list = the
+// GLB's embedded clips); nothing native exists until the first play(). The per-frame work — transitions,
+// blend spaces, hand-overs, root motion — runs in the engine; the SDK only issues calls.
+// Docs: sdk/docs/3d/animation.md (the contract), docs/animation-v2-plan.md (the engine).
+//
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.playLoop('Idle')                                    // the loop: what the character rests on
+//   await hero.anim.play('Jump', { fadeIn: 0.1, fadeOut: 0.2 })   // a one-shot over it, back to the loop after
+//
+//   const loco = hero.anim.playLoop({ Idle: 0, Walk: 2, Run: 6 })  // a blend space as the loop
+//   loco.value = hero.controller.velocity.length                  // where we are on its axis
+//   const upper = hero.anim.addLayer({ mask: 'Spine1' })
+//   upper.playLoop('Aim')                                         // arms aim, legs keep walking
+//
+// Every switch is an inertialized transition: the pose shown does not fade away, its difference to the
+// new source decays over `fade` (default 0.2 s; 0 = cut). A clip may be replaced at any time.
+//
+// The surface, top to bottom: clips → playing → root motion → the feet and the warp (`anim.feet`,
+// `anim.warp` — locomotion's post-processing of the pose) → level of detail → engine-facing.
+
+import { Aspect } from "../../core/Aspect"
+import type { Node } from "../Node"
+import type { AnimationClip } from "./AnimationClip"
+import { Core, type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
+import { Feet } from "./Feet"
+import { Warp } from "./Warp"
+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"
+  /** The feet: the contact bones, the foot lock, ground IK, footstep events. See `Feet`. */
+  feet!: Feet
+  /** The warp: stride and orientation fitted to the body's real motion, the step warp dials. See `Warp`. */
+  warp!: Warp
+
+  onAttach(): void { this._c = new Core(this.node); this.feet = new Feet(this._c); this.warp = new Warp(this._c) }
+  onDetach(): void { this._c.destroy() }
+
+  // ---- clips ----------------------------------------------------------------------------------
+  /** The clip list, in order: the GLB's embedded clips, then the clips you added (an added clip with an
+   *  embedded clip's name takes its place). */
+  get clips(): readonly AnimationClip[] { return this._c.clips() }
+  /** One clip by name or index — the resource: its name, duration, tracks, events. `undefined` if none. */
+  clip(ref: string | number): AnimationClip | undefined { return this._c.resolveClip(ref)?.[1] }
+  /** Add a clip under a name (default: its own) — from another file, procedural, or sliced. Chainable. */
+  addClip(name: string | AnimationClip, clip?: AnimationClip): this {
+    const c = typeof name === "string" ? clip : name
+    const n = typeof name === "string" ? name : name.name
+    if (!c) { console.warn(`Animator.addClip('${n}'): no clip`); return this }
+    this._c.addClip(n, c)
+    return this
+  }
+  /** What the engine measured about a clip on THIS skeleton (unlike `clip()`, which is the file's data):
+   *  speed, travel, turn, the foot contacts, the gait phase, its cycle, and comparisons with other clips.
+   *  Binds the clip on first ask. `undefined` if there is no such clip. */
+  clipInfo(clip: string | number): ClipInfo | undefined { return this._c.clipInfo(clip) }
+
+  // ---- playing (the base layer; `addLayer()` for more) ---------------------------------------
+  /** Play a one-shot: by name, index, or the first clip. It takes the layer over from whatever it showed,
+   *  transitioned over `fade`. `await` the Playback: it resolves at the hand-over (`true`, or `false` if cut
+   *  short), and what you start right then is what the clip hands over to (nothing = back to the loop). */
+  play(clip?: string | number, options: PlayOptions = {}): Playback { return this._c.play(this._c.layers[0], clip, options) }
+  /** Set the LOOP — what shows when no one-shot plays: a clip, or a blend space (`{ Idle: 0, Run: 6 }`, drive
+   *  the returned object's `value`). Takes the layer over, a one-shot included. `stop()` removes it. */
+  playLoop(def: LoopDef, options: LoopOptions = {}): Loop | undefined { return this._c.loop(this._c.layers[0], def, options) }
+  /** Fade everything out, on every layer → the rest pose. */
+  stop(options: StopOptions = {}): this { this._c.stopAll(options.fade ?? 0); return this }
+  /** The current loop (the object the last `playLoop()` returned), if any. */
+  get loop(): Loop | undefined { return this._c.layers[0].loop?.view }
+  /** A one-shot hasn't handed over yet. */
+  get busy(): boolean { return this._c.busy(this._c.layers[0]) }
+  /** What every layer shows this frame, with weights: a one-shot, or a loop's members with their shares. */
+  get active(): ActiveClip[] { return this._c.layers.flatMap((L) => this._c.active(L)) }
+  /** Where the base layer is in the GAIT CYCLE: 0 at a left-foot-down, 0.5 at a right-foot-down; -1 when
+   *  what plays has no cycle. What `play(clip, { phase: 'match' })` matches against. */
+  get phase(): number { return this._c.layerPhase(this._c.layers[0]) }
+  /** A clip's playhead, seconds (-1 = not bound). */
+  time(clip: string | number): number { return this._c.timeOf(clip) }
+  /** Scrub a clip's playhead, seconds — inspectors and debug boards (pair with `speed = 0`). Nothing is
+   *  faded or re-picked. */
+  seek(clip: string | number, time: number): void { this._c.seekTime(clip, time) }
+  /** Re-aim a playing turn clip's warp (`play({ turn })`) to `deg` for the rest of the clip; `undefined` = off. */
+  setTurn(clip: string | number, deg: number | undefined): void { this._c.setTurnOf(clip, deg) }
+  /** Global playback rate: 0.3 = slow-mo, 0 = pause. */
+  get speed(): number { return this._c.speed }
+  set speed(v: number) { this._c.setSpeed(v) }
+  /** Clip events (`clip.addEvent(0.4, 'hit')` → `anim.on('hit', …)`). */
+  on(event: string, cb: ClipEventHandler): this { this._c.on(event, cb); return this }
+  off(event: string, cb: ClipEventHandler): this { this._c.off(event, cb); return this }
+  /** A new layer on top (masked override / additive); the returned object is its handle. */
+  addLayer(options: LayerOptions = {}): Layer { return this._c.addLayer(options) }
+
+  // ---- root motion ----------------------------------------------------------------------------
+  /** The root bone's horizontal travel comes OFF the pose and moves the node — or its CharacterController
+   *  (on this node or an ancestor) as a velocity, so it collides. For clips whose hips actually travel. A
+   *  character under a `Locomotion` gets this from its displacement mode instead. */
+  get rootMotion(): boolean { return this._rootMotion }
+  set rootMotion(on: boolean) { this._rootMotion = on; this._c.setRootMotion(on, this._rootRotation) }
+  /** With `rootMotion`: the root bone's TURN is root motion too — it comes off the pose and turns the node,
+   *  so a turn clip leaves the character facing where it took it. Off by default (a walk's hip sway is a
+   *  turn too); on for a rig whose root 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) }
+
+  // ---- level of detail --------------------------------------------------------------------------
+  /** `'auto'` (default): a character small on screen or out of view is evaluated every 2nd / 4th frame
+   *  without its finger, toe and twist joints; `'full'`: every frame, every joint (a hero seen through a
+   *  scope). Independent of `Model.lod`, the mesh level. */
+  get lod(): "auto" | "full" { return this._lod }
+  set lod(v: "auto" | "full") { this._lod = v; _pushLod(this.node) }
+
+  // ---- engine-facing (a Locomotion, a bench) --------------------------------------------------
+  /** The native animator's id — 0 until something is played or bound. */
+  get _id(): number { return this._c.id }
+  /** Bind a clip to the base layer without playing it; its native slot (-1 = no such clip). */
+  _slot(clip: string | number): number { return this._c.slotIndex(clip) }
+}