lecodes-sdk 0.19.0

package/src/gl/Locomotion.ts

@@ -0,0 +1,498 @@
+// Locomotion — a character's movement, as an aspect on its node (docs/animation-v2-plan.md §2.8).
+//
+// The GAME states an intent; the ENGINE owns everything that follows. Two intents, and they have
+// different lifetimes on purpose:
+//
+//   the DIRECTION (and gait) — where to go, how fast to want to go there;
+//   the FACING — where to look. It outlives the direction: letting go of the key does not mean
+//     "never mind", it means "stop moving", so the body still owes that heading and turns to it
+//     on the spot.
+//
+// From those the engine springs a desired velocity into a simulated one, predicts the path ahead, and
+// picks what the animator's base layer shows — a start, the gait loop, a turn, a stop, a turn on the
+// spot. What actually MOVES the body is `displacement`: by default the clip's own recorded motion,
+// adjusted toward the simulation by a clamped amount. The simulation itself never reads the animation,
+// so nothing the character does can feed back into what it plays.
+//
+//   const player = new Node().aspect(CharacterController).aspect(Locomotion, {
+//     animator: model.anim,
+//     set: { idle: 'Idle', gaits: [ 'Walk', 'Run' ], starts, stops, turns, spins },
+//   })
+//   // each frame, in an aspect ordered BEFORE this one:
+//   held ? player.loco.move(direction, { gait: running ? 'run' : 'walk' }) : player.loco.move(null)
+//   player.loco.state    // 'idle' | 'start' | 'move' | 'turn' | 'stop' | 'spin'
+//   player.loco.speed    // m/s the body actually travels at
+//
+// The clip SET is the pack's names; the engine measures what each clip does itself (how far it turns,
+// how fast the gait moves, where its foot contacts fall), so nothing here is a hand-measured table.
+// Give `angle` / `speed` only to override a measurement.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, cx, cz, type Vec3Like } from "../math/vec"
+import { Animator, type FeetOptions, type WarpOptions } from "./animation/Animator"
+import { CharacterController } from "./CharacterController"
+import type { Node } from "./Node"
+
+/** How fast the character wants to go: the gait picks its clips and its speed. */
+export type Gait = "walk" | "run" | "sprint"
+/** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, or a turn on the spot. */
+export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin"
+/** Who moves the body:
+ *  `'hybrid'` (the default) — the clip's own recorded motion moves it; while the gait loop shows it
+ *    is ADJUSTED toward what the simulation wants by at most `tuning.adjust` metres a second, and a
+ *    start / turn / stop / spin moves it alone. The recording keeps the feet honest, the clamp keeps
+ *    the player in charge of the arcs. What a pack authored with root motion wants.
+ *  `'code'` — the simulation moves it and the animation has to be warped to follow (stride warping);
+ *    for packs recorded in place.
+ *  `'data'` — the clips' root motion moves it and nothing adjusts it; the simulation only predicts. */
+export type Displacement = "hybrid" | "code" | "data"
+
+/** One clip of the set: its name, or the name with what the clip itself cannot say — `gait` (which
+ *  gait a transition belongs to: a walking body plays the walking starts, stops and turns; left out =
+ *  any gait) — and overrides for what the engine would otherwise measure: `angle` (degrees the clip
+ *  turns the body, + = left) for a start / turn / spin, `speed` (m/s) for a gait clip. */
+export type LocomotionClip = string | { clip: string, gait?: Gait, angle?: number, speed?: number }
+
+/** The clips the selector may show. Everything but `idle` is a list; an empty one simply means the
+ *  engine never shows that kind (a pack without turns steers through them instead). */
+export type LocomotionSet = {
+  /** standing still */
+  idle?: LocomotionClip
+  /** the gait loop's members, slowest first — walk, run, sprint. Blended by the simulated speed. */
+  gaits?: LocomotionClip[]
+  /** standing → moving, one per direction (the engine picks by the turn each one makes) */
+  starts?: LocomotionClip[]
+  /** moving → standing */
+  stops?: LocomotionClip[]
+  /** turns taken while moving */
+  turns?: LocomotionClip[]
+  /** turns on the spot — what a facing still owed by a standing body plays */
+  spins?: LocomotionClip[]
+}
+
+/** The tuning. Times are seconds, speeds m/s, angles degrees. */
+export type LocomotionTuning = {
+  /** How briskly the simulated speed reaches the wanted one — the halflife of the difference, per
+   *  gait (default 0.27 walking, 0.2 running). Smaller = more responsive, larger = heavier. */
+  responseWalk?: number
+  responseRun?: number
+  /** How briskly the body brakes when nothing is asked for (default 0.15). Braking is not
+   *  acceleration backwards: a body plants and stops in far less than it takes to reach a run, and
+   *  with the gait's own number the tail of the curve is a long, visible glide. */
+  responseStop?: number
+  /** The same for the facing (default 0.15). */
+  responseFacing?: number
+  /** Top speed per gait. Left out (the default), each gait travels at the speed its own clip was
+   *  recorded at — which is what keeps the feet from sliding. */
+  speeds?: Partial<Record<Gait, number>>
+  /** The step warp's split when a gait is asked for at a speed that is not its clip's own: the
+   *  STRIDE (spatial squash of the leg's reach) gets ratio^strideShare, clamped to `strideBand`,
+   *  and the cadence takes all the rest — the asked speed is always delivered exactly.
+   *  0 = all cadence (slow motion), 1 = all stride (within the band). Default 0.5. */
+  strideShare?: number
+  /** How far the stride's share may squash or stretch the legs' reach (default [0.85, 1.15]) —
+   *  past it the warp re-bends legs the clip authored straight. */
+  strideBand?: [number, number]
+  /** PIN the step warp's stride ratio (a tuning bench's knob): the step width is held at exactly
+   *  this, whatever speed is asked — the body's speed falls out of stride × cadence instead of
+   *  driving the split. Leave out (or 0) for automatic. */
+  warpStride?: number
+  /** PIN the step warp's cadence ratio the same way — the animation's pace held at exactly this.
+   *  With both pinned, stride and pace are fully independent. Leave out (or 0) for automatic. */
+  warpCadence?: number
+  /** Cap on how fast the body may turn by STEERING, deg/s (default: uncapped) — the arc it walks when
+   *  the heading is off by less than `turnMin`. A start / turn / spin clip owns the facing while it
+   *  turns: the body then turns exactly as much as the (warped) animation does. */
+  turnRate?: number
+  /** Heading error that plays a turn clip instead of steering through it (default 60°). Which turn
+   *  clip is not a threshold: every one is entered where the gait phase allows nearest to its pivot,
+   *  and the one whose turn LEFT from there best answers the error wins. */
+  turnMin?: number
+  /** Facing still owed by a standing body that turns it on the spot (default 30°). Less than this it
+   *  accepts — a standing body never rotates by code, that is the one thing no tuning makes look right. */
+  spinMin?: number
+  /** Transition seconds between clips (default 0.2), and into the idle after a stop (default 0.3). */
+  blend?: number
+  stopBlend?: number
+  /** How far a start / turn / spin clip's recorded turn may be SCALED so it delivers exactly the heading
+   *  asked for, as a fraction (default 0.3 = ×0.7 … ×1.3). What lies beyond the clamp is steered once
+   *  the body moves. 0 = the recording is law. */
+  yawWarp?: number
+  /** A start or a turn hands over to the gait loop at the first foot-down after its turn is delivered
+   *  at which its pose is within this many metres of the loop's — the engine's baked fit curve —
+   *  instead of at its end (default 0.15). 0 = at the end. */
+  exitTolerance?: number
+  /** A stop asked to move again resumes the gait loop while the body still travels at this fraction of
+   *  the gait's speed or more (default 0.5); slower, it starts afresh. */
+  resumeSpeed?: number
+  /** …and then let it play this many more FOOT-DOWNS before handing over (default 0). `exitTolerance`
+   *  answers "when has this pose become the walk's", which is the earliest honest moment and not always
+   *  the best-looking one — a start that has just found the gait still reads as a start for another step
+   *  or two. 1 or 2 gives a take room to finish its thought; a take that runs out hands over at its own
+   *  end regardless, so nothing can hang. */
+  exitSteps?: number
+  /** How much braking room, in metres, to trade for each second of a stop take's lead-in that would
+   *  otherwise be skipped (default 0). A stop cannot be rewound — the variants are one cycle long, so
+   *  no earlier frame has the same foot down — so the only way to begin a stop nearer its own start is
+   *  to prefer the VARIANT that starts there for the foot the body happens to be on. Raise it (0.5…1.5)
+   *  to see the whole braking gesture; leave it at 0 to land exactly where the body should stop. */
+  stopEarly?: number
+  /** How much braking room, in metres, one extra FOOT-DOWN in the stop is worth (default 0). A stop
+   *  take is one cycle long, so wanting another step means wanting a LONGER variant, and a longer one
+   *  lands the body further along than it asked to stop — the trade is this number. Around 1 buys a
+   *  second step on a pack like Mobility Pro; 0 lands exactly where the body should stop. */
+  stopSteps?: number
+  /** How far a stop take's pose may be from the one showing, in metres, for it to be entered BEFORE
+   *  its own first foot-down (default 0.25). Ahead of that footfall a take's phase curve is an
+   *  extrapolation: it can match the body's phase arithmetically with the legs at a different stage
+   *  of the stride, which is why the pose is asked directly. 0 = never enter a take early — the body
+   *  then takes whatever later entry matches its foot, which on a walk can be three quarters of the
+   *  way through a take, on top of one of its plants. */
+  stopFit?: number
+  /** What a metre of POSE distance at the entry is worth against a metre of braking room when the
+   *  variants are ranked (default 1). Both are metres and the feet pay both: room the body has not
+   *  got is taken out of the root while a foot is planted, and a pose the transition has to hide is
+   *  dragged out of that same foot over the blend. 0 = rank by braking room alone, which picks a
+   *  take by where it ENDS and lets it start from any pose at all. */
+  stopPose?: number
+  /** Input magnitude below which a stick counts as released (default 0.2). */
+  deadZone?: number
+  /** `displacement: 'hybrid'`: how far, m/s, the body may be pushed off what the animation recorded,
+   *  toward what the simulation wants, while the gait loop shows (default 0.5) — a start, turn, stop
+   *  or spin moves the body alone, since pushing it there is its planted foot skating. 0 = the
+   *  recording is law; large = the code is law — responsive, and the feet start lying. */
+  adjust?: number
+}
+
+/** One stop take as the selector weighed it, from `stopReport()`. A stop is chosen for the foot the
+ *  body stands on and the room it needs: `phaseOk` and `afterFirstStep` are the two pass/fail rules,
+ *  `score` ranks whatever passed (lower wins), and `chosen` marks the one that plays. */
+export type StopCandidate = {
+  /** the take's clip name */
+  clip: string
+  /** seconds into it the entry would be — near its end means its braking gesture is skipped */
+  at: number
+  /** metres it still travels from that entry */
+  room: number
+  /** metres this body needs to come to rest (the same for every row) */
+  need: number
+  /** seconds from the entry to its next foot-down */
+  wait: number
+  /** foot-downs left after the entry: 0 = it plants where it stands */
+  steps: number
+  /** does it have a frame at the body's own cycle phase (the right foot down)? */
+  phaseOk: boolean
+  /** is that frame at or after its own first foot-down? Ahead of it the phase curve is an
+   *  extrapolation — it can match arithmetically at the wrong stage of the stride */
+  afterFirstStep: boolean
+  /** …and it is ahead of it, but its POSE matched what is showing closely enough to be let in
+   *  anyway (`fit` under `tuning.stopFit`) */
+  earlyByPose: boolean
+  /** the one that is playing */
+  chosen: boolean
+  /** |room − need| + the pose distance + how late in the take (lower wins) */
+  score: number
+  /** how far this entry's pose is from the one showing, in the fit measure's metres (-1 = not
+   *  measured). Under `tuning.stopFit` an entry ahead of the take's first foot-down is allowed. */
+  fit: number
+}
+
+const STOP_ROW = 9
+const STOP_ROWS = 8
+const IN = { DIR_X: 0, DIR_Z: 1, MAG: 2, FACE_X: 3, FACE_Z: 4, GAIT: 5, COUNT: 6 }
+const OUT = { STATE: 0, SPEED: 1, VEL_X: 2, VEL_Y: 3, VEL_Z: 4, YAW: 5, YAW_RATE: 6, PHASE: 7, SEQ: 8, PRED: 9, YAW_LEFT: 21, CLIP_TIME: 22, EXIT_AT: 23, STOP_OFF: 24, STOP_STEPS: 25, STOP_WAIT: 26, COUNT: 27 }
+const P = {
+  HALFLIFE_WALK: 0, HALFLIFE_RUN: 1, HALFLIFE_FACING: 2, SPEED_WALK: 3, SPEED_RUN: 4, SPEED_SPRINT: 5,
+  DEADZONE: 6, TURN_MIN: 7, TURN_BIG: 8, BLEND: 9, STOP_BLEND: 10, TAP: 11, RESUME: 12, PREDICT: 13,
+  DISPLACEMENT: 14, MODE: 15, MATCH_INTERVAL: 16, MATCH_BLEND: 17, SPIN_MIN: 18, TURN_RATE: 19,
+  HALFLIFE_STOP: 20, ADJUST: 21, YAW_WARP: 22, EXIT_TOL: 23, RESUME_SPEED: 24, EXIT_STEPS: 25, STOP_EARLY: 26, STOP_STEPS: 27, STOP_FIT: 28, STOP_POSE: 29,
+  STRIDE_SHARE: 30, STRIDE_MIN: 31, STRIDE_MAX: 32, WARP_STRIDE: 33, WARP_RATE: 34, COUNT: 35,
+}
+const KIND = { IDLE: 0, GAIT: 1, START: 2, STOP: 3, TURN: 4, MATCH: 5, SPIN: 6 }
+const STATES: LocomotionState[] = [ "idle", "start", "move", "turn", "stop", "spin" ]
+const GAITS: Gait[] = [ "walk", "run", "sprint" ]
+const RAD2DEG = 180 / Math.PI
+
+export type LocomotionEvents = {
+  /** What the selector shows changed. */
+  state: (state: LocomotionState) => void
+}
+
+export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
+  static readonly aspect = "loco"
+
+  /** The animator whose clips are shown. Default: the first one on this node or under it (a Model
+   *  child), which is the usual character — a capsule node with the model inside. */
+  animator?: Animator
+  /** The clips the selector may show. */
+  set: LocomotionSet = {}
+  /** Who moves the body (see `Displacement`). */
+  displacement: Displacement = "hybrid"
+  /** The feel (see `LocomotionTuning`). */
+  tuning: LocomotionTuning = {}
+  /** Fit the POSE to what the body does — stride and orientation warping (see `Animator.warp`, which
+   *  this simply sets). The simulation feeds the engine the body's motion every frame, so here it
+   *  only has to be turned on: `warp: true`, or `{ stride: [0.7, 1.4], orientation: 45 }`. Off by
+   *  default — a pack whose gaits already cover the speeds it is played at does not need it. */
+  warp?: WarpOptions | boolean
+  /** The FEET (see `Animator.feet`, which this simply sets). Default: the foot lock on, ground IK off
+   *  — a planted foot stays where it landed through every transition the selector makes, which is the
+   *  last of the slide once the recording moves the body. `true` = lock + ground IK (stairs, slopes);
+   *  `false` = neither; or the options themselves. */
+  feet?: FeetOptions | boolean
+
+  private _loco = 0
+  private _dir = new Vec3(0, 0, 0)
+  private _face = new Vec3(0, 0, 1)
+  private _mag = 0
+  private _gait: Gait = "walk"
+  private _seq = -1
+  private readonly _in = new Float32Array(IN.COUNT)
+  private readonly _out = new Float32Array(OUT.COUNT)
+  private readonly _names = new Map<number, string>()
+  private _report?: Float32Array
+
+  private get anim(): Animator | undefined {
+    if (this.animator) return this.animator
+    let found = this.node.get(Animator)
+    if (!found) this.node.traverse((n) => { found ??= n.get(Animator) })
+    return this.animator = found
+  }
+  private get controller(): CharacterController | undefined {
+    for (let n: Node | null = this.node; n; n = n.parent) { const c = n.get(CharacterController); if (c) return c }
+    return undefined
+  }
+
+  protected onAttach(): void { this.rebuild() }
+  protected onDetach(): void {
+    if (this._loco) { _creator.locoDestroy(this._loco); this._loco = 0 }
+  }
+
+  /** Re-read the set and the tuning — after changing either at runtime (a weapon that changes the
+   *  walk, a slowed-down character). */
+  rebuild(): void {
+    const anim = this.anim
+    if (!anim || !_creator.locoCreate) return
+    if (!this._loco) {
+      const first = this.set.idle ?? (this.set.gaits ?? [])[0]     // binding a clip is what creates the native animator
+      if (first !== undefined) anim._slot(name(first))
+      if (!anim._id) return
+      this._loco = _creator.locoCreate(anim._id)
+      if (!this._loco) return
+    }
+    _creator.locoClearSet(this._loco)
+    this._names.clear()
+    this.enter(this.set.idle, KIND.IDLE)
+    for (const c of this.set.gaits ?? []) this.enter(c, KIND.GAIT)
+    for (const c of this.set.starts ?? []) this.enter(c, KIND.START)
+    for (const c of this.set.stops ?? []) this.enter(c, KIND.STOP)
+    for (const c of this.set.turns ?? []) this.enter(c, KIND.TURN)
+    for (const c of this.set.spins ?? []) this.enter(c, KIND.SPIN)
+    if (this.warp !== undefined) anim.warp = this.warp
+    anim.feet = this.feet === undefined ? { lock: true } : this.feet === true ? { lock: true, ik: true } : this.feet === false ? { lock: false, ik: false } : this.feet
+    this.pushTuning()
+  }
+
+  /** Register one clip of the set: the engine measures the clip's own turn / speed unless given. */
+  private enter(clip: LocomotionClip | undefined, kind: number): void {
+    if (clip === undefined) return
+    const anim = this.anim
+    if (!anim) return
+    const n = name(clip)
+    const slot = anim._slot(n)
+    if (slot < 0) { console.warn(`Locomotion: no clip '${n}' on ${this.node.name || "the character"}`); return }
+    this._names.set(slot, n)
+    const o = typeof clip === "string" ? undefined : clip
+    const measured = anim.curves(n)
+    const angle = o?.angle ?? (measured ? measured.turn * RAD2DEG : 0)
+    const gait = kind === KIND.GAIT ? -1 : o?.gait ? GAITS.indexOf(o.gait) : -1
+    _creator.locoSetEntry(this._loco, slot, kind, angle, o?.speed ?? 0, gait)
+  }
+
+  /** Why the stop that is playing is the one that plays: every candidate the selector weighed, in
+   *  the order it weighed them. Read it when a stop looks wrong — the answer is usually that the
+   *  take that would have looked right was rejected by one of the two rules, not that the score
+   *  picked badly. Empty until a stop has been chosen (and on hosts without the debug read). */
+  stopReport(): StopCandidate[] {
+    if (!this._loco || !_creator.locoStopReport) return []
+    const buf = this._report ??= new Float32Array(STOP_ROWS * STOP_ROW)
+    const rows = _creator.locoStopReport(this._loco, buf)
+    const out: StopCandidate[] = []
+    for (let i = 0; i < rows; i++) {
+      const r = i * STOP_ROW
+      const flags = buf[r + 6]
+      out.push({
+        clip: this._names.get(buf[r]) ?? `slot ${buf[r]}`,
+        at: buf[r + 1], room: buf[r + 2], need: buf[r + 3], wait: buf[r + 4], steps: buf[r + 5], fit: buf[r + 8],
+        phaseOk: (flags & 1) !== 0, afterFirstStep: (flags & 2) !== 0, chosen: (flags & 4) !== 0,
+        earlyByPose: (flags & 8) !== 0,
+        score: buf[r + 7],
+      })
+    }
+    return out
+  }
+
+  /** Re-push the TUNING alone — the numbers, not the clip set. What a live tweak wants (a debug
+   *  slider, a character that gets heavier when hurt): `rebuild()` also re-measures the set, which
+   *  mid-clip is more than a changed number asks for. */
+  retune(): void { this.pushTuning() }
+
+  private pushTuning(): void {
+    if (!this._loco) return
+    const p = new Float32Array(P.COUNT)
+    _creator.locoDefaults(p)
+    const t = this.tuning
+    if (t.responseWalk !== undefined) p[P.HALFLIFE_WALK] = t.responseWalk
+    if (t.responseRun !== undefined) p[P.HALFLIFE_RUN] = t.responseRun
+    if (t.responseStop !== undefined) p[P.HALFLIFE_STOP] = t.responseStop
+    if (t.responseFacing !== undefined) p[P.HALFLIFE_FACING] = t.responseFacing
+    if (t.speeds?.walk !== undefined) p[P.SPEED_WALK] = t.speeds.walk
+    if (t.speeds?.run !== undefined) p[P.SPEED_RUN] = t.speeds.run
+    if (t.speeds?.sprint !== undefined) p[P.SPEED_SPRINT] = t.speeds.sprint
+    if (t.turnRate !== undefined) p[P.TURN_RATE] = t.turnRate
+    if (t.turnMin !== undefined) p[P.TURN_MIN] = t.turnMin
+    if (t.spinMin !== undefined) p[P.SPIN_MIN] = t.spinMin
+    if (t.blend !== undefined) p[P.BLEND] = t.blend
+    if (t.stopBlend !== undefined) p[P.STOP_BLEND] = t.stopBlend
+    if (t.yawWarp !== undefined) p[P.YAW_WARP] = t.yawWarp
+    if (t.exitTolerance !== undefined) p[P.EXIT_TOL] = t.exitTolerance
+    if (t.resumeSpeed !== undefined) p[P.RESUME_SPEED] = t.resumeSpeed
+    if (t.exitSteps !== undefined) p[P.EXIT_STEPS] = t.exitSteps
+    if (t.stopEarly !== undefined) p[P.STOP_EARLY] = t.stopEarly
+    if (t.stopSteps !== undefined) p[P.STOP_STEPS] = t.stopSteps
+    if (t.stopFit !== undefined) p[P.STOP_FIT] = t.stopFit
+    if (t.stopPose !== undefined) p[P.STOP_POSE] = t.stopPose
+    if (t.strideShare !== undefined) p[P.STRIDE_SHARE] = t.strideShare
+    if (t.strideBand !== undefined) { p[P.STRIDE_MIN] = t.strideBand[0]; p[P.STRIDE_MAX] = t.strideBand[1] }
+    if (t.warpStride !== undefined) p[P.WARP_STRIDE] = t.warpStride
+    if (t.warpCadence !== undefined) p[P.WARP_RATE] = t.warpCadence
+    if (t.deadZone !== undefined) p[P.DEADZONE] = t.deadZone
+    if (t.adjust !== undefined) p[P.ADJUST] = t.adjust
+    p[P.DISPLACEMENT] = this.displacement === "data" ? 1 : this.displacement === "hybrid" ? 2 : 0
+    _creator.locoSetParams(this._loco, p)
+  }
+
+  // ---- the intent --------------------------------------------------------------------------------
+
+  /** State the movement intent for this frame: a world direction (its length is the stick's pull,
+   *  clamped to 1) and the gait. `null` = no movement — the body stops, but it keeps facing where it
+   *  was last asked to, and turns there on the spot if it still owes the turn.
+   *  `face` states a facing of its own (aiming, strafing, a camera-relative shooter). */
+  move(direction: Vec3Like | null | undefined, options: { gait?: Gait, face?: Vec3Like } = {}): void {
+    const dx = direction ? cx(direction) : 0, dz = direction ? cz(direction) : 0
+    const len = Math.hypot(dx, dz)
+    if (len > 1e-4) {
+      this._dir = new Vec3(dx / len, 0, dz / len)
+      this._mag = Math.min(len, 1)
+      this._face = this._dir
+    } else this._mag = 0
+    if (options.face) {
+      const fx = cx(options.face), fz = cz(options.face), fl = Math.hypot(fx, fz)
+      if (fl > 1e-4) this._face = new Vec3(fx / fl, 0, fz / fl)
+    }
+    if (options.gait) this._gait = options.gait
+  }
+
+  /** Face this way without moving — the facing intent on its own (`Vec3`, or a heading in degrees,
+   *  0 = +Z, + = toward +X). A standing body turns to it on the spot. */
+  face(direction: Vec3Like | number): void {
+    if (typeof direction === "number") {
+      const a = direction / RAD2DEG
+      this._face = new Vec3(Math.sin(a), 0, Math.cos(a))
+      return
+    }
+    const fx = cx(direction), fz = cz(direction), fl = Math.hypot(fx, fz)
+    if (fl > 1e-4) this._face = new Vec3(fx / fl, 0, fz / fl)
+  }
+
+  /** The gait the intent asks for. */
+  get gait(): Gait { return this._gait }
+  set gait(g: Gait) { this._gait = g }
+  /** Is a movement intent standing right now? (The debug answer to "is a key held".) */
+  get moving(): boolean { return this._mag > (this.tuning.deadZone ?? 0.2) }
+  /** The direction the intent points, world. */
+  get direction(): Vec3 { return this._dir }
+  /** The heading the intent asks the body to face, degrees (0 = +Z, + = toward +X). */
+  get heading(): number { return Math.atan2(this._face.x, this._face.z) * RAD2DEG }
+  /** The speed the intent asks for, m/s — it jumps the moment a key goes down or the gait changes.
+   *  `speed` is what the body has made of it. */
+  get intentSpeed(): number {
+    if (!this.moving) return 0
+    const t = this.tuning.speeds
+    const named = t ? t[this._gait] : undefined
+    if (named !== undefined) return named * this._mag
+    const clip = (this.set.gaits ?? [])[GAITS.indexOf(this._gait)]
+    const measured = clip !== undefined ? this.anim?.curves(name(clip))?.speed : undefined
+    return (measured ?? 0) * this._mag
+  }
+
+  // ---- what came of it ---------------------------------------------------------------------------
+
+  /** What the selector shows. */
+  get state(): LocomotionState { return STATES[this._out[OUT.STATE]] ?? "idle" }
+  /** The body's speed, m/s — the simulation's, which is what the animation is fitted to. */
+  get speed(): number { return this._out[OUT.SPEED] }
+  /** The body's velocity, world m/s. */
+  get velocity(): Vec3 { return new Vec3(this._out[OUT.VEL_X], this._out[OUT.VEL_Y], this._out[OUT.VEL_Z]) }
+  /** Where the body faces, degrees (0 = +Z, + = toward +X) — the node's yaw, which this drives. */
+  get facing(): number { return this._out[OUT.YAW] * RAD2DEG }
+  /** Where the base layer is in the gait cycle, 0–1 (-1 when what shows has no cycle). */
+  get phase(): number { return this._out[OUT.PHASE] }
+  /** How far the STOP that is showing was entered from the phase the body was on, in cycles, signed —
+   *  measured at the switch. 0 while no stop shows; ±0.5 would be the other foot on the ground. */
+  get stopFootOffset(): number { return this._out[OUT.STOP_OFF] }
+
+  /** Foot-downs left in the stop that is showing, counted from the frame it was entered at. 0 means it
+   *  was entered past its own last footfall — the body will not step, it will only settle. -1 when no
+   *  stop shows. The number behind "he did not take a step, he just pulled the foot back". */
+  get stopStepsLeft(): number { return this._out[OUT.STOP_STEPS] }
+
+  /** Seconds from the frame the shown stop was entered at to its next foot-down. Large means it was
+   *  entered just AFTER a footfall: the leg is planted and then held still until the one after, which
+   *  reads as a foot that sticks. -1 when no stop shows. */
+  get stopStepWait(): number { return this._out[OUT.STOP_WAIT] }
+
+  /** Degrees the clip showing still turns the body by (a start / turn / spin, after its warp); 0 for
+   *  the loop and the idle — the heading the engine has committed to but not yet delivered. */
+  get yawLeft(): number { return this._out[OUT.YAW_LEFT] * RAD2DEG }
+  /** The shown transition's clip time and the time it hands over at, seconds (-1 for the loop / idle;
+   *  `exitAt` -1 = at the clip's end). A debug readout. */
+  get clipTime(): number { return this._out[OUT.CLIP_TIME] }
+  get exitAt(): number { return this._out[OUT.EXIT_AT] }
+  /** Where the body will be in 0.2 / 0.4 / 0.7 s if the intent holds — the path the selector judges
+   *  a turn by, and a debug overlay's dots. */
+  get trajectory(): Vec3[] {
+    const out: Vec3[] = []
+    for (let i = 0; i < 3; i++) out.push(new Vec3(this._out[OUT.PRED + i * 4], 0, this._out[OUT.PRED + i * 4 + 1]))
+    return out
+  }
+
+  // ---- the frame ---------------------------------------------------------------------------------
+
+  protected updateBefore(dt: number): void {
+    if (!this._loco) return
+    const i = this._in
+    i[IN.DIR_X] = this._dir.x; i[IN.DIR_Z] = this._dir.z; i[IN.MAG] = this._mag
+    i[IN.FACE_X] = this._face.x; i[IN.FACE_Z] = this._face.z
+    i[IN.GAIT] = Math.max(0, GAITS.indexOf(this._gait))
+    _creator.locoSetInput(this._loco, i)
+    _creator.locoUpdate(this._loco, dt)
+    _creator.locoRead(this._loco, this._out)
+    if (this.displacement !== "data") this.node.eulerAngles = [ 0, this._out[OUT.YAW] * RAD2DEG, 0 ]   // data: the root motion turns the node itself
+    const seq = this._out[OUT.SEQ]
+    if (seq !== this._seq) { this._seq = seq; this.emit("state", this.state) }
+  }
+
+  protected updateFixed(dt: number): void {
+    if (!this._loco) return
+    const p = this.node.position
+    _creator.locoStep(this._loco, dt, p.x, p.y, p.z)
+    if (this.displacement === "data") return    // the engine hands the root motion to the character itself
+    _creator.locoRead(this._loco, this._out)
+    const c = this.controller
+    if (c) c.move(this._out[OUT.VEL_X], this._out[OUT.VEL_Z])
+    else this.node.position = [ p.x + this._out[OUT.VEL_X] * dt, p.y, p.z + this._out[OUT.VEL_Z] * dt ]
+  }
+}
+
+const name = (clip: LocomotionClip): string => typeof clip === "string" ? clip : clip.clip