lecodes-sdk 1.0.0 → 1.2.0

package/src/gl/animation/IK.ts

@@ -1,151 +1,173 @@
-// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
-// They run after the animation wrote the pose (base anim or Animator) and before the skin is
-// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
-// walked up through parents — one instance per end effector, any Node hierarchy works.
+// IK — chains the ENGINE solves in its late pass: after every aspect's update(dt) ran, before the
+// dynamic bones and the skin flush. Attach to the END bone of the chain (the chain is its parent and
+// grandparent); nothing runs in JS per frame — the aspect only describes the chain, the host reads the
+// target nodes itself each frame and creator-anim (anchors.cpp) solves.
 //
 //   const foot = hero.bone('LeftFoot')!
 //   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
 //   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
 //   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
 //
-// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
-// slot in later behind the same API.
+// ANCHORED chains — hands on a weapon's grips (the gun-master rig): the chain rides a SOCKET of the
+// rig (`anim.sockets(...)`: named empties on a bone, a weapon's grip / magazine / bolt), keeping the
+// animated hand's pose RELATIVE to that socket on the gun the take was authored on and replaying it
+// relative to the socket on the gun in the hands — shifted and turned by the sockets' difference,
+// never re-authored. A clip's anchor spans (`clip.anchors(...)`) move the hand between sockets while
+// it plays (grip → magazine → free → bolt → grip through a reload):
+//
+//   arms.anim.sockets('ik_hand_gun', { grip_r: weapon.gripR, grip_l: weapon.gripL, mag: weapon.mag })
+//   arms.anim.sockets('ik_hand_gun', { grip_r: {...}, grip_l: {...}, mag: {...} }, { set: 'tr15' })  // the donor's
+//   arms.bone('hand_l')!.aspect(IK.TwoBone, { anchor: 'grip_l' })
+//   arms.anim.clip('R_ReloadEmpty')!.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag']] })
+//
+// Since the engine solves after the late phase, a target the game moves in its own update(dt) — the
+// gun bone placed for aiming and recoil — is reached the SAME frame.
 
 import { Aspect } from "../../core/Aspect"
 import { Vec3, type Vec3Like } from "../../math/vec"
 import { Quat } from "../../math/quat"
 import type { Node } from "../Node"
+import { Animator } from "./Animator"
+import type { Core } from "./core"
 
 type Target = Node | Vec3Like
 
-const targetPos = (t: Target | undefined): Vec3 | null => {
-  if (t === undefined || t === null) return null
-  const n = t as Node
-  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
-  return new Vec3(t as Vec3Like)
-}
+const isNode = (t: unknown): t is Node => typeof t === "object" && t !== null && typeof (t as Node).id === "number" && typeof (t as { worldMatrix?: unknown }).worldMatrix === "object"
 
-/** World rotation of a node (parent chain composed natively). */
-const worldRot = (n: Node): Quat => n.worldMatrix.rotation
+// CANIM_IK_* (creator-anim.h): the fixed-order parameter array of a chain.
+const P = { TARGET: 0, POLE: 3, HAS_POLE: 6, WEIGHT: 7, ROT: 8, ROT_WEIGHT: 12, AXIS: 13, LIMIT: 16, ENABLED: 17, ANCHOR_TIME: 18, ANCHOR_PIN: 19, COUNT: 20 }
+const stateBuf = new Float32Array(4)
 
-/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
-const setWorldRot = (n: Node, q: Quat): void => {
-  const p = n.parent
-  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
+/** The rig a bone belongs to: the nearest ancestor carrying an Animator (every Model has one); a bare
+ *  node tree gets one on its topmost node. */
+const rigOf = (bone: Node): Core => {
+  let top: Node = bone
+  for (let n: Node | null = bone; n; n = n.parent) {
+    const anim = n.get(Animator)
+    if (anim) return anim._core
+    top = n
+  }
+  top.aspect(Animator)
+  return top.get(Animator)!._core
 }
 
-const clampAngle = (q: Quat, maxRad: number): Quat => {
-  // angle of a unit quaternion = 2·acos(|w|)
-  const w = Math.min(1, Math.abs(q.w))
-  const ang = 2 * Math.acos(w)
-  if (ang <= maxRad || ang < 1e-6) return q
-  const s = Math.sqrt(1 - w * w)
-  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
-  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
-}
+/** What both chains share: the native handle, the parameter push, the readback. */
+abstract class Chain<Name extends string> extends Aspect<Name, Node> {
+  protected _rig?: Core
+  protected _ik = 0
+  protected _weight = 1
+  protected _enabled = true
+  protected abstract readonly kind: 0 | 1
 
-/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
- *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
- *  (knee/elbow) — a Node or world point. */
-class TwoBone extends Aspect<"ik", Node> {
-  static readonly aspect = "ik"
-
-  /** Where the end bone should be (Node or world position). */
-  target?: Target
-  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
-  pole?: Target
-  /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat.
-   *  Unset = the end bone keeps its animated local rotation (a hand on a grip, a foot on a slope
-   *  want it set). Blended by `weight · rotationWeight`. */
-  rotation?: Node | Quat
-  /** 0–1 contribution of `rotation` (on top of `weight`). */
-  rotationWeight = 1
   /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
-  weight = 1
-  /** Solve every frame (default). Set false to drive `solve()` yourself. */
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
+  get weight(): number { return this._weight }
+  set weight(v: number) { this._weight = v; this.push() }
+  /** Solve every frame (default). */
+  get enabled(): boolean { return this._enabled }
+  set enabled(v: boolean) { this._enabled = v; this.push() }
+  /** After the last solve: how far the end bone still is from its target, metres (0 = reached). */
+  get error(): number { return this._rig && this._ik && this._rig.ikState(this._ik, stateBuf) ? stateBuf[0]! : 0 }
+
+  onAttach(): void {
+    this._rig = rigOf(this.node)
+    this._ik = this._rig.ikCreate(this.kind, this.node.id)
+    if (!this._ik) console.warn(`IK: ${this.node.name || "the bone"} is no joint of its rig (or this host has no IK)`)
+    this.push()
   }
+  onDetach(): void {
+    if (this._rig && this._ik) this._rig.ikDestroy(this._ik)
+    this._ik = 0
+    this._rig = undefined
+  }
+  onReconfigure(): void { this.push() }
+
+  protected params(): Float32Array {
+    const p = new Float32Array(P.COUNT)
+    p[P.WEIGHT] = this._weight
+    p[P.ENABLED] = this._enabled ? 1 : 0
+    p[P.LIMIT] = 80
+    p[P.AXIS + 2] = -1
+    p[P.ROT + 3] = 1
+    p[P.ANCHOR_TIME] = 0.05
+    return p
+  }
+  /** Push the description to the engine (a no-op until attached). */
+  protected abstract push(): void
+}
 
-  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const end = this.node
-    const mid = end.parent
-    const root = mid?.parent
-    if (!mid || !root) return
-
-    const w = Math.min(1, this.weight)
-    const midLocal0 = mid.quaternion
-    const rootLocal0 = root.quaternion
-
-    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
-    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
-    if (l1 < 1e-6 || l2 < 1e-6) return
-    const eps = 1e-4
-    const toT = t.sub(a)
-    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
-
-    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
-    const ba = a.sub(b), bc = c.sub(b)
-    const cur = ba.angle(bc)
-    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
-    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
-    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
-    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
-    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
-    let axis = ba.cross(bc)
-    if (axis.lengthSq() < 1e-10) {
-      // straight limb: bend toward the pole (or any perpendicular)
-      const p = targetPos(this.pole)
-      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
-      axis = ba.cross(ref)
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
-    }
-    axis = axis.normalize()
-    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
-    const midWorld = worldRot(mid)
-    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
-
-    // 2. swing the root so the end lands on the target direction
-    const c2 = end.worldPosition
-    const rootWorld = worldRot(root)
-    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
-
-    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
-    const p = targetPos(this.pole)
-    if (p) {
-      const dir = toT.normalize()
-      const b2 = mid.worldPosition
-      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
-      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
-      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
-        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
-      }
-    }
-
-    // 4. weight: blend from the animated pose to the solved one
-    if (w < 1) {
-      root.quaternion = rootLocal0.slerp(root.quaternion, w)
-      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
-    }
+/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })` solves
+ *  upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend (knee /
+ *  elbow) — a Node or world point; `anchor` makes it ride a socket of the rig instead (see the file
+ *  header). */
+class TwoBone extends Chain<"ik"> {
+  static readonly aspect = "ik"
+  protected readonly kind = 0 as const
+  private _target?: Target
+  private _pole?: Target
+  private _rotation?: Node | Quat
+  private _rotationWeight = 1
+  private _anchor = ""
+  private _anchorTime = 0.05
+  private _anchorPin = 0
+
+  /** Where the end bone should be (a Node — read by the engine every frame — or a world position). */
+  get target(): Target | undefined { return this._target }
+  set target(v: Target | undefined) { this._target = v; this.push() }
+  /** Bend hint — the mid joint is pulled toward it (a Node or a world point). */
+  get pole(): Target | undefined { return this._pole }
+  set pole(v: Target | undefined) { this._pole = v; this.push() }
+  /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat. Unset =
+   *  the end bone keeps its animated rotation (a hand on a grip, a foot on a slope want it set). Blended
+   *  by `weight · rotationWeight`. An anchored chain takes its rotation from the socket instead. */
+  get rotation(): Node | Quat | undefined { return this._rotation }
+  set rotation(v: Node | Quat | undefined) { this._rotation = v; this.push() }
+  /** 0–1 contribution of `rotation` (on top of `weight`); for an anchored chain, of the socket's turn. */
+  get rotationWeight(): number { return this._rotationWeight }
+  set rotationWeight(v: number) { this._rotationWeight = v; this.push() }
+  /** ANCHORED: the name of the LIVE socket the end bone rides (`anim.sockets(...)`) — its target and
+   *  rotation come from the socket and the playing clips' anchor spans; `target` / `pole` / `rotation`
+   *  are ignored. '' = a plain chain. */
+  get anchor(): string { return this._anchor }
+  set anchor(v: string) { this._anchor = v ?? ""; this.push() }
+  /** Anchored: how fast the hand moves between sockets — the halflife (s) of the spring the applied
+   *  delta follows the wanted one with (default 0.05). */
+  get anchorTime(): number { return this._anchorTime }
+  set anchorTime(v: number) { this._anchorTime = v; this.push() }
+  /** Anchored: 0..1 how hard the end bone is PINNED on its socket while the playing clips leave it there
+   *  (a GAP in their spans — the hand is holding the gun). 1 = it sits exactly on the socket, so nothing
+   *  in the pose below can slide it along the gun; 0 (default) = it keeps the take's own relation to the
+   *  socket, moved by the delta. A clip's SPANS carry their own pin and default to 0, because a hand on
+   *  its way to a magazine must keep the take's motion — so this knob is about holding, not reaching. */
+  get anchorPin(): number { return this._anchorPin }
+  set anchorPin(v: number) { this._anchorPin = v; this.push() }
+  /** After the last solve: the anchor delta applied — how far (m) and how much (rad) the live socket
+   *  moved the hand off the take's own pose. 0 for a plain chain. */
+  get anchorDelta(): { distance: number, angle: number } {
+    if (!this._rig || !this._ik || !this._rig.ikState(this._ik, stateBuf)) return { distance: 0, angle: 0 }
+    return { distance: stateBuf[1]!, angle: stateBuf[2]! }
+  }
 
-    // 5. end-bone rotation: take the target's world rotation (a hand stays on its grip, a foot
-    // flat on the slope) — the solve above only placed the end's ORIGIN
-    const r = this.rotation
-    if (r !== undefined && r !== null) {
-      const rw = w * Math.min(1, Math.max(0, this.rotationWeight))
-      if (rw > 0) {
-        const want = (r as Node).id !== undefined && typeof (r as Node).worldMatrix === "object" ? worldRot(r as Node) : (r as Quat)
-        const endLocal0 = end.quaternion
-        setWorldRot(end, want)
-        if (rw < 1) end.quaternion = endLocal0.slerp(end.quaternion, rw)
-      }
+  protected push(): void {
+    const rig = this._rig
+    if (!rig || !this._ik) return
+    const p = this.params()
+    p[P.ANCHOR_TIME] = this._anchorTime
+    p[P.ANCHOR_PIN] = this._anchorPin
+    const anchored = this._anchor !== ""
+    p[P.ROT_WEIGHT] = anchored || this._rotation !== undefined ? this._rotationWeight : 0
+    let targetNode = 0, poleNode = 0, rotNode = 0
+    if (!anchored) {
+      const t = this._target, pl = this._pole, r = this._rotation
+      if (isNode(t)) targetNode = t.id
+      else if (t !== undefined) { const v = new Vec3(t); p[P.TARGET] = v.x; p[P.TARGET + 1] = v.y; p[P.TARGET + 2] = v.z }
+      if (isNode(pl)) poleNode = pl.id
+      else if (pl !== undefined) { const v = new Vec3(pl); p[P.POLE] = v.x; p[P.POLE + 1] = v.y; p[P.POLE + 2] = v.z; p[P.HAS_POLE] = 1 }
+      if (isNode(r)) rotNode = r.id
+      else if (r !== undefined) { p[P.ROT] = r.x; p[P.ROT + 1] = r.y; p[P.ROT + 2] = r.z; p[P.ROT + 3] = r.w }
     }
+    rig.ikSet(this._ik, p)
+    rig.ikNodes(this._ik, targetNode, poleNode, rotNode)
+    rig.ikAnchor(this._ik, this._anchor)
   }
 }
 
@@ -153,37 +175,36 @@ class TwoBone extends Aspect<"ik", Node> {
  *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
  *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
  *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
-class LookAt extends Aspect<"lookAt", Node> {
+class LookAt extends Chain<"lookAt"> {
   static readonly aspect = "lookAt"
-
-  target?: Target
+  protected readonly kind = 1 as const
+  private _target?: Target
+  private _axis: Vec3Like = [ 0, 0, -1 ]
+  private _limit = 80
+
+  /** What to look at (a Node — read by the engine every frame — or a world position). */
+  get target(): Target | undefined { return this._target }
+  set target(v: Target | undefined) { this._target = v; this.push() }
   /** The bone's local axis that should point at the target. */
-  axis: Vec3Like = [ 0, 0, -1 ]
+  get axis(): Vec3Like { return this._axis }
+  set axis(v: Vec3Like) { this._axis = v; this.push() }
   /** Max deflection from the animated direction, in degrees (default 80). */
-  limit = 80
-  /** 0–1 contribution. */
-  weight = 1
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const bone = this.node
-    const w = Math.min(1, this.weight)
-    const local0 = bone.quaternion
-    const from = bone.worldPosition
-    const dir = t.sub(from)
-    if (dir.lengthSq() < 1e-10) return
-    const rot = worldRot(bone)
-    const current = new Vec3(this.axis).rotate(rot)
-    let delta = Quat.fromTo(current, dir)
-    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
-    setWorldRot(bone, delta.mul(rot))
-    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
+  get limit(): number { return this._limit }
+  set limit(v: number) { this._limit = v; this.push() }
+
+  protected push(): void {
+    const rig = this._rig
+    if (!rig || !this._ik) return
+    const p = this.params()
+    const a = new Vec3(this._axis)
+    p[P.AXIS] = a.x; p[P.AXIS + 1] = a.y; p[P.AXIS + 2] = a.z
+    p[P.LIMIT] = this._limit
+    let targetNode = 0
+    const t = this._target
+    if (isNode(t)) targetNode = t.id
+    else if (t !== undefined) { const v = new Vec3(t); p[P.TARGET] = v.x; p[P.TARGET + 1] = v.y; p[P.TARGET + 2] = v.z }
+    rig.ikSet(this._ik, p)
+    rig.ikNodes(this._ik, targetNode, 0, 0)
   }
 }
 

package/src/gl/animation/Locomotion.ts

@@ -37,8 +37,9 @@ 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"
+/** What the engine shows: the idle, a start, the gait loop, a turn while moving, a stop, a turn on the spot —
+ *  an ACTION (`act()`): a one-shot that owns the body until it hands over — or the STRAFE blend (`move({ strafe })`). */
+export type LocomotionState = "idle" | "start" | "move" | "turn" | "stop" | "spin" | "action" | "strafe"
 /** 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
@@ -70,6 +71,10 @@ export type LocomotionSet = {
   turns?: LocomotionClip[]
   /** turns on the spot — what a facing still owed by a standing body plays */
   spins?: LocomotionClip[]
+  /** the STRAFE set: the same gait recorded forward, backward, to either side and on the diagonals — the members of
+   *  the directional blend `move(dir, { face, strafe: true })` shows. `angle` = the way a take travels in the body's
+   *  frame (degrees, + = left); left out, the engine reads it off the take's root. */
+  strafes?: LocomotionClip[]
 }
 
 /** The tuning. Times are seconds, speeds m/s, angles degrees. */
@@ -201,7 +206,7 @@ export type StopCandidate = {
 
 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 IN = { DIR_X: 0, DIR_Z: 1, MAG: 2, FACE_X: 3, FACE_Z: 4, GAIT: 5, ACT_SEQ: 6, ACT_SLOT: 7, ACT_DIR_X: 8, ACT_DIR_Z: 9, ACT_ANGLE: 10, ACT_TURN: 11, ACT_AT: 12, ACT_EXIT: 13, ACT_FADE: 14, ACT_RATE: 15, ACT_OUT: 16, ACT_TRAVEL: 17, ACT_TRAVEL_AT: 18, ACT_TRAVEL_AFTER: 19, STRAFE: 20, COUNT: 21 }
 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,
@@ -210,8 +215,8 @@ const P = {
   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 KIND = { IDLE: 0, GAIT: 1, START: 2, STOP: 3, TURN: 4, MATCH: 5, SPIN: 6, STRAFE: 8 }
+const STATES: LocomotionState[] = [ "idle", "start", "move", "turn", "stop", "spin", "action", "strafe" ]
 const GAITS: Gait[] = [ "walk", "run", "sprint" ]
 const RAD2DEG = 180 / Math.PI
 
@@ -249,6 +254,8 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
   private _mag = 0
   private _gait: Gait = "walk"
   private _seq = -1
+  private _act = 0
+  private _strafe = false
   private readonly _in = new Float32Array(IN.COUNT)
   private readonly _out = new Float32Array(OUT.COUNT)
   private readonly _names = new Map<number, string>()
@@ -290,6 +297,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     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)
+    for (const c of this.set.strafes ?? []) this.enter(c, KIND.STRAFE)
     if (this.warp !== undefined) anim.warp.set(this.warp)
     anim.feet.set(this.feet === undefined ? { lock: true } : this.feet === true ? { lock: true, ik: true } : this.feet === false ? { lock: false, ik: false } : this.feet)
     this.pushTuning()
@@ -306,7 +314,8 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     this._names.set(slot, n)
     const o = typeof clip === "string" ? undefined : clip
     const measured = anim.clipInfo(n)
-    const angle = o?.angle ?? (measured ? measured.turn * RAD2DEG : 0)
+    // (a strafe member's angle is the way it TRAVELS, which the engine reads off its root: 1000 = measure)
+    const angle = o?.angle ?? (kind === KIND.STRAFE ? 1000 : 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)
   }
@@ -379,8 +388,11 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
   /** 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 {
+   *  `face` states a facing of its own (aiming, a camera-relative shooter) — and with `strafe: true` the body MOVES
+   *  where the direction points while it faces there: the loop becomes the directional blend of `set.strafes` (a
+   *  guard, a lock-on), the facing is steered standing too, state `'strafe'`. Stated every frame like the rest. */
+  move(direction: Vec3Like | null | undefined, options: { gait?: Gait, face?: Vec3Like, strafe?: boolean } = {}): void {
+    this._strafe = !!options.strafe
     const dx = direction ? cx(direction) : 0, dz = direction ? cz(direction) : 0
     const len = Math.hypot(dx, dz)
     if (len > 1e-4) {
@@ -395,6 +407,57 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     if (options.gait) this._gait = options.gait
   }
 
+  /** Play an ACTION: a one-shot that OWNS the body the way a start or a stop does — a roll, a backstep, a lunging
+   *  attack. Its recording moves the body alone (in every displacement mode but `'data'`, where the host does),
+   *  the steering and the selector stand by, and when it hands over the usual rules carry on: a direction held
+   *  starts (or, still carrying speed, runs on), nothing held stands.
+   *
+   *  `direction` is where its TRAVEL must go, world (`Vec3`, or a heading in degrees, 0 = +Z, + = toward +X). A
+   *  clip travels some way relative to the body — forward, left, back; measured off its own root, or `angle`
+   *  (degrees, + = left) — and the body is turned by what is left between that and `direction`, over `turn`
+   *  seconds (default 0.12), so the travel lands exactly where it was pointed. Which clip to play is yours to
+   *  pick: the one whose travel is nearest the direction IN THE BODY'S FRAME (`direction − facing`) leaves the
+   *  least to turn. Left out = it plays where the body faces.
+   *
+   *  `at` enters the clip that many seconds in (a wind-up skipped), `rate` plays it faster or slower (its metres
+   *  stay, the time changes), `travel` takes only that share of its recorded travel (an attack aimed at a target:
+   *  0.3 to stop at the blade's length from one that is close, 1.3 to reach one a step too far — the pose is
+   *  untouched, so keep it to a fast step; `{ share, at, after }` takes another share from clip time `at` on: a
+   *  swing's take travels on after its cut, into a body that stands at the blade's length), `fade` is the transition into it and `out` the one out of it (default: the tuning's
+   *  `blend`; an action ends in ITS stance, not the idle's, and a longer way out is what hides that), and `exit` is the
+   *  clip time from which a MOVE intent may take over — the cancel window: along the way the body faces at once, a
+   *  heading that needs a turn as soon as the body has slowed to where a start can answer; with nothing asked for it plays out, to
+   *  its end (an action ends in its own recovery, at rest), and the body then STANDS THE WAY THE ACTION LEFT IT:
+   *  the facing intent that outlives a released key is not a demand after an action — no turn on the spot.
+   *  WHEN an action may be asked for (out of another one, out of a start) is the caller's rule: this cuts into
+   *  whatever shows. `state` reads `'action'` while it does. False = no such clip. */
+  act(clip: string, options: { direction?: Vec3Like | number, angle?: number, turn?: number, at?: number, exit?: number, fade?: number, out?: number, rate?: number, travel?: number | { share: number, at: number, after: number } } = {}): boolean {
+    const anim = this.anim
+    if (!anim || !this._loco) return false
+    const slot = anim._slot(clip)
+    if (slot < 0) { console.warn(`Locomotion: no clip '${clip}' on ${this.node.name || "the character"}`); return false }
+    const i = this._in
+    let dx = 0, dz = 0
+    const d = options.direction
+    if (typeof d === "number") { dx = Math.sin(d / RAD2DEG); dz = Math.cos(d / RAD2DEG) }
+    else if (d) { dx = cx(d); dz = cz(d) }
+    i[IN.ACT_SEQ] = ++this._act
+    i[IN.ACT_SLOT] = slot
+    i[IN.ACT_DIR_X] = dx; i[IN.ACT_DIR_Z] = dz
+    i[IN.ACT_ANGLE] = options.angle ?? 1000            // 1000 = measure the clip's own travel
+    i[IN.ACT_TURN] = options.turn ?? 0.12
+    i[IN.ACT_AT] = options.at ?? 0
+    i[IN.ACT_EXIT] = options.exit ?? 0
+    i[IN.ACT_FADE] = options.fade ?? 0
+    i[IN.ACT_RATE] = options.rate ?? 0
+    i[IN.ACT_OUT] = options.out ?? 0
+    const tr = options.travel
+    i[IN.ACT_TRAVEL] = typeof tr === "number" ? tr : tr?.share ?? 0
+    i[IN.ACT_TRAVEL_AT] = typeof tr === "object" ? tr.at : 0
+    i[IN.ACT_TRAVEL_AFTER] = typeof tr === "object" ? tr.after : 0
+    return true
+  }
+
   /** 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 {
@@ -477,6 +540,7 @@ export class Locomotion extends Aspect<"loco", Node, LocomotionEvents> {
     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))
+    i[IN.STRAFE] = this._strafe ? 1 : 0
     _creator.locoSetInput(this._loco, i)
     _creator.locoUpdate(this._loco, dt)
     _creator.locoRead(this._loco, this._out)

package/src/gl/animation/Playback.ts

@@ -1,8 +1,9 @@
 // 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).
+// resolves at the clip's HAND-OVER — its end (the `end` of its window) — with `true`; `false` when it
+// was cut short (replaced / stopped). What you call right after the await is what its last pose
+// transitions into: `anim.play(next)` (a chained one-shot), `anim.playLoop(next)` — nothing = back to
+// the loop over `fadeOut` (or hold, on a layer without one). A cancel window is game logic (a clip
+// event, `progress`, `busy`), not a fade: play the next clip whenever the game says so.
 // 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.
 

package/src/gl/animation/Warp.ts

@@ -2,7 +2,9 @@
 // before the feet (docs/animation-v2-plan.md §2.7). `stride` scales each leg's step to the speed the body
 // really travels at (a walk played at 1.9 m/s stops skating); `orientation` turns the lower body toward
 // where the body really goes while the spine counter-turns (arcs and strafing without a clip per angle).
-// Both need the body's motion, which a `Locomotion` feeds every frame; without one leave it off. Off by
+// Both need the body's motion — a `Locomotion` feeds it every frame, or `anim.motion = velocity` when the
+// gait is driven by hand; without either leave it off — and the CLIP's motion: its root motion, or for an
+// in-place loop the pace its pack declared (`lecodes.velocity` in the GLB animation's extras). Off by
 // default. `step` is the STEP WARP: stride / lift / pitch / slope dials solved in the knee hinge plane.
 //
 //   model.anim.warp.set(true)                                       // both, with the defaults
@@ -16,7 +18,8 @@ import type { Core } from "./core"
 export type WarpOptions = {
   /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale (default
    *  0.85…1.2). A CORRECTION: a pack whose takes already read right at the speeds it is played at wants
-   *  none of this; open the range for a pack that must cover speeds it was never recorded at. */
+   *  none of this; open the range for a pack that must cover speeds it was never recorded at. The clip's
+   *  own speed is its root motion — an in-place loop takes part only with a declared pace (see above). */
   stride?: boolean | [number, number]
   /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
    *  (default 20). The whole twist lives in one joint: a few degrees read as a lean, a lot as a broken