@rig-c/play 1.15.0 → 1.16.0

package/README.md

@@ -603,6 +603,46 @@ 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.
 
+**Physics under a drawn bone** (#173). A physics chain hung from a bone a set
+re-poses — a sleeve under a raised arm — reads the jump to the drawn angle as
+motion: the constraint remembers where its bone was and pointed, so the
+switch kicks it (on the test rig `drape`, a 110° raise throws the sleeve's
+tip about 297 units off the arm in the switch itself, against an idle
+frame-to-frame range of 1.5). Every set call takes an option for the chains
+under the bones the switch re-poses:
+
+```ts
+player.setSets(['raise'], { physics: 'carry' }); // also setSet, addSet, removeSet
+```
+
+- `'carry'` moves each affected constraint's remembered state by the rigid
+  turn of its deepest re-posed ancestor, so the chain keeps its pose relative
+  to the arm and goes on swinging from there (the switch itself moves the
+  sleeve 0 relative to the arm; gravity then re-settles it in the turned pose,
+  which is physics and not the switch).
+- `'reset'` restarts each affected constraint at the new pose, as a physics
+  `reset` key does: the chain snaps straight along its bones (17 units on the
+  same raise) and settles from there.
+- Absent, nothing changes: today's behaviour, frame for frame. This stays the
+  default.
+
+`'carry'` is recommended: on `drape` it moves the sleeve 0 relative to the arm
+at the switch and 0 at the deactivation, where `'reset'` moves it 17 units at
+the switch and 118 at the deactivation (no option: 297 and 298).
+
+A constraint is affected when its bone is a bone whose drawn rotation the call
+adds, removes or changes, or a descendant of one; every other chain is not
+touched. The option does nothing before `play` (the setup pose carries no
+physics state) and nothing when no physics hangs under a re-posed bone. Three limits:
+
+- Carry moves the positions and direction the constraint remembers; a
+  constraint with `x`/`y` keeps its translation offsets along the world axes,
+  unturned.
+- A drawn bone nested under a carried chain reads its new world from the
+  chain's state before the carry.
+- A later `seek` replays from the start with the sets then active, as it
+  always has, so it does not reproduce a carried switch.
+
 `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

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { type CanvasBackend, CanvasRenderer, type CanvasViewport } from './Canva
 export { DomRenderer, type MeshBackend, type MeshSourceRect } 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, readSetupMesh, type RegionLoading, type RigSet, type SetupMesh, type SetupMeshTarget } from './loadModel.js';
-export { type AdjustableBones, type BoneAdjust, type BoneAdjustContext, type BoneLocals, type BoneWorld, type PhysicsParameters, type PhysicsParameterPatch, type PhysicsParameterRead, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SlotFilter, type SlotIdentity, type SlotIdentityReason, type SlotIdentitySnapshot, type TrackEntry } from './player.js';
+export { type AdjustableBones, type BoneAdjust, type BoneAdjustContext, type BoneLocals, type BoneWorld, type PhysicsParameters, type PhysicsParameterPatch, type PhysicsParameterRead, type PlayOptions, type PoseBounds, type QueueOptions, type RenderMode, type RigComplete, type RigEnvironment, type RigEvent, RigPlayer, type RigPlayerOptions, type SetActivationOptions, type SlotFilter, type SlotIdentity, type SlotIdentityReason, type SlotIdentitySnapshot, 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,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,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,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9L,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACpd,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,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtF,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,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9L,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/e,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -8962,6 +8962,28 @@ function frameOf(source, pose, color = [1, 1, 1, 1], draws = () => true) {
   return { order };
 }
 const DEFAULT_ENVIRONMENT = Object.freeze({ wind: Object.freeze([1, 0]), gravity: Object.freeze([0, 1]) });
+function setPhysicsOption(call, options) {
+  if (options === void 0) return void 0;
+  if (options === null || typeof options !== "object") {
+    throw new Error(`${call}: options must be an object like { physics: 'carry' }, got ${JSON.stringify(options)}`);
+  }
+  const physics = options.physics;
+  if (physics === void 0 || physics === "carry" || physics === "reset") return physics;
+  throw new Error(`${call}: options.physics must be 'carry' or 'reset', got ${JSON.stringify(physics)}`);
+}
+function drawnChanged(before, after) {
+  const changed = /* @__PURE__ */ new Set();
+  if (before !== null) {
+    for (const [bone2, rotation] of before) if (after?.get(bone2) !== rotation) changed.add(bone2);
+  }
+  if (after !== null) {
+    for (const [bone2, rotation] of after) if (before?.get(bone2) !== rotation) changed.add(bone2);
+  }
+  return changed;
+}
+function physicsContextOf(stepper) {
+  return "first" in stepper ? stepper.track.ctx : stepper.path.ctx;
+}
 function predicateOf(names) {
   const allowed = new Set(names);
   return (slot) => allowed.has(slot);
@@ -9261,6 +9283,8 @@ class RigPlayer {
   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;
+  /** Test-only (#173's planted control): `carry` maps every state through the identity instead of the anchor's turn. Not API. */
+  carryPlant = false;
   adjustFn = null;
   /** Current preview patches, reapplied through the public core API on replay; no edit history. */
   physicsPatches = /* @__PURE__ */ new Map();
@@ -9852,11 +9876,12 @@ class RigPlayer {
    * A name not in `sets.json` throws by name; a build without `sets.json` has
    * `sets()` empty and `setSet` throws.
    */
-  setSet(name) {
+  setSet(name, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot setSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
-    this.activate(name === null ? [] : [this.namedSet(name)]);
+    const physics = setPhysicsOption("setSet", options);
+    this.activate(name === null ? [] : [this.namedSet(name)], physics);
   }
   /**
    * Makes exactly `names` the active attachment sets (#168), together: each
@@ -9865,43 +9890,59 @@ class RigPlayer {
    * 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.
+   *
+   * `options.physics` (#173) decides what a switch that re-poses `drawn` bones
+   * does to the physics constraints hung under them — on a bone whose drawn
+   * rotation this call adds, removes or changes, or on a descendant of one:
+   * `'carry'` moves each one's remembered state (where its bone was and
+   * pointed) by the rigid turn of its deepest re-posed ancestor, so the chain
+   * keeps its pose relative to the bone; `'reset'` restarts each one at the
+   * new pose, as a physics `reset` key does. Absent, the constraints read the
+   * jump as motion and kick, as they always have. Anything else throws before
+   * anything changes. Nothing to do before `play` or when no physics hangs
+   * under a re-posed bone. A later `seek` replays from the start with the sets
+   * then active and does not reproduce a carried switch. `setSet`, `addSet`
+   * and `removeSet` take the same option.
    */
-  setSets(names) {
+  setSets(names, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot setSets(${JSON.stringify(names)}): this model has no sets.json`);
     }
+    const physics = setPhysicsOption("setSets", options);
     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);
+    this.activate(sets, physics);
   }
   /**
    * 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) {
+  addSet(name, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot addSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
+    const physics = setPhysicsOption("addSet", options);
     const found = this.namedSet(name);
     if (this.activeList.includes(found)) return;
-    this.activate([...this.activeList, found]);
+    this.activate([...this.activeList, found], physics);
   }
   /**
    * 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) {
+  removeSet(name, options) {
     if (this.setList.length === 0) {
       throw new Error(`cannot removeSet(${JSON.stringify(name)}): this model has no sets.json`);
     }
+    const physics = setPhysicsOption("removeSet", options);
     const found = this.namedSet(name);
     if (!this.activeList.includes(found)) return;
-    this.activate(this.activeList.filter((s) => s !== found));
+    this.activate(this.activeList.filter((s) => s !== found), physics);
   }
   /** The declared set named `name`, or a throw naming it and the available sets. */
   namedSet(name) {
@@ -9947,11 +9988,102 @@ class RigPlayer {
     }
     return touched;
   }
+  /**
+   * The physics under the bones a set switch re-poses (#173), before the
+   * repose step: the drawn rotations went from `before` to `after` (already
+   * `drawnPose`), and every physics constraint whose bone is one of the
+   * changed bones or a descendant of one is carried or reset. Nothing to do
+   * before `play` (the setup pose carries no physics state) or when no
+   * constraint hangs under a changed bone.
+   */
+  handOverPhysics(before, after, mode) {
+    const stepper = this.tracks ?? this.track;
+    if (stepper === null || this.pose === null || this.rawPose === null) return;
+    const changed = drawnChanged(before, after);
+    if (changed.size === 0) return;
+    const parentOf = new Map(this.view.bones.map((b) => [b.name, b.parent]));
+    const anchorOf = (bone2) => {
+      for (let b = bone2; b !== void 0; b = parentOf.get(b)) if (changed.has(b)) return b;
+      return void 0;
+    };
+    const ctx = physicsContextOf(stepper);
+    const affected = [];
+    for (const c of this.view.constraints) {
+      if (c.kind !== "physics") continue;
+      const bone2 = c.record?.bone;
+      const anchor = bone2 === void 0 ? void 0 : anchorOf(bone2);
+      if (anchor === void 0) continue;
+      const state = ctx.states.get(c.name);
+      if (state === void 0 || state.pending) continue;
+      affected.push({ name: c.name, anchor });
+    }
+    if (affected.length === 0) return;
+    if (mode === "reset") {
+      for (const { name } of affected) {
+        const s = ctx.states.get(name);
+        s.remaining = 0;
+        s.lastTime = ctx.time;
+        s.pending = true;
+        s.xOffset = s.xLag = s.xVelocity = 0;
+        s.yOffset = s.yLag = s.yVelocity = 0;
+        s.rotateOffset = s.rotateLag = s.rotateVelocity = 0;
+        s.scaleOffset = s.scaleLag = s.scaleVelocity = 0;
+      }
+      return;
+    }
+    const anchors = new Set(affected.map((a) => a.anchor));
+    const worlds = (pose) => {
+      const out = /* @__PURE__ */ new Map();
+      for (const b of pose.bones) if (anchors.has(b.name)) out.set(b.name, b);
+      return out;
+    };
+    const old = worlds(this.rawPose);
+    const snapshot = captureStepperState(stepper);
+    const now = worlds(stepper.step(0));
+    restoreStepperState(stepper, snapshot);
+    const maps = /* @__PURE__ */ new Map();
+    for (const anchor of anchors) {
+      const o = old.get(anchor);
+      const n = now.get(anchor);
+      if (o === void 0 || n === void 0) continue;
+      if (this.carryPlant) {
+        maps.set(anchor, [1, 0, 0, 1, 0, 0]);
+        continue;
+      }
+      const det = o.a * o.d - o.b * o.c;
+      if (!Number.isFinite(det) || det === 0) continue;
+      const ia = o.d / det;
+      const ib = -o.b / det;
+      const ic = -o.c / det;
+      const id = o.a / det;
+      const a = n.a * ia + n.b * ic;
+      const b = n.a * ib + n.b * id;
+      const c = n.c * ia + n.d * ic;
+      const d = n.c * ib + n.d * id;
+      maps.set(anchor, [a, b, c, d, n.worldX - (a * o.worldX + b * o.worldY), n.worldY - (c * o.worldX + d * o.worldY)]);
+    }
+    const states = physicsContextOf(stepper).states;
+    for (const { name, anchor } of affected) {
+      const m = maps.get(anchor);
+      const s = states.get(name);
+      if (m === void 0 || s === void 0) continue;
+      const [a, b, c, d, x, y] = m;
+      const ux = s.ux;
+      s.ux = a * ux + b * s.uy + x;
+      s.uy = c * ux + d * s.uy + y;
+      const cx = s.cx;
+      s.cx = a * cx + b * s.cy + x;
+      s.cy = c * cx + d * s.cy + y;
+      const tx = s.tx;
+      s.tx = a * tx + b * s.ty;
+      s.ty = c * tx + d * s.ty;
+    }
+  }
   /**
    * 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) {
+  activate(sets, physics) {
     for (let i = 0; i < sets.length; i++) {
       for (let j = 0; j < i; j++) {
         const other = this.touched(sets[j]);
@@ -9978,7 +10110,9 @@ class RigPlayer {
     this.clearSeekCache();
     const drawn = this.activeSet?.drawn;
     if (drawn !== drawnBefore && !(drawn === void 0 && drawnBefore === void 0)) {
+      const posedBefore = this.drawnPose;
       this.drawnPose = drawn === void 0 ? null : drawnLocals(this.view, drawn);
+      if (physics !== void 0) this.handOverPhysics(posedBefore, this.drawnPose, physics);
       this.reposeDrawn();
       return;
     }