@zephyr3d/scene 0.9.11 → 0.9.12

package/dist/animation/animationtimeline.js

@@ -1,19 +1,19 @@
 import { Observable } from '@zephyr3d/base';
 
-/**
- * Serializable animation timeline definition.
- * @public
+/**
+ * Serializable animation timeline definition.
+ * @public
  */ class AnimationTimeline {
-    /**
-   * Root step sequence executed by runners created from this timeline.
+    /**
+   * Root step sequence executed by runners created from this timeline.
    */ steps;
-    /**
-   * Event responses declared on this timeline.
+    /**
+   * Event responses declared on this timeline.
    */ responses;
-    /**
-   * Create a timeline from a definition object or a root step array.
-   *
-   * @param definition - Timeline definition, or a shorthand array used as the root steps.
+    /**
+   * Create a timeline from a definition object or a root step array.
+   *
+   * @param definition - Timeline definition, or a shorthand array used as the root steps.
    */ constructor(definition){
         if (Array.isArray(definition)) {
             this.steps = definition;
@@ -23,28 +23,28 @@ import { Observable } from '@zephyr3d/base';
             this.responses = definition.responses ?? [];
         }
     }
-    /**
-   * Create a runtime runner for this timeline.
-   *
-   * @param animationSet - Animation set used to create and update playbacks.
-   * @returns A new stopped runner bound to this timeline and animation set.
+    /**
+   * Create a runtime runner for this timeline.
+   *
+   * @param animationSet - Animation set used to create and update playbacks.
+   * @returns A new stopped runner bound to this timeline and animation set.
    */ createRunner(animationSet) {
         return new AnimationTimelineRunner(animationSet, this);
     }
 }
-/**
- * Runtime interpreter for an AnimationTimeline.
- *
- * The interpreter is a synchronous frame-stack state machine advanced by {@link AnimationTimelineRunner.tick}, which is
- * driven by `AnimationSet.update(dt)` on the same logical clock as the animations. There is no
- * `async`/`await` in the control flow, so the runtime state can be serialized and replayed.
- * @public
+/**
+ * Runtime interpreter for an AnimationTimeline.
+ *
+ * The interpreter is a synchronous frame-stack state machine advanced by {@link AnimationTimelineRunner.tick}, which is
+ * driven by `AnimationSet.update(dt)` on the same logical clock as the animations. There is no
+ * `async`/`await` in the control flow, so the runtime state can be serialized and replayed.
+ * @public
  */ class AnimationTimelineRunner extends Observable {
-    /**
-   * Animation set used to start, stop, and query animation playbacks.
+    /**
+   * Animation set used to start, stop, and query animation playbacks.
    */ animationSet;
-    /**
-   * Timeline definition interpreted by this runner.
+    /**
+   * Timeline definition interpreted by this runner.
    */ timeline;
     _stack;
     _concurrent;
@@ -59,11 +59,11 @@ import { Observable } from '@zephyr3d/base';
     /** Ids of playbacks owned by concurrent (keep-active) branches; preserved across main-flow stops. */ _concurrentPlaybackIds;
     /** Marker/frame crossings observed since the last tick, keyed by playback id. */ _crossedMarkers;
     _crossedFrames;
-    /**
-   * Create a stopped runner for a timeline.
-   *
-   * @param animationSet - Animation set that owns clips and playbacks referenced by the timeline.
-   * @param timeline - Timeline definition to interpret.
+    /**
+   * Create a stopped runner for a timeline.
+   *
+   * @param animationSet - Animation set that owns clips and playbacks referenced by the timeline.
+   * @param timeline - Timeline definition to interpret.
    */ constructor(animationSet, timeline){
         super();
         this.animationSet = animationSet;
@@ -82,10 +82,10 @@ import { Observable } from '@zephyr3d/base';
         this._crossedMarkers = new Map();
         this._crossedFrames = new Map();
     }
-    /**
-   * Playback currently referenced by the active main-flow scope.
-   *
-   * @returns The current playback, or null when the main flow has no active playback reference.
+    /**
+   * Playback currently referenced by the active main-flow scope.
+   *
+   * @returns The current playback, or null when the main flow has no active playback reference.
    */ get currentPlayback() {
         const scope = this.activeScope();
         if (!scope?.currentPlaybackId) {
@@ -93,24 +93,24 @@ import { Observable } from '@zephyr3d/base';
         }
         return this._ownedPlaybacks.get(scope.currentPlaybackId) ?? null;
     }
-    /**
-   * Whether this runner is stopped.
-   *
-   * @returns True when the runner is stopped; otherwise false.
+    /**
+   * Whether this runner is stopped.
+   *
+   * @returns True when the runner is stopped; otherwise false.
    */ get stopped() {
         return this._stopped;
     }
-    /**
-   * Playback id for the most recent playback that completed naturally.
-   *
-   * @returns The playback id, or null when no owned playback has completed.
+    /**
+   * Playback id for the most recent playback that completed naturally.
+   *
+   * @returns The playback id, or null when no owned playback has completed.
    */ get lastCompletedPlaybackId() {
         return this._lastCompletedPlaybackId;
     }
-    /**
-   * Start or restart the runner from the beginning of the timeline.
-   *
-   * @returns This runner for chaining.
+    /**
+   * Start or restart the runner from the beginning of the timeline.
+   *
+   * @returns This runner for chaining.
    */ start() {
         this._stopped = false;
         this._stack = [
@@ -126,11 +126,11 @@ import { Observable } from '@zephyr3d/base';
         this.flush();
         return this;
     }
-    /**
-   * Stop the runner and all playbacks it owns.
-   *
-   * @param options - Optional stop behavior applied to owned playbacks.
-   * @returns This runner for chaining.
+    /**
+   * Stop the runner and all playbacks it owns.
+   *
+   * @param options - Optional stop behavior applied to owned playbacks.
+   * @returns This runner for chaining.
    */ stop(options) {
         const wasStopped = this._stopped;
         this._stopped = true;
@@ -159,13 +159,13 @@ import { Observable } from '@zephyr3d/base';
         }
         return this;
     }
-    /**
-   * Append a batch of steps to run after the main stack drains.
-   *
-   * If the runner has already completed, enqueueing steps revives it and registers it for ticking.
-   *
-   * @param steps - Steps to run as the next queued batch.
-   * @returns void
+    /**
+   * Append a batch of steps to run after the main stack drains.
+   *
+   * If the runner has already completed, enqueueing steps revives it and registers it for ticking.
+   *
+   * @param steps - Steps to run as the next queued batch.
+   * @returns void
    */ enqueue(steps) {
         if (steps.length === 0) {
             return;
@@ -179,13 +179,13 @@ import { Observable } from '@zephyr3d/base';
         }
         this.flush();
     }
-    /**
-   * Run `steps` concurrently with the current control flow (a true parallel branch). Unlike
-   * {@link AnimationTimelineRunner.enqueue}, these do not wait for the main stack to drain.
-   *
-   * @param steps - Steps to run immediately in an independent concurrent branch.
-   * @returns void
-   * @public
+    /**
+   * Run `steps` concurrently with the current control flow (a true parallel branch). Unlike
+   * {@link AnimationTimelineRunner.enqueue}, these do not wait for the main stack to drain.
+   *
+   * @param steps - Steps to run immediately in an independent concurrent branch.
+   * @returns void
+   * @public
    */ runConcurrent(steps) {
         if (steps.length === 0) {
             return;
@@ -199,15 +199,15 @@ import { Observable } from '@zephyr3d/base';
         }
         this.flush();
     }
-    /**
-   * Dispatch an event to this runner.
-   *
-   * Waiting `waitEvent` frames consume matching events first. If no waiter consumes the event,
-   * the timeline response table is evaluated.
-   *
-   * @param event - Event name to dispatch.
-   * @param payload - Optional payload returned in the result.
-   * @returns The resolved handling result for the event.
+    /**
+   * Dispatch an event to this runner.
+   *
+   * Waiting `waitEvent` frames consume matching events first. If no waiter consumes the event,
+   * the timeline response table is evaluated.
+   *
+   * @param event - Event name to dispatch.
+   * @param payload - Optional payload returned in the result.
+   * @returns The resolved handling result for the event.
    */ dispatch(event, payload) {
         // A waiting `waitEvent` frame consumes the event; flush advances past it synchronously.
         if (this.hasWaiterFor(event)) {
@@ -288,13 +288,13 @@ import { Observable } from '@zephyr3d/base';
             payload
         };
     }
-    /**
-   * Run pending non-blocking work synchronously (a zero-delta tick), without advancing any
-   * time-based waits. Lets `start()`/`dispatch()` take effect immediately while keeping all
-   * runtime state in the serializable frame stack.
-   *
-   * @returns This runner for chaining.
-   * @public
+    /**
+   * Run pending non-blocking work synchronously (a zero-delta tick), without advancing any
+   * time-based waits. Lets `start()`/`dispatch()` take effect immediately while keeping all
+   * runtime state in the serializable frame stack.
+   *
+   * @returns This runner for chaining.
+   * @public
    */ flush() {
         // Guard against re-entrancy: an `emit` listener firing during a tick may dispatch again.
         if (!this._ticking) {
@@ -302,12 +302,12 @@ import { Observable } from '@zephyr3d/base';
         }
         return this;
     }
-    /**
-   * Advance the timeline by `deltaInSeconds`. Called by `AnimationSet.update`.
-   *
-   * @param deltaInSeconds - Elapsed time in seconds for this tick.
-   * @returns void
-   * @public
+    /**
+   * Advance the timeline by `deltaInSeconds`. Called by `AnimationSet.update`.
+   *
+   * @param deltaInSeconds - Elapsed time in seconds for this tick.
+   * @returns void
+   * @public
    */ tick(deltaInSeconds) {
         if (this._stopped && this._queued.length === 0) {
             return;
@@ -352,11 +352,11 @@ import { Observable } from '@zephyr3d/base';
             this.dispatchEvent('complete', this);
         }
     }
-    /**
-   * Export the runtime state as plain data.
-   *
-   * @returns A serializable snapshot of the runner state.
-   * @public
+    /**
+   * Export the runtime state as plain data.
+   *
+   * @returns A serializable snapshot of the runner state.
+   * @public
    */ serialize() {
         return {
             stack: this._stack.map((frame)=>this.cloneFrame(frame)),
@@ -369,17 +369,17 @@ import { Observable } from '@zephyr3d/base';
             stopped: this._stopped
         };
     }
-    /**
-   * Restore runtime state previously produced by {@link AnimationTimelineRunner.serialize}.
-   *
-   * Re-create the relevant active playbacks on the AnimationSet before calling this so that
-   * playback-bound frames (play-wait, waitMarker, waitFrame) can re-attach by id.
-   *
-   * @param animationSet - Animation set containing any live playbacks referenced by the state.
-   * @param timeline - Timeline definition to bind to the restored runner.
-   * @param state - Serialized state previously returned by {@link AnimationTimelineRunner.serialize}.
-   * @returns A runner restored to the supplied runtime state.
-   * @public
+    /**
+   * Restore runtime state previously produced by {@link AnimationTimelineRunner.serialize}.
+   *
+   * Re-create the relevant active playbacks on the AnimationSet before calling this so that
+   * playback-bound frames (play-wait, waitMarker, waitFrame) can re-attach by id.
+   *
+   * @param animationSet - Animation set containing any live playbacks referenced by the state.
+   * @param timeline - Timeline definition to bind to the restored runner.
+   * @param state - Serialized state previously returned by {@link AnimationTimelineRunner.serialize}.
+   * @returns A runner restored to the supplied runtime state.
+   * @public
    */ static deserialize(animationSet, timeline, state) {
         const runner = new AnimationTimelineRunner(animationSet, timeline);
         runner._stack = state.stack.map((frame)=>runner.cloneFrame(frame));
@@ -449,15 +449,15 @@ import { Observable } from '@zephyr3d/base';
         }
         return null;
     }
-    /**
-   * Advance a frame stack in place. The top frame runs until it blocks or completes; completed
-   * frames pop and the parent sequence advances. Returns when the stack blocks or empties.
+    /**
+   * Advance a frame stack in place. The top frame runs until it blocks or completes; completed
+   * frames pop and the parent sequence advances. Returns when the stack blocks or empties.
    */ tickFrames(stack, deltaInSeconds) {
         this.tickFramesWithLeftover(stack, deltaInSeconds);
     }
-    /**
-   * Same as {@link AnimationTimelineRunner.tickFrames} but returns the time left unconsumed when the stack drains
-   * completely (so a parent sequence can hand it to its next step).
+    /**
+   * Same as {@link AnimationTimelineRunner.tickFrames} but returns the time left unconsumed when the stack drains
+   * completely (so a parent sequence can hand it to its next step).
    */ tickFramesWithLeftover(stack, deltaInSeconds) {
         let guard = 0;
         while(stack.length > 0){
@@ -568,8 +568,8 @@ import { Observable } from '@zephyr3d/base';
             status: 'pop'
         };
     }
-    /**
-   * Execute a non-blocking step immediately and return null, or return a frame to block on.
+    /**
+   * Execute a non-blocking step immediately and return null, or return a frame to block on.
    */ beginStep(step, scopeFrame) {
         const scope = scopeFrame.scope;
         switch(step.type){
@@ -776,10 +776,10 @@ import { Observable } from '@zephyr3d/base';
         this._concurrentPlaybackIds.delete(playback.id);
         this.forgetPlaybackRefs(playback.id);
     }
-    /**
-   * Cleanup when an owned playback ends (externally or naturally). Only touches runner-local
-   * bookkeeping, so it is safe to run inside `AnimationSet.update`'s playback loop. Frames blocked
-   * on this playback observe its absence on the next tick and unblock.
+    /**
+   * Cleanup when an owned playback ends (externally or naturally). Only touches runner-local
+   * bookkeeping, so it is safe to run inside `AnimationSet.update`'s playback loop. Frames blocked
+   * on this playback observe its absence on the next tick and unblock.
    */ onPlaybackEnd = (event)=>{
         const playback = this._ownedPlaybacks.get(event.playback.id);
         if (playback) {