@aura3d/animation 1.1.0 → 1.3.0

package/src/AnimationClipRegistry.ts

@@ -88,14 +88,14 @@ export interface AnimationClipRegistryDiagnostic<TClipId extends string = string
   readonly clipId?: TClipId;
 }
 
-export interface CartoonClipMapReadinessOptions<TClipId extends string = string> {
+export interface AnimationClipMapReadinessOptions<TClipId extends string = string> {
   readonly requiredActions?: readonly string[] | undefined;
   readonly clipMap: Readonly<Record<string, TClipId | readonly TClipId[] | undefined>>;
   readonly aliases?: Readonly<Record<string, string>> | undefined;
   readonly segmentedFallbackDeclared?: boolean | undefined;
 }
 
-export interface CartoonClipMapReadiness<TClipId extends string = string> {
+export interface AnimationClipMapReadiness<TClipId extends string = string> {
   readonly ok: boolean;
   readonly segmentedFallbackDeclared: boolean;
   readonly requiredActions: readonly string[];
@@ -281,14 +281,14 @@ export function createAnimationClipRegistry<
   return new AnimationClipRegistry(clips, options);
 }
 
-export function validateCartoonClipMap<
+export function validateAnimationClipMap<
   TClipId extends string = string,
   TEvent extends AnimationClipEvent = AnimationClipEvent,
   TPose = unknown
 >(
   registry: AnimationClipRegistry<TClipId, TEvent, TPose>,
-  options: CartoonClipMapReadinessOptions<TClipId>
-): CartoonClipMapReadiness<TClipId> {
+  options: AnimationClipMapReadinessOptions<TClipId>
+): AnimationClipMapReadiness<TClipId> {
   const requiredActions = options.requiredActions ?? ["speak", "listen", "gesture", "walk", "action"];
   const missingActions: string[] = [];
   const missingClipIds: TClipId[] = [];
@@ -303,8 +303,8 @@ export function validateCartoonClipMap<
       missingActions.push(action);
       diagnostics.push({
         severity: options.segmentedFallbackDeclared ? "warning" : "error",
-        code: "CARTOON_CLIP_ACTION_MISSING",
-        message: `Cartoon action "${action}" is missing a clip map entry.`
+        code: "ANIMATION_CLIP_ACTION_MISSING",
+        message: `Animation action "${action}" is missing a clip map entry.`
       });
       continue;
     }
@@ -313,8 +313,64 @@ export function validateCartoonClipMap<
         missingClipIds.push(clipId);
         diagnostics.push({
           severity: options.segmentedFallbackDeclared ? "warning" : "error",
-          code: "CARTOON_CLIP_ID_MISSING",
-          message: `Cartoon action "${action}" references missing clip "${clipId}".`,
+          code: "ANIMATION_CLIP_ID_MISSING",
+          message: `Animation action "${action}" references missing clip "${clipId}".`,
+          clipId
+        });
+      }
+    }
+  }
+
+  return {
+    ok: options.segmentedFallbackDeclared ? missingActions.length === 0 : diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+    segmentedFallbackDeclared: options.segmentedFallbackDeclared === true,
+    requiredActions,
+    missingActions,
+    missingClipIds,
+    aliasActions,
+    diagnostics
+  };
+}
+
+/**
+ * Generic (non-animation) clip-map readiness validator for locomotion / fighter / Animation Studio
+ * clip sets. Same readiness shape as {@link validateAnimationClipMap} but with neutral diagnostic
+ * codes and a configurable required-action set (defaults to a locomotion set).
+ */
+export function validateAnimationStudioClipMap<
+  TClipId extends string = string,
+  TEvent extends AnimationClipEvent = AnimationClipEvent,
+  TPose = unknown
+>(
+  registry: AnimationClipRegistry<TClipId, TEvent, TPose>,
+  options: AnimationClipMapReadinessOptions<TClipId>
+): AnimationClipMapReadiness<TClipId> {
+  const requiredActions = options.requiredActions ?? ["idle", "walk", "run"];
+  const missingActions: string[] = [];
+  const missingClipIds: TClipId[] = [];
+  const aliasActions: string[] = [];
+  const diagnostics: AnimationClipRegistryDiagnostic<TClipId>[] = [];
+
+  for (const action of requiredActions) {
+    const mapped = options.clipMap[action] ?? options.clipMap[options.aliases?.[action] ?? ""];
+    if (options.aliases?.[action]) aliasActions.push(action);
+    const clipIds = Array.isArray(mapped) ? mapped : mapped ? [mapped] : [];
+    if (clipIds.length === 0) {
+      missingActions.push(action);
+      diagnostics.push({
+        severity: options.segmentedFallbackDeclared ? "warning" : "error",
+        code: "ANIMATION_CLIP_ACTION_MISSING",
+        message: `Required action "${action}" is missing a clip map entry.`
+      });
+      continue;
+    }
+    for (const clipId of clipIds) {
+      if (!registry.has(clipId)) {
+        missingClipIds.push(clipId);
+        diagnostics.push({
+          severity: options.segmentedFallbackDeclared ? "warning" : "error",
+          code: "ANIMATION_CLIP_ID_MISSING",
+          message: `Required action "${action}" references missing clip "${clipId}".`,
           clipId
         });
       }

package/src/AnimationController.ts

@@ -123,18 +123,18 @@ export interface AnimationControllerSnapshot<TClipId extends string = string> {
   readonly clips: readonly AnimationClipPlaybackState<TClipId>[];
 }
 
-export type CartoonAnimationAction = "speak" | "listen" | "gesture" | "walk" | "action";
+export type AnimationAnimationAction = "speak" | "listen" | "gesture" | "walk" | "action";
 
-export interface CartoonAnimationTimelineBinding<TClipId extends string = string> {
-  readonly action: CartoonAnimationAction;
+export interface AnimationAnimationTimelineBinding<TClipId extends string = string> {
+  readonly action: AnimationAnimationAction;
   readonly clipId: TClipId;
   readonly loop: AnimationLoopMode | boolean;
   readonly restartOnEnter: boolean;
 }
 
-export interface CartoonAnimationTimelineSample<TClipId extends string = string> {
+export interface AnimationAnimationTimelineSample<TClipId extends string = string> {
   readonly time: number;
-  readonly action: CartoonAnimationAction;
+  readonly action: AnimationAnimationAction;
   readonly clipId: TClipId;
   readonly playback: AnimationClipPlaybackState<TClipId>;
 }
@@ -270,21 +270,21 @@ export class AnimationController<
     });
   }
 
-  bindCartoonTimelineAction(
-    action: CartoonAnimationAction,
-    bindings: readonly CartoonAnimationTimelineBinding<TClipId>[],
+  bindAnimationTimelineAction(
+    action: AnimationAnimationAction,
+    bindings: readonly AnimationAnimationTimelineBinding<TClipId>[],
     time: number,
     options: Omit<AnimationPlayOptions<TClipId>, "loop" | "restart"> = {}
-  ): CartoonAnimationTimelineSample<TClipId> {
+  ): AnimationAnimationTimelineSample<TClipId> {
     const binding = bindings.find((candidate) => candidate.action === action);
-    if (!binding) throw new Error(`No cartoon animation binding registered for action "${action}".`);
+    if (!binding) throw new Error(`No animation animation binding registered for action "${action}".`);
     const playback = this.play(binding.clipId, {
       ...options,
       loop: binding.loop,
       restart: binding.restartOnEnter,
       metadata: {
         ...(options.metadata ?? {}),
-        cartoonAction: action,
+        animationAction: action,
         timelineTime: time
       }
     });

package/src/AnimationMixer.ts

@@ -3,6 +3,7 @@ import type { AnimationClip } from "./AnimationClip.js";
 import type { AnimationEvent } from "./AnimationEvents.js";
 import type { AnimationLayer, AnimationLayerSnapshot } from "./AnimationLayer.js";
 import { cloneAnimationValue, normalizeQuat, slerpQuat, type AnimationValue } from "./Keyframe.js";
+import { DEFAULT_INERTIALIZATION_HALF_LIFE, inertializedTransitionWeight } from "./Inertialization.js";
 import { applyRootMotion, extractRootMotion, type RootMotionSample, type RootMotionTarget } from "./RootMotion.js";
 
 export type AnimationTarget = {
@@ -44,6 +45,7 @@ export class AnimationMixer {
   private applyErrors: AnimationApplyError[] = [];
   private readonly eventListeners = new Set<(event: AnimationEvent) => void>();
   private disposed = false;
+  private inertialTransition: { from: AnimationAction; to: AnimationAction; elapsed: number; halfLife: number } | undefined;
 
   constructor(target?: AnimationTarget, private readonly options: AnimationMixerOptions = {}) {
     this.target = target;
@@ -84,11 +86,28 @@ export class AnimationMixer {
     this.addAction(to);
   }
 
+  /**
+   * Inertialized transition between two actions: instead of the linear weight ramp of
+   * {@link crossFade}, the source action's weight follows a critically-damped decay (zero initial
+   * slope, momentum-preserving) so the blend carries through instead of dissolving. The transition
+   * is advanced deterministically inside {@link update}; weights always sum to 1 and the source is
+   * stopped once it has effectively faded. Pass a `halfLife` (seconds) to tune snappiness.
+   */
+  inertialCrossFade(from: AnimationAction, to: AnimationAction, halfLife = DEFAULT_INERTIALIZATION_HALF_LIFE): void {
+    this.assertAlive();
+    to.play();
+    from.weight = 1;
+    to.weight = 0;
+    this.addAction(to);
+    this.inertialTransition = { from, to, elapsed: 0, halfLife };
+  }
+
   update(delta: number): readonly AnimationEvent[] {
     this.assertAlive();
     if (!Number.isFinite(delta) || delta < 0) {
       throw new Error("AnimationMixer delta must be finite and non-negative.");
     }
+    this.advanceInertialTransition(delta * this.timeScale);
     const events: AnimationEvent[] = [];
     const accumulators = new Map<string, TargetAccumulator>();
     for (const action of this.actions) {
@@ -164,6 +183,7 @@ export class AnimationMixer {
     this.values.clear();
     this.applyErrors = [];
     this.eventListeners.clear();
+    this.inertialTransition = undefined;
     this.disposed = true;
   }
 
@@ -173,6 +193,22 @@ export class AnimationMixer {
     }
   }
 
+  private advanceInertialTransition(scaledDelta: number): void {
+    const transition = this.inertialTransition;
+    if (!transition) return;
+    transition.elapsed += scaledDelta;
+    const fromWeight = inertializedTransitionWeight(transition.elapsed, transition.halfLife);
+    transition.from.weight = fromWeight;
+    transition.to.weight = 1 - fromWeight;
+    // Retire the transition once the source has effectively faded (offset within 1e-3).
+    if (fromWeight <= 1e-3) {
+      transition.from.weight = 0;
+      transition.to.weight = 1;
+      transition.from.stop();
+      this.inertialTransition = undefined;
+    }
+  }
+
   private applyActionRootMotion(action: AnimationAction, previousTime: number): void {
     if (!this.options.applyRootMotion || action.weight <= 0) return;
     const rootMotionTarget = this.options.rootMotionTrack ?? "root.position";

package/src/AnimationStateGraph.ts

@@ -2,6 +2,7 @@ export {
   AnimationStateMachine as AnimationStateGraph,
   AnimationStateMachine,
   type AnimationState,
+  type AnimationStateBlend,
   type AnimationStateMachineGraphSnapshot,
   type AnimationStateMachineGraphState,
   type AnimationStateMachineGraphTransition,
@@ -10,16 +11,16 @@ export {
 
 import { AnimationStateMachine, type AnimationState } from "./AnimationStateMachine.js";
 
-export interface CartoonAnimationStateGraphOptions {
+export interface AnimationAnimationStateGraphOptions {
   readonly idleState?: string;
 }
 
-export interface CartoonAnimationStateGraphSample {
+export interface AnimationAnimationStateGraphSample {
   readonly frame: number;
   readonly state: string;
 }
 
-export function createCartoonAnimationStateGraph(options: CartoonAnimationStateGraphOptions = {}): AnimationStateMachine {
+export function createAnimationAnimationStateGraph(options: AnimationAnimationStateGraphOptions = {}): AnimationStateMachine {
   const idle = options.idleState ?? "idle";
   const states: readonly AnimationState[] = [
     {
@@ -41,17 +42,45 @@ export function createCartoonAnimationStateGraph(options: CartoonAnimationStateG
   return new AnimationStateMachine(states, idle);
 }
 
-export function sampleCartoonAnimationStateGraph(
+export function sampleAnimationAnimationStateGraph(
   graph: AnimationStateMachine,
   inputs: readonly Readonly<Record<string, number | boolean | string>>[],
   delta = 1 / 30
-): readonly CartoonAnimationStateGraphSample[] {
+): readonly AnimationAnimationStateGraphSample[] {
   return inputs.map((parameters, frame) => {
     for (const [key, value] of Object.entries(parameters)) graph.setParameter(key, value);
     return { frame, state: graph.update(delta) };
   });
 }
 
+export interface LocomotionAnimationStateGraphOptions {
+  readonly idleState?: string;
+}
+
+/**
+ * Reusable locomotion state graph (idle <-> walk <-> run) for character-controller and
+ * Animation Studio templates. Parameters: `isMoving` (walk), `isRunning` (run). Mirrors
+ * {@link createAnimationAnimationStateGraph} so both share the deterministic state-machine core.
+ */
+export function createLocomotionAnimationStateGraph(options: LocomotionAnimationStateGraphOptions = {}): AnimationStateMachine {
+  const idle = options.idleState ?? "idle";
+  const states: readonly AnimationState[] = [
+    {
+      name: idle,
+      transitions: [transition("run", "isRunning", 60), transition("walk", "isMoving", 40)]
+    },
+    {
+      name: "walk",
+      transitions: [transition("run", "isRunning", 60), transition(idle, "isMoving", 0, undefined, false)]
+    },
+    {
+      name: "run",
+      transitions: [transition("walk", "isRunning", 0, undefined, false), transition(idle, "isMoving", 0, undefined, false)]
+    }
+  ];
+  return new AnimationStateMachine(states, idle);
+}
+
 function transition(
   to: string,
   parameter: string,

package/src/AnimationStateMachine.ts

@@ -1,3 +1,5 @@
+import { DEFAULT_INERTIALIZATION_HALF_LIFE, inertializedTransitionWeight } from "./Inertialization.js";
+
 export type StateTransition = {
   readonly to: string;
   readonly label?: string;
@@ -47,11 +49,31 @@ export type AnimationStateMachineGraphSnapshot = {
   readonly transitions: readonly AnimationStateMachineGraphTransition[];
 };
 
+/** Inertialized blend between the previously-active state and the current state. */
+export type AnimationStateBlend = {
+  /** State exited at the last transition (equals `to` when no transition is in flight). */
+  readonly from: string;
+  /** Currently-active state. */
+  readonly to: string;
+  /** [fromWeight, toWeight], summing to 1; fromWeight decays critically-damped after a switch. */
+  readonly weights: readonly [number, number];
+  /** Seconds since the last state change. */
+  readonly elapsed: number;
+  /** True once the previous state has effectively faded out. */
+  readonly done: boolean;
+};
+
 export class AnimationStateMachine {
   readonly states = new Map<string, AnimationState>();
   readonly parameters: Record<string, number | boolean | string> = {};
   currentState: string;
   stateTime = 0;
+  /** State active immediately before the most recent transition (for inertialized blending). */
+  previousState: string;
+  /** Seconds since the most recent state change. */
+  transitionElapsed = Number.POSITIVE_INFINITY;
+  /** Half-life (seconds) of the inertialized state-transition blend. */
+  transitionHalfLife = DEFAULT_INERTIALIZATION_HALF_LIFE;
 
   constructor(states: readonly AnimationState[], initialState: string) {
     for (const state of states) {
@@ -74,6 +96,7 @@ export class AnimationStateMachine {
       }
     }
     this.currentState = initialState;
+    this.previousState = initialState;
     this.resetParametersForState(this.requireState(initialState));
   }
 
@@ -81,11 +104,34 @@ export class AnimationStateMachine {
     this.parameters[name] = value;
   }
 
+  /**
+   * Inertialized blend between {@link previousState} and {@link currentState}. The previous
+   * state's weight decays critically-damped (zero initial slope, momentum-preserving) over
+   * {@link transitionHalfLife}; consumers crossfade the two states' clips by these weights instead
+   * of snapping or linearly ramping. Deterministic given the elapsed transition time.
+   */
+  stateBlend(halfLife = this.transitionHalfLife): AnimationStateBlend {
+    const elapsed = this.transitionElapsed;
+    if (this.previousState === this.currentState || !Number.isFinite(elapsed)) {
+      return { from: this.currentState, to: this.currentState, weights: [0, 1], elapsed: Number.isFinite(elapsed) ? elapsed : 0, done: true };
+    }
+    const fromWeight = inertializedTransitionWeight(elapsed, halfLife);
+    const done = fromWeight <= 1e-3;
+    return {
+      from: this.previousState,
+      to: this.currentState,
+      weights: [done ? 0 : fromWeight, done ? 1 : 1 - fromWeight],
+      elapsed,
+      done
+    };
+  }
+
   update(delta = 0): string {
     if (!Number.isFinite(delta) || delta < 0) {
       throw new Error("AnimationStateMachine delta must be finite and non-negative.");
     }
     this.stateTime += delta;
+    this.transitionElapsed += delta;
     const state = this.requireState(this.currentState);
 
     if (isStateComplete(state, this.stateTime)) {
@@ -182,8 +228,10 @@ export class AnimationStateMachine {
 
   private transitionTo(name: string): void {
     const state = this.requireState(name);
+    this.previousState = this.currentState;
     this.currentState = name;
     this.stateTime = 0;
+    this.transitionElapsed = this.previousState === name ? Number.POSITIVE_INFINITY : 0;
     this.resetParametersForState(state);
   }
 

package/src/Bone.ts

@@ -7,6 +7,8 @@ export type BoneDescriptor = {
   readonly rotation?: Quat;
   readonly scale?: Vec3;
   readonly inverseBindMatrix?: Mat4;
+  /** Tag this bone as the start (or a member) of a spring-bone chain (secondary dynamics). */
+  readonly springChain?: boolean;
 };
 
 export class Bone {
@@ -16,6 +18,8 @@ export class Bone {
   rotation: Quat;
   scale: Vec3;
   inverseBindMatrix: Mat4;
+  /** True when this bone participates in a spring-bone chain solved by `createSpringChain`. */
+  springChain: boolean;
 
   constructor(descriptor: BoneDescriptor) {
     if (descriptor.name.trim().length === 0) {
@@ -27,6 +31,7 @@ export class Bone {
     this.rotation = descriptor.rotation ?? [0, 0, 0, 1];
     this.scale = descriptor.scale ?? [1, 1, 1];
     this.inverseBindMatrix = descriptor.inverseBindMatrix ?? identityMat4();
+    this.springChain = descriptor.springChain ?? false;
   }
 
   localMatrix(): Mat4 {

package/src/FighterAnimationAdapter.ts

@@ -0,0 +1,124 @@
+// Shared fighter animation adapter: maps a combat state to a clip key + playback speed, and
+// computes deterministic transition weights on state change. Pure (no engine/render import) so both
+// the Aura Clash arena and the fighting-game template can reuse the same mapping instead of each
+// re-deriving it inline. Transitions default to the inertialized (critically-damped) weight curve;
+// the linear crossfade is retained as an explicit fallback.
+
+import { inertializedTransitionWeight, DEFAULT_INERTIALIZATION_HALF_LIFE } from "./Inertialization.js";
+
+export type FighterClipKey =
+  | "idle"
+  | "walk"
+  | "run"
+  | "air"
+  | "down"
+  | "guard"
+  | "hurt"
+  | "ko"
+  | "light"
+  | "heavy"
+  | "special";
+
+export interface FighterAnimationStateInput {
+  /** High-level action label from the combat sim. */
+  readonly action: string;
+  /** Whether the fighter is on the ground (airborne overrides locomotion). */
+  readonly grounded: boolean;
+  /** Active attack clip key, if mid-attack (overrides everything except KO). */
+  readonly attackClipKey?: FighterClipKey | undefined;
+  /** KO takes precedence over all other states. */
+  readonly knockedOut?: boolean | undefined;
+}
+
+export interface FighterClipResolution {
+  readonly clipKey: FighterClipKey;
+  readonly speed: number;
+}
+
+export interface FighterAnimationSpeedTable {
+  readonly light?: number;
+  readonly heavy?: number;
+  readonly special?: number;
+  readonly run?: number;
+}
+
+const defaultSpeeds: Required<FighterAnimationSpeedTable> = { light: 1.45, heavy: 1.06, special: 0.94, run: 1.18 };
+
+const locomotionByAction: Readonly<Record<string, FighterClipKey>> = {
+  idle: "idle",
+  walk: "walk",
+  run: "run",
+  dash: "run",
+  guard: "guard",
+  block: "guard",
+  down: "down",
+  crouch: "down",
+  hurt: "hurt",
+  hit: "hurt"
+};
+
+/** Resolve the clip key + speed for a fighter state. Mirrors the Aura Clash arena cascade. */
+export function resolveFighterClip(input: FighterAnimationStateInput, speeds: FighterAnimationSpeedTable = {}): FighterClipResolution {
+  const table = { ...defaultSpeeds, ...speeds };
+  if (input.knockedOut) return { clipKey: "ko", speed: 1 };
+  if (input.attackClipKey) {
+    const speed = input.attackClipKey === "light" ? table.light : input.attackClipKey === "heavy" ? table.heavy : input.attackClipKey === "special" ? table.special : 1;
+    return { clipKey: input.attackClipKey, speed };
+  }
+  if (!input.grounded) return { clipKey: "air", speed: 1 };
+  const action = input.action.toLowerCase();
+  const clipKey = locomotionByAction[action] ?? "idle";
+  const speed = clipKey === "run" ? table.run : 1;
+  return { clipKey, speed };
+}
+
+export interface FighterCrossfade<TClip extends string = string> {
+  readonly from: TClip;
+  readonly to: TClip;
+  readonly weights: readonly [number, number];
+  readonly done: boolean;
+}
+
+/**
+ * Deterministic crossfade weights from a previous clip to the current clip over a transition
+ * window. `elapsed`/`duration` are in seconds. Returns clamped [fromWeight, toWeight] summing to 1.
+ * Generic over clip identifier so callers using clip keys OR raw clip names can both use it.
+ */
+export function fighterCrossfadeWeights<TClip extends string = string>(from: TClip, to: TClip, elapsed: number, duration: number): FighterCrossfade<TClip> {
+  if (from === to || duration <= 0) {
+    return { from, to, weights: [0, 1], done: true };
+  }
+  const t = Math.max(0, Math.min(1, elapsed / duration));
+  return { from, to, weights: [1 - t, t], done: t >= 1 };
+}
+
+/**
+ * Inertialized transition weights from a previous clip to the current clip. This is the **default**
+ * fighter transition: the source weight follows a critically-damped decay (zero initial slope,
+ * momentum-preserving) instead of the straight linear ramp of {@link fighterCrossfadeWeights}, so
+ * move swaps carry through smoothly rather than dissolving. Weights still sum to 1, output is
+ * deterministic (pure function of `elapsed`/`duration`/`halfLife`), so deterministic combat replay
+ * is unaffected. `halfLife` defaults to ~40% of the transition window so the source has effectively
+ * faded by the time the window closes; the linear path remains available as a fallback.
+ */
+export function fighterInertializedWeights<TClip extends string = string>(
+  from: TClip,
+  to: TClip,
+  elapsed: number,
+  duration: number,
+  halfLife?: number
+): FighterCrossfade<TClip> {
+  if (from === to || duration <= 0) {
+    return { from, to, weights: [0, 1], done: true };
+  }
+  const done = elapsed >= duration;
+  if (done) {
+    return { from, to, weights: [0, 1], done: true };
+  }
+  const life = halfLife ?? Math.max(1e-4, duration * 0.4);
+  const fromWeight = inertializedTransitionWeight(Math.max(0, elapsed), life);
+  return { from, to, weights: [fromWeight, 1 - fromWeight], done: false };
+}
+
+/** Default transition half-life re-exported for callers that want to align their own timing. */
+export { DEFAULT_INERTIALIZATION_HALF_LIFE };