@aura3d/animation 1.0.6 → 1.3.0

package/src/AnimationClipRegistry.ts

@@ -88,6 +88,23 @@ export interface AnimationClipRegistryDiagnostic<TClipId extends string = string
   readonly clipId?: TClipId;
 }
 
+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 AnimationClipMapReadiness<TClipId extends string = string> {
+  readonly ok: boolean;
+  readonly segmentedFallbackDeclared: boolean;
+  readonly requiredActions: readonly string[];
+  readonly missingActions: readonly string[];
+  readonly missingClipIds: readonly TClipId[];
+  readonly aliasActions: readonly string[];
+  readonly diagnostics: readonly AnimationClipRegistryDiagnostic<TClipId>[];
+}
+
 export interface AnimationClipManifest<
   TClipId extends string = string,
   TEvent extends AnimationClipEvent = AnimationClipEvent,
@@ -264,6 +281,113 @@ export function createAnimationClipRegistry<
   return new AnimationClipRegistry(clips, options);
 }
 
+export function validateAnimationClipMap<
+  TClipId extends string = string,
+  TEvent extends AnimationClipEvent = AnimationClipEvent,
+  TPose = unknown
+>(
+  registry: AnimationClipRegistry<TClipId, TEvent, TPose>,
+  options: AnimationClipMapReadinessOptions<TClipId>
+): AnimationClipMapReadiness<TClipId> {
+  const requiredActions = options.requiredActions ?? ["speak", "listen", "gesture", "walk", "action"];
+  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: `Animation 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: `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
+        });
+      }
+    }
+  }
+
+  return {
+    ok: options.segmentedFallbackDeclared ? missingActions.length === 0 : diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+    segmentedFallbackDeclared: options.segmentedFallbackDeclared === true,
+    requiredActions,
+    missingActions,
+    missingClipIds,
+    aliasActions,
+    diagnostics
+  };
+}
+
 function validateClipDefinition(definition: AnimationClipDefinition): void {
   if (!definition.id) {
     throw new Error("Animation clips must have a stable id.");

package/src/AnimationController.ts

@@ -123,6 +123,22 @@ export interface AnimationControllerSnapshot<TClipId extends string = string> {
   readonly clips: readonly AnimationClipPlaybackState<TClipId>[];
 }
 
+export type AnimationAnimationAction = "speak" | "listen" | "gesture" | "walk" | "action";
+
+export interface AnimationAnimationTimelineBinding<TClipId extends string = string> {
+  readonly action: AnimationAnimationAction;
+  readonly clipId: TClipId;
+  readonly loop: AnimationLoopMode | boolean;
+  readonly restartOnEnter: boolean;
+}
+
+export interface AnimationAnimationTimelineSample<TClipId extends string = string> {
+  readonly time: number;
+  readonly action: AnimationAnimationAction;
+  readonly clipId: TClipId;
+  readonly playback: AnimationClipPlaybackState<TClipId>;
+}
+
 export interface AnimationClipLoopEvent<TClipId extends string = string> {
   readonly clipId: TClipId;
   readonly playbackId: string;
@@ -246,6 +262,40 @@ export class AnimationController<
     return cloneState(playback);
   }
 
+  playOnce(clipId: TClipId, options: Omit<AnimationPlayOptions<TClipId>, "loop"> = {}): AnimationClipPlaybackState<TClipId> {
+    return this.play(clipId, {
+      ...options,
+      loop: "once",
+      restart: options.restart ?? true
+    });
+  }
+
+  bindAnimationTimelineAction(
+    action: AnimationAnimationAction,
+    bindings: readonly AnimationAnimationTimelineBinding<TClipId>[],
+    time: number,
+    options: Omit<AnimationPlayOptions<TClipId>, "loop" | "restart"> = {}
+  ): AnimationAnimationTimelineSample<TClipId> {
+    const binding = bindings.find((candidate) => candidate.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 ?? {}),
+        animationAction: action,
+        timelineTime: time
+      }
+    });
+    return {
+      time,
+      action,
+      clipId: binding.clipId,
+      playback
+    };
+  }
+
   pause(clipId?: TClipId): void {
     for (const state of this.selectStates(clipId)) {
       if (state.status === "playing") {

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

@@ -1,8 +1,105 @@
 export {
   AnimationStateMachine as AnimationStateGraph,
+  AnimationStateMachine,
   type AnimationState,
+  type AnimationStateBlend,
   type AnimationStateMachineGraphSnapshot,
   type AnimationStateMachineGraphState,
   type AnimationStateMachineGraphTransition,
   type StateTransition
 } from "./AnimationStateMachine.js";
+
+import { AnimationStateMachine, type AnimationState } from "./AnimationStateMachine.js";
+
+export interface AnimationAnimationStateGraphOptions {
+  readonly idleState?: string;
+}
+
+export interface AnimationAnimationStateGraphSample {
+  readonly frame: number;
+  readonly state: string;
+}
+
+export function createAnimationAnimationStateGraph(options: AnimationAnimationStateGraphOptions = {}): AnimationStateMachine {
+  const idle = options.idleState ?? "idle";
+  const states: readonly AnimationState[] = [
+    {
+      name: idle,
+      transitions: [
+        transition("speak", "isSpeaking", 50),
+        transition("gesture", "gesture", 40, ["gesture"]),
+        transition("walk", "isWalking", 30),
+        transition("action", "action", 60, ["action"]),
+        transition("listen", "isListening", 20)
+      ]
+    },
+    { name: "listen", transitions: [transition("speak", "isSpeaking", 50), transition(idle, "isListening", 0, undefined, false)] },
+    { name: "speak", transitions: [transition("gesture", "gesture", 60, ["gesture"]), transition(idle, "isSpeaking", 0, undefined, false)] },
+    { name: "gesture", duration: 0.4, oneShot: true, onComplete: idle },
+    { name: "walk", transitions: [transition(idle, "isWalking", 0, undefined, false), transition("action", "action", 60, ["action"])] },
+    { name: "action", duration: 0.5, oneShot: true, onComplete: idle }
+  ];
+  return new AnimationStateMachine(states, idle);
+}
+
+export function sampleAnimationAnimationStateGraph(
+  graph: AnimationStateMachine,
+  inputs: readonly Readonly<Record<string, number | boolean | string>>[],
+  delta = 1 / 30
+): 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,
+  priority: number,
+  consumeParameters?: readonly string[],
+  expected = true
+) {
+  return {
+    to,
+    priority,
+    label: `${parameter}->${to}`,
+    consumeParameters,
+    condition: (parameters: Readonly<Record<string, number | boolean | string>>) => {
+      const value = parameters[parameter];
+      if (expected !== true) return value === expected;
+      if (typeof value === "boolean") return value;
+      if (typeof value === "string") return value.trim().length > 0;
+      if (typeof value === "number") return value > 0;
+      return false;
+    }
+  };
+}

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 };