@zephyr3d/editor 0.3.4 → 0.3.5

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

@@ -388,25 +388,25 @@ 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
+/**
+ * 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;
@@ -416,10 +416,10 @@ 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.
+    /**
+   * Create an AnimationSet controlling the provided model.
+   *
+   * @param model - The SceneNode (model root) controlled by this animation set.
    */ constructor(model){
         super();
         this._model = model;
@@ -431,28 +431,28 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         this._skeletons = [];
         this._rigs = [];
     }
-    /**
-   * The model (SceneNode) controlled by this animation set.
+    /**
+   * 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 +474,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 +499,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,24 +513,24 @@ 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.fadeOut > 0 && v.fadeOutStart < 0) {
@@ -597,11 +597,11 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             v.get()?.apply();
         });
     }
-    /**
-   * 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 +609,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) {
@@ -637,91 +637,88 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             info.weight = weight;
         }
     }
-    /**
-   * 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).
+    /**
+   * 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) {
         const ani = this._animations[name];
         if (!ani) {
             console.error(`Animation ${name} not exists`);
             return;
         }
+        if (this.isPlayingAnimation(name)) {
+            this.stopAnimation(name);
+        }
         const fadeIn = Math.max(options?.fadeIn ?? 0, 0);
-        const info = this._activeAnimations.get(ani);
-        if (info) {
-            info.fadeOut = 0;
-            info.fadeIn = fadeIn;
-        } else {
-            const repeat = options?.repeat ?? 0;
-            const speedRatio = options?.speedRatio ?? 1;
-            const weight = options?.weight ?? ani.weight ?? 1;
-            this._activeAnimations.set(ani, {
-                repeat,
-                weight,
-                speedRatio,
-                fadeIn,
-                fadeOut: 0,
-                repeatCounter: 0,
-                currentTime: speedRatio < 0 ? ani.timeDuration : 0,
-                animateTime: 0,
-                fadeOutStart: 0,
-                firstFrame: true
-            });
-            ani.tracks?.forEach((v, k)=>{
-                let nodeTracks = this._activeTracks.get(k);
-                if (!nodeTracks) {
-                    nodeTracks = new Map();
-                    this._activeTracks.set(k, nodeTracks);
-                }
-                for (const track of v){
-                    const blendId = track.getBlendId();
-                    let blendedTracks = nodeTracks.get(blendId);
-                    if (!blendedTracks) {
-                        blendedTracks = [];
-                        nodeTracks.set(blendId, blendedTracks);
-                    }
-                    blendedTracks.push(track);
-                }
-            });
-            ani.skeletons?.forEach((v, k)=>{
-                const rig = this.model.findSkeletonRigById(k);
-                if (rig) {
-                    const refcount = this._activeRigs.get(rig);
-                    this._activeRigs.set(rig, refcount ? refcount + 1 : 1);
-                    rig.playing = true;
-                    return;
-                }
-                const binding = this.model.findSkinBindingById(k);
-                if (binding) {
-                    const refcount = this._activeSkinBindings.get(binding);
-                    this._activeSkinBindings.set(binding, refcount ? refcount + 1 : 1);
-                    binding.playing = true;
-                    const rigRefcount = this._activeRigs.get(binding.rig);
-                    this._activeRigs.set(binding.rig, rigRefcount ? rigRefcount + 1 : 1);
-                    binding.rig.playing = true;
+        const repeat = options?.repeat ?? 0;
+        const speedRatio = options?.speedRatio ?? 1;
+        const weight = options?.weight ?? ani.weight ?? 1;
+        this._activeAnimations.set(ani, {
+            repeat,
+            weight,
+            speedRatio,
+            fadeIn,
+            fadeOut: 0,
+            repeatCounter: 0,
+            currentTime: speedRatio < 0 ? ani.timeDuration : 0,
+            animateTime: 0,
+            fadeOutStart: 0,
+            firstFrame: true
+        });
+        ani.tracks?.forEach((v, k)=>{
+            let nodeTracks = this._activeTracks.get(k);
+            if (!nodeTracks) {
+                nodeTracks = new Map();
+                this._activeTracks.set(k, nodeTracks);
+            }
+            for (const track of v){
+                const blendId = track.getBlendId();
+                let blendedTracks = nodeTracks.get(blendId);
+                if (!blendedTracks) {
+                    blendedTracks = [];
+                    nodeTracks.set(blendId, blendedTracks);
                 }
-            });
-        }
+                blendedTracks.push(track);
+            }
+        });
+        ani.skeletons?.forEach((v, k)=>{
+            const rig = this.model.findSkeletonRigById(k);
+            if (rig) {
+                const refcount = this._activeRigs.get(rig);
+                this._activeRigs.set(rig, refcount ? refcount + 1 : 1);
+                rig.playing = true;
+                return;
+            }
+            const binding = this.model.findSkinBindingById(k);
+            if (binding) {
+                const refcount = this._activeSkinBindings.get(binding);
+                this._activeSkinBindings.set(binding, refcount ? refcount + 1 : 1);
+                binding.playing = true;
+                const rigRefcount = this._activeRigs.get(binding.rig);
+                this._activeRigs.set(binding.rig, rigRefcount ? rigRefcount + 1 : 1);
+                binding.rig.playing = true;
+            }
+        });
     }
-    /**
-   * 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.
+    /**
+   * 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) {
@@ -774,17 +771,17 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             }
         }
     }
-    /**
-   * 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) {
@@ -991,21 +988,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);
@@ -1151,8 +1148,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){
@@ -1160,12 +1157,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){