@zephyr3d/scene 0.6.1 → 0.7.1

package/dist/animation/animation.js

@@ -1,80 +1,191 @@
+import { Disposable } from '@zephyr3d/base';
+
 /**
- * Animation that contains multiple tracks
+ * Animation clip
+ *
+ * Represents a named animation composed of multiple tracks targeting various objects/properties,
+ * with an overall duration, weight, and optional auto-play behavior. Tracks may target different
+ * objects and are grouped by a per-target array. Skeletons used by this clip are tracked for
+ * lifecycle and application during playback.
+ *
+ * Typical workflow:
+ * - Create a clip via `AnimationSet.createAnimation(name)`.
+ * - Add one or more `AnimationTrack`s via `addTrack(target, track)`.
+ * - Optionally register skeletons via `addSkeleton(...)`.
+ * - Start playback through the owning `AnimationSet.playAnimation(name, options)`.
+ *
  * @public
- */ class AnimationClip {
+ */ class AnimationClip extends Disposable {
     /** @internal */ _name;
+    /** @internal */ _animationSet;
+    /** @internal */ _embedded;
     /** @internal */ _duration;
+    /** @internal */ _autoPlay;
     /** @internal */ _tracks;
+    _weight;
     /** @internal */ _skeletons;
     /**
    * Creates an animation instance
    * @param name - Name of the animation
    * @param model - Parent node if this is a skeleton animation
-   */ constructor(name){
+   */ constructor(name, animationSet, embedded = false){
+        super();
         this._name = name;
+        this._animationSet = animationSet;
+        this._embedded = embedded;
         this._tracks = new Map();
         this._duration = 0;
+        this._weight = 1;
+        this._autoPlay = false;
         this._skeletons = new Set();
     }
-    /** Disposes self */ dispose() {
-        this._tracks = null;
-        this._skeletons?.forEach((val, key)=>key.dispose());
-        this._skeletons = null;
+    /**
+   * Whether this clip is embedded (owned inline by its container/resource).
+   */ get embedded() {
+        return this._embedded;
+    }
+    /**
+   * The `AnimationSet` that owns this clip.
+   */ get animationSet() {
+        return this._animationSet;
+    }
+    /**
+   * Global blend weight for the clip.
+   *
+   * Used by the animation system when combining multiple active clips.
+   */ get weight() {
+        return this._weight;
+    }
+    set weight(val) {
+        this._weight = val;
     }
-    /** Gets the name of the animation */ get name() {
+    /**
+   * Whether this clip should start playing automatically when loaded/instantiated.
+   */ get autoPlay() {
+        return this._autoPlay;
+    }
+    set autoPlay(val) {
+        this._autoPlay = val;
+    }
+    /**
+   * The unique name of this clip.
+   */ get name() {
         return this._name;
     }
-    /** Gets all the tracks of this animation */ get tracks() {
+    /**
+   * All animation tracks grouped by target object.
+   *
+   * Key: target object; Value: list of `AnimationTrack`s affecting that target.
+   */ get tracks() {
         return this._tracks;
     }
-    /** Gets all skeletons */ get skeletons() {
+    /**
+   * All skeletons referenced by this clip.
+   */ get skeletons() {
         return this._skeletons;
     }
-    /** The duration of the animation */ get timeDuration() {
+    set skeletons(val) {
+        this._skeletons = val;
+    }
+    /**
+   * Total time span of the clip in seconds.
+   *
+   * Automatically extended when adding tracks with longer duration.
+   */ get timeDuration() {
         return this._duration;
     }
+    set timeDuration(val) {
+        this._duration = val;
+    }
     /**
-   * Adds a skeleton to the animation
-   * @param skeleton - The skeleton to be added
-   * @param meshList - The meshes controlled by the skeleton
-   * @param boundingBoxInfo - Bounding box information for the skeleton
-   */ addSkeleton(skeleton) {
-        this._skeletons.add(skeleton);
+   * Add a skeleton used by this clip.
+   *
+   * @param skeletonId - Persistent ID of Skeleton to register for this clip.
+   */ addSkeleton(skeletonId) {
+        this._skeletons.add(skeletonId);
     }
     /**
-   * Adds an animation track to the animation
-   * @param node - The node that will be controlled by the track
-   * @param track - The track to be added
-   * @returns self
-   */ addTrack(node, track) {
+   * Remove a specific track from this clip.
+   *
+   * Errors if the track does not belong to this clip. Does nothing if not found.
+   *
+   * @param track - The track instance to remove.
+   * @returns This clip (for chaining).
+   */ deleteTrack(track) {
+        if (track?.animation !== this) {
+            console.error('Cannot delete animation track which is not belongs to THIS animation');
+        }
+        for (const k of this._tracks.keys()){
+            const tracks = this._tracks.get(k);
+            const index = tracks.indexOf(track);
+            if (index >= 0) {
+                tracks.splice(index, 1);
+            }
+        }
+        return this;
+    }
+    /**
+   * Add a track to this clip for a specific target object.
+   *
+   * Constraints:
+   * - The track must not already belong to another clip.
+   * - Only one track with the same blendId may exist per target in a single clip.
+   *
+   * Side effects:
+   * - Assigns this clip to `track.animation`.
+   * - Extends `timeDuration` to cover the track duration if longer.
+   * - Calls `track.reset(target)` to initialize the target state if needed.
+   *
+   * @param target - Target object controlled by the track.
+   * @param track - Track to add.
+   * @returns This clip (for chaining).
+   */ addTrack(target, track) {
         if (!track) {
-            return;
+            return this;
         }
         if (track.animation) {
             if (track.animation === this) {
-                return;
+                return this;
             } else {
                 console.error('Track is already in another animation');
-                return;
+                return this;
             }
         }
         const blendId = track.getBlendId();
-        const tracks = this._tracks.get(node);
+        const tracks = this._tracks.get(target);
         if (tracks && tracks.findIndex((track)=>track.getBlendId() === blendId) >= 0) {
             console.error('Tracks with same BlendId could not be added to same animation');
-            return;
+            return this;
         }
         track.animation = this;
-        let trackInfo = this._tracks.get(node);
+        let trackInfo = this._tracks.get(target);
         if (!trackInfo) {
             trackInfo = [];
-            this._tracks.set(node, trackInfo);
+            this._tracks.set(target, trackInfo);
         }
         trackInfo.push(track);
-        this._duration = Math.max(this._duration, track.interpolator.maxTime);
-        track.reset(node);
+        this._duration = Math.max(this._duration, track.getDuration() ?? 0);
+        track.reset(target);
         return this;
     }
+    /** @internal */ resample(frames, callback) {
+        for(let frame = 0; frame <= frames; frame++){
+            const t = frame / this.timeDuration;
+            for (const [k, v] of this.tracks){
+                for (const track of v){
+                    const state = track.calculateState(k, t);
+                    track.applyState(k, state);
+                }
+            }
+            for (const sk of this.skeletons){
+                const skeleton = this._animationSet.model.findSkeletonById(sk);
+                if (skeleton) {
+                    skeleton.computeJoints();
+                }
+            }
+            callback(frame);
+        }
+    }
 }
 
 export { AnimationClip };

package/dist/animation/animation.js.map

@@ -1 +1 @@
-{"version":3,"file":"animation.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"animation.js","sources":["../../src/animation/animation.ts"],"sourcesContent":["import { Disposable } from '@zephyr3d/base';\r\nimport type { AnimationSet } from './animationset';\r\nimport type { AnimationTrack } from './animationtrack';\r\n\r\n/**\r\n * Animation clip\r\n *\r\n * Represents a named animation composed of multiple tracks targeting various objects/properties,\r\n * with an overall duration, weight, and optional auto-play behavior. Tracks may target different\r\n * objects and are grouped by a per-target array. Skeletons used by this clip are tracked for\r\n * lifecycle and application during playback.\r\n *\r\n * Typical workflow:\r\n * - Create a clip via `AnimationSet.createAnimation(name)`.\r\n * - Add one or more `AnimationTrack`s via `addTrack(target, track)`.\r\n * - Optionally register skeletons via `addSkeleton(...)`.\r\n * - Start playback through the owning `AnimationSet.playAnimation(name, options)`.\r\n *\r\n * @public\r\n */\r\nexport class AnimationClip extends Disposable {\r\n  /** @internal */\r\n  protected _name: string;\r\n  /** @internal */\r\n  protected _animationSet: AnimationSet;\r\n  /** @internal */\r\n  protected _embedded: boolean;\r\n  /** @internal */\r\n  protected _duration: number;\r\n  /** @internal */\r\n  protected _autoPlay: boolean;\r\n  /** @internal */\r\n  protected _tracks: Map<object, AnimationTrack[]>;\r\n  protected _weight: number;\r\n  /** @internal */\r\n  protected _skeletons: Set<string>;\r\n  /**\r\n   * Creates an animation instance\r\n   * @param name - Name of the animation\r\n   * @param model - Parent node if this is a skeleton animation\r\n   */\r\n  constructor(name: string, animationSet: AnimationSet, embedded = false) {\r\n    super();\r\n    this._name = name;\r\n    this._animationSet = animationSet;\r\n    this._embedded = embedded;\r\n    this._tracks = new Map();\r\n    this._duration = 0;\r\n    this._weight = 1;\r\n    this._autoPlay = false;\r\n    this._skeletons = new Set();\r\n  }\r\n  /**\r\n   * Whether this clip is embedded (owned inline by its container/resource).\r\n   */\r\n  get embedded() {\r\n    return this._embedded;\r\n  }\r\n  /**\r\n   * The `AnimationSet` that owns this clip.\r\n   */\r\n  get animationSet() {\r\n    return this._animationSet;\r\n  }\r\n  /**\r\n   * Global blend weight for the clip.\r\n   *\r\n   * Used by the animation system when combining multiple active clips.\r\n   */\r\n  get weight() {\r\n    return this._weight;\r\n  }\r\n  set weight(val: number) {\r\n    this._weight = val;\r\n  }\r\n  /**\r\n   * Whether this clip should start playing automatically when loaded/instantiated.\r\n   */\r\n  get autoPlay() {\r\n    return this._autoPlay;\r\n  }\r\n  set autoPlay(val: boolean) {\r\n    this._autoPlay = val;\r\n  }\r\n  /**\r\n   * The unique name of this clip.\r\n   */\r\n  get name() {\r\n    return this._name;\r\n  }\r\n  /**\r\n   * All animation tracks grouped by target object.\r\n   *\r\n   * Key: target object; Value: list of `AnimationTrack`s affecting that target.\r\n   */\r\n  get tracks() {\r\n    return this._tracks;\r\n  }\r\n  /**\r\n   * All skeletons referenced by this clip.\r\n   */\r\n  get skeletons() {\r\n    return this._skeletons;\r\n  }\r\n  set skeletons(val: Set<string>) {\r\n    this._skeletons = val;\r\n  }\r\n  /**\r\n   * Total time span of the clip in seconds.\r\n   *\r\n   * Automatically extended when adding tracks with longer duration.\r\n   */\r\n  get timeDuration() {\r\n    return this._duration;\r\n  }\r\n  set timeDuration(val) {\r\n    this._duration = val;\r\n  }\r\n  /**\r\n   * Add a skeleton used by this clip.\r\n   *\r\n   * @param skeletonId - Persistent ID of Skeleton to register for this clip.\r\n   */\r\n  addSkeleton(skeletonId: string) {\r\n    this._skeletons.add(skeletonId);\r\n  }\r\n  /**\r\n   * Remove a specific track from this clip.\r\n   *\r\n   * Errors if the track does not belong to this clip. Does nothing if not found.\r\n   *\r\n   * @param track - The track instance to remove.\r\n   * @returns This clip (for chaining).\r\n   */\r\n  deleteTrack(track: AnimationTrack) {\r\n    if (track?.animation !== this) {\r\n      console.error('Cannot delete animation track which is not belongs to THIS animation');\r\n    }\r\n    for (const k of this._tracks.keys()) {\r\n      const tracks = this._tracks.get(k)!;\r\n      const index = tracks.indexOf(track);\r\n      if (index >= 0) {\r\n        tracks.splice(index, 1);\r\n      }\r\n    }\r\n    return this;\r\n  }\r\n  /**\r\n   * Add a track to this clip for a specific target object.\r\n   *\r\n   * Constraints:\r\n   * - The track must not already belong to another clip.\r\n   * - Only one track with the same blendId may exist per target in a single clip.\r\n   *\r\n   * Side effects:\r\n   * - Assigns this clip to `track.animation`.\r\n   * - Extends `timeDuration` to cover the track duration if longer.\r\n   * - Calls `track.reset(target)` to initialize the target state if needed.\r\n   *\r\n   * @param target - Target object controlled by the track.\r\n   * @param track - Track to add.\r\n   * @returns This clip (for chaining).\r\n   */\r\n  addTrack(target: object, track: AnimationTrack) {\r\n    if (!track) {\r\n      return this;\r\n    }\r\n    if (track.animation) {\r\n      if (track.animation === this) {\r\n        return this;\r\n      } else {\r\n        console.error('Track is already in another animation');\r\n        return this;\r\n      }\r\n    }\r\n    const blendId = track.getBlendId();\r\n    const tracks = this._tracks.get(target);\r\n    if (tracks && tracks.findIndex((track) => track.getBlendId() === blendId) >= 0) {\r\n      console.error('Tracks with same BlendId could not be added to same animation');\r\n      return this;\r\n    }\r\n    track.animation = this;\r\n    let trackInfo = this._tracks.get(target);\r\n    if (!trackInfo) {\r\n      trackInfo = [];\r\n      this._tracks.set(target, trackInfo);\r\n    }\r\n    trackInfo.push(track);\r\n    this._duration = Math.max(this._duration, track.getDuration() ?? 0);\r\n    track.reset(target);\r\n    return this;\r\n  }\r\n  /** @internal */\r\n  resample(frames: number, callback: (frame: number) => void) {\r\n    for (let frame = 0; frame <= frames; frame++) {\r\n      const t = frame / this.timeDuration;\r\n      for (const [k, v] of this.tracks) {\r\n        for (const track of v) {\r\n          const state = track.calculateState(k, t);\r\n          track.applyState(k, state);\r\n        }\r\n      }\r\n      for (const sk of this.skeletons) {\r\n        const skeleton = this._animationSet.model.findSkeletonById(sk);\r\n        if (skeleton) {\r\n          skeleton.computeJoints();\r\n        }\r\n      }\r\n      callback(frame);\r\n    }\r\n  }\r\n}\r\n"],"names":["AnimationClip","Disposable","_weight","name","animationSet","embedded","_name","_animationSet","_embedded","_tracks","Map","_duration","_autoPlay","_skeletons","Set","weight","val","autoPlay","tracks","skeletons","timeDuration","addSkeleton","skeletonId","add","deleteTrack","track","animation","console","error","k","keys","get","index","indexOf","splice","addTrack","target","blendId","getBlendId","findIndex","trackInfo","set","push","Math","max","getDuration","reset","resample","frames","callback","frame","t","v","state","calculateState","applyState","sk","skeleton","model","findSkeletonById","computeJoints"],"mappings":"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"}

package/dist/animation/animationset.js

@@ -1,53 +1,118 @@
-import { weightedAverage } from '@zephyr3d/base';
-import { Application } from '../app.js';
+import { Disposable, weightedAverage } from '@zephyr3d/base';
+import { AnimationClip } from './animation.js';
 
-/**
- * Animation set
- * @public
- */ class AnimationSet {
+/**
+ * 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 {
     /** @internal */ _model;
     /** @internal */ _animations;
-    /** @internal */ _scene;
+    /** @internal */ _skeletons;
     /** @internal */ _activeTracks;
     /** @internal */ _activeSkeletons;
     /** @internal */ _activeAnimations;
-    /**
-   * Creates an instance of AnimationSet
-   * @param scene - The scene to which the animation set belongs
-   */ constructor(scene, model){
-        this._scene = scene;
+    /**
+   * Create an AnimationSet controlling the provided model.
+   *
+   * @param model - The SceneNode (model root) controlled by this animation set.
+   */ constructor(model){
+        super();
         this._model = model;
-        this._scene.animationSet.push(this);
         this._animations = {};
         this._activeTracks = new Map();
         this._activeSkeletons = new Map();
         this._activeAnimations = new Map();
+        this._skeletons = [];
     }
-    /**
-   * How many animations in this set
+    /**
+   * The model (SceneNode) controlled by this animation set.
+   */ get model() {
+        return this._model;
+    }
+    /**
+   * Number of animation clips registered in this set.
    */ get numAnimations() {
         return Object.getOwnPropertyNames(this._animations).length;
     }
-    /**
-   * Gets an animation clip by name
-   * @param name - name of the animation to get
+    /**
+   * The skeletons used by animations in this set.
+   */ get skeletons() {
+        return this._skeletons;
+    }
+    /**
+   * 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;
     }
-    /**
-   * Adds an animation
-   */ add(animation) {
-        this._animations[animation.name] = animation;
+    /**
+   * 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');
+            return null;
+        } else {
+            const animation = new AnimationClip(name, this, embedded);
+            this._animations[name] = animation;
+            this._model.scene?.queueUpdateNode(this._model);
+            return animation;
+        }
     }
-    /**
-   * Gets names of all the animations of the model
-   * @returns An array of string that contains the animation names
+    /**
+   * 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) {
+            this.stopAnimation(name);
+            delete this._animations[name];
+            animation.dispose();
+        }
+    }
+    /**
+   * Get the list of all registered animation names.
+   *
+   * @returns An array of clip names.
    */ getAnimationNames() {
         return Object.keys(this._animations);
     }
-    /**
-   * Updates all animations of the model
-   */ 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 all active skeletons to update skinning transforms.
+   *
+   * @param deltaInSeconds - Time step in seconds since last update.
+   */ update(deltaInSeconds) {
         this._activeAnimations.forEach((v, k)=>{
             if (v.fadeOut > 0 && v.fadeOutStart < 0) {
                 v.fadeOutStart = v.animateTime;
@@ -56,7 +121,7 @@ import { Application } from '../app.js';
             if (v.firstFrame) {
                 v.firstFrame = false;
             } else {
-                const timeAdvance = Application.instance.device.frameInfo.elapsedFrame * 0.001 * v.speedRatio;
+                const timeAdvance = deltaInSeconds * v.speedRatio;
                 v.currentTime += timeAdvance;
                 v.animateTime += timeAdvance;
                 if (v.currentTime > k.timeDuration) {
@@ -77,7 +142,9 @@ import { Application } from '../app.js';
         });
         // Update tracks
         this._activeTracks.forEach((v, k)=>{
-            v.forEach((tracks)=>{
+            v.forEach((alltracks)=>{
+                // Only deal with tracks which have not been removed
+                const tracks = alltracks.filter((track)=>track.animation && this.isPlayingAnimation(track.animation.name));
                 if (tracks.length > 0) {
                     const weights = tracks.map((track)=>{
                         const info = this._activeAnimations.get(track.animation);
@@ -89,7 +156,11 @@ import { Application } from '../app.js';
                         }
                         return weight * fadeIn * fadeOut;
                     });
-                    const states = tracks.map((track)=>track.calculateState(this._activeAnimations.get(track.animation).currentTime));
+                    const states = tracks.map((track)=>{
+                        const info = this._activeAnimations.get(track.animation);
+                        const t = info.currentTime / track.animation.timeDuration * track.getDuration();
+                        return track.calculateState(k, t);
+                    });
                     const state = weightedAverage(weights, states, (a, b, t)=>{
                         return tracks[0].mixState(a, b, t);
                     });
@@ -102,37 +173,56 @@ import { Application } from '../app.js';
             k.apply();
         });
     }
-    /**
-   * Checks whether an animation is playing
-   * @param name - Name of the animation to be checked
-   * @returns true if the animation is 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) {
-        return name ? this._activeAnimations.has(this._animations[name]) : this._activeAnimations.size > 0;
+        if (name) {
+            const animation = this._animations[name];
+            return !!animation && this._activeAnimations.has(animation);
+        }
+        return this._activeAnimations.size > 0;
     }
-    /**
-   * Gets the weight of specific animation which is currently playing
-   * @param name - Name of the animation
-   * @returns Weight of the animation or 0 if this animation is not playing
-   */ getAnimationWeight(name) {
-        const ani = this._animations[name];
-        const info = this._activeAnimations.get(ani);
-        return info?.weight ?? 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.
+   */ getAnimationClip(name) {
+        return this._animations[name] ?? null;
     }
-    /**
-   * Sets the weight of specific animation which is currently playing
-   * @param name - Name of the animation
-   * @param weight - New weight value
+    /**
+   * 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) {
+            console.error(`Animation ${name} not exists`);
+            return;
+        }
         const info = this._activeAnimations.get(ani);
         if (info) {
             info.weight = weight;
         }
     }
-    /**
-   * Starts playing an animation of the model
-   * @param name - Name of the animation to play
-   * @param options - Playing options
+    /**
+   * Start (or update) playback of an animation clip.
+   *
+   * Behavior:
+   * - If the clip is already playing, updates its fade-in (resets fade-out).
+   * - 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) {
         const ani = this._animations[name];
         if (!ani) {
@@ -147,7 +237,7 @@ import { Application } from '../app.js';
         } else {
             const repeat = options?.repeat ?? 0;
             const speedRatio = options?.speedRatio ?? 1;
-            const weight = options?.weight ?? 1;
+            const weight = options?.weight ?? ani.weight ?? 1;
             this._activeAnimations.set(ani, {
                 repeat,
                 weight,
@@ -177,20 +267,37 @@ import { Application } from '../app.js';
                 }
             });
             ani.skeletons?.forEach((v, k)=>{
-                const refcount = this._activeSkeletons.get(k);
-                if (refcount) {
-                    this._activeSkeletons.set(k, refcount + 1);
-                } else {
-                    this._activeSkeletons.set(k, 1);
+                const skeleton = this.model.findSkeletonById(k);
+                if (skeleton) {
+                    const refcount = this._activeSkeletons.get(skeleton);
+                    if (refcount) {
+                        this._activeSkeletons.set(skeleton, refcount + 1);
+                    } else {
+                        this._activeSkeletons.set(skeleton, 1);
+                    }
+                    skeleton.playing = true;
                 }
             });
         }
     }
-    /**
-   * Stops playing an animation of the model
-   * @param name - Name of the animation to stop playing
+    /**
+   * 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) {
+            console.error(`Animation ${name} not exists`);
+            return;
+        }
         const info = this._activeAnimations.get(ani);
         if (info) {
             const fadeOut = Math.max(options?.fadeOut ?? 0, 0);
@@ -199,28 +306,34 @@ import { Application } from '../app.js';
                 info.fadeOutStart = -1;
             } else {
                 this._activeAnimations.delete(ani);
-                this._activeTracks.forEach((v, k)=>{
+                this._activeTracks.forEach((v)=>{
                     v.forEach((tracks, id)=>{
                         v.set(id, tracks.filter((track)=>track.animation !== ani));
                     });
                 });
                 ani.skeletons?.forEach((v, k)=>{
-                    const refcount = this._activeSkeletons.get(k);
-                    if (refcount === 1) {
-                        k.reset(this._model);
-                        this._activeSkeletons.delete(k);
-                    } else {
-                        this._activeSkeletons.set(k, refcount - 1);
+                    const skeleton = this.model.findSkeletonById(k);
+                    if (skeleton) {
+                        const refcount = this._activeSkeletons.get(skeleton);
+                        if (refcount === 1) {
+                            skeleton.reset();
+                            this._activeSkeletons.delete(skeleton);
+                        } else {
+                            this._activeSkeletons.set(skeleton, refcount - 1);
+                        }
                     }
                 });
             }
         }
     }
-    dispose() {
-        const index = this._scene.animationSet.indexOf(this);
-        if (index >= 0) {
-            this._scene.animationSet.splice(index, 1);
-        }
+    /**
+   * 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){
             this._animations[k].dispose();
         }