@aura3d/animation 1.0.6 → 1.3.0

package/src/HumanoidRetargeting.ts

@@ -108,6 +108,14 @@ export interface HumanoidBoneRetargetBinding {
   readonly source: HumanoidBoneBinding;
   readonly target: HumanoidBoneBinding;
   readonly scale: number;
+  /**
+   * Source rig rest-pose local rotation for this bone (identity when unknown). Captured at
+   * map-build time from `source.restPose[bone].rotation` or the binding's own `rotation` so the
+   * pose retargeter can reconcile differing bind orientations without re-reading the rigs.
+   */
+  readonly sourceRest?: AnimationQuaternion;
+  /** Target rig rest-pose local rotation for this bone (identity when unknown). */
+  readonly targetRest?: AnimationQuaternion;
 }
 
 export interface HumanoidRetargetingMap {
@@ -118,6 +126,10 @@ export interface HumanoidRetargetingMap {
   readonly requiredCoverage: number;
   readonly bindings: Partial<Record<HumanoidBoneName, HumanoidBoneRetargetBinding>>;
   readonly diagnostics: readonly HumanoidRetargetingDiagnostic[];
+  /** Source rig facing axis (defaults to `"z"`) used for hip/root facing reconciliation. */
+  readonly sourceFacingAxis?: HumanoidAxis;
+  /** Target rig facing axis (defaults to `"z"`) used for hip/root facing reconciliation. */
+  readonly targetFacingAxis?: HumanoidAxis;
 }
 
 export interface RetargetHumanoidPoseOptions {
@@ -126,6 +138,20 @@ export interface RetargetHumanoidPoseOptions {
   readonly scaleRootMotion?: boolean;
 }
 
+export interface AnimationHumanoidRetargetingOptions extends HumanoidRetargetingOptions {
+  readonly requiredClips?: readonly string[];
+  readonly availableClips?: readonly string[];
+  readonly mouthBlendshapeNames?: readonly string[];
+  readonly retargetMapProvided?: boolean;
+}
+
+export interface AnimationHumanoidRetargetingDiagnostics extends HumanoidRigDiagnostics {
+  readonly kind: "animation-humanoid-retargeting-diagnostics";
+  readonly mouthReady: boolean;
+  readonly clipReady: boolean;
+  readonly retargetMapProvided: boolean;
+}
+
 export function analyzeHumanoidRig(
   rig: HumanoidRigDefinition,
   options: HumanoidRetargetingOptions = {}
@@ -313,7 +339,9 @@ export function createHumanoidRetargetingMap(
       bone,
       source: sourceBinding,
       target: targetBinding,
-      scale: estimateBoneScale(sourceBinding, targetBinding, source.scale, target.scale)
+      scale: estimateBoneScale(sourceBinding, targetBinding, source.scale, target.scale),
+      sourceRest: restRotationFor(source, bone, sourceBinding),
+      targetRest: restRotationFor(target, bone, targetBinding)
     };
   }
 
@@ -337,10 +365,44 @@ export function createHumanoidRetargetingMap(
     coverage,
     requiredCoverage,
     bindings,
-    diagnostics
+    diagnostics,
+    sourceFacingAxis: source.facingAxis ?? "z",
+    targetFacingAxis: target.facingAxis ?? "z"
   };
 }
 
+/**
+ * Retarget a source-rig {@link AnimationPose} onto the target rig described by `map`.
+ *
+ * This is NOT a 1:1 rotation copy. For each bone we reconcile differing rest/bind orientations and
+ * a differing facing axis, and scale translations by the per-bone length ratio:
+ *
+ *   1. Rest-pose reconciliation (per bone, local space). Let `Rs0` be the source rest local
+ *      rotation and `Rt0` the target rest local rotation (both from the rigs' `restPose`/binding
+ *      `rotation`, identity when unknown). An animation expresses a source local rotation `Ra`.
+ *      The motion *away from rest* in the source's local frame is the delta `D = Rs0⁻¹ · Ra`. We
+ *      re-anchor that delta onto the target rest: `Rt = Rt0 · D = Rt0 · Rs0⁻¹ · Ra`.
+ *      When both rests are identity (or equal) this collapses to a straight copy, and an identity
+ *      map (source rig === target rig) is therefore a no-op.
+ *
+ *   2. Facing-axis / coordinate-frame conversion. If the source faces a different cardinal axis
+ *      than the target, the hips (root) rotation is pre-multiplied by the frame-alignment rotation
+ *      `F` that carries the source facing axis onto the target facing axis: `Rt_hips = F · Rt_hips`.
+ *      This only touches the root so child bones inherit the reframe through the hierarchy.
+ *
+ *   3. Position / hip-height scaling (unchanged from before): translations are scaled by the
+ *      bone's length ratio (`binding.scale`), and optional root motion by the average bone scale.
+ *
+ * The signature and return type are unchanged.
+ *
+ * Honesty note: step 1 is the well-known "rest-delta" reconciliation. It is exact when the source
+ * and target rest orientations are the bones' true local bind rotations and the bones are mapped
+ * one-to-one (the common case for humanoid GLBs). It does NOT model differing bone *roll* beyond
+ * what the rest rotations capture, nor parent-chain reparametrization when intermediate bones
+ * (e.g. chest/upperChest) are present on one rig and absent on the other — those remain
+ * approximate. Step 2 corrects whole-body facing only via the root; per-limb axis remaps that
+ * aren't expressible as a single root rotation are not handled.
+ */
 export function retargetHumanoidPose(
   sourcePose: AnimationPose,
   map: HumanoidRetargetingMap,
@@ -354,6 +416,8 @@ export function retargetHumanoidPose(
     }
   }
 
+  const facing = facingAlignmentQuat(map.sourceFacingAxis ?? "z", map.targetFacingAxis ?? "z");
+
   for (const bone of HUMANOID_BONES) {
     const binding = map.bindings[bone];
     if (!binding) continue;
@@ -361,7 +425,7 @@ export function retargetHumanoidPose(
     const sourceTransform = sourcePose.bones[binding.source.name] ?? sourcePose.bones[bone];
     if (!sourceTransform) continue;
 
-    const retargeted = scaleTransform(sourceTransform, binding.scale);
+    const retargeted = retargetBoneTransform(sourceTransform, binding, bone === "hips" ? facing : undefined);
     bones[binding.target.name] = retargeted;
 
     if (options.includeSemanticBoneNames) {
@@ -397,6 +461,55 @@ export function humanoidRetargetingDiagnostics(
   return createHumanoidRetargetingMap(source, target, options).diagnostics;
 }
 
+export function analyzeAnimationHumanoidRetargeting(
+  rig: HumanoidRigDefinition,
+  options: AnimationHumanoidRetargetingOptions = {}
+): AnimationHumanoidRetargetingDiagnostics {
+  const base = analyzeHumanoidRig(rig, { minRequiredCoverage: 0.9, requireRestPose: true, ...options });
+  const diagnostics: HumanoidRetargetingDiagnostic[] = [...base.diagnostics];
+  const requiredClips = options.requiredClips ?? ["Idle", "Talk", "Gesture", "Walk"];
+  const availableClips = new Set(options.availableClips ?? []);
+  const missingClips = requiredClips.filter((clip) => !availableClips.has(clip));
+  const mouthReady = (options.mouthBlendshapeNames?.length ?? 0) > 0
+    || Array.isArray(rig.metadata?.mouthBlendshapeNames) && (rig.metadata.mouthBlendshapeNames as unknown[]).length > 0;
+  const retargetMapProvided = options.retargetMapProvided ?? Boolean(rig.metadata?.retargetMapProvided);
+
+  if (!mouthReady) {
+    diagnostics.push({
+      severity: "error",
+      code: "ANIMATION_MOUTH_METADATA_MISSING",
+      message: "Animation retargeting requires mouth blendshape or mouth-card metadata.",
+      rigId: rig.id
+    });
+  }
+  for (const clip of missingClips) {
+    diagnostics.push({
+      severity: "error",
+      code: "ANIMATION_REQUIRED_CLIP_MISSING",
+      message: `Animation retargeting requires clip "${clip}".`,
+      rigId: rig.id
+    });
+  }
+  if (!retargetMapProvided) {
+    diagnostics.push({
+      severity: "error",
+      code: "ANIMATION_RETARGET_MAP_MISSING",
+      message: "Animation retargeting requires external bone-map/retarget metadata.",
+      rigId: rig.id
+    });
+  }
+
+  return {
+    kind: "animation-humanoid-retargeting-diagnostics",
+    ...base,
+    ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+    diagnostics,
+    mouthReady,
+    clipReady: missingClips.length === 0,
+    retargetMapProvided
+  };
+}
+
 const HUMANOID_SIDE_PAIRS: readonly { readonly left: HumanoidBoneName; readonly right: HumanoidBoneName }[] = [
   { left: "leftShoulder", right: "rightShoulder" },
   { left: "leftUpperArm", right: "rightUpperArm" },
@@ -447,14 +560,125 @@ function averageBindingScale(map: HumanoidRetargetingMap): number {
   return scales.reduce((sum, scale) => sum + scale, 0) / scales.length;
 }
 
-function scaleTransform(transform: AnimationPoseTransform, scale: number): AnimationPoseTransform {
+const IDENTITY_QUAT: AnimationQuaternion = { x: 0, y: 0, z: 0, w: 1 };
+
+/**
+ * Extract the rest local rotation for a bone, preferring the rig's explicit `restPose` entry and
+ * falling back to the binding's own `rotation`. Returns identity when neither is present.
+ */
+function restRotationFor(
+  rig: HumanoidRigDefinition,
+  bone: HumanoidBoneName,
+  binding: HumanoidBoneBinding
+): AnimationQuaternion {
+  const fromRestPose = rig.restPose?.[bone]?.rotation;
+  if (fromRestPose) return normalizeQuatObj(fromRestPose);
+  if (binding.rotation) return normalizeQuatObj(binding.rotation);
+  return IDENTITY_QUAT;
+}
+
+/**
+ * Apply rest-pose reconciliation + (root-only) facing alignment + length scaling to one bone.
+ * See {@link retargetHumanoidPose} for the math derivation.
+ */
+function retargetBoneTransform(
+  transform: AnimationPoseTransform,
+  binding: HumanoidBoneRetargetBinding,
+  facing?: AnimationQuaternion
+): AnimationPoseTransform {
+  const sourceRest = binding.sourceRest ?? IDENTITY_QUAT;
+  const targetRest = binding.targetRest ?? IDENTITY_QUAT;
+
+  let rotation = transform.rotation;
+  if (rotation) {
+    // Rt = Rt0 · Rs0⁻¹ · Ra
+    const delta = multiplyQuat(invertQuat(sourceRest), normalizeQuatObj(rotation));
+    rotation = multiplyQuat(targetRest, delta);
+    if (facing) {
+      // Whole-body facing correction, applied on the root before its local rotation.
+      rotation = multiplyQuat(facing, rotation);
+    }
+    rotation = normalizeQuatObj(rotation);
+  } else if (facing) {
+    // No animated rotation but a facing delta still needs to reframe the root.
+    rotation = normalizeQuatObj(multiplyQuat(facing, targetRest));
+  }
+
   return {
-    position: transform.position ? scaleVector(transform.position, scale) : undefined,
-    rotation: transform.rotation,
+    position: transform.position ? scaleVector(transform.position, binding.scale) : undefined,
+    rotation,
     scale: transform.scale
   };
 }
 
+/**
+ * Rotation that carries `from` cardinal axis onto `to` cardinal axis (shortest arc). Used to
+ * reconcile rigs that face different world axes (e.g. +Z forward vs -Z forward, or +X vs +Z).
+ */
+function facingAlignmentQuat(from: HumanoidAxis, to: HumanoidAxis): AnimationQuaternion | undefined {
+  if (from === to) return undefined;
+  const a = axisVector(from);
+  const b = axisVector(to);
+  return shortestArcQuat(a, b);
+}
+
+function axisVector(axis: HumanoidAxis): AnimationVector3 {
+  switch (axis) {
+    case "x": return { x: 1, y: 0, z: 0 };
+    case "-x": return { x: -1, y: 0, z: 0 };
+    case "y": return { x: 0, y: 1, z: 0 };
+    case "-y": return { x: 0, y: -1, z: 0 };
+    case "z": return { x: 0, y: 0, z: 1 };
+    case "-z": return { x: 0, y: 0, z: -1 };
+    default: return { x: 0, y: 0, z: 1 };
+  }
+}
+
+/** Quaternion of the shortest rotation from unit vector `a` to unit vector `b`. */
+function shortestArcQuat(a: AnimationVector3, b: AnimationVector3): AnimationQuaternion {
+  const dot = a.x * b.x + a.y * b.y + a.z * b.z;
+  if (dot >= 1 - 1e-8) return IDENTITY_QUAT;
+  if (dot <= -1 + 1e-8) {
+    // Opposite vectors: rotate 180° about any axis orthogonal to a.
+    let ortho: AnimationVector3 = Math.abs(a.x) < 0.9 ? { x: 1, y: 0, z: 0 } : { x: 0, y: 1, z: 0 };
+    ortho = crossVec(a, ortho);
+    const len = Math.hypot(ortho.x, ortho.y, ortho.z) || 1;
+    return normalizeQuatObj({ x: ortho.x / len, y: ortho.y / len, z: ortho.z / len, w: 0 });
+  }
+  const c = crossVec(a, b);
+  const w = 1 + dot;
+  return normalizeQuatObj({ x: c.x, y: c.y, z: c.z, w });
+}
+
+function crossVec(a: AnimationVector3, b: AnimationVector3): AnimationVector3 {
+  return {
+    x: a.y * b.z - a.z * b.y,
+    y: a.z * b.x - a.x * b.z,
+    z: a.x * b.y - a.y * b.x
+  };
+}
+
+function multiplyQuat(a: AnimationQuaternion, b: AnimationQuaternion): AnimationQuaternion {
+  return {
+    x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+    y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+    z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+    w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z
+  };
+}
+
+function invertQuat(q: AnimationQuaternion): AnimationQuaternion {
+  // Unit quaternion inverse is its conjugate; normalize defensively first.
+  const n = normalizeQuatObj(q);
+  return { x: -n.x, y: -n.y, z: -n.z, w: n.w };
+}
+
+function normalizeQuatObj(q: AnimationQuaternion): AnimationQuaternion {
+  const len = Math.hypot(q.x, q.y, q.z, q.w);
+  if (len <= 1e-9) return IDENTITY_QUAT;
+  return { x: q.x / len, y: q.y / len, z: q.z / len, w: q.w / len };
+}
+
 function cloneTransform(transform: AnimationPoseTransform): AnimationPoseTransform {
   return {
     position: transform.position ? { ...transform.position } : undefined,

package/src/IK.ts

@@ -62,6 +62,16 @@ export function solveTwoBoneIk(input: TwoBoneIkInput): TwoBoneIkResult {
   };
 }
 
+/**
+ * Convenience knee/elbow pole hint: a point offset from the mid-joint along a forward direction,
+ * giving {@link solveTwoBoneIk} a stable bend plane (knees point forward, elbows back). Pure.
+ */
+export function kneePoleHint(root: Vec3, mid: Vec3, forward: Vec3, distance = 1): Vec3 {
+  const dir = normalize(forward);
+  const center: Vec3 = [(root[0] + mid[0]) / 2, (root[1] + mid[1]) / 2, (root[2] + mid[2]) / 2];
+  return [center[0] + dir[0] * distance, center[1] + dir[1] * distance, center[2] + dir[2] * distance];
+}
+
 function projectedPoleDirection(root: Vec3, axis: Vec3, pole: Vec3): Vec3 {
   const poleDelta = subtract(pole, root);
   const projected = subtract(poleDelta, scale(axis, dot(poleDelta, axis)));

package/src/Inertialization.ts

@@ -0,0 +1,269 @@
+// Inertialization: a critically-damped decay of the *pose offset* captured at the moment a
+// transition begins, added on top of the destination pose. Unlike a linear crossfade (which
+// interpolates two clips by a straight ramp and visibly "snaps" its slope at both ends), an
+// inertialized transition starts the destination pose already offset by the source pose's
+// difference (and optionally its velocity), then lets that offset decay smoothly to zero. The
+// result is C1-continuous at the transition boundary: no velocity discontinuity, so motion
+// "carries through" the swap instead of dissolving.
+//
+// This module is pure and deterministic: no `Date.now()`, no `Math.random()`, no engine/render
+// imports. Given the same inputs and the same `t` it always returns the same result, so it is
+// safe inside deterministic replay (combat sims) and reproducible tests.
+//
+// Two layers are provided:
+//   1. Scalar / vector / quaternion offset primitives (`inertializedScalar`, ...).
+//   2. A pose-space `Inertializer` that records a transition between two `AnimationValue` poses
+//      and samples the inertialized pose at a given time.
+// Plus a weight-domain helper (`inertializedTransitionWeight`) for consumers that blend two
+// clips by weight (e.g. the fighter adapter / `applyClips` call sites) rather than by pose.
+
+import {
+  cloneAnimationValue,
+  normalizeQuat,
+  type AnimationValue,
+  type Quat,
+  type Vec3
+} from "./Keyframe.js";
+
+const LN2 = Math.log(2);
+
+/** Default transition half-life in seconds. ~0.12s reads as a snappy-but-smooth swap. */
+export const DEFAULT_INERTIALIZATION_HALF_LIFE = 0.12;
+
+/**
+ * Decay rate `k` (1/seconds) for a given half-life. The critically-damped envelope used here is
+ * `(1 + k·t)·e^(−k·t)`; because of the `(1 + k·t)` term the offset is not exactly halved at
+ * `t = halfLife` (it crosses 0.5 a little later) — `halfLife` parameterizes the e-folding decay
+ * rate, not a literal 50%-crossing time. A non-positive half-life means an instant snap (rate ∞).
+ */
+export function inertializationDecayRate(halfLife: number): number {
+  if (!Number.isFinite(halfLife) || halfLife <= 0) return Number.POSITIVE_INFINITY;
+  return LN2 / halfLife;
+}
+
+/**
+ * Critically-damped decay of a scalar offset `offset0` with initial velocity `velocity0`,
+ * sampled at time `t` (seconds) since the transition. Decays smoothly to zero; preserves the
+ * initial velocity at `t = 0` (so momentum carries through). Deterministic.
+ */
+export function inertializedScalar(offset0: number, velocity0: number, t: number, halfLife: number): number {
+  if (!(t > 0)) return offset0;
+  const k = inertializationDecayRate(halfLife);
+  if (!Number.isFinite(k)) return 0; // instant snap
+  // x(t) = (x0 + (v0 + k·x0)·t)·e^(−k·t);  x(0)=x0, x'(0)=v0, x(∞)=0.
+  return (offset0 + (velocity0 + k * offset0) * t) * Math.exp(-k * t);
+}
+
+/**
+ * Source-clip weight for an inertialized transition, decaying from 1 → 0 with zero initial slope
+ * (critically damped, monotonic). The destination weight is `1 − thisWeight`. A drop-in,
+ * smoother replacement for a linear `1 − t/duration` ramp. `elapsed`/`halfLife` in seconds.
+ */
+export function inertializedTransitionWeight(elapsed: number, halfLife: number): number {
+  if (!(elapsed > 0)) return 1;
+  const k = inertializationDecayRate(halfLife);
+  if (!Number.isFinite(k)) return 0; // instant snap
+  const w = (1 + k * elapsed) * Math.exp(-k * elapsed);
+  return w < 0 ? 0 : w > 1 ? 1 : w;
+}
+
+/** Vector3 offset decay (per-component critically-damped). `velocity0` defaults to zero. */
+export function inertializedVec3(offset0: Vec3, t: number, halfLife: number, velocity0: Vec3 = [0, 0, 0]): Vec3 {
+  return [
+    inertializedScalar(offset0[0], velocity0[0], t, halfLife),
+    inertializedScalar(offset0[1], velocity0[1], t, halfLife),
+    inertializedScalar(offset0[2], velocity0[2], t, halfLife)
+  ];
+}
+
+// ---- quaternion helpers (local; unit-quaternion algebra) -------------------------------------
+
+function quatConjugate(q: Quat): Quat {
+  return [-q[0], -q[1], -q[2], q[3]];
+}
+
+function quatMultiply(a: Quat, b: Quat): Quat {
+  return [
+    a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+    a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+    a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+    a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2]
+  ];
+}
+
+/** Shortest-arc axis/angle of a unit quaternion; angle in [0, π], axis normalized (or +X). */
+function quatToAxisAngle(q: Quat): { axis: Vec3; angle: number } {
+  const n = normalizeQuat(q);
+  // Force the shorter arc (w >= 0) so the decayed rotation never takes the long way around.
+  const w = n[3] < 0 ? -n[3] : n[3];
+  const sign = n[3] < 0 ? -1 : 1;
+  const angle = 2 * Math.acos(Math.min(1, w));
+  const s = Math.sqrt(Math.max(0, 1 - w * w));
+  if (s < 1e-8) return { axis: [1, 0, 0], angle: 0 };
+  return { axis: [(sign * n[0]) / s, (sign * n[1]) / s, (sign * n[2]) / s], angle };
+}
+
+function quatFromAxisAngle(axis: Vec3, angle: number): Quat {
+  const half = angle / 2;
+  const s = Math.sin(half);
+  return [axis[0] * s, axis[1] * s, axis[2] * s, Math.cos(half)];
+}
+
+/**
+ * Critically-damped decay of the rotational offset `source · target⁻¹`, re-applied to `target`.
+ * At `t = 0` returns `source`; as `t → ∞` returns `target`. `angularSpeed0` (rad/s, about the
+ * offset axis) optionally carries rotational momentum through the transition. Deterministic.
+ */
+export function inertializedQuat(source: Quat, target: Quat, t: number, halfLife: number, angularSpeed0 = 0): Quat {
+  const offset = quatMultiply(normalizeQuat(source), quatConjugate(normalizeQuat(target)));
+  const { axis, angle } = quatToAxisAngle(offset);
+  if (angle === 0 && angularSpeed0 === 0) return normalizeQuat(target);
+  const decayedAngle = inertializedScalar(angle, angularSpeed0, t, halfLife);
+  const decayedOffset = quatFromAxisAngle(axis, decayedAngle);
+  return normalizeQuat(quatMultiply(decayedOffset, normalizeQuat(target)));
+}
+
+// ---- pose-space inertializer ------------------------------------------------------------------
+
+/** A pose is a map of animation target → value (scalar / vec3 / quaternion supported for decay). */
+export type InertializationPose = Readonly<Record<string, AnimationValue>>;
+
+/**
+ * Optional per-target velocities at transition time. Scalars → number (units/s), vec3 → Vec3
+ * (units/s), quaternions → number (rad/s about the offset axis). Targets absent here decay from
+ * rest (velocity 0).
+ */
+export type InertializationVelocities = Readonly<Record<string, number | Vec3>>;
+
+export interface InertializerOptions {
+  /** Transition half-life in seconds (default {@link DEFAULT_INERTIALIZATION_HALF_LIFE}). */
+  readonly halfLife?: number;
+}
+
+interface RecordedOffset {
+  readonly type: "scalar" | "vector3" | "quaternion" | "snap";
+  readonly source: AnimationValue;
+  readonly target: AnimationValue;
+  readonly velocity: number | Vec3;
+}
+
+export interface Inertializer {
+  readonly halfLife: number;
+  /**
+   * Record a transition from `previousPose` to `targetPose` (the destination clip's pose at the
+   * transition instant), with optional per-target velocities. Resets the transition clock.
+   */
+  recordTransition(previousPose: InertializationPose, targetPose: InertializationPose, velocities?: InertializationVelocities): void;
+  /**
+   * Sample the inertialized pose `t` seconds after the recorded transition. At `t = 0` equals the
+   * source pose for every recorded target; as `t` grows it converges to the target pose.
+   */
+  sampleInertialized(t: number): InertializationPose;
+  /** True once the offset has decayed to within `epsilon` of the target across all targets. */
+  settled(t: number, epsilon?: number): boolean;
+  /** Clear the recorded transition. */
+  reset(): void;
+}
+
+function classify(value: AnimationValue): RecordedOffset["type"] {
+  if (typeof value === "number") return "scalar";
+  if (Array.isArray(value)) {
+    if (value.length === 3) return "vector3";
+    if (value.length === 4) return "quaternion";
+  }
+  return "snap";
+}
+
+/**
+ * Create a pose-space inertializer. Pure/deterministic given fixed `t`. Use it to replace a
+ * linear state-transition crossfade with a momentum-preserving decay of the pose difference.
+ */
+export function createInertializer(options: InertializerOptions = {}): Inertializer {
+  const halfLife = options.halfLife ?? DEFAULT_INERTIALIZATION_HALF_LIFE;
+  let offsets = new Map<string, RecordedOffset>();
+
+  return {
+    halfLife,
+    recordTransition(previousPose, targetPose, velocities) {
+      const next = new Map<string, RecordedOffset>();
+      for (const [target, targetValue] of Object.entries(targetPose)) {
+        const sourceValue = previousPose[target];
+        if (sourceValue === undefined) continue;
+        const type = classify(targetValue);
+        const velocity = velocities?.[target] ?? (type === "vector3" ? ([0, 0, 0] as Vec3) : 0);
+        next.set(target, {
+          type,
+          source: cloneAnimationValue(sourceValue),
+          target: cloneAnimationValue(targetValue),
+          velocity
+        });
+      }
+      offsets = next;
+    },
+    sampleInertialized(t) {
+      const pose: Record<string, AnimationValue> = {};
+      for (const [target, rec] of offsets) {
+        pose[target] = sampleOffset(rec, t, halfLife);
+      }
+      return pose;
+    },
+    settled(t, epsilon = 1e-3) {
+      for (const [, rec] of offsets) {
+        if (!offsetSettled(rec, t, halfLife, epsilon)) return false;
+      }
+      return true;
+    },
+    reset() {
+      offsets = new Map<string, RecordedOffset>();
+    }
+  };
+}
+
+function sampleOffset(rec: RecordedOffset, t: number, halfLife: number): AnimationValue {
+  switch (rec.type) {
+    case "scalar": {
+      const target = rec.target as number;
+      const offset0 = (rec.source as number) - target;
+      return target + inertializedScalar(offset0, rec.velocity as number, t, halfLife);
+    }
+    case "vector3": {
+      const target = rec.target as Vec3;
+      const source = rec.source as Vec3;
+      const offset0: Vec3 = [source[0] - target[0], source[1] - target[1], source[2] - target[2]];
+      const decayed = inertializedVec3(offset0, t, halfLife, rec.velocity as Vec3);
+      return [target[0] + decayed[0], target[1] + decayed[1], target[2] + decayed[2]];
+    }
+    case "quaternion":
+      return inertializedQuat(rec.source as Quat, rec.target as Quat, t, halfLife, rec.velocity as number);
+    default:
+      // Non-interpolable (boolean/string/other array length): snap to target immediately.
+      return cloneAnimationValue(rec.target);
+  }
+}
+
+function offsetSettled(rec: RecordedOffset, t: number, halfLife: number, epsilon: number): boolean {
+  switch (rec.type) {
+    case "scalar": {
+      const offset0 = (rec.source as number) - (rec.target as number);
+      return Math.abs(inertializedScalar(offset0, rec.velocity as number, t, halfLife)) <= epsilon;
+    }
+    case "vector3": {
+      const target = rec.target as Vec3;
+      const source = rec.source as Vec3;
+      const decayed = inertializedVec3(
+        [source[0] - target[0], source[1] - target[1], source[2] - target[2]],
+        t,
+        halfLife,
+        rec.velocity as Vec3
+      );
+      return Math.hypot(decayed[0], decayed[1], decayed[2]) <= epsilon;
+    }
+    case "quaternion": {
+      const offset = quatMultiply(normalizeQuat(rec.source as Quat), quatConjugate(normalizeQuat(rec.target as Quat)));
+      const { angle } = quatToAxisAngle(offset);
+      return Math.abs(inertializedScalar(angle, rec.velocity as number, t, halfLife)) <= epsilon;
+    }
+    default:
+      return true;
+  }
+}

package/src/LocomotionController.ts

@@ -1,5 +1,6 @@
 import { AnimationClip } from "./AnimationClip.js";
 import { AnimationTrack } from "./AnimationTrack.js";
+import type { FootIkRig } from "./FootIk.js";
 import { applyRootMotion, extractRootMotion } from "./RootMotion.js";
 
 export interface LocomotionControllerState {
@@ -28,6 +29,8 @@ export interface LocomotionControllerOptions {
   readonly pathRadius?: number;
   readonly strideAmplitude?: number;
   readonly rootMotionScale?: number;
+  /** Optional foot-IK rig so locomotion can ground feet on uneven terrain (no foot sliding). */
+  readonly footIkRig?: FootIkRig;
 }
 
 export interface ProceduralWalkClipOptions {
@@ -43,6 +46,8 @@ export class LocomotionController {
   readonly strideAmplitude: number;
   readonly rootMotionScale: number;
   readonly state: LocomotionControllerState;
+  /** Optional foot-IK rig hook; call `footIk.solveFootPlacement(...)` to ground feet. */
+  readonly footIk: FootIkRig | undefined;
 
   constructor(options: LocomotionControllerOptions) {
     if (!Number.isFinite(options.clip.duration) || options.clip.duration <= 0) {
@@ -52,6 +57,7 @@ export class LocomotionController {
     this.rootMotionTrack = options.rootMotionTrack ?? "root.position";
     this.strideAmplitude = options.strideAmplitude ?? 1;
     this.rootMotionScale = options.rootMotionScale ?? 1;
+    this.footIk = options.footIkRig;
     this.state = {
       speed: options.speed ?? 1,
       inPlace: options.inPlace ?? false,