@aura3d/animation 4.7.18 → 5.0.1

package/dist/AnimationAction.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationClip } from "./AnimationClip.js";
+import { AnimationClip } from "./AnimationClip.js";
 import { type AnimationEvent } from "./AnimationEvents.js";
 export type LoopMode = "once" | "repeat" | "pingpong";
 export type AnimationActionSnapshot = {
@@ -10,6 +10,42 @@ export type AnimationActionSnapshot = {
     readonly playing: boolean;
     readonly paused: boolean;
     readonly loopMode: LoopMode;
+    /**
+     * Playback details are included for inspection. Use `serialize()` rather than
+     * `snapshot()` when the result must be restored: serialization also verifies
+     * and records the complete clip identity.
+     */
+    readonly state?: {
+        readonly version: 1;
+        readonly clipIdentity?: string;
+        /** `null` represents unlimited repetitions in JSON. */
+        readonly repetitions: number | null;
+        readonly clampWhenFinished: boolean;
+        readonly maxEventCatchUp: number;
+        readonly pingPongForward: boolean;
+        readonly loopsCompleted: number;
+        readonly fade: {
+            readonly duration: number;
+            readonly elapsed: number;
+            readonly startWeight: number;
+            readonly targetWeight: number;
+        } | null;
+        readonly warp: {
+            readonly duration: number;
+            readonly elapsed: number;
+            readonly from: number;
+            readonly to: number;
+        } | null;
+        readonly lastPlaybackDelta: number;
+        readonly signals: {
+            readonly loopDelta: number;
+            readonly finishedDirection: -1 | 0 | 1;
+            /** `null` represents an unrepresentably large event overflow. */
+            readonly eventOverflow: number | null;
+        };
+    };
+    /** Optional derived field used by the glTF binding; it is not an enabled flag. */
+    readonly active?: boolean;
 };
 /**
  * Playback signals an {@link AnimationAction} produced during `update` and that
@@ -20,6 +56,16 @@ export type AnimationActionSnapshot = {
 export type AnimationActionPlaybackSignals = {
     readonly loopDelta: number;
     readonly finishedDirection: -1 | 0 | 1;
+    /** Marker occurrences omitted because the per-update catch-up limit was reached. */
+    readonly eventOverflow: number;
+};
+type WarpSegment = {
+    readonly distance: number;
+    readonly duration: number;
+    readonly elapsed: number;
+    readonly from: number;
+    readonly to: number;
+    readonly inWarp: boolean;
 };
 export declare class AnimationAction {
     readonly clip: AnimationClip;
@@ -47,14 +93,20 @@ export declare class AnimationAction {
     clampWhenFinished: boolean;
     playing: boolean;
     paused: boolean;
+    /** Maximum marker callbacks produced by one update. Excess is reported in playback signals. */
+    maxEventCatchUp: number;
+    /** Signed unwrapped clip-time distance actually traveled by the last update. */
+    lastPlaybackDelta: number;
     private pingPongForward;
     private loopsCompleted;
     private signalLoopDelta;
     private signalFinishedDirection;
+    private signalEventOverflow;
     private fadeDuration;
     private fadeElapsed;
     private fadeStartWeight;
     private fadeTargetWeight;
+    private warpState;
     constructor(clip: AnimationClip);
     play(): this;
     pause(): this;
@@ -69,8 +121,14 @@ export declare class AnimationAction {
      */
     setLoop(loopMode: LoopMode, repetitions?: number): this;
     reset(): this;
+    /** Copy the phase and reflected direction of another action, optionally scaling its phase. */
+    synchronizePlayback(other: AnimationAction, normalized?: boolean): this;
     seek(time: number): this;
     fadeTo(weight: number, duration: number): this;
+    /** Linearly interpolate the signed playback rate over unpaused mixer time. */
+    warp(startTimeScale: number, endTimeScale: number, duration: number): this;
+    /** @internal Convert travel through a monotonic linear-rate segment to mixer time. */
+    static consumedWarpDuration(segment: Pick<WarpSegment, "distance" | "duration" | "from" | "to">, travelled: number): number;
     /**
      * Advances playback by `delta` seconds scaled by `timeScale` (signed — a
      * negative product reverses the playhead) and returns the clip marker events
@@ -81,6 +139,14 @@ export declare class AnimationAction {
      * keeps blending), otherwise it stops.
      */
     update(delta: number): readonly AnimationEvent[];
+    /** @internal Integrate monotonic parts separately so a rate reversal retains marker crossings. */
+    static warpSegments(delta: number, warp: {
+        readonly duration: number;
+        readonly elapsed: number;
+        readonly from: number;
+        readonly to: number;
+    }): WarpSegment[];
+    private advancePlayback;
     /**
      * Drains the `loop`/`finished` signals accumulated by the last `update`. The
      * owning {@link AnimationMixer} calls this once per update per action; direct
@@ -90,5 +156,18 @@ export declare class AnimationAction {
     consumePlaybackSignals(): AnimationActionPlaybackSignals;
     private finish;
     snapshot(): AnimationActionSnapshot;
+    /**
+     * Capture a JSON-safe, restorable action state. The identity covers the full
+     * clip, including keyframes, interpolation and event payloads; custom clip
+     * implementations and non-JSON event payloads cannot be silently dropped.
+     */
+    serialize(): AnimationActionSnapshot;
+    /**
+     * Restore in place without calling `play()`, emitting events, or applying a
+     * pose. Pre-versioned snapshots retain their fields but start with unlimited
+     * repetitions, forward reflection, no transition and no pending signals.
+     */
+    restore(snapshot: AnimationActionSnapshot): this;
 }
+export {};
 //# sourceMappingURL=AnimationAction.d.ts.map

package/dist/AnimationAction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationAction.d.ts","sourceRoot":"","sources":["../../../../packages/animation/src/AnimationAction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEtD,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACxC,CAAC;AAEF,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,IAAI,SAAK;IACT,MAAM,SAAK;IACX;;;;;OAKG;IACH,SAAS,SAAK;IACd,QAAQ,EAAE,QAAQ,CAAY;IAC9B;;;;OAIG;IACH,WAAW,SAAY;IACvB;;;;OAIG;IACH,iBAAiB,UAAS;IAC1B,OAAO,UAAS;IAChB,MAAM,UAAS;IACf,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,uBAAuB,CAAiB;IAChD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,IAAI,EAAE,aAAa;IAI/B,IAAI,IAAI,IAAI;IAmBZ,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IASZ,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ/B,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAWvD,KAAK,IAAI,IAAI;IAUb,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAYxB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAc9C;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE;IAsGhD;;;;;OAKG;IACH,sBAAsB,IAAI,8BAA8B;IAUxD,OAAO,CAAC,MAAM;IAYd,QAAQ,IAAI,uBAAuB;CAYpC"}
+{"version":3,"file":"AnimationAction.d.ts","sourceRoot":"","sources":["../src/AnimationAction.ts"],"names":[],"mappings":"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"}