@zephyr3d/editor 0.3.0 → 0.3.1

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

@@ -292,25 +292,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;
@@ -318,10 +318,10 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
     /** @internal */ _activeTracks;
     /** @internal */ _activeSkeletons;
     /** @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;
@@ -331,35 +331,35 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         this._activeAnimations = new Map();
         this._skeletons = [];
     }
-    /**
-   * 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;
     }
-    /**
-   * 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');
@@ -371,12 +371,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) {
@@ -385,24 +385,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 all active skeletons to update skinning transforms.
-   *
-   * @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 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) {
@@ -464,11 +464,11 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             v.get()?.apply(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];
@@ -476,23 +476,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) {
@@ -504,16 +504,16 @@ 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, 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) {
@@ -571,18 +571,18 @@ 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.
+    /**
+   * 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) {
@@ -617,18 +617,18 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             }
         }
     }
-    /**
-   * Copy a humanoid animation clip from another AnimationSet into this one via humanoid rig mapping.
-   *
-   * Prerequisites:
-   * - Both source and destination skeletons must have a non-null `humanoidJointMapping`.
-   * - Joints are matched by shared `HumanoidBodyRig` / `HumanoidHandRig` keys instead of joint names.
-   * - The source clip must exist in `sourceSet` and must be driven by exactly one skeleton.
-   *
-   * @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`.
-   * @returns The newly created AnimationClip, or null on failure.
+    /**
+   * Copy a humanoid animation clip from another AnimationSet into this one via humanoid rig mapping.
+   *
+   * Prerequisites:
+   * - Both source and destination skeletons must have a non-null `humanoidJointMapping`.
+   * - Joints are matched by shared `HumanoidBodyRig` / `HumanoidHandRig` keys instead of joint names.
+   * - The source clip must exist in `sourceSet` and must be driven by exactly one skeleton.
+   *
+   * @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`.
+   * @returns The newly created AnimationClip, or null on failure.
    */ copyHumanoidAnimationFrom(sourceSet, animationName, targetName) {
         const destName = targetName ?? animationName;
         const sourceClip = sourceSet.get(animationName);
@@ -796,21 +796,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 the new {@link AnimationSet.copyHumanoidAnimationFrom} method 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 the new {@link AnimationSet.copyHumanoidAnimationFrom} method instead.
    */ copyAnimationFrom(sourceSet, animationName, targetName, excludeJoint) {
         const destName = targetName ?? animationName;
         const sourceClip = sourceSet.get(animationName);
@@ -960,12 +960,12 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
             return ordered;
         }
     }
-    /**
-   * 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){