rig-play 1.5.0 → 1.6.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 —
@@ -628,6 +652,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
@@ -8341,6 +8346,9 @@ class RigPlayer {
   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);
@@ -8361,6 +8369,7 @@ class RigPlayer {
     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");
   }
   /**
@@ -8619,6 +8628,37 @@ class RigPlayer {
       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 +8724,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 +8760,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() {