lecodes-sdk 1.0.0 → 1.1.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/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

package/src/gl/animation/core.ts

@@ -25,15 +25,24 @@ export type PlayOptions = {
   fade?: number
   /** Transition seconds for the way in only (overrides `fade`). */
   fadeIn?: number
-  /** One-shots: the transition BACK to the loop at the end (overrides `fade`; `0` = cut at the end).
-   *  It starts this long before the clip ends — while it still plays — so the hand-over lands on the
-   *  last pose, not after it. On a layer with no loop the clip HOLDS its last frame (a rock that broke
-   *  stays broken) — `anim.stop({ fade })` is the way back to rest. */
+  /** One-shots: the transition BACK to the loop after the end (overrides `fade`; `0` = cut at the end).
+   *  The clip plays to its last frame; the loop then takes over and the difference between the two poses
+   *  (and their velocities) decays over this time, so no part of the clip is cut — to play less of it,
+   *  give it an `end`. On a layer with no loop the clip HOLDS its last frame (a rock that broke stays
+   *  broken) — `anim.stop({ fade })` is the way back to rest. */
   fadeOut?: number
   /** Playback rate for this clip (default 1). */
   speed?: number
   /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
   restart?: boolean
+  /** Play a WINDOW of the clip, seconds of the clip: enter at `start` (default 0; only when the play
+   *  rewinds — see `restart`) and treat `end` (default the clip's end) as the end — the hand-over fires
+   *  there, the last frame held there, events beyond it never fire. Only the swing of a longer take, the
+   *  wind-up without the recovery. A window that lives in the clip table belongs in
+   *  `AnimationClip.from(clip, { from, to })` instead. Not combined with `phase`. Hosts without the
+   *  window play the whole clip. */
+  start?: number
+  end?: number
   /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
    *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
    *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
@@ -293,6 +302,12 @@ export class Core {
   ensure(): boolean {
     if (this.id) return true
     if (this.embedded().length === 0 && this.table.size === 0) { console.warn(`Animator: no clips on ${this.node.name || "the node"} — nothing to play`); return false }
+    return this.ensureRig()
+  }
+  /** The native animator for the RIG alone — an IK chain or a socket on a model that has no clips
+   *  still needs the joint tree described to the engine. False = no transform hierarchy (warned). */
+  ensureRig(): boolean {
+    if (this.id) return true
     ensureEvents()
     this.id = _creator.animatorCreate(this.node.id)
     if (!this.id) { console.warn("Animator: node has no transform hierarchy"); return false }
@@ -303,6 +318,7 @@ export class Core {
     if (this._feetParams && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, this._feetParams)
     if (this.speed !== 1) _creator.animatorSetGlobal(this.id, this.speed, false)
     for (const L of this.layers) if (L.index > 0) this.pushLayer(L)
+    for (const s of this._sockets.values()) this.pushSocket(s)
     return true
   }
   destroy(): void {
@@ -378,6 +394,11 @@ export class Core {
     s.playback = rec
     _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
     if (o.turn !== undefined) _creator.animatorSlotSetTurn?.(this.id, s.slot, o.turn * Math.PI / 180, true)
+    if (o.start !== undefined || o.end !== undefined) {
+      const st = Math.max(0, o.start ?? 0), en = o.end === undefined ? -1 : Math.min(o.end, clip.duration)
+      if (en >= 0 && en <= st) console.warn(`Animator: '${name}' window ${st}–${o.end} is empty (${clip.duration.toFixed(2)}s clip)`)
+      _creator.animatorSlotSetWindow?.(this.id, s.slot, st, en)
+    }
     if (phase !== undefined) _creator.animatorSeekPhase(this.id, s.slot, phase)
     return new Playback(rec, this)
   }
@@ -671,6 +692,11 @@ export class Core {
     this._warp = params
     if (this.id) _creator.animatorSetWarpParams(this.id, params)
   }
+  /** The body's world velocity this frame (m/s) — the game side of the stride / orientation fit. Nothing
+   *  to feed before the animator exists; hosts without the warp stage have no method. */
+  setMotion(vx: number, vy: number, vz: number): void {
+    if (this.id && _creator.animatorSetMotion) _creator.animatorSetMotion(this.id, vx, vy, vz)
+  }
   /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
   private _feetParams?: Float32Array
   setFeetParams(params: Float32Array): void {
@@ -682,6 +708,41 @@ export class Core {
   footState(side: 0 | 1, out: Float32Array): boolean {
     return this.id !== 0 && _creator.animatorFootState !== undefined && _creator.animatorFootState(this.id, side, out)
   }
+  // ---- IK chains + sockets (creator-anim anchors.cpp; the aspects in IK.ts) ----
+  // Hosts without the chains (an engine predating them) get a warning once and inert chains.
+  private static _warnedIk = false
+  private hasIk(): boolean {
+    if (_creator.animatorIkCreate) return true
+    if (!Core._warnedIk) { Core._warnedIk = true; console.warn("IK: this host has no IK chains (engine predates them) — chains and sockets are inert") }
+    return false
+  }
+  /** A chain ending in `endEntity` (kind 0 two-bone: the bone, its parent, its grandparent; 1 look-at). 0 = none. */
+  ikCreate(kind: 0 | 1, endEntity: number): number {
+    if (!this.ensureRig() || !this.hasIk()) return 0
+    return _creator.animatorIkCreate!(this.id, kind, endEntity)
+  }
+  ikDestroy(ik: number): void { if (this.id && _creator.animatorIkDestroy) _creator.animatorIkDestroy(this.id, ik) }
+  ikSet(ik: number, params: Float32Array): void { if (this.id && _creator.animatorIkSet) _creator.animatorIkSet(this.id, ik, params) }
+  ikNodes(ik: number, target: number, pole: number, rotation: number): void { if (this.id && _creator.animatorIkNodes) _creator.animatorIkNodes(this.id, ik, target, pole, rotation) }
+  ikAnchor(ik: number, socket: string): void { if (this.id && _creator.animatorIkAnchor) _creator.animatorIkAnchor(this.id, ik, socket) }
+  ikState(ik: number, out: Float32Array): boolean { return this.id !== 0 && _creator.animatorIkState !== undefined && _creator.animatorIkState(this.id, ik, out) }
+  /** Sockets by "set/name", replayed when the animator is (re)created. */
+  private readonly _sockets = new Map<string, { set: string, name: string, joint: number, node: number, trs: Float32Array | null }>()
+  /** Define a socket on joint `joint` (a bone's entity): a NODE socket (read by the engine every frame) or a
+   *  fixed TRS in the joint's space. set "" = the live set, any other name = a donor's. */
+  setSocket(set: string, name: string, joint: number, node: number, trs: Float32Array | null): void {
+    const rec = { set, name, joint, node, trs }
+    this._sockets.set(`${set}/${name}`, rec)
+    if (this.ensureRig()) this.pushSocket(rec)
+  }
+  removeSocket(set: string, name: string): void {
+    this._sockets.delete(`${set}/${name}`)
+    if (this.id && _creator.animatorSetSocket) _creator.animatorSetSocket(this.id, set, name, 0, 0, null)
+  }
+  private pushSocket(s: { set: string, name: string, joint: number, node: number, trs: Float32Array | null }): void {
+    if (this.hasIk() && _creator.animatorSetSocket) _creator.animatorSetSocket(this.id, s.set, s.name, s.joint, s.node, s.trs)
+  }
+
   private readonly _steps = new Set<StepHandler>()
   onStepHandler(cb: StepHandler): void { this._steps.add(cb) }
   offStepHandler(cb: StepHandler): void { this._steps.delete(cb) }