@rig-c/play 1.14.0 → 1.15.0

package/README.md

@@ -556,6 +556,64 @@ active (`null`), track evaluation runs with zero extra work and produces
 byte-identical poses. An unknown set name throws by name; on a build without
 `sets.json`, `sets()` is empty (`[]`) and `setSet` throws.
 
+**Several sets at once** (#168): sets that touch disjoint slots can be active
+together — a mouth viseme driven by audio beside an arm gesture driven by
+input, without building every combination as its own set:
+
+```ts
+player.setSets(['viseme_o', 'gesture_chin']); // exactly these, together
+player.removeSet('viseme_o');                 // the gesture stays
+player.addSet('viseme_a');                    // beside the active ones; already active = no change
+player.activeSets;                            // ['viseme_a', 'gesture_chin'] in sets.json order
+player.set;                                   // null: several are active (one active → its name)
+player.setSets([]);                           // restore base / track attachments
+```
+
+A set *touches* every slot it covers, every slot it `hides` and the
+`<base>_still` companion it hides. Two active sets touching the same slot are
+refused by name — `sets "viseme_o" and "talk_point" both touch slot "mouth"` —
+and nothing changes; precedence is never guessed. Disjoint sets compose as the
+union of each alone, whatever the order they were named or added in, and every
+rule above (applied to the held pose, after track evaluation, uncovered slots
+untouched) holds for the composition. `setSet(name)` keeps meaning *exactly this
+one* (`setSets([name])`) and `setSet(null)` is `setSets([])`; an unknown or
+repeated name throws by name. `slotIdentity()` reports the list as `sets`
+beside `set`.
+
+**Drawn bones** (#170): a set from `@rig-c/parts` that replaces a limb
+(a *gesture* subset set) carries `drawn` — the world rotation, in degrees
+(CCW, Y up), each of its bones was painted at — and its attachments are
+placed in the frame of the bones posed there:
+
+```json
+"wave": {
+  "slots": { "arm_upper": "arm_upper_wave", "arm_lower": "arm_lower_wave" },
+  "drawn": { "shoulder": 50, "elbow": 95 }
+}
+```
+
+While such a set is active its bones are posed at those angles, the way
+`rig-parts check --set` poses them: in document order, each drawn bone's
+local rotation is the drawn angle less its world rotation at local 0 under
+its already-posed parents (no constraint applied), computed once when the set
+is activated. On a track that local rotation replaces the clip's rotation
+of that bone on every pose, before `adjust` (so `adjust` still has the last
+word); every other bone keeps playing. Activating or clearing a drawn set
+poses the held pose again at the same time. Two active sets drawing the same
+bone are refused by name, as two sets touching one slot are. A `drawn` naming
+a bone the document does not have is refused when `sets.json` is loaded.
+
+`sets.json` keys are read strictly. Besides `slots`, `hides` and `drawn`, a
+set may carry `drawnLength`, `registration` and `threshold`, which parts
+writes and which place nothing under `check --set`: play reads past them by
+name and gives them no meaning. Any other key, on a set or on the document
+(which takes `spec`, `sets` and `threshold`), is refused by name rather than
+ignored.
+
+To switch one driver's set while another stays — a new viseme while a gesture
+holds — name the new list in one call (`setSets(['viseme_a', 'gesture_chin'])`)
+or `removeSet` then `addSet`; the first re-poses once, the second twice.
+
 ### Slot identity snapshot (`slotIdentity()`)
 
 To inspect which attachment key, owning skin and visibility state each slot
@@ -566,7 +624,8 @@ holds on the current frame — for a parts explorer or review overlay — withou
 const snap = player.slotIdentity();
 // {
 //   generation: number,              // matches player.generation and player.posedFrame().generation
-//   set: string | null,              // active set name (player.set)
+//   set: string | null,              // the one active set (player.set); null when none or several
+//   sets: readonly string[],         // every active set (player.activeSets), sets.json order
 //   skin: string | null,             // active skin name (player.skin ?? null)
 //   slots: readonly [                // every slot in posed draw order (z = 0 .. slots.length - 1)
 //     {
@@ -589,7 +648,7 @@ ones included) appears in `snap.slots`:
   and the skin that owns it (`skin`).
 - Non-drawn slots report `attachment: null`, `skin: null`, and why they are
   absent from `posedFrame().order`:
-  - `'set-hide'` — hidden by the active attachment set (`set.hides` or a
+  - `'set-hide'` — hidden by an active attachment set (`set.hides` or a
     `<base>_still` companion of a slot the set covers or hides).
   - `'timeline-null'` — cleared by an active attachment timeline key (`null`).
   - `'no-attachment'` — no attachment in the setup pose or under the active skin

package/dist/index.js

@@ -8579,6 +8579,9 @@ function readSetupMesh(assets, target) {
   return readSetupMesh$1(underNoSkin(assets.document.doc), target);
 }
 const SETS_SPECS = ["spine-parts-sets/1", "rig-parts-sets/1"];
+const SET_KEYS_NOT_POSED = ["drawnLength", "registration", "threshold"];
+const SET_KEYS = ["slots", "hides", "drawn", ...SET_KEYS_NOT_POSED];
+const SETS_DOCUMENT_KEYS = ["spec", "sets", "threshold"];
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -8597,10 +8600,16 @@ function readSetsText(text, where, doc) {
       `${where}: spec is ${JSON.stringify(raw.spec)}, not "${SETS_SPECS[0]}" or "${SETS_SPECS[1]}"`
     );
   }
+  for (const key of Object.keys(raw)) {
+    if (!SETS_DOCUMENT_KEYS.includes(key)) {
+      throw new Error(`${where}: unknown key ${JSON.stringify(key)} (known: ${SETS_DOCUMENT_KEYS.join(", ")})`);
+    }
+  }
   if (!isRecord(raw.sets) && !Array.isArray(raw.sets)) {
     throw new Error(`${where}: "sets" must be an object or an array`);
   }
   const knownSlots = new Set(doc.slots.map((slot) => slot.name));
+  const knownBones = new Set(doc.bones.map((bone2) => bone2.name));
   const attachmentsBySlot = /* @__PURE__ */ new Map();
   for (const skin of doc.skins) {
     for (const [slotName, table] of Object.entries(skin.attachments)) {
@@ -8636,6 +8645,12 @@ function readSetsText(text, where, doc) {
       throw new Error(`${where}: duplicate set "${name}"`);
     }
     seenNames.add(name);
+    for (const key of Object.keys(item)) {
+      if (Array.isArray(raw.sets) && key === "name") continue;
+      if (!SET_KEYS.includes(key)) {
+        throw new Error(`${where}: set "${name}" has unknown key ${JSON.stringify(key)} (known: ${SET_KEYS.join(", ")})`);
+      }
+    }
     if (!isRecord(item.slots)) {
       throw new Error(`${where}: set "${name}" must have a "slots" object`);
     }
@@ -8670,11 +8685,28 @@ function readSetsText(text, where, doc) {
         if (!hides.includes(hidden)) hides.push(hidden);
       }
     }
+    let drawn;
+    if (item.drawn !== void 0) {
+      if (!isRecord(item.drawn)) {
+        throw new Error(`${where}: set "${name}" "drawn" must be an object of bone name → degrees`);
+      }
+      drawn = {};
+      for (const [boneName, degrees] of Object.entries(item.drawn)) {
+        if (!knownBones.has(boneName)) {
+          throw new Error(`${where}: set "${name}" draws unknown bone "${boneName}"`);
+        }
+        if (typeof degrees !== "number" || !Number.isFinite(degrees)) {
+          throw new Error(`${where}: set "${name}" drawn bone "${boneName}" must be a finite number of degrees`);
+        }
+        drawn[boneName] = degrees;
+      }
+    }
     out.push(
       Object.freeze({
         name,
         slots: Object.freeze(slots),
-        hides: Object.freeze(hides)
+        hides: Object.freeze(hides),
+        ...drawn === void 0 || Object.keys(drawn).length === 0 ? {} : { drawn: Object.freeze(drawn) }
       })
     );
   }
@@ -8942,6 +8974,47 @@ function hiddenBySet(slotName, set) {
   }
   return false;
 }
+function touchedBySet(view, set) {
+  const touched = /* @__PURE__ */ new Set();
+  for (const slot of view.slots) {
+    if (slot.name in set.slots || hiddenBySet(slot.name, set)) touched.add(slot.name);
+  }
+  return touched;
+}
+function normaliseDegrees(deg) {
+  let v = (deg % 360 + 360) % 360;
+  if (v > 180) v -= 360;
+  return v;
+}
+function drawnLocals(view, drawn) {
+  const names = new Set(view.bones.map((b) => b.name));
+  const realParent = (parent) => parent !== void 0 && parent.endsWith("_d") && names.has(parent.slice(0, -2)) ? parent.slice(0, -2) : parent;
+  const bones = view.bones.map((b) => ({ ...b, parent: realParent(b.parent) }));
+  const locals = /* @__PURE__ */ new Map();
+  for (let i = 0; i < bones.length; i++) {
+    const target = drawn[bones[i].name];
+    if (target === void 0) continue;
+    bones[i] = { ...bones[i], rotation: 0 };
+    const pose = poseRawSetup({ ...view, bones, slots: [], constraints: [] });
+    const world = pose.bones.find((b) => b.name === bones[i].name);
+    if (world === void 0) throw new Error(`drawn bone ${JSON.stringify(bones[i].name)} was not posed`);
+    const rotation = normaliseDegrees(target - normaliseDegrees(Math.atan2(world.c, world.a) * 180 / Math.PI));
+    bones[i] = { ...bones[i], rotation };
+    locals.set(bones[i].name, rotation);
+  }
+  return locals;
+}
+function composeSets(sets) {
+  if (sets.length === 0) return null;
+  if (sets.length === 1) return sets[0];
+  const drawn = sets.filter((s) => s.drawn !== void 0);
+  return {
+    name: sets.map((s) => s.name).join("+"),
+    slots: Object.assign({}, ...sets.map((s) => s.slots)),
+    hides: sets.flatMap((s) => s.hides),
+    ...drawn.length === 0 ? {} : { drawn: Object.assign({}, ...drawn.map((s) => s.drawn)) }
+  };
+}
 function applySetToPose(view, raw, set) {
   const coveredNames = new Set(Object.keys(set.slots));
   const overrideSlots = view.slots.flatMap((slot) => {
@@ -9182,7 +9255,12 @@ class RigPlayer {
   cachedIdentityGen = -1;
   setList;
   setsByName;
+  /** The active sets in declaration order (#168); `activeSet` is their composition. */
+  activeList = [];
   activeSet = null;
+  touchedSets = /* @__PURE__ */ new Map();
+  /** The active sets' drawn bones as local rotations, applied before `adjust` on every pose (#170); null when none draws. */
+  drawnPose = null;
   adjustFn = null;
   /** Current preview patches, reapplied through the public core API on replay; no edit history. */
   physicsPatches = /* @__PURE__ */ new Map();
@@ -9193,6 +9271,7 @@ class RigPlayer {
   draws = () => true;
   /** Handed to every track the player opens; reads the current `adjust` so setting it later needs no reopen. */
   adjustHook = (locals, ctx) => {
+    if (this.drawnPose !== null) for (const [bone2, rotation] of this.drawnPose) locals.bone(bone2).rotation = rotation;
     if (this.adjustFn !== null) this.adjustFn(locals, ctx);
   };
   listeners = {
@@ -9726,8 +9805,7 @@ class RigPlayer {
       this.reopen();
       this.stepTo(time);
     } else if (this.rawPose !== null) {
-      this.setup = poseRawSetup(this.view);
-      this.setRawPose(this.setup);
+      this.setRawPose(this.drawnSetup());
     } else {
       this.poseGeneration++;
       this.cachedIdentity = null;
@@ -9741,9 +9819,17 @@ class RigPlayer {
   sets() {
     return this.setList;
   }
-  /** The currently active attachment set's name, or `null` when the base attachments are active. */
+  /**
+   * The active attachment set's name when exactly one is active; `null` when
+   * the base attachments are active or when several sets are (read
+   * `activeSets` for the list).
+   */
   get set() {
-    return this.activeSet?.name ?? null;
+    return this.activeList.length === 1 ? this.activeList[0].name : null;
+  }
+  /** Every active attachment set's name, in `sets.json` declaration order (`[]` when none). */
+  get activeSets() {
+    return this.activeList.map((s) => s.name);
   }
   /**
    * Switches the active attachment set (#134): every slot the set covers takes
@@ -9757,6 +9843,12 @@ class RigPlayer {
    * frames untouched; when no set is active (`null`), track evaluation runs
    * with zero overhead and produces byte-identical poses.
    *
+   * A set with `drawn` (#170) also poses its bones at those world angles, as
+   * `@rig-c/parts check --set` does, replacing a clip's rotation of them.
+   *
+   * `setSet(name)` means exactly this one set: any other active sets are
+   * cleared (`setSets([name])`), and `setSet(null)` is `setSets([])`.
+   *
    * A name not in `sets.json` throws by name; a build without `sets.json` has
    * `sets()` empty and `setSet` throws.
    */
@@ -9764,27 +9856,135 @@ class RigPlayer {
     if (this.setList.length === 0) {
       throw new Error(`cannot setSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
-    if (name === null) {
-      this.activeSet = null;
-      this.clearSeekCache();
-      const base2 = this.rawPose ?? (this.setup ?? (this.setup = poseRawSetup(this.view)));
-      this.rawPose = base2;
-      this.pose = base2;
-      this.poseGeneration++;
-      this.cachedIdentity = null;
-      return;
+    this.activate(name === null ? [] : [this.namedSet(name)]);
+  }
+  /**
+   * Makes exactly `names` the active attachment sets (#168), together: each
+   * set covers and hides its slots as it does alone, provided no two of them
+   * touch the same slot (cover it, hide it, or hide it as a `<base>_still`
+   * companion). Composition does not depend on the order of `names`. An
+   * unknown name, a repeated name or two sets touching one slot throw by name
+   * and leave the active sets as they were; `[]` restores the base.
+   */
+  setSets(names) {
+    if (this.setList.length === 0) {
+      throw new Error(`cannot setSets(${JSON.stringify(names)}): this model has no sets.json`);
+    }
+    const sets = names.map((name) => this.namedSet(name));
+    for (let i = 0; i < sets.length; i++) {
+      for (let j = 0; j < i; j++) {
+        if (sets[i] === sets[j]) throw new Error(`set ${JSON.stringify(sets[i].name)} is named twice in setSets`);
+      }
     }
+    this.activate(sets);
+  }
+  /**
+   * Activates `name` beside the sets already active (#168): a set already
+   * active is left as it is; one touching a slot an active set touches throws
+   * by name (the slot and both sets) and changes nothing.
+   */
+  addSet(name) {
+    if (this.setList.length === 0) {
+      throw new Error(`cannot addSet(${JSON.stringify(name)}): this model has no sets.json`);
+    }
+    const found = this.namedSet(name);
+    if (this.activeList.includes(found)) return;
+    this.activate([...this.activeList, found]);
+  }
+  /**
+   * Deactivates `name`, keeping every other active set (#168). An unknown name
+   * throws by name; a set that is not active is left as it is.
+   */
+  removeSet(name) {
+    if (this.setList.length === 0) {
+      throw new Error(`cannot removeSet(${JSON.stringify(name)}): this model has no sets.json`);
+    }
+    const found = this.namedSet(name);
+    if (!this.activeList.includes(found)) return;
+    this.activate(this.activeList.filter((s) => s !== found));
+  }
+  /** The declared set named `name`, or a throw naming it and the available sets. */
+  namedSet(name) {
     const found = this.setsByName.get(name);
     if (found === void 0) {
       throw new Error(
         `no set named ${JSON.stringify(name)} in sets.json (available: ${this.setList.map((s) => s.name).join(", ")})`
       );
     }
-    this.activeSet = found;
+    return found;
+  }
+  /**
+   * Poses again after the drawn bones changed (#170): through the tracks at
+   * the same time when the player has played, else the setup pose with the
+   * drawn bones at their rotations.
+   */
+  reposeDrawn() {
+    const stepper = this.tracks ?? this.track;
+    if (stepper !== null && this.pose !== null) {
+      this.setRawPose(stepper.step(0));
+      return;
+    }
+    this.setRawPose(this.drawnSetup());
+  }
+  /** The setup pose with the active sets' drawn bones at their rotations (#170); the plain setup pose when none draws. */
+  drawnSetup() {
+    const setup = this.setup ?? (this.setup = poseRawSetup(this.view));
+    if (this.drawnPose === null) return setup;
+    return poseRawSetup({
+      ...this.view,
+      bones: this.view.bones.map((b) => {
+        const rotation = this.drawnPose?.get(b.name);
+        return rotation === void 0 ? b : { ...b, rotation };
+      })
+    });
+  }
+  /** The slots `set` touches, computed once per set. */
+  touched(set) {
+    let touched = this.touchedSets.get(set.name);
+    if (touched === void 0) {
+      touched = touchedBySet(this.view, set);
+      this.touchedSets.set(set.name, touched);
+    }
+    return touched;
+  }
+  /**
+   * Makes `sets` (distinct) the active sets: refuses any two touching one slot
+   * before changing anything, then applies their composition to the held pose.
+   */
+  activate(sets) {
+    for (let i = 0; i < sets.length; i++) {
+      for (let j = 0; j < i; j++) {
+        const other = this.touched(sets[j]);
+        for (const slot of this.touched(sets[i])) {
+          if (other.has(slot)) {
+            throw new Error(
+              `sets ${JSON.stringify(sets[j].name)} and ${JSON.stringify(sets[i].name)} both touch slot ${JSON.stringify(slot)}; active sets must cover and hide disjoint slots`
+            );
+          }
+        }
+        const otherDrawn = sets[j].drawn;
+        for (const bone2 of Object.keys(sets[i].drawn ?? {})) {
+          if (otherDrawn !== void 0 && bone2 in otherDrawn) {
+            throw new Error(
+              `sets ${JSON.stringify(sets[j].name)} and ${JSON.stringify(sets[i].name)} both pose bone ${JSON.stringify(bone2)}; active sets must draw disjoint bones`
+            );
+          }
+        }
+      }
+    }
+    const drawnBefore = this.activeSet?.drawn;
+    this.activeList = this.setList.filter((s) => sets.includes(s));
+    this.activeSet = composeSets(this.activeList);
     this.clearSeekCache();
+    const drawn = this.activeSet?.drawn;
+    if (drawn !== drawnBefore && !(drawn === void 0 && drawnBefore === void 0)) {
+      this.drawnPose = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+      this.reposeDrawn();
+      return;
+    }
     const base = this.rawPose ?? (this.setup ?? (this.setup = poseRawSetup(this.view)));
     this.rawPose = base;
-    this.pose = applySetToPose(this.view, base, found);
+    this.pose = this.activeSet === null ? base : applySetToPose(this.view, base, this.activeSet);
     this.poseGeneration++;
     this.cachedIdentity = null;
   }
@@ -10020,7 +10220,8 @@ class RigPlayer {
     }
     const snapshot = Object.freeze({
       generation: this.poseGeneration,
-      set: this.activeSet?.name ?? null,
+      set: this.set,
+      sets: Object.freeze(this.activeSets),
       skin: this.skinName ?? null,
       slots: Object.freeze(slots)
     });