@zephyr3d/scene 0.9.10 → 0.9.11

package/dist/animation/animationset.js

@@ -8,9 +8,9 @@ import { HumanoidBodyRig } from './skeleton.js';
 import { createSkeletalMaskedAnimationClip } from './animationmask.js';
 
 let nextAnimationPlaybackId = 1;
-/**
- * Runtime handle for one playback of an AnimationClip.
- * @public
+/**
+ * Runtime handle for one playback of an AnimationClip.
+ * @public
  */ class AnimationPlayback extends Observable {
     /** @internal */ _animationSet;
     /** @internal */ _clip;
@@ -606,7 +606,26 @@ function bakeHumanoidRotationTracks(sourceClip, srcSkeleton, dstSkeleton, srcRoo
         dstClip.addTrack(remap.dstNode, track);
     }
 }
-class AnimationSet extends makeObservable(Disposable)() {
+/**
+ * Animation set
+ *
+ * Manages a collection of named animation clips for a model and orchestrates:
+ * - Playback state (time, loops, speed, weights, fade-in/out).
+ * - Blending across multiple tracks targeting the same property via weighted averages.
+ * - Skeleton usage and application for clips that drive skeletal animation.
+ * - Active track registration and cleanup as clips start/stop.
+ *
+ * Usage:
+ * - Create or retrieve `AnimationClip`s by name.
+ * - Start playback with `playAnimation(name, options)`.
+ * - Advance animation with `update(deltaSeconds)`.
+ * - Optionally adjust weight while playing with `setAnimationWeight(name, weight)`.
+ *
+ * Lifetime:
+ * - Disposing the set releases references to the model, clips, and clears active state.
+ *
+ * @public
+ */ class AnimationSet extends makeObservable(Disposable)() {
     /** @internal */ _model;
     /** @internal */ _animations;
     /** @internal */ _skeletons;
@@ -615,18 +634,18 @@ class AnimationSet extends makeObservable(Disposable)() {
     /** @internal */ _activeSkinBindings;
     /** @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
+    /**
+   * 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.
+    /**
+   * Create an AnimationSet controlling the provided model.
+   *
+   * @param model - The SceneNode (model root) controlled by this animation set.
    */ constructor(model){
         super();
         this._model = model;
@@ -639,40 +658,40 @@ class AnimationSet extends makeObservable(Disposable)() {
         this._rigs = [];
         this._timelineTickers = new Set();
     }
-    /**
-   * Register a callback advanced by {@link update} using the same delta time as the animations.
-   * @internal
+    /**
+   * 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
+    /**
+   * Unregister a callback previously registered with {@link _registerTimelineTicker}.
+   * @internal
    */ _unregisterTimelineTicker(ticker) {
         this._timelineTickers.delete(ticker);
     }
-    /**
-   * 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;
     }
@@ -694,20 +713,20 @@ class AnimationSet extends makeObservable(Disposable)() {
         }
         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');
@@ -719,12 +738,12 @@ class AnimationSet extends makeObservable(Disposable)() {
             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) {
@@ -733,24 +752,24 @@ class AnimationSet extends makeObservable(Disposable)() {
             animation.dispose();
         }
     }
-    /**
-   * Get the list of all registered animation names.
-   *
-   * @returns An array of clip names.
+    /**
+   * Get the list of all registered animation names.
+   *
+   * @returns An array of clip names.
    */ getAnimationNames() {
         return Object.keys(this._animations);
     }
-    /**
-   * Advance and apply active animations.
-   *
-   * Responsibilities per call:
-   * - Update time cursor for each active clip (respecting speedRatio and looping).
-   * - Enforce repeat limits and apply fade-out termination if configured.
-   * - For each animated target, blend active tracks (weighted by clip weight × fade-in × fade-out)
-   *   and apply the resulting state to the target.
-   * - Apply shared rig modifiers once, then update skin binding palettes.
-   *
-   * @param deltaInSeconds - Time step in seconds since last update.
+    /**
+   * Advance and apply active animations.
+   *
+   * Responsibilities per call:
+   * - Update time cursor for each active clip (respecting speedRatio and looping).
+   * - Enforce repeat limits and apply fade-out termination if configured.
+   * - For each animated target, blend active tracks (weighted by clip weight × fade-in × fade-out)
+   *   and apply the resulting state to the target.
+   * - Apply shared rig modifiers once, then update skin binding palettes.
+   *
+   * @param deltaInSeconds - Time step in seconds since last update.
    */ update(deltaInSeconds) {
         this._activeAnimations.forEach((v, k)=>{
             if (!v.started) {
@@ -891,11 +910,11 @@ class AnimationSet extends makeObservable(Disposable)() {
             this._timelineTickers.forEach((ticker)=>ticker(deltaInSeconds));
         }
     }
-    /**
-   * Check whether an animation is currently playing.
-   *
-   * @param name - Optional animation name. If omitted, returns true if any animation is playing.
-   * @returns True if playing; otherwise false.
+    /**
+   * Check whether an animation is currently playing.
+   *
+   * @param name - Optional animation name. If omitted, returns true if any animation is playing.
+   * @returns True if playing; otherwise false.
    */ isPlayingAnimation(name) {
         if (name) {
             const animation = this._animations[name];
@@ -903,23 +922,23 @@ class AnimationSet extends makeObservable(Disposable)() {
         }
         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) {
@@ -933,8 +952,8 @@ class AnimationSet extends makeObservable(Disposable)() {
             info.playback._setWeight(weight);
         }
     }
-    /**
-   * Create a playback handle without starting it.
+    /**
+   * Create a playback handle without starting it.
    */ createPlayback(name, options) {
         const ani = this._animations[name];
         if (!ani) {
@@ -943,15 +962,15 @@ class AnimationSet extends makeObservable(Disposable)() {
         }
         return new AnimationPlayback(this, ani, options);
     }
-    /**
-   * Start an animation and return its playback handle.
+    /**
+   * 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.
+    /**
+   * Get currently active playbacks.
    */ getPlaybacks(name) {
         const playbacks = [];
         this._activeAnimations.forEach((info, clip)=>{
@@ -961,28 +980,28 @@ class AnimationSet extends makeObservable(Disposable)() {
         });
         return playbacks;
     }
-    /**
-   * Get the currently active playback for a clip.
+    /**
+   * Get the currently active playback for a clip.
    */ getPlayback(name) {
         const clip = this._animations[name];
         return clip ? this._activeAnimations.get(clip)?.playback ?? null : null;
     }
-    /**
-   * Start (or update) playback of an animation clip.
-   *
-   * Behavior:
-   * - If the clip is already playing, stops it first.
-   * - Otherwise initializes playback state (repeat counter, speed, weight, initial time).
-   * - Registers clip tracks and skeletons into the active sets for blending and application.
-   *
-   * @param name - Name of the animation to play.
-   * @param options - Playback options (repeat, speedRatio, fadeIn).
+    /**
+   * Start (or update) playback of an animation clip.
+   *
+   * Behavior:
+   * - If the clip is already playing, stops it first.
+   * - Otherwise initializes playback state (repeat counter, speed, weight, initial time).
+   * - Registers clip tracks and skeletons into the active sets for blending and application.
+   *
+   * @param name - Name of the animation to play.
+   * @param options - Playback options (repeat, speedRatio, fadeIn).
    */ playAnimation(name, options) {
         this.play(name, options);
     }
-    /**
-   * Start a previously created playback.
-   * @internal
+    /**
+   * Start a previously created playback.
+   * @internal
    */ startPlayback(playback) {
         const ani = playback.clip;
         if (!ani) {
@@ -1137,17 +1156,17 @@ class AnimationSet extends makeObservable(Disposable)() {
         const offset = ((time - range.start) % range.duration + range.duration) % range.duration;
         return range.start + offset;
     }
-    /**
-   * Stop a playback handle.
-   * @internal
+    /**
+   * 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
+    /**
+   * Pause a playback handle.
+   * @internal
    */ pausePlayback(playback) {
         const info = this._activeAnimations.get(playback.clip);
         if (info?.playback === playback && !info.paused) {
@@ -1158,9 +1177,9 @@ class AnimationSet extends makeObservable(Disposable)() {
             this.dispatchEvent('playbackpause', event);
         }
     }
-    /**
-   * Resume a playback handle.
-   * @internal
+    /**
+   * Resume a playback handle.
+   * @internal
    */ resumePlayback(playback) {
         const info = this._activeAnimations.get(playback.clip);
         if (info?.playback === playback && info.paused) {
@@ -1171,9 +1190,9 @@ class AnimationSet extends makeObservable(Disposable)() {
             this.dispatchEvent('playbackresume', event);
         }
     }
-    /**
-   * Seek a playback handle.
-   * @internal
+    /**
+   * Seek a playback handle.
+   * @internal
    */ seekPlayback(playback, time, options) {
         const clip = playback.clip;
         const info = this._activeAnimations.get(clip);
@@ -1193,9 +1212,9 @@ class AnimationSet extends makeObservable(Disposable)() {
             }
         }
     }
-    /**
-   * Set playback weight.
-   * @internal
+    /**
+   * Set playback weight.
+   * @internal
    */ setPlaybackWeight(playback, weight) {
         playback._setWeight(weight);
         const info = this._activeAnimations.get(playback.clip);
@@ -1204,9 +1223,9 @@ class AnimationSet extends makeObservable(Disposable)() {
             info.targetWeight = weight;
         }
     }
-    /**
-   * Set playback speed ratio.
-   * @internal
+    /**
+   * Set playback speed ratio.
+   * @internal
    */ setPlaybackSpeedRatio(playback, speedRatio) {
         playback._setSpeedRatio(speedRatio);
         const info = this._activeAnimations.get(playback.clip);
@@ -1214,9 +1233,9 @@ class AnimationSet extends makeObservable(Disposable)() {
             info.speedRatio = speedRatio;
         }
     }
-    /**
-   * Fade playback weight to a target value.
-   * @internal
+    /**
+   * Fade playback weight to a target value.
+   * @internal
    */ fadePlaybackTo(playback, weight, duration) {
         const info = this._activeAnimations.get(playback.clip);
         if (info?.playback === playback) {
@@ -1302,18 +1321,18 @@ class AnimationSet extends makeObservable(Disposable)() {
     crossedBackward(fromTime, toTime, targetTime, duration) {
         return toTime <= fromTime ? targetTime < fromTime && targetTime >= toTime : duration > 0 && targetTime < fromTime && targetTime >= 0 || targetTime >= toTime;
     }
-    /**
-   * Stop playback of an animation clip.
-   *
-   * Behavior:
-   * - If `options.fadeOut > 0`, marks the clip for fade-out; actual removal occurs after fade completes.
-   * - If `fadeOut` is 0 or omitted, immediately:
-   *   - Removes the clip from active animations.
-   *   - Unregisters its tracks from active track maps.
-   *   - Decrements skeleton reference counts; resets and removes skeletons when refcount reaches 0.
-   *
-   * @param name - Name of the animation to stop.
-   * @param options - Optional fade-out configuration.
+    /**
+   * 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) {
@@ -1378,17 +1397,17 @@ class AnimationSet extends makeObservable(Disposable)() {
             }
         }
     }
-    /**
-   * 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) {
@@ -1595,21 +1614,21 @@ class AnimationSet extends makeObservable(Disposable)() {
         }
         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);
@@ -1755,8 +1774,8 @@ class AnimationSet extends makeObservable(Disposable)() {
             return ordered;
         }
     }
-    /**
-   * Reset all skeleton modifiers
+    /**
+   * Reset all skeleton modifiers
    */ resetSkeletonModifiers() {
         for (const sk of this._skeletons){
             for (const modifier of sk.get().modifiers){
@@ -1764,12 +1783,12 @@ class AnimationSet extends makeObservable(Disposable)() {
             }
         }
     }
-    /**
-   * 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){