lecodes-sdk 0.19.0

package/src/gl/animation/Animator.ts

@@ -0,0 +1,329 @@
+// 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) }
+}

package/src/gl/animation/Layer.ts

@@ -0,0 +1,39 @@
+// Layer — one layer of an Animator (`anim.addLayer({ mask: 'Spine1' })` for the upper body,
+// `{ 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 { ActiveClip, Core, LayerRec, LoopDef, LoopOptions, PlayOptions, StopOptions } from "./core"
+import type { Loop } from "./Loop"
+import type { Playback } from "./Playback"
+
+export class Layer {
+  private readonly _r: LayerRec
+  private readonly _c: Core
+  /** @internal — created by the Animator. */
+  constructor(rec: LayerRec, core: Core) { this._r = rec; this._c = core }
+
+  /** Play a one-shot on this layer (transitioned over `fade`); resolves at its hand-over. */
+  play(clip?: string | number, options: PlayOptions = {}): Playback { return this._c.play(this._r, clip, options) }
+  /** Set / transition this layer's loop (a clip, or a blend space) — over `fade` from whatever the
+   *  layer shows, a one-shot included (it is cut short). */
+  playLoop(def: LoopDef, options: LoopOptions = {}): Loop | undefined { return this._c.loop(this._r, def, options) }
+  /** Fade everything on this layer out — one-shots and its loop. */
+  stop(options: StopOptions = {}): this { this._c.stopLayer(this._r, options.fade ?? 0); return this }
+  /** ANTICIPATION for the NEXT play / playLoop on this layer (consumed by it): the transition begins with
+   *  every joint moving AGAINST the new clip's motion - `amount` x its velocity - and the transition's
+   *  spring brings it round: a wind-up before the swing. Position and rotation, the joints the layer
+   *  drives. 0.3-1 reads as a natural anticipation; the duration is the transition's own fade.
+   *  Ignored by hosts without it. */
+  anticipate(amount: number): this { this._c.anticipate(this._r, amount); return this }
+  /** This layer's current loop (the object the last `playLoop()` returned), if any. */
+  get loop(): Loop | undefined { return this._r.loop?.view }
+  /** Where this layer is in the gait cycle, 0–1 (-1 = what it shows has no cycle). */
+  get phase(): number { return this._c.layerPhase(this._r) }
+  /** Layer contribution 0–1. */
+  get weight(): number { return this._r.weight }
+  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) }
+  /** What this layer shows this frame with its weight — its one-shot, or its loop's members. */
+  get active(): ActiveClip[] { return this._c.active(this._r) }
+}

package/src/gl/animation/Loop.ts

@@ -0,0 +1,31 @@
+// Loop — a layer's LOOP: what it shows when no one-shot plays (`anim.playLoop('Idle')` — one looping clip,
+// or `anim.playLoop({ Idle: 0, Walking: 2, Run: 6 })` — a blend whose members cycle in phase and `value`
+// picks the mix: 1D linear between neighbours, `[x, y]` positions = a 2D gradient band). A one-shot takes
+// the layer over and hands it back; `playLoop(next)` transitions to another; `stop()` removes it. The
+// object returned by `playLoop()` (also `anim.loop`) is the handle; a replaced loop's object goes dead.
+
+import type { BlendPosition, Core, LoopRec } from "./core"
+
+export class Loop {
+  private readonly _r: LoopRec
+  private readonly _c: Core
+  /** @internal — created by playLoop(). */
+  constructor(rec: LoopRec, core: Core) { this._r = rec; this._c = core }
+
+  /** Position on the axis (number) or plane (`[x, y]`) — units are whatever the positions use. Live
+   *  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 GAIT cycle, 0–1: 0 at a left-foot-down, 0.5 at a right-foot-down —
+   *  one clock for every member, aligned by their contacts (a walk and a run whose feet land at
+   *  different fractions of their clips still agree). Set it to jump the cycle: `playLoop(def,
+   *  { phase })` on the way in, or here to re-sync with something else. */
+  get phase(): number { return this._c.loopPhase(this._r) }
+  set phase(v: number) { this._c.setLoopPhase(this._r, v) }
+  /** Each member's share of the mix, 0–1. */
+  get weights(): Record<string, number> {
+    const out: Record<string, number> = {}
+    for (const m of this._r.members) out[m.name] = this._c.slotWeight(m.slot)
+    return out
+  }
+}

package/src/gl/animation/Playback.ts

@@ -0,0 +1,52 @@
+// Playback — the handle `play()` returns (docs/animator-plan.md). Thenable: `await anim.play('slash')`
+// resolves at the clip's HAND-OVER — where its fade-back starts (`end − fadeOut`; the end when there
+// is no fadeOut) — with `true`; `false` when it was cut short (replaced / stopped). What
+// you call right after the await is what the clip fades into: `anim.play(next)` (a chained one-shot,
+// crossfaded), `anim.playLoop(next)` — nothing = back to the loop (or hold, on a layer without one).
+// Returning one from an `async` function flattens it into `Promise<boolean>` — return `p.done` (or
+// make the function sync) when the caller needs the handle.
+
+import type { AnimationClip } from "./AnimationClip"
+import type { Core, PlaybackRec, StopOptions } from "./core"
+import type { Layer } from "./Layer"
+
+export class Playback implements PromiseLike<boolean> {
+  private readonly _r: PlaybackRec
+  private readonly _c: Core
+  /** @internal — created by play(). */
+  constructor(rec: PlaybackRec, core: Core) { this._r = rec; this._c = core }
+
+  /** The clip that plays. */
+  get clip(): AnimationClip { return this._r.slot.clip }
+  /** The layer it plays on. */
+  get layer(): Layer { return this._r.slot.layer.view }
+  /** Clock (s). */
+  get time(): number { return this._r.slot.playback === 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 }
+  /** Where this clip is in the GAIT cycle now, 0–1 (-1 when it has none). */
+  get phase(): number { return this._c.slotPhase(this._r.slot) }
+  /** The root yaw the clip has turned the body by so far, radians (+ = left) — a turn clip's progress. */
+  get turned(): number { return this._c.slotCurveAt(this._r.slot, 2) }
+  /** The root yaw still to come: where this clip will leave the body facing, relative to now (rad). */
+  get turnLeft(): number { return this._c.slotTurn(this._r.slot) - this.turned }
+  /** The horizontal distance the clip's root has travelled so far, metres. */
+  get travelled(): number { return this._c.slotCurveAt(this._r.slot, 1) }
+  /** Not handed over yet (the clip still owns the layer). */
+  get playing(): boolean { return this._r.playing }
+  /** Contribution to the pose: 1 while this clip is the layer's source, 0 once something else took
+   *  the layer over (the difference between the two poses is what decays, not this weight). */
+  get weight(): number { return this._r.slot.playback === 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 }
+
+  then<A = boolean, B = never>(onFulfilled?: ((v: boolean) => A | PromiseLike<A>) | null, onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B> {
+    return this._r.done.then(onFulfilled, onRejected)
+  }
+
+  /** Move the clock (s). */
+  seek(time: number): this { this._c.seek(this._r.slot, time); return this }
+  /** Cut this clip short (the layer's loop comes back if nothing else takes over), over `fade`. */
+  stop(options: StopOptions = {}): this { this._c.stopSlot(this._r.slot, options.fade ?? 0); return this }
+}