@aura3d/animation 1.4.0 → 1.4.2

package/src/IK.ts

@@ -1,117 +0,0 @@
-import { lerpVec3, type Vec3 } from "./Keyframe.js";
-
-export interface TwoBoneIkInput {
-  readonly root: Vec3;
-  readonly mid: Vec3;
-  readonly end: Vec3;
-  readonly target: Vec3;
-  readonly pole?: Vec3;
-  readonly weight?: number;
-  readonly allowStretch?: boolean;
-}
-
-export interface TwoBoneIkResult {
-  readonly root: Vec3;
-  readonly mid: Vec3;
-  readonly end: Vec3;
-  readonly reached: boolean;
-  readonly stretched: boolean;
-  readonly upperLength: number;
-  readonly lowerLength: number;
-  readonly targetDistance: number;
-  readonly endDistanceToTarget: number;
-  readonly poleInfluence: number;
-}
-
-export function solveTwoBoneIk(input: TwoBoneIkInput): TwoBoneIkResult {
-  const weight = clamp(input.weight ?? 1, 0, 1);
-  const upperLength = distance(input.root, input.mid);
-  const lowerLength = distance(input.mid, input.end);
-  if (upperLength <= 1e-6 || lowerLength <= 1e-6) {
-    throw new Error("Two-bone IK requires non-zero upper and lower segment lengths.");
-  }
-  const targetDelta = subtract(input.target, input.root);
-  const targetDistance = length(targetDelta);
-  if (targetDistance <= 1e-6) {
-    throw new Error("Two-bone IK target must be distinct from the root.");
-  }
-
-  const maxReach = upperLength + lowerLength;
-  const minReach = Math.abs(upperLength - lowerLength) + 1e-5;
-  const solveDistance = input.allowStretch ? targetDistance : clamp(targetDistance, minReach, maxReach - 1e-5);
-  const axis = normalize(targetDelta);
-  const poleDirection = projectedPoleDirection(input.root, axis, input.pole ?? input.mid);
-  const adjacent = clamp((upperLength * upperLength + solveDistance * solveDistance - lowerLength * lowerLength) / (2 * solveDistance), 0, upperLength);
-  const height = Math.sqrt(Math.max(0, upperLength * upperLength - adjacent * adjacent));
-  const solvedEnd = add(input.root, scale(axis, solveDistance));
-  const solvedMid = add(add(input.root, scale(axis, adjacent)), scale(poleDirection, height));
-  const mid = lerpVec3(input.mid, solvedMid, weight);
-  const end = lerpVec3(input.end, solvedEnd, weight);
-  const endDistanceToTarget = distance(end, input.target);
-  return {
-    root: input.root,
-    mid,
-    end,
-    reached: endDistanceToTarget <= 1e-3,
-    stretched: targetDistance > maxReach && input.allowStretch === true,
-    upperLength,
-    lowerLength,
-    targetDistance,
-    endDistanceToTarget,
-    poleInfluence: Math.abs(dot(normalize(subtract(mid, input.root)), poleDirection))
-  };
-}
-
-/**
- * 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)));
-  const projectedLength = length(projected);
-  if (projectedLength > 1e-6) return scale(projected, 1 / projectedLength);
-  const fallback = Math.abs(axis[1]) < 0.9 ? [0, 1, 0] as const : [1, 0, 0] as const;
-  const fallbackProjected = subtract(fallback, scale(axis, dot(fallback, axis)));
-  return normalize(fallbackProjected);
-}
-
-function add(left: Vec3, right: Vec3): Vec3 {
-  return [left[0] + right[0], left[1] + right[1], left[2] + right[2]];
-}
-
-function subtract(left: Vec3, right: Vec3): Vec3 {
-  return [left[0] - right[0], left[1] - right[1], left[2] - right[2]];
-}
-
-function scale(value: Vec3, scalar: number): Vec3 {
-  return [value[0] * scalar, value[1] * scalar, value[2] * scalar];
-}
-
-function dot(left: Vec3, right: Vec3): number {
-  return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
-}
-
-function length(value: Vec3): number {
-  return Math.hypot(value[0], value[1], value[2]);
-}
-
-function distance(left: Vec3, right: Vec3): number {
-  return length(subtract(left, right));
-}
-
-function normalize(value: Vec3): Vec3 {
-  const valueLength = length(value);
-  if (valueLength <= 1e-6) return [0, 1, 0];
-  return scale(value, 1 / valueLength);
-}
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(max, value));
-}

package/src/Inertialization.ts

@@ -1,269 +0,0 @@
-// 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/Keyframe.ts

@@ -1,159 +0,0 @@
-export type Vec3 = readonly [number, number, number];
-export type Quat = readonly [number, number, number, number];
-export type Mat4 = readonly [
-  number, number, number, number,
-  number, number, number, number,
-  number, number, number, number,
-  number, number, number, number
-];
-
-export type NumberArray = readonly number[];
-
-export type AnimationValue = number | boolean | string | Vec3 | Quat | NumberArray;
-
-export type InterpolationMode = "step" | "linear" | "cubicspline";
-
-export type Keyframe<T extends AnimationValue = AnimationValue> = {
-  readonly time: number;
-  readonly value: T;
-  readonly interpolation?: InterpolationMode;
-  readonly inTangent?: T;
-  readonly outTangent?: T;
-};
-
-export type SerializedKeyframe<T extends AnimationValue = AnimationValue> = {
-  readonly time: number;
-  readonly value: T;
-  readonly interpolation?: InterpolationMode;
-  readonly inTangent?: T;
-  readonly outTangent?: T;
-};
-
-export function validateKeyframes<T extends AnimationValue>(keyframes: readonly Keyframe<T>[]): void {
-  if (keyframes.length === 0) {
-    throw new Error("Animation track requires at least one keyframe.");
-  }
-  let previous = -Number.MAX_VALUE;
-  for (const keyframe of keyframes) {
-    if (!Number.isFinite(keyframe.time) || keyframe.time < 0) {
-      throw new Error("Keyframe time must be finite and non-negative.");
-    }
-    if (keyframe.time <= previous) {
-      throw new Error("Keyframes must be sorted by strictly increasing time.");
-    }
-    previous = keyframe.time;
-  }
-}
-
-export function serializeKeyframe<T extends AnimationValue>(keyframe: Keyframe<T>): SerializedKeyframe<T> {
-  return {
-    time: keyframe.time,
-    value: cloneAnimationValue(keyframe.value),
-    ...(keyframe.interpolation ? { interpolation: keyframe.interpolation } : {}),
-    ...(keyframe.inTangent !== undefined ? { inTangent: cloneAnimationValue(keyframe.inTangent) } : {}),
-    ...(keyframe.outTangent !== undefined ? { outTangent: cloneAnimationValue(keyframe.outTangent) } : {})
-  };
-}
-
-export function deserializeKeyframe<T extends AnimationValue>(keyframe: SerializedKeyframe<T>): Keyframe<T> {
-  return serializeKeyframe(keyframe);
-}
-
-export function cloneAnimationValue<T extends AnimationValue>(value: T): T {
-  return Array.isArray(value) ? ([...value] as unknown as T) : value;
-}
-
-export function lerpNumber(a: number, b: number, t: number): number {
-  return a + (b - a) * t;
-}
-
-export function lerpVec3(a: Vec3, b: Vec3, t: number): Vec3 {
-  return [lerpNumber(a[0], b[0], t), lerpNumber(a[1], b[1], t), lerpNumber(a[2], b[2], t)];
-}
-
-export function normalizeQuat(q: Quat): Quat {
-  const length = Math.hypot(q[0], q[1], q[2], q[3]);
-  if (length <= 1e-9) {
-    return [0, 0, 0, 1];
-  }
-  return [q[0] / length, q[1] / length, q[2] / length, q[3] / length];
-}
-
-export function slerpQuat(a: Quat, b: Quat, t: number): Quat {
-  let bx = b[0];
-  let by = b[1];
-  let bz = b[2];
-  let bw = b[3];
-  let cos = a[0] * bx + a[1] * by + a[2] * bz + a[3] * bw;
-  if (cos < 0) {
-    cos = -cos;
-    bx = -bx;
-    by = -by;
-    bz = -bz;
-    bw = -bw;
-  }
-  if (cos > 0.9995) {
-    return normalizeQuat([lerpNumber(a[0], bx, t), lerpNumber(a[1], by, t), lerpNumber(a[2], bz, t), lerpNumber(a[3], bw, t)]);
-  }
-  const theta = Math.acos(Math.max(-1, Math.min(1, cos)));
-  const sinTheta = Math.sin(theta);
-  const wa = Math.sin((1 - t) * theta) / sinTheta;
-  const wb = Math.sin(t * theta) / sinTheta;
-  return [a[0] * wa + bx * wb, a[1] * wa + by * wb, a[2] * wa + bz * wb, a[3] * wa + bw * wb];
-}
-
-export function identityMat4(): Mat4 {
-  return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
-}
-
-export function composeMat4(translation: Vec3 = [0, 0, 0], rotation: Quat = [0, 0, 0, 1], scale: Vec3 = [1, 1, 1]): Mat4 {
-  const [x, y, z, w] = normalizeQuat(rotation);
-  const x2 = x + x;
-  const y2 = y + y;
-  const z2 = z + z;
-  const xx = x * x2;
-  const xy = x * y2;
-  const xz = x * z2;
-  const yy = y * y2;
-  const yz = y * z2;
-  const zz = z * z2;
-  const wx = w * x2;
-  const wy = w * y2;
-  const wz = w * z2;
-  return [
-    (1 - (yy + zz)) * scale[0], (xy + wz) * scale[0], (xz - wy) * scale[0], 0,
-    (xy - wz) * scale[1], (1 - (xx + zz)) * scale[1], (yz + wx) * scale[1], 0,
-    (xz + wy) * scale[2], (yz - wx) * scale[2], (1 - (xx + yy)) * scale[2], 0,
-    translation[0], translation[1], translation[2], 1
-  ];
-}
-
-export function multiplyMat4(a: Mat4, b: Mat4): Mat4 {
-  const out = new Array<number>(16).fill(0);
-  for (let row = 0; row < 4; row += 1) {
-    for (let col = 0; col < 4; col += 1) {
-      const a0 = a[row * 4]!;
-      const a1 = a[row * 4 + 1]!;
-      const a2 = a[row * 4 + 2]!;
-      const a3 = a[row * 4 + 3]!;
-      out[col + row * 4] =
-        a0 * b[col]! +
-        a1 * b[col + 4]! +
-        a2 * b[col + 8]! +
-        a3 * b[col + 12]!;
-    }
-  }
-  return out as unknown as Mat4;
-}
-
-export function invertTranslationMat4(matrix: Mat4): Mat4 {
-  return [
-    matrix[0], matrix[4], matrix[8], 0,
-    matrix[1], matrix[5], matrix[9], 0,
-    matrix[2], matrix[6], matrix[10], 0,
-    -(matrix[12] * matrix[0] + matrix[13] * matrix[1] + matrix[14] * matrix[2]),
-    -(matrix[12] * matrix[4] + matrix[13] * matrix[5] + matrix[14] * matrix[6]),
-    -(matrix[12] * matrix[8] + matrix[13] * matrix[9] + matrix[14] * matrix[10]),
-    1
-  ];
-}

package/src/LocomotionController.ts

@@ -1,155 +0,0 @@
-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 {
-  speed: number;
-  inPlace: boolean;
-  paused: boolean;
-  pathRadius: number;
-}
-
-export interface LocomotionControllerSample {
-  clipName: string;
-  clipTime: number;
-  worldX: number;
-  worldZ: number;
-  heading: number;
-  stride: number;
-  rootMotionDistance: number;
-}
-
-export interface LocomotionControllerOptions {
-  readonly clip: AnimationClip;
-  readonly rootMotionTrack?: string;
-  readonly speed?: number;
-  readonly inPlace?: boolean;
-  readonly paused?: boolean;
-  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 {
-  readonly name?: string;
-  readonly duration?: number;
-  readonly distance?: number;
-  readonly rootMotionTrack?: string;
-}
-
-export class LocomotionController {
-  readonly clip: AnimationClip;
-  readonly rootMotionTrack: string;
-  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) {
-      throw new Error("LocomotionController requires a clip with positive finite duration.");
-    }
-    this.clip = options.clip;
-    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,
-      paused: options.paused ?? false,
-      pathRadius: options.pathRadius ?? 1
-    };
-  }
-
-  setSpeed(speed: number): this {
-    if (!Number.isFinite(speed) || speed < 0) {
-      throw new Error("LocomotionController speed must be finite and non-negative.");
-    }
-    this.state.speed = speed;
-    return this;
-  }
-
-  setInPlace(inPlace: boolean): this {
-    this.state.inPlace = inPlace;
-    return this;
-  }
-
-  setPaused(paused: boolean): this {
-    this.state.paused = paused;
-    return this;
-  }
-
-  setPathRadius(pathRadius: number): this {
-    if (!Number.isFinite(pathRadius) || pathRadius <= 0) {
-      throw new Error("LocomotionController pathRadius must be positive and finite.");
-    }
-    this.state.pathRadius = pathRadius;
-    return this;
-  }
-
-  sample(elapsedSeconds: number): LocomotionControllerSample {
-    if (!Number.isFinite(elapsedSeconds) || elapsedSeconds < 0) {
-      throw new Error("LocomotionController elapsed time must be finite and non-negative.");
-    }
-    const scaledTime = this.state.paused ? 0 : elapsedSeconds * this.state.speed;
-    const previousTime = Math.max(0, scaledTime - 1 / 60);
-    const clipTime = wrapTime(scaledTime, this.clip.duration);
-    const previousClipTime = wrapTime(previousTime, this.clip.duration);
-    const target = { position: [0, 0, 0] as [number, number, number] };
-    const rootMotion = extractRootMotion(this.clip, {
-      target: this.rootMotionTrack,
-      fromTime: previousClipTime,
-      toTime: clipTime,
-      loop: true
-    });
-    applyRootMotion(target, rootMotion, this.state.inPlace ? 0 : this.rootMotionScale);
-    const rootMotionDistance = this.state.inPlace ? 0 : scaledTime * this.rootMotionScale;
-    const pathAngle = this.state.inPlace ? -0.9 : rootMotionDistance / Math.max(0.1, this.state.pathRadius);
-    return {
-      clipName: this.clip.name,
-      clipTime,
-      worldX: this.state.inPlace ? 0 : Math.sin(pathAngle) * this.state.pathRadius,
-      worldZ: this.state.inPlace ? 0 : Math.cos(pathAngle) * this.state.pathRadius,
-      heading: this.state.inPlace ? 0 : pathAngle + Math.PI / 2,
-      stride: Math.sin((clipTime / this.clip.duration) * Math.PI * 2) * this.strideAmplitude,
-      rootMotionDistance: Math.hypot(target.position[0], target.position[2]) + rootMotionDistance
-    };
-  }
-}
-
-export function createRootMotionWalkClip(options: ProceduralWalkClipOptions = {}): AnimationClip {
-  const name = options.name ?? "a3d-procedural-root-walk";
-  const duration = options.duration ?? 1.2;
-  const distance = options.distance ?? 1.28;
-  const target = options.rootMotionTrack ?? "root.position";
-  if (!Number.isFinite(duration) || duration <= 0 || !Number.isFinite(distance) || distance <= 0) {
-    throw new Error("Root-motion walk clip duration and distance must be positive finite values.");
-  }
-  return new AnimationClip({
-    name,
-    duration,
-    tracks: [
-      new AnimationTrack({
-        target,
-        valueType: "vector3",
-        keyframes: [
-          { time: 0, value: [0, 0, 0], interpolation: "linear" },
-          { time: duration * 0.25, value: [0, 0, distance * 0.25], interpolation: "linear" },
-          { time: duration * 0.5, value: [0, 0, distance * 0.5], interpolation: "linear" },
-          { time: duration * 0.75, value: [0, 0, distance * 0.75], interpolation: "linear" },
-          { time: duration, value: [0, 0, distance], interpolation: "linear" }
-        ]
-      })
-    ]
-  });
-}
-
-function wrapTime(time: number, duration: number): number {
-  const wrapped = time % duration;
-  return wrapped < 0 ? wrapped + duration : wrapped;
-}