rig-play 1.5.0 → 1.7.0

package/README.md

@@ -263,6 +263,30 @@ box, an inverse clip removes nothing, and bounding boxes, paths and points do
 not draw and do not count. Both cost nothing until called and read the same
 numbers in `dom` and `canvas` mode.
 
+### Drawing some slots only
+
+`slots` is a draw filter — an allow list of slot names or a predicate — settable up
+front and on a live player. The pose is the whole rig's whatever the filter:
+bones, constraints, physics, `bone()`, `adjust`, events and tracks see no filter;
+only the draw does, in both modes, and `bounds()` reads the drawn slots. A
+clipping slot the filter leaves out does not clip. An allow list naming a slot
+the document does not have is refused by name.
+
+```ts
+const hand = new RigPlayer(frontRoot, assets, { slots: ['hand_f', 'arm_f_lo'] });
+player.slots = (slot) => !slot.startsWith('weapon');
+```
+
+Two players over one `ModelAssets` share the load but each poses the rig. To
+pose it once and draw it twice — a hand drawn again in front of another
+character — give a second renderer this player's pose under another filter:
+
+```ts
+const front = new DomRenderer(frontRoot, assets.regionImages, assets.pageImages);
+// each frame, after player.frame(dt):
+front.render(player.posedFrame(['hand_f', 'arm_f_lo']));
+```
+
 ### Several tracks
 
 A base on track 0, a layer over it, a one-shot played once and mixed back out —
@@ -282,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,
@@ -628,6 +658,7 @@ name, and unloading is still elements first, bitmaps second.
 | `DomTexture` | none | Not exported; there is no atlas page to attach a texture to. |
 | `new Skeleton(assets.data)` and `new AnimationState(new AnimationStateData(assets.data))` | `new RigPlayer(root, assets, options?)` | The player holds the pose and the track. |
 | `state.setAnimation(0, 'walk', true)` | `player.play('walk', { loop: true })` | `loop` defaults to true. `play` opens the animation at its first pose with the physics reset there. `player.current` names what is playing. |
+| `skeleton.findSlot('x').attachment = null` to hide a slot, or a second skeleton with slots emptied | `RigPlayerOptions.slots`, `player.slots`, `player.posedFrame(slots)` | A draw filter since 1.6.0 — the pose is the whole rig's; a clipping slot left out does not clip. See *Drawing some slots only*. |
 | `state.setAnimation(1, 'smile', false)` with a mix, `addAnimation`, `setEmptyAnimation`, `addEmptyAnimation`, `getCurrent(track)` | `player.play(name, { track, loop, mix })`, `player.queue(name, { track, loop, mix, delay })`, `player.clear(track, { mix })`, `player.queueClear(track, { mix, delay })`, `player.entry(track)` | Since 1.5.0, rig-c's live tracks: the runtime's mixing at tolerance 0. Constraint, sequence, draw-order and path-deform timelines are not mixed and are refused on the tracks. See *Several tracks*. |
 | `state.update(delta)`, `state.apply(skeleton)`, `skeleton.update(delta)`, `skeleton.updateWorldTransform(Physics.update)`, `renderer.render(skeleton)` | `player.frame(dt)` | Or `player.advance(dt)` then `player.draw()`, to time the two apart. |
 | time scale (the caller's own, on the spine-core side) | `player.timeScale` | Multiplies every step. 0 holds the pose without re-posing it; a negative value is not stepped. |

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './Canva
 export { DomRenderer, type MeshBackend } from './DomRenderer.js';
 export { type PageLayout, type PageRegion, type RegionEncoding, type RegionImage, revokeRegions, type UnpackRegionsOptions, unpackRegions } from './DomTexture.js';
 export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument, type RegionLoading } from './loadModel.js';
-export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEvent, RigPlayer, type RigPlayerOptions, type TrackEntry } from './player.js';
+export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type TrackEntry } from './player.js';
 export type { BlendMode, PosedClip, PosedFrame, PosedMesh, PosedRegion, PosedSlot, } from './posedFrame.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChQ,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnK,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5H,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACjR,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -8216,7 +8216,7 @@ function trianglesOf(source, drawn) {
   }
   return kept;
 }
-function clipCover(pose, active) {
+function clipCover(pose, active, draws = () => true) {
   const polygons = new Map(pose.clips.map((c) => [c[0], { end: c[2], polygon: c[3] }]));
   const shownOf = new Map(pose.shown.map((s) => [s.slot, s]));
   const cover = /* @__PURE__ */ new Map();
@@ -8227,7 +8227,7 @@ function clipCover(pose, active) {
     const clip = g?.kind === "clipping" ? polygons.get(slot) : void 0;
     if (shown !== void 0 && g?.kind === "clipping" && clip !== void 0) {
       if (current !== null && current.end === slot) current = null;
-      if (active.has(shown.bone) && current === null) {
+      if (active.has(shown.bone) && current === null && draws(slot)) {
         current = { end: clip.end, clip: { polygon: clip.polygon, inverse: g.inverse, convex: g.convex } };
       }
       continue;
@@ -8237,16 +8237,17 @@ function clipCover(pose, active) {
   }
   return cover;
 }
-function frameOf(source, pose, color = [1, 1, 1, 1]) {
+function frameOf(source, pose, color = [1, 1, 1, 1], draws = () => true) {
   const { drawn: regions, why } = drawnRegions(source.doc, pose.shown, pose.drawOrder, source.uv);
   if (regions === null) throw new CoreInputError(`the page UVs are not posed: ${why}`);
   const regionOf = new Map(regions.map((r) => [r.slot, r]));
   const rows = new Map(pose.slots.map((row) => [row[0], row]));
   const z = new Map(pose.drawOrder.map((slot, index) => [slot, index]));
-  const cover = clipCover(pose, source.active);
+  const cover = clipCover(pose, source.active, draws);
   const [sr, sg, sb, sa] = color;
   const order = [];
   for (const d of pose.drawn) {
+    if (!draws(d.slot)) continue;
     const bone2 = source.boneOf.get(d.slot);
     if (bone2 === void 0 || !source.active.has(bone2)) continue;
     const found = regionOf.get(d.slot);
@@ -8294,6 +8295,10 @@ function frameOf(source, pose, color = [1, 1, 1, 1]) {
   }
   return { order };
 }
+function predicateOf(names) {
+  const allowed = new Set(names);
+  return (slot) => allowed.has(slot);
+}
 class RigPlayer {
   /**
    * The renderer this player draws through — its knobs and counters are the
@@ -8337,10 +8342,17 @@ 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;
   adjustFn = null;
+  slotFilter = null;
+  /** `slotFilter` as a predicate; every slot when null. */
+  draws = () => true;
   /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
   adjustHook = (locals) => {
     if (this.adjustFn !== null) this.adjustFn(locals);
@@ -8356,11 +8368,13 @@ 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;
     this.meshBackend = options.meshBackend;
     this.adjustFn = options.adjust ?? null;
+    if (options.slots !== void 0 && options.slots !== null) this.slots = options.slots;
     this.active = this.create(options.mode ?? "dom");
   }
   /**
@@ -8425,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 });
@@ -8449,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);
@@ -8460,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);
@@ -8472,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);
@@ -8492,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;
@@ -8533,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;
   }
@@ -8607,18 +8636,49 @@ 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);
     }
   }
+  /**
+   * Which slots this player draws (`SlotFilter`), or null for every slot.
+   * Settable on a live player: the next `draw` shows it, and `bounds()` reads
+   * the drawn slots. An allow list naming a slot the document does not have
+   * is refused by name. The pose is the whole rig's: `bone()`, `adjust`, the
+   * events and the tracks see no filter.
+   */
+  get slots() {
+    return this.slotFilter;
+  }
+  set slots(filter) {
+    if (filter === null) {
+      this.slotFilter = null;
+      this.draws = () => true;
+      return;
+    }
+    if (typeof filter === "function") {
+      this.slotFilter = filter;
+      this.draws = filter;
+      return;
+    }
+    if (!Array.isArray(filter)) throw new Error(`slots must be an array of slot names, a function, or null, got ${typeof filter}`);
+    const known = new Set(this.read.doc.slots.map((slot) => slot.name));
+    const unknown = filter.filter((name) => !known.has(name));
+    if (unknown.length > 0) {
+      throw new Error(`no slot named ${unknown.map((n) => JSON.stringify(n)).join(", ")} in this document (slots: ${[...known].join(", ")})`);
+    }
+    const allowed = new Set(filter);
+    this.slotFilter = [...filter];
+    this.draws = (slot) => allowed.has(slot);
+  }
   /**
    * The per-pose adjustment of bone locals (`BoneAdjust`), or null for none.
    * It is applied by every track the player opens — `play`, the reopen inside
@@ -8684,7 +8744,7 @@ class RigPlayer {
    * mode; nothing is computed until called.
    */
   bounds() {
-    const frame2 = this.pose === null ? frameOf(this.source, this.posed(), this.color) : this.posedFrame();
+    const frame2 = this.pose === null ? frameOf(this.source, this.posed(), this.color, this.draws) : this.posedFrame();
     let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
     for (const slot of frame2.order) {
       const points = slot.kind === "region" ? slot.corners : slot.vertices;
@@ -8720,10 +8780,17 @@ class RigPlayer {
     if (this.setup === null) this.setup = poseRawSetup(this.view);
     return this.setup;
   }
-  /** The pose the player holds, as the frame record the renderer draws. */
-  posedFrame() {
+  /**
+   * The pose the player holds, as the frame record the renderer draws — under
+   * this player's `slots` filter, or under `slots` given here instead (a
+   * second renderer over the same assets drawing this player's pose on
+   * another root: `other.render(player.posedFrame(['hand_f']))`, the one rig
+   * posed once).
+   */
+  posedFrame(slots) {
     if (this.pose === null) return { order: [] };
-    return frameOf(this.source, this.pose, this.color);
+    const draws = slots === void 0 ? this.draws : slots === null ? () => true : typeof slots === "function" ? slots : predicateOf(slots);
+    return frameOf(this.source, this.pose, this.color, draws);
   }
   /** Removes the renderer's elements and hands its GPU pages back. The assets stay the caller's. */
   dispose() {