@zephyr3d/scene 0.9.9 → 0.9.11

package/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
@@ -407,7 +625,7 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
  * - Disposing the set releases references to the model, clips, and clears active state.
  *
  * @public
- */ class AnimationSet extends Disposable {
+ */ class AnimationSet extends makeObservable(Disposable)() {
     /** @internal */ _model;
     /** @internal */ _animations;
     /** @internal */ _skeletons;
@@ -417,6 +635,14 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     /** @internal */ _activeRigs;
     /** @internal */ _activeAnimations;
     /**
+   * 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.
@@ -430,6 +656,19 @@ 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);
+    }
+    /**
+   * Unregister a callback previously registered with {@link _registerTimelineTicker}.
+   * @internal
+   */ _unregisterTimelineTicker(ticker) {
+        this._timelineTickers.delete(ticker);
     }
     /**
    * The model (SceneNode) controlled by this animation set.
@@ -533,30 +772,99 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
    * @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,6 +904,11 @@ 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.
@@ -635,7 +948,43 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         const info = this._activeAnimations.get(ani);
         if (info) {
             info.weight = weight;
+            info.targetWeight = weight;
+            info.playback._setWeight(weight);
+        }
+    }
+    /**
+   * Create a playback handle without starting it.
+   */ createPlayback(name, options) {
+        const ani = this._animations[name];
+        if (!ani) {
+            console.error(`Animation ${name} not exists`);
+            return null;
         }
+        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.
@@ -648,29 +997,55 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
    * @param name - Name of the animation to play.
    * @param options - Playback options (repeat, speedRatio, fadeIn).
    */ playAnimation(name, options) {
-        const ani = this._animations[name];
+        this.play(name, options);
+    }
+    /**
+   * Start a previously created playback.
+   * @internal
+   */ startPlayback(playback) {
+        const ani = playback.clip;
         if (!ani) {
-            console.error(`Animation ${name} not exists`);
             return;
         }
-        if (this.isPlayingAnimation(name)) {
-            this.stopAnimation(name);
-        }
+        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,6 +1082,245 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             }
         });
     }
+    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.
    *
@@ -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,6 +1385,15 @@ 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);
             }
         }
     }
@@ -1176,5 +1802,5 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     }
 }
 
-export { AnimationSet };
+export { AnimationPlayback, AnimationSet };
 //# sourceMappingURL=animationset.js.map