rig-play 1.1.0 → 1.2.0

package/README.md

@@ -263,6 +263,35 @@ 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.
 
+### Adjusting bones
+
+A per-pose write to bone locals — a breath's scale, a look's rotation, a mouth
+driven while the body holds still:
+
+```ts
+const player = new RigPlayer(root, assets, {
+  adjust: (bones) => { bones.bone('mouth').scaleY = 1 + openness; },
+});
+player.adjust = null;   // or set it later; setting it re-poses the held pose at once
+```
+
+The function runs once per pose, after the animation's timelines and before the
+world transforms, constraints and physics — `rig-c/core`'s `openTrack({ adjust })`,
+which rig-c holds to the Spine runtime at tolerance 0. **A write lasts one
+pose.** The core poses every step from the setup pose, so a value you want held
+is written again each pose and nothing compounds; a 0.8 caller that multiplied a
+channel on a skeleton it kept between frames writes the value it wants, every
+pose. It runs on every pose the animation is applied to, the first one after
+`play` included, and `seek` and a `mode` change keep it.
+
+A paused player and a zero step re-pose nothing, so a change the function would
+make is not seen until the next step — unless you ask: setting `player.adjust`
+re-poses the held pose at the same track time, and `player.repose()` does the
+same for a function whose own state changed (the mouth above), without stepping,
+firing events or drawing. A non-finite value, a bone the document does not have,
+or an error the function throws refuses that step in the core's words, and the
+track is reopened by the next `play` or `seek`.
+
 ### One load, several players
 
 One `loadModel` backs any number of players: the regions are cut once, and
@@ -569,6 +598,9 @@ name, and unloading is still elements first, bitmaps second.
 | tint: skeleton × slot × attachment colour | `player.color` × slot × attachment | `player.color` is `[r, g, b, a]` and takes the place of the skeleton's colour. The product arrives as `tint` on each `PosedSlot`. |
 | dark (two-colour) tint: unsupported | `DomRenderer`: unsupported. `CanvasRenderer`: drawn | Carried as `dark` on a `PosedSlot`. The canvas mode's canvas2d fallback draws alpha only. |
 | `renderer.dispose()` | `player.dispose()` | Then `assets.dispose()`, as before. `DomRenderer.dispose()` and `CanvasRenderer.dispose()` exist for a renderer you constructed yourself. |
+| `skeleton.findBone('head').worldX`, `.worldY`, `.a` … `.d` | `player.bone('head')` | `{ x, y, a, b, c, d, rotationX, rotationY, scaleX, scaleY, active }`, the core's world transform for the pose the player holds (the setup pose before `play`). An unknown name is refused by name. Since 1.1.0. |
+| `bone.scaleY = …` on a `Skeleton` between `state.apply` and `updateWorldTransform` | `RigPlayerOptions.adjust`, `player.adjust`, `player.repose()` | A function called once per pose with the pose's bone locals (`bones.bone('mouth').scaleY = v`). A write lasts one pose: the core poses every step from the setup pose, so write the value you want, every pose — nothing compounds. See *Adjusting bones*. Since 1.2.0. |
+| `skeleton.getBounds(offset, size)` | `player.bounds()` | `{ x, y, width, height }` or null, world units, Y up: the box of every drawn region's corners and mesh's vertices, a slot under a clip counted inside the clip's own box. `ModelAssets.stage` remains the declared framing, not this box. Since 1.1.0. |
 
 ### No counterpart in 1.0.0
 
@@ -586,13 +618,6 @@ export, for which 1.0.0 declares nothing:
   load, several players.
 - **More than one track, mixing between animations, or queueing one after another.**
   `RigPlayer` declares one track; `play` reopens it at the animation's first pose.
-- **Reading or writing a bone.** No bone is exposed: nothing sets a bone's local values
-  between the step and the draw, and nothing returns a bone's world transform. What is
-  readable is the posed slots: `player.posedFrame()` carries each drawn slot's world
-  `corners` or `vertices`.
-- **A bounds query for the current pose.** None is declared. `ModelAssets.stage` is the
-  stage the document states (or null), which is the rig's declared framing and not the
-  box of the pose being drawn.
 - **Changing the skin after construction.** `skin` is a `RigPlayerOptions` field and
   `RigPlayer` declares no way to change it later; a second player over the same assets
   is the declared route.

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 RegionImage, revokeRegions, unpackRegions } from './DomTexture.js';
 export { type LoadModelOptions, loadModel, type ModelAssets, type ModelDocument } from './loadModel.js';
-export { type BoneWorld, type PoseBounds, type RenderMode, type RigEvent, RigPlayer, type RigPlayerOptions } from './player.js';
+export { type AdjustableBones, type BoneAdjust, type BoneLocals, type BoneWorld, type PoseBounds, type RenderMode, type RigEvent, RigPlayer, type RigPlayerOptions } 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,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAChI,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,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxL,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -3819,6 +3819,81 @@ function posedBones(doc, timelines, t, plant = {}) {
     return bone2;
   });
 }
+const LOCAL_CHANNELS = { rotation: 0, x: 0, y: 0, scaleX: 1, scaleY: 1, shearX: 0, shearY: 0 };
+class StepLocals {
+  constructor(bones, index, setup) {
+    this.bones = bones;
+    this.index = index;
+    this.setup = setup;
+  }
+  read(channel2) {
+    return this.bones[this.index][channel2] ?? LOCAL_CHANNELS[channel2];
+  }
+  write(channel2, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) throw new CoreInputError(`the adjustment wrote bone "${this.setup.name}" ${channel2} = ${String(value)}, not a finite number`);
+    if (this.bones[this.index] === this.setup) this.bones[this.index] = { ...this.setup };
+    this.bones[this.index][channel2] = value;
+  }
+  get rotation() {
+    return this.read("rotation");
+  }
+  set rotation(v) {
+    this.write("rotation", v);
+  }
+  get x() {
+    return this.read("x");
+  }
+  set x(v) {
+    this.write("x", v);
+  }
+  get y() {
+    return this.read("y");
+  }
+  set y(v) {
+    this.write("y", v);
+  }
+  get scaleX() {
+    return this.read("scaleX");
+  }
+  set scaleX(v) {
+    this.write("scaleX", v);
+  }
+  get scaleY() {
+    return this.read("scaleY");
+  }
+  set scaleY(v) {
+    this.write("scaleY", v);
+  }
+  get shearX() {
+    return this.read("shearX");
+  }
+  set shearX(v) {
+    this.write("shearX", v);
+  }
+  get shearY() {
+    return this.read("shearY");
+  }
+  set shearY(v) {
+    this.write("shearY", v);
+  }
+}
+function adjustLocals(doc, bones, adjust) {
+  const views = /* @__PURE__ */ new Map();
+  const names = doc.bones.map((b) => b.name);
+  adjust({
+    names,
+    bone(name) {
+      let view = views.get(name);
+      if (view === void 0) {
+        const index = names.indexOf(name);
+        if (index < 0) throw new CoreInputError(`the adjustment asked for bone ${JSON.stringify(name)}, which is not one of this document's bones`);
+        view = new StepLocals(bones, index, doc.bones[index]);
+        views.set(name, view);
+      }
+      return view;
+    }
+  });
+}
 const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
 function posedSlots(doc, timelines, t, plant = {}, sliders = [], placeholders) {
   const resolve = plant.shown ?? shownAttachment;
@@ -3895,6 +3970,7 @@ function stepRows(posed) {
 function posedBoneStep(doc, timelines, t, plant, constraints, sliders, step) {
   const active = activeBones(doc);
   const bones = posedBones(doc, timelines, t, plant);
+  if (step?.adjust !== void 0) adjustLocals(doc, bones, step.adjust);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   if (constraints !== void 0 && step !== void 0) {
     const records = stepPhysicsRecords(pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, active, step.ctx, step.before);
@@ -4819,16 +4895,16 @@ function animationOf(doc, animation) {
   if (anim === void 0) throw new CoreInputError(`animation "${animation}" is not one of this document's [${doc.animations.map((a) => a.name).join(", ")}]`);
   return anim;
 }
-function openWalk(doc, anim, plant, reset, mode, shape) {
+function openWalk(doc, anim, plant, reset, mode, shape, adjust) {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
   const ctx = freshStepContext(plant.physicsStep);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
-  const track = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, trackTime: 0, last: -1 };
+  const track = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, adjust, trackTime: 0, last: -1 };
   return { track, first: stepWalk(track, 0, true) };
 }
 function stepWalk(track, dt, first = false) {
-  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx } = track;
+  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx, adjust } = track;
   track.trackTime += dt;
   const trackTime = track.trackTime;
   const last = track.last;
@@ -4836,7 +4912,7 @@ function stepWalk(track, dt, first = false) {
   const before = ctx.time;
   ctx.time += mode.clock === void 0 ? dt : mode.clock(dt, t - (first ? 0 : Math.max(last, 0)));
   const sliders = [];
-  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before });
+  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust });
   if (first) ctx.phase = "update";
   const placeholders = /* @__PURE__ */ new Map();
   const slots = posedSlots(doc, anim.timelines, t, raw, sliders, placeholders);
@@ -4856,8 +4932,8 @@ function stepWalk(track, dt, first = false) {
   track.last = t;
   return pose;
 }
-function openRawTrack(doc, animation, plant, reset, mode) {
-  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE);
+function openRawTrack(doc, animation, plant, reset, mode, adjust) {
+  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust);
 }
 function stepRawTrack(track, dt) {
   return stepWalk(track, dt);
@@ -4866,7 +4942,8 @@ const HELD = { loop: false, keep: false };
 const LOOPED = { loop: true, keep: false, live: true };
 function openTrack(doc, animation, options, plant = {}) {
   if (typeof options !== "object" || options === null || typeof options.loop !== "boolean") throw new CoreInputError(`the live track's options.loop is ${JSON.stringify(options?.loop)}, not true or false`);
-  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD);
+  if (options.adjust !== void 0 && typeof options.adjust !== "function") throw new CoreInputError(`the live track's options.adjust is ${typeof options.adjust}, not a function`);
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD, options.adjust);
   return new Track(track, first);
 }
 class Track {
@@ -4896,7 +4973,7 @@ class Track {
       this.latest = pose.animationTime;
       return pose;
     } catch (err) {
-      if (err instanceof CoreInputError) this.refused = `${n} (${err.message})`;
+      this.refused = `${n} (${err instanceof Error ? err.message : String(err)})`;
       throw err;
     }
   }
@@ -7221,6 +7298,11 @@ class RigPlayer {
   paused = false;
   pose = null;
   setup = null;
+  adjustFn = null;
+  /** 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);
+  };
   listeners = {
     event: /* @__PURE__ */ new Set(),
     complete: /* @__PURE__ */ new Set()
@@ -7234,6 +7316,7 @@ class RigPlayer {
     this.root = root;
     this.assets = assets;
     this.meshBackend = options.meshBackend;
+    this.adjustFn = options.adjust ?? null;
     this.active = this.create(options.mode ?? "dom");
   }
   /**
@@ -7342,6 +7425,33 @@ class RigPlayer {
     if (this.pose === null) return;
     this.renderer.render(this.posedFrame());
   }
+  /**
+   * 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
+   * `seek` — and by the pose drawn again after `mode` changes, on every pose
+   * the animation is applied to, the first one included. Setting it re-poses
+   * the pose the player holds at once (`repose`), so a held or paused player
+   * shows the change on its next `draw` without a step.
+   */
+  get adjust() {
+    return this.adjustFn;
+  }
+  set adjust(fn) {
+    if (fn !== null && typeof fn !== "function") throw new Error(`adjust must be a function or null, got ${typeof fn}`);
+    this.adjustFn = fn;
+    this.repose();
+  }
+  /**
+   * Poses the held pose again at the same track time, through the current
+   * `adjust`, without stepping, firing or drawing. A paused player and a zero
+   * step re-pose nothing, so a caller whose adjustment reads its own state
+   * (a mouth driven while the body is held) calls this when that state
+   * changed, then `draw`. Nothing before `play`.
+   */
+  repose() {
+    if (this.track === null || this.pose === null) return;
+    this.pose = this.track.step(0);
+  }
   /**
    * Where `name` is in the pose the player holds — the pose of the last
    * `advance`/`frame`/`seek`, or the setup pose before `play`. Read off the
@@ -7427,7 +7537,7 @@ class RigPlayer {
     this.pose = null;
   }
   open() {
-    this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation" });
+    this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook });
     this.pose = this.track.first;
   }
   /**