@aura3d/animation 1.3.3 → 1.4.1

package/src/AnimationEvents.ts

@@ -1,34 +0,0 @@
-export type AnimationEventMarker = {
-  readonly name: string;
-  readonly time: number;
-  readonly payload?: unknown;
-};
-
-export type AnimationEvent = AnimationEventMarker & {
-  readonly clipName: string;
-};
-
-export function eventsBetween(markers: readonly AnimationEventMarker[], clipName: string, fromTime: number, toTime: number, duration: number, looped: boolean): readonly AnimationEvent[] {
-  const events: AnimationEvent[] = [];
-  if (duration <= 0) {
-    return events;
-  }
-  if (!looped || toTime >= fromTime) {
-    for (const marker of markers) {
-      if (marker.time > fromTime && marker.time <= toTime) {
-        events.push({ ...marker, clipName });
-      }
-    }
-    return events;
-  }
-  const lateEvents: AnimationEvent[] = [];
-  const earlyEvents: AnimationEvent[] = [];
-  for (const marker of markers) {
-    if (marker.time > fromTime && marker.time <= duration) {
-      lateEvents.push({ ...marker, clipName });
-    } else if (marker.time >= 0 && marker.time <= toTime) {
-      earlyEvents.push({ ...marker, clipName });
-    }
-  }
-  return [...lateEvents, ...earlyEvents];
-}

package/src/AnimationLayer.ts

@@ -1,73 +0,0 @@
-import type { AnimationAction } from "./AnimationAction.js";
-
-export type AnimationLayerSnapshot = {
-  readonly name: string;
-  readonly weight: number;
-  readonly additive: boolean;
-  readonly mask: readonly string[];
-  readonly actions: readonly string[];
-};
-
-export type AnimationLayerOptions = {
-  readonly weight?: number;
-  readonly additive?: boolean;
-  readonly mask?: readonly string[];
-};
-
-export class AnimationLayer {
-  readonly name: string;
-  weight: number;
-  additive: boolean;
-  readonly mask: readonly string[];
-  readonly actions: AnimationAction[] = [];
-  private readonly baseWeights = new WeakMap<AnimationAction, number>();
-
-  constructor(name: string, weightOrOptions: number | AnimationLayerOptions = 1) {
-    if (name.trim().length === 0) {
-      throw new Error("AnimationLayer name cannot be empty.");
-    }
-    this.name = name;
-    const options = typeof weightOrOptions === "number" ? { weight: weightOrOptions } : weightOrOptions;
-    this.weight = options.weight ?? 1;
-    this.additive = options.additive ?? false;
-    this.mask = [...(options.mask ?? [])];
-    if (!Number.isFinite(this.weight) || this.weight < 0) {
-      throw new Error("AnimationLayer weight must be finite and non-negative.");
-    }
-    for (const entry of this.mask) {
-      if (entry.trim().length === 0) {
-        throw new Error("AnimationLayer mask entries cannot be empty.");
-      }
-    }
-  }
-
-  add(action: AnimationAction): void {
-    if (!this.actions.includes(action)) {
-      this.actions.push(action);
-      this.baseWeights.set(action, action.weight);
-    }
-  }
-
-  applyWeight(): void {
-    for (const action of this.actions) {
-      action.setWeight((this.baseWeights.get(action) ?? action.weight) * this.weight);
-    }
-  }
-
-  capturesTarget(target: string): boolean {
-    if (this.mask.length === 0) {
-      return true;
-    }
-    return this.mask.some((entry) => target === entry || target.startsWith(`${entry}.`));
-  }
-
-  snapshot(): AnimationLayerSnapshot {
-    return {
-      name: this.name,
-      weight: this.weight,
-      additive: this.additive,
-      mask: [...this.mask],
-      actions: this.actions.map((action) => action.clip.name)
-    };
-  }
-}

package/src/AnimationMixer.ts

@@ -1,402 +0,0 @@
-import { AnimationAction, type AnimationActionSnapshot } from "./AnimationAction.js";
-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 = {
-  setAnimationValue?: (target: string, value: AnimationValue) => void;
-  applyRootMotion?: (sample: RootMotionSample) => void;
-  position?: [number, number, number];
-};
-
-export type AnimationMixerOptions = {
-  readonly applyRootMotion?: boolean;
-  readonly rootMotionTrack?: string;
-  readonly rootMotionScale?: number;
-};
-
-export type AnimationMixerSnapshot = {
-  readonly timeScale: number;
-  readonly actionCount: number;
-  readonly actions: readonly AnimationActionSnapshot[];
-  readonly layers: readonly AnimationLayerSnapshot[];
-  readonly values: Readonly<Record<string, AnimationValue>>;
-  readonly applyErrors: readonly AnimationApplyError[];
-};
-
-export type AnimationApplyError = {
-  readonly target: string;
-  readonly message: string;
-};
-
-type MixerLayer = Pick<AnimationLayer, "name" | "weight" | "additive" | "mask" | "actions" | "capturesTarget" | "snapshot">;
-type WeightedAccumulator = { value: AnimationValue; weight: number; type: string };
-type TargetAccumulator = { type: string; base?: WeightedAccumulator; additive?: AnimationValue };
-
-export class AnimationMixer {
-  readonly target: AnimationTarget | undefined;
-  timeScale = 1;
-  private readonly actions: AnimationAction[] = [];
-  private readonly layers: AnimationLayer[] = [];
-  private readonly values = new Map<string, AnimationValue>();
-  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;
-  }
-
-  play(clip: AnimationClip): AnimationAction {
-    this.assertAlive();
-    const action = new AnimationAction(clip).play();
-    this.actions.push(action);
-    return action;
-  }
-
-  addAction(action: AnimationAction): void {
-    this.assertAlive();
-    if (!this.actions.includes(action)) {
-      this.actions.push(action);
-    }
-  }
-
-  addLayer(layer: AnimationLayer): void {
-    this.assertAlive();
-    if (!this.layers.includes(layer)) {
-      this.layers.push(layer);
-    }
-  }
-
-  stopAll(): void {
-    this.assertAlive();
-    for (const action of this.actions) {
-      action.stop();
-    }
-  }
-
-  crossFade(from: AnimationAction, to: AnimationAction, duration: number): void {
-    this.assertAlive();
-    from.fadeTo(0, duration);
-    to.play().fadeTo(1, duration);
-    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) {
-      const previousTime = action.time;
-      const actionEvents = action.update(delta * this.timeScale);
-      if (actionEvents.length > 0) {
-        events.push(...actionEvents);
-      }
-      if (!action.playing && action.weight <= 0) {
-        continue;
-      }
-      this.applyActionRootMotion(action, previousTime);
-      for (const track of action.clip.tracks) {
-        const sample = track.sample(action.time);
-        for (const layer of this.layersForAction(action)) {
-          if (layer.capturesTarget(track.target)) {
-            blendInto(accumulators, track.target, track.valueType, sample, action.weight * layer.weight, layer.additive);
-          }
-        }
-      }
-    }
-    this.values.clear();
-    this.applyErrors = [];
-    for (const [target, accumulator] of accumulators) {
-      const value = finalizeTargetBlend(accumulator);
-      this.values.set(target, value);
-      try {
-        this.target?.setAnimationValue?.(target, value);
-      } catch (error) {
-        this.applyErrors.push({
-          target,
-          message: error instanceof Error ? error.message : String(error)
-        });
-      }
-    }
-    for (const event of events) {
-      for (const listener of Array.from(this.eventListeners)) {
-        listener(event);
-      }
-    }
-    return events;
-  }
-
-  getValue(target: string): AnimationValue | undefined {
-    const value = this.values.get(target);
-    return value === undefined ? undefined : cloneAnimationValue(value);
-  }
-
-  onEvent(listener: (event: AnimationEvent) => void): () => void {
-    this.assertAlive();
-    this.eventListeners.add(listener);
-    return () => this.eventListeners.delete(listener);
-  }
-
-  snapshot(): AnimationMixerSnapshot {
-    const values: Record<string, AnimationValue> = {};
-    for (const [target, value] of this.values) {
-      values[target] = cloneAnimationValue(value);
-    }
-    return {
-      timeScale: this.timeScale,
-      actionCount: this.actions.length,
-      actions: this.actions.map((action) => action.snapshot()),
-      layers: this.layers.map((layer) => layer.snapshot()),
-      values,
-      applyErrors: this.applyErrors.map((error) => ({ ...error }))
-    };
-  }
-
-  dispose(): void {
-    this.actions.length = 0;
-    this.layers.length = 0;
-    this.values.clear();
-    this.applyErrors = [];
-    this.eventListeners.clear();
-    this.inertialTransition = undefined;
-    this.disposed = true;
-  }
-
-  private assertAlive(): void {
-    if (this.disposed) {
-      throw new Error("AnimationMixer has been disposed.");
-    }
-  }
-
-  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";
-    if (!action.clip.tracks.some((track) => track.target === rootMotionTarget)) return;
-    const sample = extractRootMotion(action.clip, {
-      fromTime: previousTime,
-      toTime: action.time,
-      loop: action.loopMode === "repeat",
-      target: rootMotionTarget
-    });
-    const scaledSample = action.weight === 1
-      ? sample
-      : {
-          ...sample,
-          delta: [
-            sample.delta[0] * action.weight,
-            sample.delta[1] * action.weight,
-            sample.delta[2] * action.weight
-          ] as [number, number, number]
-        };
-    this.target?.applyRootMotion?.(scaledSample);
-    if (this.target?.position) {
-      applyRootMotion(this.target as RootMotionTarget, scaledSample, this.options.rootMotionScale ?? 1);
-    }
-  }
-
-  private layersForAction(action: AnimationAction): readonly MixerLayer[] {
-    if (this.layers.length === 0) {
-      return UNMASKED_LAYERS;
-    }
-    const owningLayers = this.layers.filter((layer) => layer.actions.includes(action));
-    return owningLayers.length > 0 ? owningLayers : UNMASKED_LAYERS;
-  }
-}
-
-const UNMASKED_LAYER: MixerLayer = {
-  name: "default",
-  weight: 1,
-  additive: false,
-  mask: [],
-  actions: [],
-  capturesTarget: () => true,
-  snapshot: () => ({ name: "default", weight: 1, additive: false, mask: [], actions: [] })
-};
-const UNMASKED_LAYERS: readonly MixerLayer[] = [UNMASKED_LAYER];
-
-function blendInto(accumulators: Map<string, TargetAccumulator>, target: string, type: string, value: AnimationValue, weight: number, additive: boolean): void {
-  if (weight <= 0) {
-    return;
-  }
-  const current = accumulators.get(target);
-  if (!current) {
-    const accumulator: TargetAccumulator = { type };
-    if (additive) {
-      accumulator.additive = additiveContribution(type, value, weight);
-    } else {
-      accumulator.base = { value: cloneAnimationValue(value), weight, type };
-    }
-    accumulators.set(target, accumulator);
-    return;
-  }
-  if (current.type !== type) {
-    throw new Error(`Cannot blend ${type} animation track into existing ${current.type} target ${target}.`);
-  }
-  if (additive) {
-    current.additive = current.additive === undefined
-      ? additiveContribution(type, value, weight)
-      : combineAdditive(type, current.additive, value, weight);
-    return;
-  }
-  if (!current.base) {
-    current.base = { value: cloneAnimationValue(value), weight, type };
-    return;
-  }
-  blendBase(current.base, type, value, weight);
-}
-
-function blendBase(current: WeightedAccumulator, type: string, value: AnimationValue, weight: number): void {
-  const total = current.weight + weight;
-  const t = weight / total;
-  if (type === "scalar") {
-    current.value = (current.value as number) + ((value as number) - (current.value as number)) * t;
-  } else if (type === "vector3") {
-    const a = current.value as [number, number, number];
-    const b = value as [number, number, number];
-    current.value = [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
-  } else if (type === "quaternion") {
-    current.value = slerpQuat(current.value as [number, number, number, number], value as [number, number, number, number], t);
-  } else if (type === "number-array") {
-    const a = current.value as readonly number[];
-    const b = value as readonly number[];
-    if (a.length !== b.length) {
-      throw new Error("Cannot blend number-array animation values with different lengths.");
-    }
-    current.value = a.map((component, index) => component + (b[index]! - component) * t);
-  } else {
-    current.value = cloneAnimationValue(value);
-  }
-  current.weight = total;
-}
-
-function finalizeTargetBlend(accumulator: TargetAccumulator): AnimationValue {
-  const base = accumulator.base
-    ? finalizeBaseBlend(accumulator.base)
-    : accumulator.additive !== undefined
-      ? additiveNeutral(accumulator.type, accumulator.additive)
-      : undefined;
-  if (base === undefined) {
-    throw new Error("Animation target accumulator has no sampled value.");
-  }
-  if (accumulator.additive === undefined) {
-    return base;
-  }
-  return applyAdditive(accumulator.type, base, accumulator.additive);
-}
-
-function finalizeBaseBlend(accumulator: WeightedAccumulator): AnimationValue {
-  if (accumulator.type === "quaternion") {
-    return normalizeQuat(accumulator.value as [number, number, number, number]);
-  }
-  return cloneAnimationValue(accumulator.value);
-}
-
-function additiveContribution(type: string, value: AnimationValue, weight: number): AnimationValue {
-  if (type === "scalar") {
-    return (value as number) * weight;
-  }
-  if (type === "vector3") {
-    const vector = value as [number, number, number];
-    return [vector[0] * weight, vector[1] * weight, vector[2] * weight];
-  }
-  if (type === "number-array") {
-    return (value as readonly number[]).map((component) => component * weight);
-  }
-  if (type === "quaternion") {
-    return slerpQuat([0, 0, 0, 1], normalizeQuat(value as [number, number, number, number]), weight);
-  }
-  throw new Error("Additive animation layers require numeric, vector, quaternion, or number-array tracks.");
-}
-
-function combineAdditive(type: string, current: AnimationValue, value: AnimationValue, weight: number): AnimationValue {
-  return applyAdditive(type, current, additiveContribution(type, value, weight));
-}
-
-function applyAdditive(type: string, base: AnimationValue, delta: AnimationValue): AnimationValue {
-  if (type === "scalar") {
-    return (base as number) + (delta as number);
-  }
-  if (type === "vector3") {
-    const a = base as [number, number, number];
-    const b = delta as [number, number, number];
-    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
-  }
-  if (type === "number-array") {
-    const a = base as readonly number[];
-    const b = delta as readonly number[];
-    if (a.length !== b.length) {
-      throw new Error("Cannot add number-array animation values with different lengths.");
-    }
-    return a.map((component, index) => component + b[index]!);
-  }
-  if (type === "quaternion") {
-    return normalizeQuat(multiplyQuat(base as [number, number, number, number], delta as [number, number, number, number]));
-  }
-  throw new Error("Additive animation layers require numeric, vector, quaternion, or number-array tracks.");
-}
-
-function additiveNeutral(type: string, value: AnimationValue): AnimationValue {
-  if (type === "scalar") {
-    return 0;
-  }
-  if (type === "vector3") {
-    return [0, 0, 0];
-  }
-  if (type === "number-array") {
-    return (value as readonly number[]).map(() => 0);
-  }
-  if (type === "quaternion") {
-    return [0, 0, 0, 1];
-  }
-  throw new Error("Additive animation layers require numeric, vector, quaternion, or number-array tracks.");
-}
-
-function multiplyQuat(a: [number, number, number, number], b: [number, number, number, number]): [number, number, number, number] {
-  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]
-  ];
-}

package/src/AnimationStateGraph.ts

@@ -1,105 +0,0 @@
-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;
-    }
-  };
-}