@zephyr3d/editor 0.3.5 → 0.3.7

package/dist/vendor/zephyr3d/scene/dist/animation/animationset.js

@@ -1,4 +1,4 @@
-import { Disposable, weightedAverage, Quaternion, Interpolator, Vector3 } from '@zephyr3d/base';
+import { makeObservable, Disposable, weightedAverage, Quaternion, Observable, Interpolator, Vector3 } from '@zephyr3d/base';
 import { AnimationClip } from './animation.js';
 import { NodeRotationTrack } from './rotationtrack.js';
 import { NodeEulerRotationTrack } from './eulerrotationtrack.js';
@@ -7,6 +7,224 @@ import { NodeScaleTrack } from './scaletrack.js';
 import { HumanoidBodyRig } from './skeleton.js';
 import { createSkeletalMaskedAnimationClip } from './animationmask.js';
 
+let nextAnimationPlaybackId = 1;
+/**
+ * Runtime handle for one playback of an AnimationClip.
+ * @public
+ */ class AnimationPlayback extends Observable {
+    /** @internal */ _animationSet;
+    /** @internal */ _clip;
+    /** @internal */ _options;
+    /** @internal */ _id;
+    /** @internal */ _frameWaiters;
+    /** @internal */ _state;
+    /** @internal */ _time;
+    /** @internal */ _weight;
+    /** @internal */ _speedRatio;
+    /** @internal */ _layer;
+    /** @internal */ _priority;
+    /** @internal */ _interruptible;
+    constructor(animationSet, clip, options){
+        super();
+        this._animationSet = animationSet;
+        this._clip = clip;
+        this._options = {
+            ...options ?? {}
+        };
+        this._id = this._options.id ?? `animation-playback-${nextAnimationPlaybackId++}`;
+        this._state = 'scheduled';
+        this._speedRatio = this._options.speedRatio ?? 1;
+        this._weight = this._options.weight ?? clip.weight ?? 1;
+        this._time = this._speedRatio < 0 ? clip.timeDuration : 0;
+        this._layer = this._options.layer ?? 'default';
+        this._priority = this._options.priority ?? 0;
+        this._interruptible = this._options.interruptible ?? true;
+        this._frameWaiters = new Map();
+    }
+    get id() {
+        return this._id;
+    }
+    get animationSet() {
+        return this._animationSet;
+    }
+    get clip() {
+        return this._clip;
+    }
+    get state() {
+        return this._state;
+    }
+    get time() {
+        return this._time;
+    }
+    set time(value) {
+        this.seek(value);
+    }
+    get normalizedTime() {
+        return this._clip.timeDuration > 0 ? this._time / this._clip.timeDuration : 0;
+    }
+    set normalizedTime(value) {
+        this.seek(value * this._clip.timeDuration);
+    }
+    get weight() {
+        return this._weight;
+    }
+    set weight(value) {
+        this._animationSet.setPlaybackWeight(this, value);
+    }
+    get speedRatio() {
+        return this._speedRatio;
+    }
+    set speedRatio(value) {
+        this._animationSet.setPlaybackSpeedRatio(this, value);
+    }
+    get layer() {
+        return this._layer;
+    }
+    get priority() {
+        return this._priority;
+    }
+    get interruptible() {
+        return this._interruptible;
+    }
+    play() {
+        this._animationSet.startPlayback(this);
+        return this;
+    }
+    pause() {
+        this._animationSet.pausePlayback(this);
+        return this;
+    }
+    resume() {
+        this._animationSet.resumePlayback(this);
+        return this;
+    }
+    stop(options) {
+        this._animationSet.stopPlayback(this, options);
+        return this;
+    }
+    seek(time, options) {
+        this._animationSet.seekPlayback(this, time, options);
+        return this;
+    }
+    fadeTo(weight, duration) {
+        this._animationSet.fadePlaybackTo(this, weight, duration);
+        return this;
+    }
+    crossFadeTo(name, options) {
+        const duration = Math.max(options?.duration ?? 0, 0);
+        this.stop({
+            fadeOut: duration,
+            reason: 'interrupted'
+        });
+        return this._animationSet.play(name, {
+            ...options,
+            fadeIn: duration
+        });
+    }
+    waitForComplete() {
+        return new Promise((resolve)=>{
+            this.once('complete', ()=>resolve(this));
+        });
+    }
+    waitForMarker(idOrName) {
+        if (this._state === 'stopped' || this._state === 'completed') {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve)=>{
+            const handler = (event)=>{
+                if (event.marker.id === idOrName || event.marker.name === idOrName) {
+                    this.off('marker', handler);
+                    this.off('stop', stop);
+                    resolve(event);
+                }
+            };
+            const stop = ()=>{
+                this.off('marker', handler);
+                this.off('stop', stop);
+                resolve(undefined);
+            };
+            this.on('marker', handler);
+            this.on('stop', stop);
+        });
+    }
+    waitForFrame(frame) {
+        if (this._state === 'stopped' || this._state === 'completed') {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve)=>{
+            const waiters = this._frameWaiters.get(frame) ?? [];
+            let settled = false;
+            let stop;
+            const wrappedResolve = (event)=>{
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                this.off('stop', stop);
+                resolve(event);
+            };
+            stop = ()=>{
+                const current = this._frameWaiters.get(frame);
+                if (current) {
+                    this._frameWaiters.set(frame, current.filter((item)=>item !== wrappedResolve));
+                }
+                wrappedResolve(undefined);
+            };
+            waiters.push(wrappedResolve);
+            this._frameWaiters.set(frame, waiters);
+            this.on('stop', stop);
+        });
+    }
+    /** @internal */ _getOptions() {
+        return this._options;
+    }
+    /** @internal */ _setState(state) {
+        this._state = state;
+    }
+    /** @internal */ _setTime(time) {
+        this._time = time;
+    }
+    /** @internal */ _setWeight(weight) {
+        this._weight = weight;
+    }
+    /** @internal */ _setSpeedRatio(speedRatio) {
+        this._speedRatio = speedRatio;
+    }
+    /** @internal */ _getWatchedFrames() {
+        return [
+            ...this._frameWaiters.keys()
+        ];
+    }
+    /** @internal */ _emitStart(event) {
+        this.dispatchEvent('start', event);
+    }
+    /** @internal */ _emitLoop(event) {
+        this.dispatchEvent('loop', event);
+    }
+    /** @internal */ _emitMarker(event) {
+        this.dispatchEvent('marker', event);
+    }
+    /** @internal */ _emitFrame(event) {
+        this.dispatchEvent('frame', event);
+        const waiters = this._frameWaiters.get(event.frame);
+        if (waiters) {
+            this._frameWaiters.delete(event.frame);
+            waiters.forEach((resolve)=>resolve(event));
+        }
+    }
+    /** @internal */ _emitComplete(event) {
+        this.dispatchEvent('complete', event);
+    }
+    /** @internal */ _emitStop(event) {
+        this.dispatchEvent('stop', event);
+    }
+    /** @internal */ _emitPause(event) {
+        this.dispatchEvent('pause', event);
+    }
+    /** @internal */ _emitResume(event) {
+        this.dispatchEvent('resume', event);
+    }
+}
 function cloneInterpolator(src) {
     return new Interpolator(src.mode, src.target, src.inputs instanceof Float32Array ? new Float32Array(src.inputs) : [
         ...src.inputs
@@ -388,26 +606,26 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         dstClip.addTrack(remap.dstNode, track);
     }
 }
-/**
- * Animation set
- *
- * Manages a collection of named animation clips for a model and orchestrates:
- * - Playback state (time, loops, speed, weights, fade-in/out).
- * - Blending across multiple tracks targeting the same property via weighted averages.
- * - Skeleton usage and application for clips that drive skeletal animation.
- * - Active track registration and cleanup as clips start/stop.
- *
- * Usage:
- * - Create or retrieve `AnimationClip`s by name.
- * - Start playback with `playAnimation(name, options)`.
- * - Advance animation with `update(deltaSeconds)`.
- * - Optionally adjust weight while playing with `setAnimationWeight(name, weight)`.
- *
- * Lifetime:
- * - Disposing the set releases references to the model, clips, and clears active state.
- *
- * @public
- */ class AnimationSet extends Disposable {
+/**
+ * Animation set
+ *
+ * Manages a collection of named animation clips for a model and orchestrates:
+ * - Playback state (time, loops, speed, weights, fade-in/out).
+ * - Blending across multiple tracks targeting the same property via weighted averages.
+ * - Skeleton usage and application for clips that drive skeletal animation.
+ * - Active track registration and cleanup as clips start/stop.
+ *
+ * Usage:
+ * - Create or retrieve `AnimationClip`s by name.
+ * - Start playback with `playAnimation(name, options)`.
+ * - Advance animation with `update(deltaSeconds)`.
+ * - Optionally adjust weight while playing with `setAnimationWeight(name, weight)`.
+ *
+ * Lifetime:
+ * - Disposing the set releases references to the model, clips, and clears active state.
+ *
+ * @public
+ */ class AnimationSet extends makeObservable(Disposable)() {
     /** @internal */ _model;
     /** @internal */ _animations;
     /** @internal */ _skeletons;
@@ -416,10 +634,18 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     /** @internal */ _activeSkinBindings;
     /** @internal */ _activeRigs;
     /** @internal */ _activeAnimations;
-    /**
-   * Create an AnimationSet controlling the provided model.
-   *
-   * @param model - The SceneNode (model root) controlled by this animation set.
+    /**
+   * Callbacks driven by the same logical clock as the animations (see {@link update}).
+   *
+   * Used by higher-level constructs (e.g. timeline runners) that need to advance
+   * wall-clock-independent timers in sync with playback, so they pause/scale with the
+   * game clock instead of running on real time.
+   * @internal
+   */ _timelineTickers;
+    /**
+   * Create an AnimationSet controlling the provided model.
+   *
+   * @param model - The SceneNode (model root) controlled by this animation set.
    */ constructor(model){
         super();
         this._model = model;
@@ -430,29 +656,42 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         this._activeAnimations = new Map();
         this._skeletons = [];
         this._rigs = [];
+        this._timelineTickers = new Set();
+    }
+    /**
+   * Register a callback advanced by {@link update} using the same delta time as the animations.
+   * @internal
+   */ _registerTimelineTicker(ticker) {
+        this._timelineTickers.add(ticker);
     }
-    /**
-   * The model (SceneNode) controlled by this animation set.
+    /**
+   * Unregister a callback previously registered with {@link _registerTimelineTicker}.
+   * @internal
+   */ _unregisterTimelineTicker(ticker) {
+        this._timelineTickers.delete(ticker);
+    }
+    /**
+   * The model (SceneNode) controlled by this animation set.
    */ get model() {
         return this._model;
     }
-    /**
-   * Number of animation clips registered in this set.
+    /**
+   * Number of animation clips registered in this set.
    */ get numAnimations() {
         return Object.getOwnPropertyNames(this._animations).length;
     }
-    /**
-   * The skeletons used by animations in this set.
+    /**
+   * The skeletons used by animations in this set.
    */ get skeletons() {
         return this._skeletons;
     }
-    /**
-   * The shared rigs used by animations in this set.
+    /**
+   * The shared rigs used by animations in this set.
    */ get rigs() {
         return this._rigs;
     }
-    /**
-   * Per-skin bindings used by skinned meshes in this set.
+    /**
+   * Per-skin bindings used by skinned meshes in this set.
    */ get skinBindings() {
         return this._skeletons;
     }
@@ -474,20 +713,20 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         }
         return rig;
     }
-    /**
-   * Retrieve an animation clip by name.
-   *
-   * @param name - Name of the animation.
-   * @returns The clip if present; otherwise null.
+    /**
+   * Retrieve an animation clip by name.
+   *
+   * @param name - Name of the animation.
+   * @returns The clip if present; otherwise null.
    */ get(name) {
         return this._animations[name] ?? null;
     }
-    /**
-   * Create and register a new animation clip.
-   *
-   * @param name - Unique name for the animation clip.
-   * @param embedded - Whether the clip is embedded/owned (implementation-specific). Default false.
-   * @returns The created clip, or null if the name is empty or not unique.
+    /**
+   * Create and register a new animation clip.
+   *
+   * @param name - Unique name for the animation clip.
+   * @param embedded - Whether the clip is embedded/owned (implementation-specific). Default false.
+   * @returns The created clip, or null if the name is empty or not unique.
    */ createAnimation(name, embedded = false) {
         if (!name || this._animations[name]) {
             console.error('Animation must have unique name');
@@ -499,12 +738,12 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             return animation;
         }
     }
-    /**
-   * Delete and dispose an animation clip by name.
-   *
-   * - If the animation is currently playing, it is first stopped (immediately).
-   *
-   * @param name - Name of the animation to remove.
+    /**
+   * Delete and dispose an animation clip by name.
+   *
+   * - If the animation is currently playing, it is first stopped (immediately).
+   *
+   * @param name - Name of the animation to remove.
    */ deleteAnimation(name) {
         const animation = this._animations[name];
         if (animation) {
@@ -513,50 +752,119 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             animation.dispose();
         }
     }
-    /**
-   * Get the list of all registered animation names.
-   *
-   * @returns An array of clip names.
+    /**
+   * Get the list of all registered animation names.
+   *
+   * @returns An array of clip names.
    */ getAnimationNames() {
         return Object.keys(this._animations);
     }
-    /**
-   * Advance and apply active animations.
-   *
-   * Responsibilities per call:
-   * - Update time cursor for each active clip (respecting speedRatio and looping).
-   * - Enforce repeat limits and apply fade-out termination if configured.
-   * - For each animated target, blend active tracks (weighted by clip weight × fade-in × fade-out)
-   *   and apply the resulting state to the target.
-   * - Apply shared rig modifiers once, then update skin binding palettes.
-   *
-   * @param deltaInSeconds - Time step in seconds since last update.
+    /**
+   * Advance and apply active animations.
+   *
+   * Responsibilities per call:
+   * - Update time cursor for each active clip (respecting speedRatio and looping).
+   * - Enforce repeat limits and apply fade-out termination if configured.
+   * - For each animated target, blend active tracks (weighted by clip weight × fade-in × fade-out)
+   *   and apply the resulting state to the target.
+   * - Apply shared rig modifiers once, then update skin binding palettes.
+   *
+   * @param deltaInSeconds - Time step in seconds since last update.
    */ update(deltaInSeconds) {
         this._activeAnimations.forEach((v, k)=>{
+            if (!v.started) {
+                v.started = true;
+                const event = this.createPlaybackEvent(v, k);
+                v.playback._emitStart(event);
+                this.dispatchEvent('playbackstart', event);
+            }
+            if (v.paused) {
+                return;
+            }
             if (v.fadeOut > 0 && v.fadeOutStart < 0) {
                 v.fadeOutStart = v.animateTime;
             }
+            if (v.completed) {
+                v.animateTime += Math.abs(deltaInSeconds * v.speedRatio);
+                if (v.fadeOut > 0 && v.animateTime - v.fadeOutStart >= v.fadeOut) {
+                    this.stopAnimation(k.name, {
+                        reason: v.stopReason
+                    });
+                }
+                return;
+            }
             // Update animation time
             if (v.firstFrame) {
                 v.firstFrame = false;
             } else {
+                const previousTime = v.currentTime;
                 const timeAdvance = deltaInSeconds * v.speedRatio;
                 v.currentTime += timeAdvance;
                 v.animateTime += timeAdvance;
+                const direction = timeAdvance >= 0 ? 1 : -1;
                 if (k.timeDuration > 0) {
-                    if (v.currentTime > k.timeDuration) {
-                        v.repeatCounter += Math.max(1, Math.floor(v.currentTime / k.timeDuration));
+                    if (v.rangeEnd !== null && v.speedRatio >= 0 && v.currentTime >= v.rangeEnd) {
+                        v.currentTime = v.rangeEnd;
+                        v.playback._setTime(v.currentTime);
+                        this.completePlayback(k, v);
+                        return;
+                    } else if (v.rangeStart !== null && v.speedRatio < 0 && v.currentTime <= v.rangeStart) {
+                        v.currentTime = v.rangeStart;
+                        v.playback._setTime(v.currentTime);
+                        this.completePlayback(k, v);
+                        return;
+                    } else if (v.currentTime > k.timeDuration) {
+                        const loops = Math.max(1, Math.floor(v.currentTime / k.timeDuration));
+                        if (v.repeat !== 0 && v.repeatCounter + loops >= v.repeat) {
+                            v.repeatCounter += loops;
+                            v.currentTime = k.timeDuration;
+                            v.playback._setTime(v.currentTime);
+                            this.emitCrossedMarkers(v, k, previousTime, v.currentTime, direction);
+                            this.emitCrossedFrames(v, k, previousTime, v.currentTime, direction);
+                            this.completePlayback(k, v);
+                            return;
+                        }
+                        v.repeatCounter += loops;
                         v.currentTime %= k.timeDuration;
+                        const event = this.createPlaybackEvent(v, k);
+                        v.playback._emitLoop(event);
+                        this.dispatchEvent('playbackloop', event);
                     } else if (v.currentTime < 0) {
-                        v.repeatCounter += Math.max(1, Math.ceil(-v.currentTime / k.timeDuration));
+                        const loops = Math.max(1, Math.ceil(-v.currentTime / k.timeDuration));
+                        if (v.repeat !== 0 && v.repeatCounter + loops >= v.repeat) {
+                            v.repeatCounter += loops;
+                            v.currentTime = 0;
+                            v.playback._setTime(v.currentTime);
+                            this.emitCrossedMarkers(v, k, previousTime, v.currentTime, direction);
+                            this.emitCrossedFrames(v, k, previousTime, v.currentTime, direction);
+                            this.completePlayback(k, v);
+                            return;
+                        }
+                        v.repeatCounter += loops;
                         v.currentTime = (v.currentTime % k.timeDuration + k.timeDuration) % k.timeDuration;
+                        const event = this.createPlaybackEvent(v, k);
+                        v.playback._emitLoop(event);
+                        this.dispatchEvent('playbackloop', event);
                     }
                 }
+                v.playback._setTime(v.currentTime);
+                this.emitCrossedMarkers(v, k, previousTime, v.currentTime, direction);
+                this.emitCrossedFrames(v, k, previousTime, v.currentTime, direction);
                 if (v.repeat !== 0 && v.repeatCounter >= v.repeat) {
-                    this.stopAnimation(k.name);
+                    this.completePlayback(k, v);
                 } else if (v.fadeOut > 0) {
                     if (v.animateTime - v.fadeOutStart >= v.fadeOut) {
-                        this.stopAnimation(k.name);
+                        this.stopAnimation(k.name, {
+                            reason: v.stopReason
+                        });
+                    }
+                }
+                if (v.fadeToDuration > 0) {
+                    const t = Math.min(1, (v.animateTime - v.fadeToStart) / v.fadeToDuration);
+                    v.weight = v.fadeFromWeight + (v.fadeTargetWeight - v.fadeFromWeight) * t;
+                    v.playback._setWeight(v.weight);
+                    if (t >= 1) {
+                        v.fadeToDuration = 0;
                     }
                 }
             }
@@ -596,12 +904,17 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         this._skeletons.forEach((v)=>{
             v.get()?.apply();
         });
+        // Advance logical-clock timers (e.g. timeline `wait` steps) with the same delta time,
+        // so they stay in sync with playback and pause/scale with the game clock.
+        if (this._timelineTickers.size > 0) {
+            this._timelineTickers.forEach((ticker)=>ticker(deltaInSeconds));
+        }
     }
-    /**
-   * Check whether an animation is currently playing.
-   *
-   * @param name - Optional animation name. If omitted, returns true if any animation is playing.
-   * @returns True if playing; otherwise false.
+    /**
+   * Check whether an animation is currently playing.
+   *
+   * @param name - Optional animation name. If omitted, returns true if any animation is playing.
+   * @returns True if playing; otherwise false.
    */ isPlayingAnimation(name) {
         if (name) {
             const animation = this._animations[name];
@@ -609,23 +922,23 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         }
         return this._activeAnimations.size > 0;
     }
-    /**
-   * Get an animation clip by name.
-   *
-   * Alias of `get(name)` returning a nullable type.
-   *
-   * @param name - Name of the animation.
-   * @returns The clip if present; otherwise null.
+    /**
+   * Get an animation clip by name.
+   *
+   * Alias of `get(name)` returning a nullable type.
+   *
+   * @param name - Name of the animation.
+   * @returns The clip if present; otherwise null.
    */ getAnimationClip(name) {
         return this._animations[name] ?? null;
     }
-    /**
-   * Set the runtime blend weight for a currently playing animation.
-   *
-   * Has no effect if the clip is not active.
-   *
-   * @param name - Name of the playing animation.
-   * @param weight - New weight value used during blending.
+    /**
+   * Set the runtime blend weight for a currently playing animation.
+   *
+   * Has no effect if the clip is not active.
+   *
+   * @param name - Name of the playing animation.
+   * @param weight - New weight value used during blending.
    */ setAnimationWeight(name, weight) {
         const ani = this._animations[name];
         if (!ani) {
@@ -635,42 +948,104 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         const info = this._activeAnimations.get(ani);
         if (info) {
             info.weight = weight;
+            info.targetWeight = weight;
+            info.playback._setWeight(weight);
         }
     }
-    /**
-   * Start (or update) playback of an animation clip.
-   *
-   * Behavior:
-   * - If the clip is already playing, stops it first.
-   * - Otherwise initializes playback state (repeat counter, speed, weight, initial time).
-   * - Registers clip tracks and skeletons into the active sets for blending and application.
-   *
-   * @param name - Name of the animation to play.
-   * @param options - Playback options (repeat, speedRatio, fadeIn).
-   */ playAnimation(name, options) {
+    /**
+   * Create a playback handle without starting it.
+   */ createPlayback(name, options) {
         const ani = this._animations[name];
         if (!ani) {
             console.error(`Animation ${name} not exists`);
-            return;
+            return null;
         }
-        if (this.isPlayingAnimation(name)) {
-            this.stopAnimation(name);
+        return new AnimationPlayback(this, ani, options);
+    }
+    /**
+   * Start an animation and return its playback handle.
+   */ play(name, options) {
+        const playback = this.createPlayback(name, options);
+        playback?.play();
+        return playback;
+    }
+    /**
+   * Get currently active playbacks.
+   */ getPlaybacks(name) {
+        const playbacks = [];
+        this._activeAnimations.forEach((info, clip)=>{
+            if (!name || clip.name === name) {
+                playbacks.push(info.playback);
+            }
+        });
+        return playbacks;
+    }
+    /**
+   * Get the currently active playback for a clip.
+   */ getPlayback(name) {
+        const clip = this._animations[name];
+        return clip ? this._activeAnimations.get(clip)?.playback ?? null : null;
+    }
+    /**
+   * Start (or update) playback of an animation clip.
+   *
+   * Behavior:
+   * - If the clip is already playing, stops it first.
+   * - Otherwise initializes playback state (repeat counter, speed, weight, initial time).
+   * - Registers clip tracks and skeletons into the active sets for blending and application.
+   *
+   * @param name - Name of the animation to play.
+   * @param options - Playback options (repeat, speedRatio, fadeIn).
+   */ playAnimation(name, options) {
+        this.play(name, options);
+    }
+    /**
+   * Start a previously created playback.
+   * @internal
+   */ startPlayback(playback) {
+        const ani = playback.clip;
+        if (!ani) {
+            return;
         }
+        const options = playback._getOptions();
         const fadeIn = Math.max(options?.fadeIn ?? 0, 0);
         const repeat = options?.repeat ?? 0;
-        const speedRatio = options?.speedRatio ?? 1;
-        const weight = options?.weight ?? ani.weight ?? 1;
+        const speedRatio = playback.speedRatio;
+        const weight = playback.weight;
+        const rangeStart = ani.resolveTimeRef(options?.range?.start);
+        const rangeEnd = ani.resolveTimeRef(options?.range?.end);
+        const syncSource = this.resolvePlaybackSyncSource(options?.sync);
+        const initialTime = this.computePlaybackInitialTime(ani, speedRatio, rangeStart, rangeEnd, options?.sync, syncSource);
+        if (this.isPlayingAnimation(ani.name)) {
+            this.stopAnimation(ani.name, {
+                reason: 'replaced'
+            });
+        }
+        playback._setState('playing');
+        playback._setTime(initialTime);
         this._activeAnimations.set(ani, {
+            playback,
             repeat,
             weight,
+            targetWeight: weight,
             speedRatio,
             fadeIn,
             fadeOut: 0,
             repeatCounter: 0,
-            currentTime: speedRatio < 0 ? ani.timeDuration : 0,
+            currentTime: initialTime,
             animateTime: 0,
             fadeOutStart: 0,
-            firstFrame: true
+            fadeToStart: 0,
+            fadeToDuration: 0,
+            fadeFromWeight: weight,
+            fadeTargetWeight: weight,
+            firstFrame: true,
+            started: false,
+            paused: false,
+            stopReason: 'manual',
+            completed: false,
+            rangeStart,
+            rangeEnd
         });
         ani.tracks?.forEach((v, k)=>{
             let nodeTracks = this._activeTracks.get(k);
@@ -707,18 +1082,257 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             }
         });
     }
-    /**
-   * Stop playback of an animation clip.
-   *
-   * Behavior:
-   * - If `options.fadeOut > 0`, marks the clip for fade-out; actual removal occurs after fade completes.
-   * - If `fadeOut` is 0 or omitted, immediately:
-   *   - Removes the clip from active animations.
-   *   - Unregisters its tracks from active track maps.
-   *   - Decrements skeleton reference counts; resets and removes skeletons when refcount reaches 0.
-   *
-   * @param name - Name of the animation to stop.
-   * @param options - Optional fade-out configuration.
+    resolvePlaybackSyncSource(sync) {
+        if (!sync?.target) {
+            return null;
+        }
+        const playback = this.resolveActivePlayback(sync.target);
+        if (!playback) {
+            return null;
+        }
+        const info = this._activeAnimations.get(playback.clip);
+        return info?.playback === playback ? {
+            playback,
+            info,
+            clip: playback.clip
+        } : null;
+    }
+    resolveActivePlayback(target) {
+        const named = this.getPlayback(target);
+        if (named) {
+            return named;
+        }
+        for (const info of this._activeAnimations.values()){
+            if (info.playback.id === target) {
+                return info.playback;
+            }
+        }
+        return null;
+    }
+    computePlaybackInitialTime(clip, speedRatio, rangeStart, rangeEnd, sync, syncSource) {
+        const fallback = speedRatio < 0 ? rangeEnd ?? rangeStart ?? clip.timeDuration : rangeStart ?? 0;
+        if (!sync || !syncSource) {
+            return fallback;
+        }
+        const destination = this.getPlaybackEffectiveRange(clip, rangeStart, rangeEnd);
+        if (destination.duration <= 0) {
+            return fallback;
+        }
+        const offset = Number.isFinite(sync.offset) ? sync.offset ?? 0 : 0;
+        const wrap = sync.wrap ?? true;
+        if ((sync.mode ?? 'normalized') === 'time') {
+            return this.constrainPlaybackTime(syncSource.info.currentTime + offset, destination, wrap);
+        }
+        const source = this.getPlaybackEffectiveRange(syncSource.clip, syncSource.info.rangeStart, syncSource.info.rangeEnd);
+        if (source.duration <= 0) {
+            return fallback;
+        }
+        const phase = (syncSource.info.currentTime - source.start) / source.duration + offset;
+        return this.constrainPlaybackTime(destination.start + phase * destination.duration, destination, wrap);
+    }
+    getPlaybackEffectiveRange(clip, rangeStart, rangeEnd) {
+        const start = rangeStart ?? 0;
+        const end = rangeEnd ?? clip.timeDuration;
+        return start <= end ? {
+            start,
+            end,
+            duration: end - start
+        } : {
+            start: end,
+            end: start,
+            duration: start - end
+        };
+    }
+    constrainPlaybackTime(time, range, wrap) {
+        if (!Number.isFinite(time)) {
+            return range.start;
+        }
+        if (!wrap) {
+            return Math.max(range.start, Math.min(range.end, time));
+        }
+        if (time >= range.start && time < range.end) {
+            return time;
+        }
+        const offset = ((time - range.start) % range.duration + range.duration) % range.duration;
+        return range.start + offset;
+    }
+    /**
+   * Stop a playback handle.
+   * @internal
+   */ stopPlayback(playback, options) {
+        if (this._activeAnimations.get(playback.clip)?.playback === playback) {
+            this.stopAnimation(playback.clip.name, options);
+        }
+    }
+    /**
+   * Pause a playback handle.
+   * @internal
+   */ pausePlayback(playback) {
+        const info = this._activeAnimations.get(playback.clip);
+        if (info?.playback === playback && !info.paused) {
+            info.paused = true;
+            playback._setState('paused');
+            const event = this.createPlaybackEvent(info, playback.clip);
+            playback._emitPause(event);
+            this.dispatchEvent('playbackpause', event);
+        }
+    }
+    /**
+   * Resume a playback handle.
+   * @internal
+   */ resumePlayback(playback) {
+        const info = this._activeAnimations.get(playback.clip);
+        if (info?.playback === playback && info.paused) {
+            info.paused = false;
+            playback._setState('playing');
+            const event = this.createPlaybackEvent(info, playback.clip);
+            playback._emitResume(event);
+            this.dispatchEvent('playbackresume', event);
+        }
+    }
+    /**
+   * Seek a playback handle.
+   * @internal
+   */ seekPlayback(playback, time, options) {
+        const clip = playback.clip;
+        const info = this._activeAnimations.get(clip);
+        const duration = clip.timeDuration;
+        const clampedTime = duration > 0 ? Math.max(0, Math.min(duration, time)) : Math.max(0, time);
+        const previousTime = info?.currentTime ?? playback.time;
+        playback._setTime(clampedTime);
+        if (info?.playback === playback) {
+            info.currentTime = clampedTime;
+            if (options?.emitEvents) {
+                const direction = clampedTime >= previousTime ? 1 : -1;
+                this.emitCrossedMarkers(info, clip, previousTime, clampedTime, direction);
+                this.emitCrossedFrames(info, clip, previousTime, clampedTime, direction);
+            }
+            if (options?.apply) {
+                this.update(0);
+            }
+        }
+    }
+    /**
+   * Set playback weight.
+   * @internal
+   */ setPlaybackWeight(playback, weight) {
+        playback._setWeight(weight);
+        const info = this._activeAnimations.get(playback.clip);
+        if (info?.playback === playback) {
+            info.weight = weight;
+            info.targetWeight = weight;
+        }
+    }
+    /**
+   * Set playback speed ratio.
+   * @internal
+   */ setPlaybackSpeedRatio(playback, speedRatio) {
+        playback._setSpeedRatio(speedRatio);
+        const info = this._activeAnimations.get(playback.clip);
+        if (info?.playback === playback) {
+            info.speedRatio = speedRatio;
+        }
+    }
+    /**
+   * Fade playback weight to a target value.
+   * @internal
+   */ fadePlaybackTo(playback, weight, duration) {
+        const info = this._activeAnimations.get(playback.clip);
+        if (info?.playback === playback) {
+            info.fadeFromWeight = info.weight;
+            info.fadeTargetWeight = weight;
+            info.targetWeight = weight;
+            info.fadeToStart = info.animateTime;
+            info.fadeToDuration = Math.max(duration, 0);
+            if (info.fadeToDuration === 0) {
+                info.weight = weight;
+                playback._setWeight(weight);
+            }
+        } else {
+            playback._setWeight(weight);
+        }
+    }
+    createPlaybackEvent(info, clip) {
+        return {
+            playback: info.playback,
+            animationSet: this,
+            clip,
+            time: info.currentTime,
+            normalizedTime: clip.timeDuration > 0 ? info.currentTime / clip.timeDuration : 0
+        };
+    }
+    completePlayback(clip, info) {
+        if (info.completed) {
+            return;
+        }
+        const event = this.createPlaybackEvent(info, clip);
+        const completionFadeOut = Math.max(info.playback._getOptions().completionFadeOut ?? 0, 0);
+        info.playback._setState('completed');
+        info.playback._emitComplete(event);
+        this.dispatchEvent('playbackcomplete', event);
+        if (completionFadeOut > 0) {
+            info.completed = true;
+            info.fadeOut = completionFadeOut;
+            info.fadeOutStart = info.animateTime;
+            info.stopReason = 'completed';
+            return;
+        }
+        this.stopAnimation(clip.name, {
+            reason: 'completed'
+        });
+    }
+    emitCrossedMarkers(info, clip, fromTime, toTime, direction) {
+        for (const marker of this.getCrossedMarkers(clip, fromTime, toTime, direction)){
+            const event = {
+                ...this.createPlaybackEvent(info, clip),
+                marker,
+                direction
+            };
+            info.playback._emitMarker(event);
+            this.dispatchEvent('marker', event);
+        }
+    }
+    emitCrossedFrames(info, clip, fromTime, toTime, direction) {
+        for (const frame of info.playback._getWatchedFrames()){
+            const frameTime = frame / clip.frameRate;
+            const crossed = direction >= 0 ? this.crossedForward(fromTime, toTime, frameTime, clip.timeDuration) : this.crossedBackward(fromTime, toTime, frameTime, clip.timeDuration);
+            if (crossed) {
+                const event = {
+                    ...this.createPlaybackEvent(info, clip),
+                    frame
+                };
+                info.playback._emitFrame(event);
+                this.dispatchEvent('frame', event);
+            }
+        }
+    }
+    getCrossedMarkers(clip, fromTime, toTime, direction) {
+        return clip.markers.filter((marker)=>{
+            const markerTime = clip.resolveMarkerTime(marker);
+            if (markerTime === null) {
+                return false;
+            }
+            return direction >= 0 ? this.crossedForward(fromTime, toTime, markerTime, clip.timeDuration) : this.crossedBackward(fromTime, toTime, markerTime, clip.timeDuration);
+        });
+    }
+    crossedForward(fromTime, toTime, targetTime, duration) {
+        return toTime >= fromTime ? targetTime > fromTime && targetTime <= toTime : duration > 0 && targetTime > fromTime && targetTime <= duration || targetTime <= toTime;
+    }
+    crossedBackward(fromTime, toTime, targetTime, duration) {
+        return toTime <= fromTime ? targetTime < fromTime && targetTime >= toTime : duration > 0 && targetTime < fromTime && targetTime >= 0 || targetTime >= toTime;
+    }
+    /**
+   * Stop playback of an animation clip.
+   *
+   * Behavior:
+   * - If `options.fadeOut > 0`, marks the clip for fade-out; actual removal occurs after fade completes.
+   * - If `fadeOut` is 0 or omitted, immediately:
+   *   - Removes the clip from active animations.
+   *   - Unregisters its tracks from active track maps.
+   *   - Decrements skeleton reference counts; resets and removes skeletons when refcount reaches 0.
+   *
+   * @param name - Name of the animation to stop.
+   * @param options - Optional fade-out configuration.
    */ stopAnimation(name, options) {
         const ani = this._animations[name];
         if (!ani) {
@@ -728,9 +1342,12 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         const info = this._activeAnimations.get(ani);
         if (info) {
             const fadeOut = Math.max(options?.fadeOut ?? 0, 0);
+            const reason = options?.reason ?? 'manual';
             if (fadeOut !== 0) {
                 info.fadeOut = fadeOut;
                 info.fadeOutStart = -1;
+                info.stopReason = reason;
+                info.playback._setState('stopping');
             } else {
                 this._activeAnimations.delete(ani);
                 this._activeTracks.forEach((v)=>{
@@ -768,20 +1385,29 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
                         }
                     }
                 });
+                const event = {
+                    ...this.createPlaybackEvent(info, ani),
+                    reason
+                };
+                if (reason !== 'completed') {
+                    info.playback._setState('stopped');
+                }
+                info.playback._emitStop(event);
+                this.dispatchEvent('playbackstop', event);
             }
         }
     }
-    /**
-   * Create a skeletal-only masked clip from an existing clip in this set.
-   *
-   * The generated clip is a regular `AnimationClip`: it contains cloned node transform tracks
-   * for the selected rig joints and can be played/blended through the normal animation system.
-   * Non-skeletal tracks are skipped by default.
-   *
-   * @param sourceName - Name of the source clip.
-   * @param targetName - Name of the generated clip.
-   * @param options - Humanoid semantic or joint-name based mask options.
-   * @returns The generated clip, or null on failure.
+    /**
+   * Create a skeletal-only masked clip from an existing clip in this set.
+   *
+   * The generated clip is a regular `AnimationClip`: it contains cloned node transform tracks
+   * for the selected rig joints and can be played/blended through the normal animation system.
+   * Non-skeletal tracks are skipped by default.
+   *
+   * @param sourceName - Name of the source clip.
+   * @param targetName - Name of the generated clip.
+   * @param options - Humanoid semantic or joint-name based mask options.
+   * @returns The generated clip, or null on failure.
    */ createSkeletalMaskedAnimation(sourceName, targetName, options) {
         const sourceClip = this.get(sourceName);
         if (!sourceClip) {
@@ -988,21 +1614,21 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         }
         return dstClip;
     }
-    /**
-   * Copy an animation clip from another AnimationSet into this one.
-   *
-   * Prerequisites:
-   * - Both sets must reference skeletons with identical joint names and counts.
-   * - The source clip must exist in `sourceSet`.
-   *
-   * @param sourceSet - The AnimationSet to copy from.
-   * @param animationName - Name of the clip to copy.
-   * @param targetName - Name for the new clip in this set. Defaults to `animationName`.
-   * @param excludeJoint - Optional predicate; joints whose name returns true are excluded from
-   *   skeleton structure matching.
-   * @returns The newly created AnimationClip, or null on failure.
-   *
-   * @deprecated Use AnimationSet.copyHumanoidAnimationFrom instead.
+    /**
+   * Copy an animation clip from another AnimationSet into this one.
+   *
+   * Prerequisites:
+   * - Both sets must reference skeletons with identical joint names and counts.
+   * - The source clip must exist in `sourceSet`.
+   *
+   * @param sourceSet - The AnimationSet to copy from.
+   * @param animationName - Name of the clip to copy.
+   * @param targetName - Name for the new clip in this set. Defaults to `animationName`.
+   * @param excludeJoint - Optional predicate; joints whose name returns true are excluded from
+   *   skeleton structure matching.
+   * @returns The newly created AnimationClip, or null on failure.
+   *
+   * @deprecated Use AnimationSet.copyHumanoidAnimationFrom instead.
    */ copyAnimationFrom(sourceSet, animationName, targetName, excludeJoint) {
         const destName = targetName ?? animationName;
         const sourceClip = sourceSet.get(animationName);
@@ -1148,8 +1774,8 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             return ordered;
         }
     }
-    /**
-   * Reset all skeleton modifiers
+    /**
+   * Reset all skeleton modifiers
    */ resetSkeletonModifiers() {
         for (const sk of this._skeletons){
             for (const modifier of sk.get().modifiers){
@@ -1157,12 +1783,12 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             }
         }
     }
-    /**
-   * Dispose the animation set and release owned resources.
-   *
-   * - Disposes the weak reference to the model.
-   * - Disposes all registered animation clips.
-   * - Clears active animations, tracks, and skeleton references.
+    /**
+   * Dispose the animation set and release owned resources.
+   *
+   * - Disposes the weak reference to the model.
+   * - Disposes all registered animation clips.
+   * - Clears active animations, tracks, and skeleton references.
    */ onDispose() {
         super.onDispose();
         for(const k in this._animations){
@@ -1176,5 +1802,5 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     }
 }
 
-export { AnimationSet };
+export { AnimationPlayback, AnimationSet };
 //# sourceMappingURL=animationset.js.map