@certe/atmos-animation 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# 🎬 @certe/atmos-animation
+
+Skeletal animation system for the Atmos Engine. Provides skeleton data structures, keyframe sampling, pose blending, and an `AnimationMixer` component for clip playback and cross-fading.
+
+---
+
+## 🔑 Key Concepts
+
+- **Skeleton** — Joint hierarchy with inverse bind matrices and a rest pose
+- **AnimationClip** — Named collection of keyframe tracks targeting individual joints
+- **AnimationMixer** — Component that plays clips, blends weighted layers, and outputs bone matrices for GPU skinning
+
+---
+
+## 🚀 Quick Start
+
+```ts
+import { AnimationMixer, createSkeleton, createAnimationClip } from '@certe/atmos-animation';
+
+// Typically created automatically by instantiateModel() for glTF skinned meshes
+const mixer = gameObject.addComponent(AnimationMixer);
+mixer.skeleton = skeleton;
+mixer.addClip(walkClip);
+mixer.addClip(runClip);
+
+// Play
+const walkLayer = mixer.play(walkClip, { loop: true });
+
+// Cross-fade to run over 0.3 seconds
+const runLayer = mixer.play(runClip, { loop: true, weight: 0 });
+mixer.crossFade(walkLayer, runLayer, 0.3);
+```
+
+---
+
+## 📖 API Overview
+
+### Skeleton
+
+```ts
+import { createSkeleton, getInverseBindMatrix } from '@certe/atmos-animation';
+
+const skeleton = createSkeleton(
+  joints,               // Array<{ name, parentIndex }>
+  inverseBindMatrices,  // Float32Array (jointCount × 16)
+  restT, restR, restS   // Optional rest pose arrays
+);
+
+// Read one joint's IBM
+const ibm = Mat4.create();
+getInverseBindMatrix(ibm, skeleton, jointIndex);
+```
+
+### AnimationClip & Tracks
+
+```ts
+import { createAnimationClip } from '@certe/atmos-animation';
+
+const clip = createAnimationClip('walk', [
+  {
+    jointIndex: 0,
+    channel: 'rotation',
+    interpolation: 'LINEAR',
+    times: new Float32Array([0, 0.5, 1.0]),
+    values: new Float32Array([/* quaternion keyframes */]),
+  },
+]);
+// clip.duration is auto-computed from max track time
+```
+
+### Keyframe Sampling
+
+```ts
+import { sampleTrack } from '@certe/atmos-animation';
+
+const out = new Float32Array(4); // 4 for rotation, 3 for translation/scale
+sampleTrack(out, track, time);
+// Binary search + LINEAR (lerp/slerp) or STEP interpolation
+```
+
+### AnimationMixer Component
+
+| Method | Description |
+|---|---|
+| `play(clip, opts?)` | Play a clip, returns `AnimationLayer` |
+| `playByName(name, opts?)` | Play by clip name with optional cross-fade |
+| `crossFade(from, to, duration)` | Smooth transition between layers |
+| `stop(layer)` | Stop and remove a layer |
+| `resetToRestPose()` | Clear all layers |
+| `addClip(clip)` | Register a clip for `playByName` |
+
+| Property | Description |
+|---|---|
+| `skeleton` | The `Skeleton` to animate |
+| `boneMatrices` | `Float32Array` output (jointCount × 16) for GPU upload |
+| `clipNames` | Sorted list of registered clip names |
+| `speed` | Global playback speed multiplier |
+| `loop` | Default looping behavior |
+
+### Blending Algorithm
+
+Each frame, `onUpdate(dt)`:
+
+1. Sample all active layers' tracks at their current time
+2. Blend translation/scale as **delta-from-rest** weighted by layer weight
+3. Blend rotation via **weighted quaternion accumulation** with shortest-path sign flip
+4. Fill undriven joints with rest pose
+5. Call `computeBoneMatrices()` to produce final GPU-ready matrices
+
+---
+
+## 📁 Structure
+
+```
+packages/animation/src/
+  index.ts            # Public API
+  skeleton.ts         # Skeleton type + factory
+  animation-clip.ts   # AnimationClip + KeyframeTrack
+  keyframe-sampler.ts # Binary search + lerp/slerp (zero-alloc)
+  pose.ts             # computeBoneMatrices() — two-pass world × IBM
+  animation-mixer.ts  # AnimationMixer component
+  animation-handler.ts # Animation event handling
+  register-builtins.ts # Component registry integration
+```
+
+---
+
+## 🔗 Dependencies
+
+- `@certe/atmos-core` — Component lifecycle
+- `@certe/atmos-math` — Vec3, Mat4, Quat for pose computation and interpolation

package/dist/animation-clip.d.ts

@@ -0,0 +1,25 @@
+/** Interpolation mode for a keyframe track. */
+export type Interpolation = 'LINEAR' | 'STEP';
+/** Which transform channel a track controls. */
+export type AnimationChannel = 'translation' | 'rotation' | 'scale';
+/** A single track of keyframes targeting one joint's transform channel. */
+export interface KeyframeTrack {
+    jointIndex: number;
+    channel: AnimationChannel;
+    interpolation: Interpolation;
+    /** Keyframe timestamps in seconds. */
+    times: Float32Array;
+    /** Keyframe values (3 floats for T/S, 4 floats for R per keyframe). */
+    values: Float32Array;
+}
+/** A named animation clip containing multiple keyframe tracks. */
+export interface AnimationClip {
+    name: string;
+    duration: number;
+    tracks: readonly KeyframeTrack[];
+}
+/**
+ * Create an animation clip. Computes duration from the max time across all tracks.
+ */
+export declare function createAnimationClip(name: string, tracks: KeyframeTrack[]): AnimationClip;
+//# sourceMappingURL=animation-clip.d.ts.map

package/dist/animation-clip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-clip.d.ts","sourceRoot":"","sources":["../src/animation-clip.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9C,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,GAAG,OAAO,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,uEAAuE;IACvE,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EAAE,GACtB,aAAa,CASf"}

package/dist/animation-clip.js

@@ -0,0 +1,15 @@
+/**
+ * Create an animation clip. Computes duration from the max time across all tracks.
+ */
+export function createAnimationClip(name, tracks) {
+    let duration = 0;
+    for (const track of tracks) {
+        if (track.times.length > 0) {
+            const last = track.times[track.times.length - 1];
+            if (last > duration)
+                duration = last;
+        }
+    }
+    return { name, duration, tracks };
+}
+//# sourceMappingURL=animation-clip.js.map

package/dist/animation-clip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-clip.js","sourceRoot":"","sources":["../src/animation-clip.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,MAAuB;IAEvB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;YAClD,IAAI,IAAI,GAAG,QAAQ;gBAAE,QAAQ,GAAG,IAAI,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACpC,CAAC"}

package/dist/animation-handler.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AnimationHandler: lives on model root, delegates to child AnimationMixers.
+ * Provides a single control point for animation playback across all skinned meshes.
+ */
+import { Component } from '@certe/atmos-core';
+export declare class AnimationHandler extends Component {
+    /** Which clip to auto-play on start. */
+    initialClip: string;
+    /** Default playback speed multiplier. */
+    speed: number;
+    /** Whether clips loop by default. */
+    loop: boolean;
+    /** Whether to auto-play initialClip on start. */
+    autoplay: boolean;
+    /** Recursively collect all AnimationMixers from this GameObject and descendants. */
+    private _collectMixers;
+    /** Union of all clip names across child mixers, sorted and deduplicated. */
+    get clipNames(): string[];
+    /** Name of the currently playing clip (from first mixer found), or empty string. */
+    get currentClip(): string;
+    /** Play a clip by name on all child mixers. */
+    play(name: string, opts?: {
+        speed?: number;
+        loop?: boolean;
+        crossFadeDuration?: number;
+    }): void;
+    /** Stop all layers on all child mixers. */
+    stop(): void;
+    onStart(): void;
+}
+//# sourceMappingURL=animation-handler.d.ts.map

package/dist/animation-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-handler.d.ts","sourceRoot":"","sources":["../src/animation-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAc,MAAM,mBAAmB,CAAC;AAG1D,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,wCAAwC;IACxC,WAAW,SAAM;IACjB,yCAAyC;IACzC,KAAK,SAAK;IACV,qCAAqC;IACrC,IAAI,UAAQ;IACZ,iDAAiD;IACjD,QAAQ,UAAQ;IAEhB,oFAAoF;IACpF,OAAO,CAAC,cAAc;IAWtB,4EAA4E;IAC5E,IAAI,SAAS,IAAI,MAAM,EAAE,CAMxB;IAED,oFAAoF;IACpF,IAAI,WAAW,IAAI,MAAM,CAGxB;IAED,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,GAAG,IAAI;IAYR,2CAA2C;IAC3C,IAAI,IAAI,IAAI;IAQZ,OAAO,IAAI,IAAI;CAWhB"}

package/dist/animation-handler.js

@@ -0,0 +1,75 @@
+/**
+ * AnimationHandler: lives on model root, delegates to child AnimationMixers.
+ * Provides a single control point for animation playback across all skinned meshes.
+ */
+import { Component } from '@certe/atmos-core';
+import { AnimationMixer } from './animation-mixer.js';
+export class AnimationHandler extends Component {
+    /** Which clip to auto-play on start. */
+    initialClip = '';
+    /** Default playback speed multiplier. */
+    speed = 1;
+    /** Whether clips loop by default. */
+    loop = true;
+    /** Whether to auto-play initialClip on start. */
+    autoplay = true;
+    /** Recursively collect all AnimationMixers from this GameObject and descendants. */
+    _collectMixers() {
+        const result = [];
+        const walk = (go) => {
+            const mixer = go.getComponent(AnimationMixer);
+            if (mixer)
+                result.push(mixer);
+            for (const child of go.children)
+                walk(child);
+        };
+        walk(this.gameObject);
+        return result;
+    }
+    /** Union of all clip names across child mixers, sorted and deduplicated. */
+    get clipNames() {
+        const names = new Set();
+        for (const mixer of this._collectMixers()) {
+            for (const n of mixer.clipNames)
+                names.add(n);
+        }
+        return [...names].sort();
+    }
+    /** Name of the currently playing clip (from first mixer found), or empty string. */
+    get currentClip() {
+        const mixers = this._collectMixers();
+        return mixers.length > 0 ? mixers[0].currentClip : '';
+    }
+    /** Play a clip by name on all child mixers. */
+    play(name, opts) {
+        const speed = opts?.speed ?? this.speed;
+        const loop = opts?.loop ?? this.loop;
+        for (const mixer of this._collectMixers()) {
+            mixer.playByName(name, {
+                speed,
+                loop,
+                crossFadeDuration: opts?.crossFadeDuration,
+            });
+        }
+    }
+    /** Stop all layers on all child mixers. */
+    stop() {
+        for (const mixer of this._collectMixers()) {
+            for (const layer of [...mixer.layers]) {
+                mixer.stop(layer);
+            }
+        }
+    }
+    onStart() {
+        // Disable autoplay on all child mixers so they don't play independently
+        for (const mixer of this._collectMixers()) {
+            mixer.autoplay = false;
+        }
+        // Stop any existing playback (e.g. from previous play cycle) before starting
+        this.stop();
+        if (this.autoplay && this.initialClip) {
+            this.play(this.initialClip, { speed: this.speed, loop: this.loop });
+        }
+    }
+}
+//# sourceMappingURL=animation-handler.js.map

package/dist/animation-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-handler.js","sourceRoot":"","sources":["../src/animation-handler.ts"],"names":[],"mappings":"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"}

package/dist/animation-mixer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * AnimationMixer component: manages animation playback, blending, and crossfade.
+ * Produces bone matrices each frame for GPU skinning.
+ */
+import { Component } from '@certe/atmos-core';
+import type { Skeleton } from './skeleton.js';
+import type { AnimationClip } from './animation-clip.js';
+/** A single active animation layer. */
+export interface AnimationLayer {
+    clip: AnimationClip;
+    time: number;
+    speed: number;
+    weight: number;
+    loop: boolean;
+    playing: boolean;
+    /** Internal: used for crossfade weight ramping. */
+    _fadeSpeed: number;
+    /** Internal: target weight for crossfade. */
+    _fadeTarget: number;
+}
+export declare class AnimationMixer extends Component {
+    /** Final bone matrices (jointCount * 16 floats), uploaded to GPU each frame. */
+    boneMatrices: Float32Array | null;
+    /** Which clip to auto-play on start. */
+    initialClip: string;
+    /** Default playback speed multiplier. */
+    speed: number;
+    /** Whether clips loop by default. */
+    loop: boolean;
+    /** Whether to auto-play initialClip on start. */
+    autoplay: boolean;
+    private _skeleton;
+    private _layers;
+    private _clips;
+    private _blendedT;
+    private _blendedR;
+    private _blendedS;
+    private _accumWeightR;
+    get skeleton(): Skeleton | null;
+    set skeleton(sk: Skeleton | null);
+    /** Reset bone matrices to rest pose and stop all layers. */
+    resetToRestPose(): void;
+    /** Play a clip, returning the layer handle. */
+    play(clip: AnimationClip, opts?: {
+        speed?: number;
+        weight?: number;
+        loop?: boolean;
+    }): AnimationLayer;
+    /**
+     * Crossfade from one layer to another over `duration` seconds.
+     * `from` fades to 0 weight, `to` fades to 1 weight.
+     */
+    crossFade(from: AnimationLayer, to: AnimationLayer, duration: number): void;
+    /** Stop and remove a layer. */
+    stop(layer: AnimationLayer): void;
+    /** Get all active layers (read-only). */
+    get layers(): readonly AnimationLayer[];
+    /** Register a clip by name. */
+    addClip(clip: AnimationClip): void;
+    /** Sorted list of registered clip names. */
+    get clipNames(): string[];
+    /** Name of the currently playing clip (first layer), or empty string. */
+    get currentClip(): string;
+    /** Play a clip by name, with optional crossfade from the current clip. */
+    playByName(name: string, opts?: {
+        speed?: number;
+        loop?: boolean;
+        crossFadeDuration?: number;
+    }): AnimationLayer | null;
+    onStart(): void;
+    onUpdate(dt: number): void;
+    private _advanceLayers;
+    private _accumulateLayer;
+}
+//# sourceMappingURL=animation-mixer.d.ts.map

package/dist/animation-mixer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-mixer.d.ts","sourceRoot":"","sources":["../src/animation-mixer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD,qBAAa,cAAe,SAAQ,SAAS;IAC3C,gFAAgF;IAChF,YAAY,EAAE,YAAY,GAAG,IAAI,CAAQ;IAEzC,wCAAwC;IACxC,WAAW,SAAM;IACjB,yCAAyC;IACzC,KAAK,SAAK;IACV,qCAAqC;IACrC,IAAI,UAAQ;IACZ,iDAAiD;IACjD,QAAQ,UAAQ;IAEhB,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAoC;IAGlD,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,SAAS,CAA6B;IAG9C,OAAO,CAAC,aAAa,CAA6B;IAElD,IAAI,QAAQ,IAAI,QAAQ,GAAG,IAAI,CAA2B;IAE1D,IAAI,QAAQ,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,EAmB/B;IAED,4DAA4D;IAC5D,eAAe,IAAI,IAAI;IAUvB,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE;QAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,GAAG,cAAc;IAelB;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAS3E,+BAA+B;IAC/B,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAMjC,yCAAyC;IACzC,IAAI,MAAM,IAAI,SAAS,cAAc,EAAE,CAEtC;IAED,+BAA+B;IAC/B,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAIlC,4CAA4C;IAC5C,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAED,yEAAyE;IACzE,IAAI,WAAW,IAAI,MAAM,CAGxB;IAED,0EAA0E;IAC1E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,GAAG,cAAc,GAAG,IAAI;IAczB,OAAO,IAAI,IAAI;IAMf,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAgE1B,OAAO,CAAC,cAAc;IAkCtB,OAAO,CAAC,gBAAgB;CAqDzB"}

package/dist/animation-mixer.js

@@ -0,0 +1,274 @@
+/**
+ * AnimationMixer component: manages animation playback, blending, and crossfade.
+ * Produces bone matrices each frame for GPU skinning.
+ */
+import { Component } from '@certe/atmos-core';
+import { Quat } from '@certe/atmos-math';
+import { sampleTrack } from './keyframe-sampler.js';
+import { computeBoneMatrices } from './pose.js';
+// Scratch arrays for blending (module-level, zero alloc)
+const _sampledT = new Float32Array(3);
+const _sampledR = new Float32Array(4);
+const _sampledS = new Float32Array(3);
+const _blendR = new Float32Array(4);
+export class AnimationMixer extends Component {
+    /** Final bone matrices (jointCount * 16 floats), uploaded to GPU each frame. */
+    boneMatrices = null;
+    /** Which clip to auto-play on start. */
+    initialClip = '';
+    /** Default playback speed multiplier. */
+    speed = 1;
+    /** Whether clips loop by default. */
+    loop = true;
+    /** Whether to auto-play initialClip on start. */
+    autoplay = true;
+    _skeleton = null;
+    _layers = [];
+    _clips = new Map();
+    // Per-joint blended T/R/S (allocated when skeleton is set)
+    _blendedT = null;
+    _blendedR = null;
+    _blendedS = null;
+    // Accumulated rotation weight per joint (for rest-pose fill after blending)
+    _accumWeightR = null;
+    get skeleton() { return this._skeleton; }
+    set skeleton(sk) {
+        this._skeleton = sk;
+        if (sk) {
+            const jc = sk.jointCount;
+            this._blendedT = new Float32Array(jc * 3);
+            this._blendedR = new Float32Array(jc * 4);
+            this._blendedS = new Float32Array(jc * 3);
+            this.boneMatrices = new Float32Array(jc * 16);
+            // Compute rest-pose bone matrices immediately so GPU has valid data before first update
+            this._blendedT.set(sk.restT);
+            this._blendedR.set(sk.restR);
+            this._blendedS.set(sk.restS);
+            computeBoneMatrices(this.boneMatrices, sk, this._blendedT, this._blendedR, this._blendedS);
+        }
+        else {
+            this.boneMatrices = null;
+            this._blendedT = null;
+            this._blendedR = null;
+            this._blendedS = null;
+        }
+    }
+    /** Reset bone matrices to rest pose and stop all layers. */
+    resetToRestPose() {
+        const sk = this._skeleton;
+        if (!sk || !this.boneMatrices || !this._blendedT)
+            return;
+        this._layers.length = 0;
+        this._blendedT.set(sk.restT);
+        this._blendedR.set(sk.restR);
+        this._blendedS.set(sk.restS);
+        computeBoneMatrices(this.boneMatrices, sk, this._blendedT, this._blendedR, this._blendedS);
+    }
+    /** Play a clip, returning the layer handle. */
+    play(clip, opts) {
+        const layer = {
+            clip,
+            time: 0,
+            speed: opts?.speed ?? 1,
+            weight: opts?.weight ?? 1,
+            loop: opts?.loop ?? true,
+            playing: true,
+            _fadeSpeed: 0,
+            _fadeTarget: opts?.weight ?? 1,
+        };
+        this._layers.push(layer);
+        return layer;
+    }
+    /**
+     * Crossfade from one layer to another over `duration` seconds.
+     * `from` fades to 0 weight, `to` fades to 1 weight.
+     */
+    crossFade(from, to, duration) {
+        const d = Math.max(duration, 0.001);
+        from._fadeTarget = 0;
+        from._fadeSpeed = from.weight / d;
+        to.weight = 0;
+        to._fadeTarget = 1;
+        to._fadeSpeed = 1 / d;
+    }
+    /** Stop and remove a layer. */
+    stop(layer) {
+        layer.playing = false;
+        const idx = this._layers.indexOf(layer);
+        if (idx >= 0)
+            this._layers.splice(idx, 1);
+    }
+    /** Get all active layers (read-only). */
+    get layers() {
+        return this._layers;
+    }
+    /** Register a clip by name. */
+    addClip(clip) {
+        this._clips.set(clip.name, clip);
+    }
+    /** Sorted list of registered clip names. */
+    get clipNames() {
+        return [...this._clips.keys()].sort();
+    }
+    /** Name of the currently playing clip (first layer), or empty string. */
+    get currentClip() {
+        const first = this._layers[0];
+        return first ? first.clip.name : '';
+    }
+    /** Play a clip by name, with optional crossfade from the current clip. */
+    playByName(name, opts) {
+        const clip = this._clips.get(name);
+        if (!clip)
+            return null;
+        const layer = this.play(clip, {
+            speed: opts?.speed ?? this.speed,
+            loop: opts?.loop ?? this.loop,
+        });
+        if (opts?.crossFadeDuration && this._layers.length > 1) {
+            const from = this._layers[this._layers.length - 2];
+            this.crossFade(from, layer, opts.crossFadeDuration);
+        }
+        return layer;
+    }
+    onStart() {
+        if (this.autoplay && this.initialClip) {
+            this.playByName(this.initialClip, { speed: this.speed, loop: this.loop });
+        }
+    }
+    onUpdate(dt) {
+        if (!this._skeleton || !this._blendedT)
+            return;
+        const jc = this._skeleton.jointCount;
+        // Advance layers and handle fades
+        this._advanceLayers(dt);
+        // Start from rest pose (T/S stay as rest, R zeroed for accumulation)
+        const sk = this._skeleton;
+        this._blendedT.set(sk.restT);
+        this._blendedS.set(sk.restS);
+        this._blendedR.fill(0);
+        // Track accumulated rotation weight per joint
+        if (!this._accumWeightR || this._accumWeightR.length !== jc) {
+            this._accumWeightR = new Float32Array(jc);
+        }
+        this._accumWeightR.fill(0);
+        // Accumulate weighted samples
+        for (const layer of this._layers) {
+            if (!layer.playing || layer.weight <= 0)
+                continue;
+            this._accumulateLayer(layer, jc);
+        }
+        // Fill in rest-pose quaternion for joints not fully covered by animations
+        const br = this._blendedR;
+        for (let j = 0; j < jc; j++) {
+            const aw = this._accumWeightR[j];
+            const rOff = j * 4;
+            if (aw < 0.001) {
+                // No animation touched this joint — use rest pose directly
+                br[rOff] = sk.restR[rOff];
+                br[rOff + 1] = sk.restR[rOff + 1];
+                br[rOff + 2] = sk.restR[rOff + 2];
+                br[rOff + 3] = sk.restR[rOff + 3];
+            }
+            else if (aw < 0.999) {
+                // Partially covered — blend in rest pose for remaining weight
+                const restW = 1 - aw;
+                const dot = br[rOff] * sk.restR[rOff] + br[rOff + 1] * sk.restR[rOff + 1] +
+                    br[rOff + 2] * sk.restR[rOff + 2] + br[rOff + 3] * sk.restR[rOff + 3];
+                const sign = dot < 0 ? -1 : 1;
+                br[rOff] = br[rOff] + sk.restR[rOff] * restW * sign;
+                br[rOff + 1] = br[rOff + 1] + sk.restR[rOff + 1] * restW * sign;
+                br[rOff + 2] = br[rOff + 2] + sk.restR[rOff + 2] * restW * sign;
+                br[rOff + 3] = br[rOff + 3] + sk.restR[rOff + 3] * restW * sign;
+            }
+            Quat.normalize(br.subarray(rOff, rOff + 4), br.subarray(rOff, rOff + 4));
+        }
+        // Compute final bone matrices
+        computeBoneMatrices(this.boneMatrices, this._skeleton, this._blendedT, this._blendedR, this._blendedS);
+    }
+    _advanceLayers(dt) {
+        for (let i = this._layers.length - 1; i >= 0; i--) {
+            const layer = this._layers[i];
+            if (!layer.playing)
+                continue;
+            // Advance time
+            layer.time += dt * layer.speed;
+            // Loop or clamp
+            if (layer.loop) {
+                if (layer.clip.duration > 0) {
+                    layer.time = layer.time % layer.clip.duration;
+                    if (layer.time < 0)
+                        layer.time += layer.clip.duration;
+                }
+            }
+            else {
+                layer.time = Math.min(layer.time, layer.clip.duration);
+            }
+            // Apply fade
+            if (layer._fadeSpeed > 0) {
+                if (layer.weight < layer._fadeTarget) {
+                    layer.weight = Math.min(layer.weight + layer._fadeSpeed * dt, layer._fadeTarget);
+                }
+                else if (layer.weight > layer._fadeTarget) {
+                    layer.weight = Math.max(layer.weight - layer._fadeSpeed * dt, layer._fadeTarget);
+                }
+                // Remove fully faded-out layers
+                if (layer._fadeTarget === 0 && layer.weight <= 0) {
+                    this._layers.splice(i, 1);
+                }
+            }
+        }
+    }
+    _accumulateLayer(layer, jointCount) {
+        const w = layer.weight;
+        const bt = this._blendedT;
+        const br = this._blendedR;
+        const bs = this._blendedS;
+        const sk = this._skeleton;
+        // Sample each track and blend using delta-from-rest for T/S,
+        // weighted accumulation + rest fill for R (done in onUpdate post-pass).
+        for (const track of layer.clip.tracks) {
+            const ji = track.jointIndex;
+            if (ji < 0 || ji >= jointCount)
+                continue;
+            switch (track.channel) {
+                case 'translation': {
+                    sampleTrack(_sampledT, track, layer.time);
+                    const off = ji * 3;
+                    // Delta from rest: bt starts at restT, add (sampled - rest) * weight
+                    bt[off] = bt[off] + (_sampledT[0] - sk.restT[off]) * w;
+                    bt[off + 1] = bt[off + 1] + (_sampledT[1] - sk.restT[off + 1]) * w;
+                    bt[off + 2] = bt[off + 2] + (_sampledT[2] - sk.restT[off + 2]) * w;
+                    break;
+                }
+                case 'rotation': {
+                    sampleTrack(_sampledR, track, layer.time);
+                    const rOff = ji * 4;
+                    this._accumWeightR[ji] = this._accumWeightR[ji] + w;
+                    // Weighted quaternion accumulation (shortest path)
+                    _blendR[0] = br[rOff];
+                    _blendR[1] = br[rOff + 1];
+                    _blendR[2] = br[rOff + 2];
+                    _blendR[3] = br[rOff + 3];
+                    const dot = _blendR[0] * _sampledR[0] + _blendR[1] * _sampledR[1] +
+                        _blendR[2] * _sampledR[2] + _blendR[3] * _sampledR[3];
+                    const sign = dot < 0 ? -1 : 1;
+                    br[rOff] = br[rOff] + _sampledR[0] * w * sign;
+                    br[rOff + 1] = br[rOff + 1] + _sampledR[1] * w * sign;
+                    br[rOff + 2] = br[rOff + 2] + _sampledR[2] * w * sign;
+                    br[rOff + 3] = br[rOff + 3] + _sampledR[3] * w * sign;
+                    break;
+                }
+                case 'scale': {
+                    sampleTrack(_sampledS, track, layer.time);
+                    const sOff = ji * 3;
+                    // Delta from rest: bs starts at restS, add (sampled - rest) * weight
+                    bs[sOff] = bs[sOff] + (_sampledS[0] - sk.restS[sOff]) * w;
+                    bs[sOff + 1] = bs[sOff + 1] + (_sampledS[1] - sk.restS[sOff + 1]) * w;
+                    bs[sOff + 2] = bs[sOff + 2] + (_sampledS[2] - sk.restS[sOff + 2]) * w;
+                    break;
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=animation-mixer.js.map