@aura3d/animation 1.1.0 → 1.3.0

package/src/LocomotionKit.ts

@@ -0,0 +1,89 @@
+import { BlendTree1D, type BlendTreeWeight } from "./BlendTree.js";
+import { createLocomotionAnimationStateGraph } from "./AnimationStateGraph.js";
+import type { AnimationStateBlend, AnimationStateMachine } from "./AnimationStateMachine.js";
+import type { FootIkRig } from "./FootIk.js";
+
+/**
+ * Composable locomotion kit: maps a scalar movement speed into a discrete locomotion state
+ * (idle/walk/run) plus blended clip weights, using the real `BlendTree1D` and
+ * `createLocomotionAnimationStateGraph` primitives. This is the deterministic, browser-free
+ * core a `character-controller` template wires to a physics `CharacterController`, input, and
+ * an `AnimationController` crossfade.
+ */
+export interface LocomotionKitOptions<TClipId extends string = string> {
+  readonly idleClip: TClipId;
+  readonly walkClip: TClipId;
+  readonly runClip: TClipId;
+  /** Speed at which the walk clip reaches full weight (default 1). */
+  readonly walkSpeed?: number;
+  /** Speed at which the run clip reaches full weight (default 4). */
+  readonly runSpeed?: number;
+  /** Speed above which the character is considered moving (default 0.05). */
+  readonly movingThreshold?: number;
+  /** Speed at/above which the character is considered running (default = runSpeed, so state stays coherent with the blend). */
+  readonly runningThreshold?: number;
+  /** Optional foot-IK rig so locomotion can ground feet on uneven terrain (no foot sliding). */
+  readonly footIkRig?: FootIkRig;
+}
+
+export interface LocomotionKitSample<TClipId extends string = string> {
+  readonly speed: number;
+  readonly state: string;
+  readonly moving: boolean;
+  readonly running: boolean;
+  readonly clipWeights: ReadonlyArray<{ readonly clip: TClipId; readonly weight: number }>;
+  /**
+   * Inertialized blend between the previously-active discrete state and the current one. When the
+   * state graph switches (e.g. walk→run), the previous state's clip fades out on a critically-damped
+   * curve instead of snapping — momentum-preserving idle↔walk↔run transitions.
+   */
+  readonly stateTransition: AnimationStateBlend;
+}
+
+export interface LocomotionKit<TClipId extends string = string> {
+  readonly graph: AnimationStateMachine;
+  /** Optional foot-IK rig hook; call `footIk.solveFootPlacement(...)` to ground feet. */
+  readonly footIk: FootIkRig | undefined;
+  /** Blend clip weights for a speed (sum ~= 1), independent of the discrete state graph. */
+  blendWeights(speed: number): ReadonlyArray<BlendTreeWeight<TClipId>>;
+  /** Advance the state graph and produce the full locomotion sample for a speed. */
+  sample(speed: number, delta?: number): LocomotionKitSample<TClipId>;
+}
+
+export function createLocomotionKit<TClipId extends string = string>(options: LocomotionKitOptions<TClipId>): LocomotionKit<TClipId> {
+  const walkSpeed = options.walkSpeed ?? 1;
+  const runSpeed = options.runSpeed ?? 4;
+  const movingThreshold = options.movingThreshold ?? 0.05;
+  const runningThreshold = options.runningThreshold ?? runSpeed;
+
+  const tree = new BlendTree1D<TClipId>([
+    { value: options.idleClip, threshold: 0 },
+    { value: options.walkClip, threshold: walkSpeed },
+    { value: options.runClip, threshold: runSpeed }
+  ]);
+  const graph = createLocomotionAnimationStateGraph();
+
+  return {
+    graph,
+    footIk: options.footIkRig,
+    blendWeights(speed: number) {
+      return tree.weights(Math.max(0, speed));
+    },
+    sample(speed: number, delta = 1 / 30): LocomotionKitSample<TClipId> {
+      const clamped = Math.max(0, speed);
+      const moving = clamped > movingThreshold;
+      const running = clamped >= runningThreshold;
+      graph.setParameter("isMoving", moving);
+      graph.setParameter("isRunning", running);
+      const state = graph.update(delta);
+      return {
+        speed: clamped,
+        state,
+        moving,
+        running,
+        clipWeights: tree.weights(clamped).map((weight) => ({ clip: weight.value, weight: weight.weight })),
+        stateTransition: graph.stateBlend()
+      };
+    }
+  };
+}

package/src/MotionQuality.ts

@@ -17,8 +17,8 @@ export interface AnimationMotionQualityReport {
   readonly healthy: boolean;
 }
 
-export interface CartoonAnimationMotionQualityReport extends AnimationMotionQualityReport {
-  readonly kind: "cartoon-animation-motion-quality";
+export interface AnimationAnimationMotionQualityReport extends AnimationMotionQualityReport {
+  readonly kind: "animation-animation-motion-quality";
   readonly staticPoseRejected: boolean;
   readonly issues: readonly string[];
 }
@@ -103,10 +103,10 @@ export function summarizeAnimationMotion(
   };
 }
 
-export function summarizeCartoonAnimationMotion(
+export function summarizeAnimationAnimationMotion(
   samples: readonly AnimationMotionSample[],
   options: Pick<AnimationMotionQualityOptions, "minimumSamples" | "minimumTimeRangeSeconds" | "minimumPoseDiversityScore"> = {}
-): CartoonAnimationMotionQualityReport {
+): AnimationAnimationMotionQualityReport {
   const base = summarizeAnimationMotion(samples, options);
   const issues = [
     base.sampleCount < (options.minimumSamples ?? 8) ? "not enough motion samples" : undefined,
@@ -116,7 +116,7 @@ export function summarizeCartoonAnimationMotion(
   ].filter((issue): issue is string => Boolean(issue));
   return {
     ...base,
-    kind: "cartoon-animation-motion-quality",
+    kind: "animation-animation-motion-quality",
     staticPoseRejected: issues.length > 0,
     issues,
     healthy: issues.length === 0

package/src/RigQuality.ts

@@ -0,0 +1,101 @@
+import {
+  HUMANOID_BONES,
+  type HumanoidBoneName,
+  type HumanoidRigDefinition
+} from "./HumanoidRetargeting.js";
+
+/**
+ * Body-acting suitability grade for an (inferred) humanoid rig.
+ *
+ * - **A** — full humanoid: spine/neck/head, both arms with forearms + hands, both legs with lower
+ *   legs + feet. Safe for the full performance vocabulary (gesture, point, walk/run, foot work).
+ * - **B** — partial humanoid: enough of the body to act (spine/head + both arms or both legs) but
+ *   missing limbs/extremities; the director should avoid the motions that need the missing chain.
+ * - **C** — mascot / sparse (~8 mappable nodes): a torso + head + stub arms; head/torso acting only,
+ *   no real limb motion.
+ * - **D** — not suitable for body acting: no usable skeleton (root/props only).
+ */
+export type RigGrade = "A" | "B" | "C" | "D";
+
+export interface RigQualityReport {
+  readonly grade: RigGrade;
+  /** Human-readable justifications for the grade (what was present / missing). */
+  readonly reasons: string[];
+  readonly hasLegs: boolean;
+  readonly hasKnees: boolean;
+  readonly hasAnkles: boolean;
+  readonly hasFeet: boolean;
+  /** Count of canonical humanoid bones that resolve to a real node. */
+  readonly mappedBoneCount: number;
+}
+
+/** A bone counts as mapped when it resolves to a non-empty target node name. */
+function isMapped(rig: HumanoidRigDefinition, bone: HumanoidBoneName): boolean {
+  const binding = rig.bones[bone];
+  return Boolean(binding && typeof binding.name === "string" && binding.name.length > 0);
+}
+
+/**
+ * Grade a rig for body-acting suitability. Pure + deterministic — driven only by which canonical
+ * {@link HUMANOID_BONES} resolve to nodes, so it works on the output of `inferHumanoidRig` for any
+ * skeleton naming convention (Mixamo / Blender / UE / sparse mascot / rich humanoid).
+ */
+export function gradeRig(rig: HumanoidRigDefinition): RigQualityReport {
+  const has = (bone: HumanoidBoneName): boolean => isMapped(rig, bone);
+  const mappedBoneCount = HUMANOID_BONES.reduce((n, bone) => (has(bone) ? n + 1 : n), 0);
+
+  // Limb-chain capability (mirrors FootIk's notion of a usable leg chain).
+  const hasLegs = (has("leftUpperLeg") || has("leftLowerLeg")) && (has("rightUpperLeg") || has("rightLowerLeg"));
+  const hasKnees = has("leftLowerLeg") && has("rightLowerLeg");
+  const hasAnkles = has("leftFoot") && has("rightFoot");
+  const hasFeet = hasAnkles; // foot node == ankle/foot joint in the canonical skeleton.
+
+  // Spine / head axis.
+  const hasSpine = has("spine") || has("chest") || has("upperChest");
+  const hasHead = has("head");
+  const hasNeck = has("neck");
+
+  // Arm chains.
+  const hasBothUpperArms = has("leftUpperArm") && has("rightUpperArm");
+  const hasBothForearms = has("leftLowerArm") && has("rightLowerArm");
+  const hasBothHands = has("leftHand") && has("rightHand");
+  const hasBothLowerLegs = has("leftLowerLeg") && has("rightLowerLeg");
+
+  const reasons: string[] = [];
+  reasons.push(`${mappedBoneCount} of ${HUMANOID_BONES.length} canonical humanoid bones mapped`);
+
+  // --- D: no usable skeleton --------------------------------------------------------------------
+  // Without a spine/head axis OR both upper arms there is nothing to act with.
+  if (mappedBoneCount < 5 || (!hasSpine && !hasHead) || (!hasBothUpperArms && !hasLegs)) {
+    reasons.push("not enough body structure to drive body acting (D)");
+    if (!hasSpine && !hasHead) reasons.push("missing spine/head axis");
+    if (!hasBothUpperArms) reasons.push("missing a pair of upper arms");
+    if (!hasLegs) reasons.push("missing a usable pair of legs");
+    return { grade: "D", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
+  }
+
+  // --- A: full humanoid -------------------------------------------------------------------------
+  const fullUpperBody = hasSpine && hasNeck && hasHead && hasBothUpperArms && hasBothForearms && hasBothHands;
+  const fullLowerBody = hasLegs && hasBothLowerLegs && hasFeet;
+  if (mappedBoneCount >= 18 && fullUpperBody && fullLowerBody) {
+    reasons.push("full humanoid: spine/neck/head + both arms (forearms+hands) + both legs (lower legs+feet) (A)");
+    return { grade: "A", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
+  }
+
+  // --- B: partial humanoid ----------------------------------------------------------------------
+  // Enough body to act: a spine/head axis plus at least a full pair of arms OR a full pair of legs.
+  const usableArms = hasBothUpperArms && hasBothForearms;
+  const usableLegs = hasLegs && hasBothLowerLegs;
+  if ((hasSpine || hasHead) && (usableArms || usableLegs) && mappedBoneCount >= 10) {
+    reasons.push("partial humanoid: body acting possible but a limb chain or extremities are missing (B)");
+    if (!fullUpperBody) reasons.push("incomplete upper body (forearms/hands/neck)");
+    if (!fullLowerBody) reasons.push("incomplete lower body (lower legs/feet)");
+    return { grade: "B", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
+  }
+
+  // --- C: mascot / sparse -----------------------------------------------------------------------
+  reasons.push("mascot/sparse rig: head + torso acting only, no real limb chains (C)");
+  if (!usableArms) reasons.push("no usable forearm chain on both arms");
+  if (!usableLegs) reasons.push("no usable lower-leg chain on both legs");
+  return { grade: "C", reasons, hasLegs, hasKnees, hasAnkles, hasFeet, mappedBoneCount };
+}

package/src/SecondaryAnimationFixtures.ts

@@ -88,12 +88,10 @@ export function sampleSecondaryAnimationFixture(options: SecondaryAnimationFixtu
       deterministicReplay: true
     },
     hash: "",
-    claimBoundary: "Secondary animation fixture adapts old foot-IK ground placement and spring-bone secondary motion into deterministic telemetry; it does not claim production foot locking, retargeting, full-body IK, cloth/hair simulation, Unity Animation Rigging parity, or Unreal Control Rig parity.",
+    claimBoundary: "Secondary animation fixture provides the deterministic FootIkSample/SpringBoneSample telemetry shapes and oracle values; the real runtimes now live in FootIk.ts (two-bone foot IK + foot-lock on solveTwoBoneIk + a ground query) and SpringBones.ts (integrated spring chain). The fixture still does not claim retargeting, general full-body IK, cloth/hair simulation, Unity Animation Rigging parity, or Unreal Control Rig parity.",
     blockedClaims: [
-      "production foot locking parity",
       "full-body IK solver parity",
       "runtime retargeting parity",
-      "production spring-bone collision parity",
       "Unity Animation Rigging parity",
       "Unreal Control Rig parity"
     ] as const

package/src/Skeleton.ts

@@ -1,5 +1,5 @@
 import { Bone, type BoneDescriptor } from "./Bone.js";
-import { multiplyMat4, type Mat4 } from "./Keyframe.js";
+import { multiplyMat4, type Mat4, type Vec3 } from "./Keyframe.js";
 
 export class Skeleton {
   readonly bones: readonly Bone[];
@@ -31,4 +31,48 @@ export class Skeleton {
     const worlds = this.worldMatrices();
     return this.bones.map((bone, index) => multiplyMat4(worlds[index]!, bone.inverseBindMatrix));
   }
+
+  /** World-space positions (translation component of each bone's world matrix). */
+  boneWorldPositions(): readonly Vec3[] {
+    return this.worldMatrices().map((m) => [m[12]!, m[13]!, m[14]!] as Vec3);
+  }
+
+  /**
+   * Ordered descendant chain from a bone (by name or index), following the first child at each
+   * level. Returns bone indices root-first — the input to {@link createSpringChain} (use the
+   * matching {@link boneWorldPositions} as the rest pose). Members tagged `springChain` are honored;
+   * the walk stops at the first leaf or when a child is no longer part of the chain.
+   */
+  springChainIndices(root: string | number): readonly number[] {
+    const rootIndex = typeof root === "number" ? root : this.bones.findIndex((b) => b.name === root);
+    if (rootIndex < 0 || rootIndex >= this.bones.length) {
+      throw new Error(`Spring chain root ${String(root)} not found in skeleton.`);
+    }
+    const chain: number[] = [rootIndex];
+    let current = rootIndex;
+    for (;;) {
+      const childIndex = this.bones.findIndex((b, i) => i > current && b.parentIndex === current);
+      if (childIndex < 0) break;
+      chain.push(childIndex);
+      current = childIndex;
+    }
+    return chain;
+  }
+
+  /**
+   * Write solved spring-chain world positions back onto the bones as local translations (relative
+   * to each bone's solved parent), so the deformed chain renders. `chainIndices` and `positions`
+   * are root-first and aligned.
+   */
+  writeSpringChainBack(chainIndices: readonly number[], positions: readonly Vec3[]): void {
+    if (chainIndices.length !== positions.length) {
+      throw new Error("Spring chain indices and positions must align.");
+    }
+    for (let i = 1; i < chainIndices.length; i += 1) {
+      const boneIndex = chainIndices[i]!;
+      const parentPos = positions[i - 1]!;
+      const pos = positions[i]!;
+      this.bones[boneIndex]!.translation = [pos[0] - parentPos[0], pos[1] - parentPos[1], pos[2] - parentPos[2]];
+    }
+  }
 }

package/src/SpringBones.ts

@@ -0,0 +1,243 @@
+// Spring bones: secondary dynamics for hair, cloth flaps, tails, and accessories. A chain of
+// particles hangs off a kinematic root (driven by the character's animation). Each particle is
+// pulled toward its rest pose by a spring, pulled down by gravity, damped, kept at its bone length
+// by a distance constraint, and pushed out of optional sphere/capsule colliders. The result
+// composes on top of any clip for free — it just reacts to how the root moves.
+//
+// Integration is semi-implicit (symplectic) Euler with a fixed timestep (subdivided into substeps
+// for stiffness stability), so it is deterministic: the same root-motion stream and the same `dt`
+// always produce the same chain. Pure: no `Date.now()` / `Math.random()`, no engine/render import.
+//
+// The deterministic `SpringBoneSample` / `springSample()` in SecondaryAnimationFixtures remain the
+// telemetry oracle/data-shape; this runtime produces the same invariants via `telemetry()`.
+
+import type { Quat, Vec3 } from "./Keyframe.js";
+
+export interface SpringCollider {
+  readonly kind: "sphere" | "capsule";
+  readonly center: Vec3;
+  /** Capsule second endpoint (ignored for spheres). */
+  readonly tail?: Vec3;
+  readonly radius: number;
+}
+
+export interface SpringChainOptions {
+  /** Rest-pose world positions of the chain, root first (index 0 is the kinematic root). */
+  readonly bones: readonly Vec3[];
+  /** Spring stiffness pulling each particle to its rest pose (default 40). */
+  readonly stiffness?: number;
+  /** Velocity damping (default 4). Higher = settles faster. */
+  readonly damping?: number;
+  /** Gravity acceleration (default [0,-9.81,0]). */
+  readonly gravity?: Vec3;
+  /** Optional colliders the chain is pushed out of. */
+  readonly colliders?: readonly SpringCollider[];
+  /** Integration substeps per `integrate` call (default 2) for stiffness stability. */
+  readonly substeps?: number;
+  /** Optional chain label (telemetry). */
+  readonly name?: string;
+}
+
+/** Root transform driving the chain each frame. */
+export interface SpringRootTransform {
+  readonly position: Vec3;
+  /** Optional rotation so the rest offsets follow the character's facing. */
+  readonly rotation?: Quat;
+}
+
+export interface SpringChainTelemetry {
+  readonly name: string;
+  readonly boneCount: number;
+  readonly stiffness: number;
+  readonly damping: number;
+  readonly rootPosition: Vec3;
+  readonly tipPosition: Vec3;
+  /** Distance from root to tip (how far the chain swings out). */
+  readonly maxDisplacement: number;
+  /** Number of particles currently resolved against a collider this step. */
+  readonly collisionContacts: number;
+  /** Total kinetic energy (Σ½|v|²); used to verify damping decay. */
+  readonly kineticEnergy: number;
+}
+
+export interface SpringChain {
+  /** Advance the chain by `dt` seconds with the root at `rootTransform`. Deterministic. */
+  integrate(dt: number, rootTransform: SpringRootTransform): void;
+  /** Current solved world positions (index 0 is the root). */
+  positions(): readonly Vec3[];
+  /** Telemetry for tests/gates and matching the fixture oracle's invariants. */
+  telemetry(): SpringChainTelemetry;
+  /** Reset the chain to its rest pose at a root transform (zero velocity). */
+  reset(rootTransform?: SpringRootTransform): void;
+}
+
+/**
+ * Create a spring-bone chain. Bind it to a bone subtree (see {@link tagSpringChain}) and call
+ * {@link SpringChain.integrate} each frame; write {@link SpringChain.positions} back onto the bones.
+ */
+export function createSpringChain(options: SpringChainOptions): SpringChain {
+  if (options.bones.length < 2) {
+    throw new Error("Spring chain requires at least a root and one child bone.");
+  }
+  const stiffness = options.stiffness ?? 40;
+  const damping = options.damping ?? 4;
+  const gravity = options.gravity ?? [0, -9.81, 0];
+  const colliders = options.colliders ?? [];
+  const substeps = Math.max(1, Math.floor(options.substeps ?? 2));
+  const name = options.name ?? "spring-chain";
+
+  // Rest offset of each particle relative to its parent, in the root's initial frame.
+  const restOffsets: Vec3[] = options.bones.map((bone, i) =>
+    i === 0 ? [0, 0, 0] : sub(bone, options.bones[i - 1]!)
+  );
+  const restLengths: number[] = restOffsets.map((o) => len(o));
+
+  const positions: Vec3[] = options.bones.map((b) => [...b] as Vec3);
+  const velocities: Vec3[] = options.bones.map(() => [0, 0, 0] as Vec3);
+  let contacts = 0;
+
+  function rotatedRestOffset(i: number, rotation: Quat | undefined): Vec3 {
+    return rotation ? rotateVec3(restOffsets[i]!, rotation) : restOffsets[i]!;
+  }
+
+  function step(dt: number, root: SpringRootTransform): void {
+    contacts = 0;
+    // Root particle is kinematic.
+    positions[0] = [...root.position] as Vec3;
+    velocities[0] = [0, 0, 0];
+    for (let i = 1; i < positions.length; i += 1) {
+      const parent = positions[i - 1]!;
+      const rest = add(parent, rotatedRestOffset(i, root.rotation));
+      const p = positions[i]!;
+      const v = velocities[i]!;
+      // a = stiffness*(rest - p) + gravity - damping*v  (semi-implicit: update v, then p)
+      const ax = stiffness * (rest[0] - p[0]) + gravity[0] - damping * v[0];
+      const ay = stiffness * (rest[1] - p[1]) + gravity[1] - damping * v[1];
+      const az = stiffness * (rest[2] - p[2]) + gravity[2] - damping * v[2];
+      const nv: [number, number, number] = [v[0] + ax * dt, v[1] + ay * dt, v[2] + az * dt];
+      let np: Vec3 = [p[0] + nv[0] * dt, p[1] + nv[1] * dt, p[2] + nv[2] * dt];
+
+      // Distance constraint: keep the bone length to the parent.
+      np = enforceLength(parent, np, restLengths[i]!);
+
+      // Collider push-out.
+      for (const collider of colliders) {
+        const resolved = pushOut(np, collider);
+        if (resolved) {
+          np = resolved.position;
+          // Remove the inward velocity component so it doesn't tunnel back in.
+          const dot = nv[0] * resolved.normal[0] + nv[1] * resolved.normal[1] + nv[2] * resolved.normal[2];
+          if (dot < 0) {
+            nv[0] -= dot * resolved.normal[0];
+            nv[1] -= dot * resolved.normal[1];
+            nv[2] -= dot * resolved.normal[2];
+          }
+          contacts += 1;
+        }
+      }
+
+      // Recompute velocity from the constrained position so energy bookkeeping stays consistent.
+      velocities[i] = [(np[0] - p[0]) / dt, (np[1] - p[1]) / dt, (np[2] - p[2]) / dt];
+      positions[i] = np;
+    }
+  }
+
+  return {
+    integrate(dt, rootTransform) {
+      if (!Number.isFinite(dt) || dt <= 0) throw new Error("Spring chain dt must be finite and positive.");
+      const sub = dt / substeps;
+      for (let s = 0; s < substeps; s += 1) step(sub, rootTransform);
+    },
+    positions() {
+      return positions.map((p) => [...p] as Vec3);
+    },
+    telemetry() {
+      const tip = positions[positions.length - 1]!;
+      const root = positions[0]!;
+      let ke = 0;
+      for (const v of velocities) ke += 0.5 * (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+      return {
+        name,
+        boneCount: positions.length,
+        stiffness,
+        damping,
+        rootPosition: [...root] as Vec3,
+        tipPosition: [...tip] as Vec3,
+        maxDisplacement: dist(root, tip),
+        collisionContacts: contacts,
+        kineticEnergy: ke
+      };
+    },
+    reset(rootTransform) {
+      const rootPos = rootTransform?.position ?? options.bones[0]!;
+      const rotation = rootTransform?.rotation;
+      positions[0] = [...rootPos] as Vec3;
+      velocities[0] = [0, 0, 0];
+      for (let i = 1; i < positions.length; i += 1) {
+        positions[i] = add(positions[i - 1]!, rotatedRestOffset(i, rotation));
+        velocities[i] = [0, 0, 0];
+      }
+    }
+  };
+}
+
+function enforceLength(anchor: Vec3, point: Vec3, length: number): Vec3 {
+  const d = sub(point, anchor);
+  const l = len(d);
+  if (l <= 1e-8) return [anchor[0], anchor[1] + length, anchor[2]];
+  const s = length / l;
+  return [anchor[0] + d[0] * s, anchor[1] + d[1] * s, anchor[2] + d[2] * s];
+}
+
+function pushOut(point: Vec3, collider: SpringCollider): { position: Vec3; normal: Vec3 } | undefined {
+  const closest = collider.kind === "capsule" && collider.tail
+    ? closestPointOnSegment(point, collider.center, collider.tail)
+    : collider.center;
+  const d = sub(point, closest);
+  const l = len(d);
+  if (l >= collider.radius) return undefined;
+  const normal: Vec3 = l <= 1e-8 ? [0, 1, 0] : [d[0] / l, d[1] / l, d[2] / l];
+  return {
+    position: [closest[0] + normal[0] * collider.radius, closest[1] + normal[1] * collider.radius, closest[2] + normal[2] * collider.radius],
+    normal
+  };
+}
+
+function closestPointOnSegment(p: Vec3, a: Vec3, b: Vec3): Vec3 {
+  const ab = sub(b, a);
+  const t = clamp(dot(sub(p, a), ab) / Math.max(1e-8, dot(ab, ab)), 0, 1);
+  return [a[0] + ab[0] * t, a[1] + ab[1] * t, a[2] + ab[2] * t];
+}
+
+function add(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+function sub(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function dot(a: Vec3, b: Vec3): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function len(a: Vec3): number {
+  return Math.hypot(a[0], a[1], a[2]);
+}
+function dist(a: Vec3, b: Vec3): number {
+  return len(sub(a, b));
+}
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function rotateVec3(v: Vec3, q: Quat): Vec3 {
+  // v' = q * v * q⁻¹ (unit quaternion).
+  const [x, y, z, w] = q;
+  const ix = w * v[0] + y * v[2] - z * v[1];
+  const iy = w * v[1] + z * v[0] - x * v[2];
+  const iz = w * v[2] + x * v[1] - y * v[0];
+  const iw = -x * v[0] - y * v[1] - z * v[2];
+  return [
+    ix * w + iw * -x + iy * -z - iz * -y,
+    iy * w + iw * -y + iz * -x - ix * -z,
+    iz * w + iw * -z + ix * -y - iy * -x
+  ];
+}

package/src/browser-index.ts

@@ -9,6 +9,7 @@ export * from "./Bone.js";
 export * from "./Skeleton.js";
 export * from "./Skinning.js";
 export * from "./BlendTree.js";
+export * from "./Inertialization.js";
 export * from "./AnimationStateMachine.js";
 export * from "./RootMotion.js";
 export * from "./MotionQuality.js";
@@ -16,12 +17,16 @@ export * from "./LocomotionController.js";
 export * from "./SceneAnimationBridge.js";
 export * from "./ECSAnimationBridge.js";
 export * from "./IK.js";
+export * from "./FootIk.js";
+export * from "./SpringBones.js";
 export * from "./MotionMatchingFixtures.js";
 export * from "./SecondaryAnimationFixtures.js";
 export * from "./CrowdAnimation.js";
-export * from "./Retargeting.js";
 export * from "./AnimationClipEvents.js";
-export { AnimationClipRegistry, validateCartoonClipMap } from "./AnimationClipRegistry.js";
+export { AnimationClipRegistry, createAnimationClipRegistry, validateAnimationClipMap, validateAnimationStudioClipMap } from "./AnimationClipRegistry.js";
+export { createAnimationAnimationStateGraph, createLocomotionAnimationStateGraph, sampleAnimationAnimationStateGraph } from "./AnimationStateGraph.js";
+export * from "./LocomotionKit.js";
+export * from "./FighterAnimationAdapter.js";
 export type {
   AnimationClipDefinition,
   AnimationClipId,
@@ -34,12 +39,16 @@ export type {
   AnimationKeyframe,
   AnimationTrack as AnimationClipTrack,
   AnimationTrackTarget,
-  CartoonClipMapReadiness,
-  CartoonClipMapReadinessOptions,
+  AnimationClipMapReadiness,
+  AnimationClipMapReadinessOptions,
   RegisteredAnimationClip
 } from "./AnimationClipRegistry.js";
 export * from "./AnimationController.js";
 export * from "./HumanoidRetargeting.js";
+export * from "./HumanoidBoneInference.js";
+export * from "./RigQuality.js";
+export * from "./library/standardHumanoidClips.js";
+export * from "./library/performanceStateGraph.js";
 export { AnimationClipThreeCompat } from "./threejs-compatibility/AnimationClip.js";
 export type { ThreeCompatKeyframeTrack, ThreeCompatLoopMode } from "./threejs-compatibility/AnimationClip.js";
 export { AnimationActionThreeCompat } from "./threejs-compatibility/AnimationAction.js";

package/src/index.ts

@@ -9,20 +9,24 @@ export * from "./Bone.js";
 export * from "./Skeleton.js";
 export * from "./Skinning.js";
 export * from "./BlendTree.js";
+export * from "./Inertialization.js";
 export * from "./AnimationStateMachine.js";
 export * from "./AnimationStateGraph.js";
+export * from "./LocomotionKit.js";
+export * from "./FighterAnimationAdapter.js";
 export * from "./RootMotion.js";
 export * from "./MotionQuality.js";
 export * from "./LocomotionController.js";
 export * from "./SceneAnimationBridge.js";
 export * from "./ECSAnimationBridge.js";
 export * from "./IK.js";
+export * from "./FootIk.js";
+export * from "./SpringBones.js";
 export * from "./MotionMatchingFixtures.js";
 export * from "./SecondaryAnimationFixtures.js";
 export * from "./CrowdAnimation.js";
-export * from "./Retargeting.js";
 export * from "./AnimationClipEvents.js";
-export { AnimationClipRegistry, validateCartoonClipMap } from "./AnimationClipRegistry.js";
+export { AnimationClipRegistry, createAnimationClipRegistry, validateAnimationClipMap, validateAnimationStudioClipMap } from "./AnimationClipRegistry.js";
 export type {
   AnimationClipDefinition,
   AnimationClipId,
@@ -35,12 +39,16 @@ export type {
   AnimationKeyframe,
   AnimationTrack as AnimationClipTrack,
   AnimationTrackTarget,
-  CartoonClipMapReadiness,
-  CartoonClipMapReadinessOptions,
+  AnimationClipMapReadiness,
+  AnimationClipMapReadinessOptions,
   RegisteredAnimationClip
 } from "./AnimationClipRegistry.js";
 export * from "./AnimationController.js";
 export * from "./HumanoidRetargeting.js";
+export * from "./HumanoidBoneInference.js";
+export * from "./RigQuality.js";
+export * from "./library/standardHumanoidClips.js";
+export * from "./library/performanceStateGraph.js";
 export { AnimationClipThreeCompat } from "./threejs-compatibility/AnimationClip.js";
 export type { ThreeCompatKeyframeTrack, ThreeCompatLoopMode } from "./threejs-compatibility/AnimationClip.js";
 export { AnimationActionThreeCompat } from "./threejs-compatibility/AnimationAction.js";