rig-play 1.6.0 → 1.7.0

package/README.md

@@ -306,9 +306,15 @@ player.entry(2);                                            // { animation, loop
 `play(name)` keeps meaning what it meant: a plain play on track 0 runs on rig-c's
 single live track, which poses everything the core poses. The first call that
 composes — a `mix`, a `track` above 0, a `queue`, a `clear` — moves the player onto
-the tracks, carrying the single track over by replay (its animation set, pose 0
-taken, stepped to its time); from then on `seek` and `skin` are refused by name,
-since the player cannot replay a composition to a time — step it forward instead.
+the tracks, carrying the single track over by **replay** (its animation set, pose 0
+taken, stepped to its time in `seekStep` increments — one pose per step played, so
+on a stage that idled a while that is one long frame; the core offers no hand-over
+of a live track's state). To never pay it, stand the player on the tracks from the
+start: `new RigPlayer(root, assets, { tracks: true })`. Pick the single track for a
+rig whose animations key what the tracks do not mix (below); pick the tracks for
+layering. Either way, after the first `mix`, `track` above 0, `queue` or `clear`,
+`seek` and `skin` are refused by name, since the player cannot replay a composition
+to a time — step it forward instead.
 Every entry mixes from the setup pose each step, so `adjust` writes still last one
 pose. **What the tracks do not mix**, in rig-c's words at `play`/`queue`: an
 animation keying a constraint (ik, transform, path, physics, slider), a sequence,

package/dist/index.js

@@ -8342,6 +8342,10 @@ class RigPlayer {
   loop = true;
   /** One past the highest track touched — how many `current(track)` reads a step takes. */
   trackCount = 0;
+  /** `RigPlayerOptions.tracks`: every play opens the live tracks, never the single track. */
+  trackMode;
+  /** Set once anything beyond a plain play on track 0 happened: a mix, another track, a queue, a clear. `seek` and `skin` then cannot replay and refuse. */
+  beyondBase = false;
   paused = false;
   pose = null;
   setup = null;
@@ -8364,6 +8368,7 @@ class RigPlayer {
     this.view = options.skin === void 0 ? underNoSkin(read.doc) : underSkin(read.doc, options.skin);
     this.source = frameSource(this.view, read.parsed);
     this.seekStep = options.seekStep ?? 1 / 60;
+    this.trackMode = options.tracks === true;
     if (!(this.seekStep > 0)) throw new Error(`seekStep must be a positive number of seconds, got ${String(options.seekStep)}`);
     this.root = root;
     this.assets = assets;
@@ -8434,7 +8439,8 @@ class RigPlayer {
     const loop = options.loop ?? true;
     const mix = options.mix ?? 0;
     this.paused = false;
-    if (this.tracks === null && track === 0 && mix === 0) {
+    if (track !== 0 || mix !== 0) this.beyondBase = true;
+    if (this.tracks === null && track === 0 && mix === 0 && !this.trackMode) {
       this.animation = name;
       this.loop = loop;
       this.track = openTrack(this.view, name, { loop, reset: "animation", adjust: this.adjustHook });
@@ -8458,6 +8464,7 @@ class RigPlayer {
    */
   queue(name, options = {}) {
     const track = options.track ?? 0;
+    this.beyondBase = true;
     const tracks = this.compose();
     tracks.addAnimation(track, name, { loop: options.loop ?? true, mixDuration: options.mix ?? 0, delay: options.delay ?? 0 });
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8469,6 +8476,7 @@ class RigPlayer {
    * setup pose. The pose the player holds is re-posed at once.
    */
   clear(track = 0, options = {}) {
+    this.beyondBase = true;
     const tracks = this.compose();
     tracks.setEmptyAnimation(track, options.mix ?? 0);
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8481,6 +8489,7 @@ class RigPlayer {
    * its last `mix` seconds.
    */
   queueClear(track = 0, options = {}) {
+    this.beyondBase = true;
     const tracks = this.compose();
     tracks.addEmptyAnimation(track, options.mix ?? 0, options.delay ?? 0);
     this.trackCount = Math.max(this.trackCount, track + 1);
@@ -8501,11 +8510,14 @@ class RigPlayer {
     return this.tracks !== null;
   }
   /**
-   * The live tracks, opened by the first composing call. A single track in
-   * play is carried over by replay: track 0 set to its animation, pose 0 taken
-   * by `start()` (the player's — nothing steps before it) and the tracks
-   * stepped to the single track's time in `seekStep` increments, so a physics
-   * rig's history restarts there and nothing is fired on the way.
+   * The live tracks, opened by the first composing call (or by the first
+   * `play` under `tracks: true`). A single track in play is carried over by
+   * replay: track 0 set to its animation, pose 0 taken by `start()` (the
+   * player's — nothing steps before it) and the tracks stepped to the single
+   * track's time in `seekStep` increments, so a physics rig's history
+   * restarts there and nothing is fired on the way. The core offers no
+   * hand-over of a live track's state, so that replay costs one pose per
+   * `seekStep` of time played — which `tracks: true` avoids entirely.
    */
   compose() {
     if (this.tracks !== null) return this.tracks;
@@ -8542,12 +8554,20 @@ class RigPlayer {
   seek(time) {
     if (this.animation === null) throw new Error("seek before play: no animation is open");
     if (!(time >= 0) || !Number.isFinite(time)) throw new Error(`seek time must be a finite time at or above 0, got ${String(time)}`);
-    if (this.tracks !== null) throw new Error("seek is defined for a single animation on track 0; after a mix, another track, a queue or a clear the player cannot replay to a time — step it forward with frame/advance instead");
+    if (this.beyondBase) throw new Error("seek is defined for a single animation on track 0; after a mix, another track, a queue or a clear the player cannot replay to a time — step it forward with frame/advance instead");
     this.reopen();
     this.stepTo(time);
   }
-  /** The single track opened again with track 0's animation as `play` last set it, at pose 0. */
+  /** Whatever is open, opened again with track 0's animation as `play` last set it, at pose 0: the single track, or the tracks under `tracks: true`. */
   reopen() {
+    if (this.tracks !== null) {
+      const tracks = openTracks(this.view, { reset: "animation", adjust: this.adjustHook });
+      tracks.setAnimation(0, this.animation, { loop: this.loop, mixDuration: 0 });
+      this.trackCount = 1;
+      this.tracks = tracks;
+      this.pose = tracks.start();
+      return;
+    }
     this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook });
     this.pose = this.track.first;
   }
@@ -8616,14 +8636,14 @@ class RigPlayer {
   }
   set skin(name) {
     if (name === this.skinName) return;
-    if (this.tracks !== null) throw new Error("skin cannot change after a mix, another track, a queue or a clear: the player cannot replay those to the current time — set it before composing, or play again");
+    if (this.beyondBase) throw new Error("skin cannot change after a mix, another track, a queue or a clear: the player cannot replay those to the current time — set it before composing, or play again");
     const view = name === void 0 ? underNoSkin(this.read.doc) : underSkin(this.read.doc, name);
     this.view = view;
     this.source = frameSource(view, this.read.parsed);
     this.skinName = name;
     this.setup = null;
-    if (this.animation !== null && this.track !== null) {
-      const time = this.track.trackTime;
+    if (this.animation !== null && (this.track !== null || this.tracks !== null)) {
+      const time = this.time;
       this.reopen();
       this.stepTo(time);
     }