rig-play 1.9.2 → 1.10.0

package/README.md

@@ -213,6 +213,87 @@ player.dispose();
 assets.dispose();
 ```
 
+### A minimal page
+
+Layout is the caller's, so the first page is the place to see it: the root
+element is the rig's world origin, Y up, and scaling it is a CSS transform the
+player cannot see. This one loads a build, fits its stage box to a container,
+tells the renderer about the scale, and plays the first animation:
+
+```html
+<!doctype html>
+<meta charset="utf-8">
+<div id="stage" style="position: relative; width: 480px; height: 640px; overflow: hidden"></div>
+<script type="module">
+  import { loadModel, RigPlayer } from 'https://cdn.jsdelivr.net/npm/@rig-c/play@1/dist/index.js';
+
+  const stage = document.getElementById('stage');
+  const assets = await loadModel({ modelUrl: 'rigs/look/skeleton.model.json' });
+  const root = stage.appendChild(document.createElement('div'));
+  const player = new RigPlayer(root, assets);
+  player.play(assets.animations[0].name);
+
+  // Fit the rig's stage box (world units, Y up) to the container: scale it, and
+  // put the origin where the box's left edge and top land.
+  const box = assets.stage ?? player.bounds();
+  const scale = Math.min(stage.clientWidth / box.width, stage.clientHeight / box.height);
+  root.style.cssText = `position: absolute; transform-origin: 0 0; transform: scale(${scale});
+    left: ${-box.x * scale}px; top: ${(box.y + box.height) * scale}px`;
+  player.renderer.syncPixelRatio(); // raster at the size on screen, not the unscaled one
+
+  let last = performance.now();
+  requestAnimationFrame(function tick(now) {
+    player.frame((now - last) / 1000);
+    last = now;
+    requestAnimationFrame(tick);
+  });
+</script>
+```
+
+`syncPixelRatio()` is what makes the scale cheap: without it the mesh canvases
+raster at the device pixel ratio of the *unscaled* rig, `1 / scale` times more
+pixels than the screen shows. Call it again after anything that changes the
+scale. `tests/readme-page.spec.ts` runs this block as written, against the
+package built from this tree.
+
+### Wind, gravity and dragging the rig
+
+A rig's physics links answer the world the page sets (#121). `environment()`
+gives them spine-core's skeleton-level wind and gravity — x right, **y down**,
+the runtime's axes; each constraint's authored `wind` / `gravity` is its
+response, so a link stating `wind: 0` feels none — and `moved()` tells them the
+page moved or turned the rig, in the skeleton's world (y up), so a dragged rig
+trails its cloth. Both apply from the next step, at any time. Added to the
+minimal page above:
+
+```ts
+// A wind slider, -1 (left) to 1 (right). The runtime starts at wind [1, 0], so set calm first.
+const wind = stage.appendChild(Object.assign(document.createElement('input'),
+  { type: 'range', min: '-1', max: '1', step: '0.01', value: '0' }));
+player.environment({ wind: [0, 0] });
+wind.addEventListener('input', () => player.environment({ wind: [Number(wind.value), 0] }));
+
+// Drag the rig: move the root, and tell the physics how far, in world units with y up.
+let held = null; // the pointer's position while a drag is held
+stage.addEventListener('pointerdown', (e) => { if (e.target !== wind) held = { x: e.clientX, y: e.clientY }; });
+addEventListener('pointerup', () => { held = null; });
+stage.addEventListener('pointermove', (e) => {
+  if (!held) return;
+  const dx = e.clientX - held.x, dy = e.clientY - held.y;
+  held = { x: e.clientX, y: e.clientY };
+  root.style.left = `${parseFloat(root.style.left) + dx}px`;
+  root.style.top = `${parseFloat(root.style.top) + dy}px`;
+  player.moved({ x: dx / scale, y: -dy / scale });
+});
+```
+
+The block is plain JavaScript, so it runs inside the page as written.
+`environment(null)` returns to the runtime's start values, and `environment()`
+reads what stands. The state is the player's, not a track's: every track and
+layer answers the same world, and a `seek` replays under the environment as it
+stands — no history is kept. A rig with no physics ignores both.
+`tests/readme-page.spec.ts` runs this block in the minimal page.
+
 The player owns one track: `play(name, { loop })` opens an animation at its first
 pose, `frame(dt)` steps it (or `advance(dt)` then `draw()`, to time the two
 apart), `pause()` / `resume()` hold and release it, `timeScale` scales every

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, 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 SlotFilter, 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 RigEnvironment, 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,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,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"}
+{"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,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,cAAc,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACtS,YAAY,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1741,6 +1741,7 @@ function slotBonePlan(bones, active, records, skipped) {
   });
   return plan;
 }
+const RUNTIME_RAD = RUNTIME_PI / 180;
 const PHYSICS_FIELDS = [
   "bone",
   "scaleY",
@@ -1949,6 +1950,30 @@ function resetPhysicsState(s, time) {
   s.rotateOffset = s.rotateLag = s.rotateVelocity = 0;
   s.scaleOffset = s.scaleLag = s.scaleVelocity = 0;
 }
+const DEFAULT_PHYSICS_ENVIRONMENT = Object.freeze({ wind: Object.freeze([1, 0]), gravity: Object.freeze([0, 1]) });
+function translatePhysics(ctx, x, y) {
+  for (const s of ctx.states.values()) {
+    s.ux -= x;
+    s.uy -= y;
+    s.cx -= x;
+    s.cy -= y;
+  }
+}
+function rotatePhysics(ctx, x, y, degrees) {
+  const r = degrees * RUNTIME_RAD;
+  const cos = Math.cos(r);
+  const sin = Math.sin(r);
+  for (const s of ctx.states.values()) {
+    const dx = s.cx - x;
+    const dy = s.cy - y;
+    const tx = dx * cos - dy * sin - dx;
+    const ty = dx * sin + dy * cos - dy;
+    s.ux -= tx;
+    s.uy -= ty;
+    s.cx -= tx;
+    s.cy -= ty;
+  }
+}
 function physicsState(ctx, name) {
   let s = ctx.states.get(name);
   if (s === void 0) {
@@ -1975,6 +2000,7 @@ function stepPhysics(r, w, length, ctx) {
   s.lastTime = ctx.time;
   const bx = w.worldX;
   const by = w.worldY;
+  const env = ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
   let z = 0;
   if (s.pending) {
     s.pending = false;
@@ -2005,16 +2031,18 @@ function stepPhysics(r, w, length, ctx) {
         const e = r.strength;
         const wind = r.wind * f;
         const g = r.gravity * f;
+        const ax = wind * env.wind[0] + g * env.gravity[0];
+        const ay = wind * env.wind[1] + g * env.gravity[1];
         const xs = s.xOffset;
         const ys = s.yOffset;
         do {
           if (x) {
-            s.xVelocity += (wind - s.xOffset * e) * m;
+            s.xVelocity += (ax - s.xOffset * e) * m;
             s.xOffset += s.xVelocity * t;
             s.xVelocity *= d;
           }
           if (y) {
-            s.yVelocity -= (g + s.yOffset * e) * m;
+            s.yVelocity -= (ay + s.yOffset * e) * m;
             s.yOffset += s.yVelocity * t;
             s.yVelocity *= d;
           }
@@ -2061,20 +2089,20 @@ function stepPhysics(r, w, length, ctx) {
         if (d === -1) d = Math.pow(r.damping, 60 * t);
         const m = r.massInverse * t;
         const e = r.strength;
-        const wind = r.wind;
-        const g = r.gravity;
+        const ax = r.wind * env.wind[0] + r.gravity * env.gravity[0];
+        const ay = r.wind * env.wind[1] + r.gravity * env.gravity[1];
         const h = l / f;
         const rs = s.rotateOffset;
         const ss = s.scaleOffset;
         for (; ; ) {
           a -= t;
           if (scaleX) {
-            s.scaleVelocity += (wind * c - g * sn - s.scaleOffset * e) * m;
+            s.scaleVelocity += (ax * c - ay * sn - s.scaleOffset * e) * m;
             s.scaleOffset += s.scaleVelocity * t;
             s.scaleVelocity *= d;
           }
           if (rotateOrShearX) {
-            s.rotateVelocity -= ((wind * sn + g * c) * h + s.rotateOffset * e) * m;
+            s.rotateVelocity -= ((ax * sn + ay * c) * h + s.rotateOffset * e) * m;
             s.rotateOffset += s.rotateVelocity * t;
             s.rotateVelocity *= d;
             if (a < t) break;
@@ -4938,6 +4966,38 @@ function checkedClock(clock, who) {
     return moved;
   };
 }
+function setEnvironmentOn(ctx, env, who) {
+  if (typeof env !== "object" || env === null || Array.isArray(env)) throw new CoreInputError(`${who} setEnvironment was given ${env === null ? "null" : Array.isArray(env) ? "an array" : typeof env}, not an object { wind?: [x, y], gravity?: [x, y] }`);
+  const given = env;
+  for (const key of Object.keys(given)) {
+    if (key !== "wind" && key !== "gravity") throw new CoreInputError(`${who} setEnvironment names "${key}", which is not one of [wind, gravity]`);
+  }
+  const pair = (key) => {
+    const v = given[key];
+    if (v === void 0) return void 0;
+    if (!Array.isArray(v) || v.length !== 2 || v.some((n) => typeof n !== "number" || !Number.isFinite(n))) throw new CoreInputError(`${who} setEnvironment's ${key} is ${JSON.stringify(v)}, not a pair of finite numbers [x, y] (x to the right, y down)`);
+    return Object.freeze([v[0], v[1]]);
+  };
+  const wind = pair("wind");
+  const gravity = pair("gravity");
+  const standing = ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
+  ctx.env = Object.freeze({ wind: wind ?? standing.wind, gravity: gravity ?? standing.gravity });
+}
+function environmentOf(ctx) {
+  return ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
+}
+function translateOn(ctx, x, y, who) {
+  for (const [k, v] of [["x", x], ["y", y]]) {
+    if (typeof v !== "number" || !Number.isFinite(v)) throw new CoreInputError(`${who} physicsTranslate's ${k} is ${String(v)}, not a finite distance in the skeleton's world`);
+  }
+  translatePhysics(ctx, x, y);
+}
+function rotateOn(ctx, x, y, degrees, who) {
+  for (const [k, v] of [["x", x], ["y", y], ["degrees", degrees]]) {
+    if (typeof v !== "number" || !Number.isFinite(v)) throw new CoreInputError(`${who} physicsRotate's ${k} is ${String(v)}, not a finite number`);
+  }
+  rotatePhysics(ctx, x, y, degrees);
+}
 function loopedTime(trackTime, duration) {
   return duration === 0 ? 0 : trackTime % duration;
 }
@@ -5065,6 +5125,25 @@ class Track {
   get duration() {
     return this.track.duration;
   }
+  get environment() {
+    return environmentOf(this.track.ctx);
+  }
+  setEnvironment(environment) {
+    this.live("setEnvironment");
+    setEnvironmentOn(this.track.ctx, environment, "the live track's");
+  }
+  physicsTranslate(x, y) {
+    this.live("physicsTranslate");
+    translateOn(this.track.ctx, x, y, "the live track's");
+  }
+  physicsRotate(x, y, degrees) {
+    this.live("physicsRotate");
+    rotateOn(this.track.ctx, x, y, degrees, "the live track's");
+  }
+  /** A refused track refuses every call that would move it, naming the step it was refused at. */
+  live(call) {
+    if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again (${call} not made)`);
+  }
   step(dt) {
     const n = this.steps + 1;
     if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again`);
@@ -5988,6 +6067,21 @@ class Tracks {
   get trackTime() {
     return this.time;
   }
+  get environment() {
+    return environmentOf(this.path.ctx);
+  }
+  setEnvironment(environment) {
+    this.live("setEnvironment");
+    setEnvironmentOn(this.path.ctx, environment, "the live tracks'");
+  }
+  physicsTranslate(x, y) {
+    this.live("physicsTranslate");
+    translateOn(this.path.ctx, x, y, "the live tracks'");
+  }
+  physicsRotate(x, y, degrees) {
+    this.live("physicsRotate");
+    rotateOn(this.path.ctx, x, y, degrees, "the live tracks'");
+  }
   live(call) {
     if (this.refused !== null) throw new CoreInputError(`the live tracks were refused at ${this.refused}, after their entries and physics had moved; open them again (${call} not made)`);
   }
@@ -8448,6 +8542,7 @@ 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 predicateOf(names) {
   const allowed = new Set(names);
   return (slot) => allowed.has(slot);
@@ -8474,6 +8569,8 @@ class RigPlayer {
   read;
   skinName;
   seekStep;
+  /** The environment the page set, or null for the runtime's start values (`environment`). */
+  env = null;
   /**
    * The single live track (`openTrack`): what a plain `play` on track 0 runs
    * on, as every 1.x player did — one animation, every construct the core
@@ -8601,6 +8698,7 @@ class RigPlayer {
       this.loop = loop;
       this.track = openTrack(this.view, name, { loop, reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
       this.pose = this.track.first;
+      this.applyEnvironment(this.track);
       return;
     }
     const tracks = this.compose();
@@ -8700,9 +8798,58 @@ class RigPlayer {
     this.tracks = tracks;
     this.track = null;
     this.pose = tracks.start();
+    this.applyEnvironment(tracks);
     if (time > 0) this.stepTo(time);
     return tracks;
   }
+  /**
+   * The world the rig's physics answers (#121): `wind` and `gravity`, as
+   * spine-core's skeleton-level `windX/windY` and `gravityX/gravityY` — x to
+   * the right and **y down**, the runtime's axes — to which each physics
+   * constraint's authored `wind` / `gravity` is the response. The runtime's
+   * start values are `{ wind: [1, 0], gravity: [0, 1] }`; a player never given
+   * one poses exactly as it did without this method. A half left out keeps its
+   * standing value, `null` returns both to the start values, and the call
+   * applies from the next step on, at any time, with no ramp of the player's
+   * own — the springs are the smoothing. It is the player's, not a track's:
+   * every track and layer answers the same world, and a `seek` or a replay
+   * poses under the environment as it stands (no history is kept). Returns the
+   * environment now standing.
+   */
+  environment(environment) {
+    if (environment === null) {
+      this.env = null;
+      this.stepper()?.setEnvironment(DEFAULT_ENVIRONMENT);
+    } else if (environment !== void 0) {
+      const live = this.stepper();
+      if (live) {
+        live.setEnvironment(environment);
+        this.env = live.environment;
+      } else {
+        const base = this.env ?? DEFAULT_ENVIRONMENT;
+        this.env = { wind: environment.wind ?? base.wind, gravity: environment.gravity ?? base.gravity };
+      }
+    }
+    return this.stepper()?.environment ?? this.env ?? DEFAULT_ENVIRONMENT;
+  }
+  /**
+   * The page moved or turned the whole rig since the last step (#121), in the
+   * skeleton's world — units, y up, degrees counter-clockwise — so physics
+   * sees it the way spine-core's `Skeleton.physicsTranslate` /
+   * `physicsRotate(0, 0, Δ)` make it: a rig dragged across the page trails
+   * its cloth. The root element's layout stays the caller's; this tells the
+   * physics what the caller did to it (a page-pixel delta divided by the
+   * root's scale, its y negated). Applies to the next step; before `play`
+   * there is nothing to move.
+   */
+  moved(motion) {
+    const live = this.stepper();
+    if (!live) return;
+    const x = motion.x ?? 0;
+    const y = motion.y ?? 0;
+    if (x !== 0 || y !== 0) live.physicsTranslate(x, y);
+    if (motion.rotation) live.physicsRotate(0, 0, motion.rotation);
+  }
   /** Stops stepping; `frame` keeps drawing the pose it holds. */
   pause() {
     this.paused = true;
@@ -8735,10 +8882,20 @@ class RigPlayer {
       this.trackCount = 1;
       this.tracks = tracks;
       this.pose = tracks.start();
+      this.applyEnvironment(tracks);
       return;
     }
     this.track = openTrack(this.view, this.animation, { loop: this.loop, reset: "animation", adjust: this.adjustHook, clock: physicsClockStep });
     this.pose = this.track.first;
+    this.applyEnvironment(this.track);
+  }
+  /** What is open: the tracks, the single track, or nothing before `play`. */
+  stepper() {
+    return this.tracks ?? this.track;
+  }
+  /** A newly opened track or tracks answer the environment the player stands in; one never set leaves it untouched. */
+  applyEnvironment(live) {
+    if (this.env !== null) live.setEnvironment(this.env);
   }
   /** Steps whatever is open forward to `time` in `seekStep` increments, the last one shorter. */
   stepTo(time) {