spine-rigc 2.54.0 → 2.56.0

package/src/timelines.ts

@@ -476,7 +476,7 @@ export interface PhysicsPoseRule {
    * the value, and the row's `why` — the key's sentence — opens with the arms a
    * key can still take. Until this field existed `src/types.ts` said of all four
    * rows that "the bounds are the runtime's, not a policy", which is true of two
-   * of the eight ways out.
+   * of the nine ways out.
    */
   basis: readonly PhysicsBoundBasis[];
   /** The bound in words, for a message: what the value has to be. */
@@ -517,7 +517,7 @@ const STRENGTH_OUTSIDE: readonly PhysicsOutsideArm[] = [
 ];
 
 /**
- * The eight ways out of the four bounds, each with its basis (issue #798). They
+ * The nine ways out of the four bounds, each with its basis (issue #798). They
  * are named constants rather than literals inside the rows because each row's
  * `why` quotes its own — the key's sentence and `A23`'s setup sentence are then
  * one text about one number, as `STRENGTH_OUTSIDE` already made them for two.
@@ -531,7 +531,8 @@ const STRENGTH_OUTSIDE: readonly PhysicsOutsideArm[] = [
  * exactly where the rig with no constraint does, on every step; `mix` −0.5 is
  * finite and moves the bone by exactly −1× what +0.5 moves it by; `damping` 2 is
  * finite over the walk (Infinity only at step 1,065); `damping` −0.5 at 45 fps is
- * NaN at step 2. `T113` re-takes all eight on every run.
+ * NaN at step 2. The ninth, `damping` 1 (issue #1422), is finite on every step
+ * and its velocity never decays. `T113` re-takes all nine on every run.
  */
 const MIX_BELOW_0: PhysicsBoundBasis = {
   kind: 'behavioural',
@@ -584,6 +585,33 @@ const DAMPING_ABOVE_1: PhysicsBoundBasis = {
   witness: { value: 2 },
   does: 'above 1 every velocity grows on every step and the offset diverges',
 };
+/**
+ * `damping` at exactly 1 (issue #1422) — inside the bound from #794 until then.
+ *
+ * 🔑 The decay `damping ** (60 * step)` is 1 at every rate, so the step map
+ * `physicsStepStability` derives has determinant 1, and for every `k` under the
+ * bound its two eigenvalues are a complex pair of modulus √1 = 1: ON the unit
+ * circle, where every other damping puts them inside it. Nothing an excitation
+ * puts into the offset ever decays, so the rig is marginal at best — and the
+ * excitation is not benign. [measured on issue #1422, spine-core and rigc's core
+ * identical bit for bit, x drive, inertia 1, fps 30, strength 100, the runtime's
+ * default world, 600 s at 60 Hz] one such link held its peak offset at 40.3 for
+ * the whole walk; two identical ones on one chain grew it LINEARLY, 6.03e3 at
+ * 60 s to 6.09e4 at 600 s; three ran past 10⁶ at 316 s. The parent's undamped
+ * oscillation reaches the child through inertia at exactly the child's own
+ * frequency. Detuning the second link's strength by 1 % held it flat, which is
+ * why the refusal is of the value and not of a pair: equal maps are the edge,
+ * and no authored number states how close is too close.
+ */
+const DAMPING_AT_1: PhysicsBoundBasis = {
+  kind: 'behavioural',
+  when: (v) => v === 1,
+  witness: { value: 1 },
+  does:
+    'at 1 the per-step decay is 1 at every rate, so no velocity ever decays: the step\'s two eigenvalues lie ON the unit ' +
+    'circle (modulus √1 = 1) rather than inside it, so nothing a push puts in (wind, gravity, a key, the bone moving) ever ' +
+    'dies out, and two such constraints on one chain stepping alike resonate and grow without limit',
+};
 const DAMPING_BELOW_0: PhysicsBoundBasis = {
   kind: 'arithmetic',
   when: (v) => v < 0,
@@ -626,8 +654,8 @@ const DAMPING_BELOW_0: PhysicsBoundBasis = {
  *
  * 🔎 Each row's `basis` says, per way out, whether the runtime's arithmetic
  * fails there or the value runs and rigc refuses what it does (issue #798). Of
- * the eight ways out, two are arithmetic — `mass` at 0 and `damping` below 0 —
- * and six are rigc's call.
+ * the nine ways out, two are arithmetic — `mass` at 0 and `damping` below 0 —
+ * and seven are rigc's call.
  */
 export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
   {
@@ -697,7 +725,7 @@ export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
     timeline: 'damping',
     field: 'damping',
     toPose: (v) => v,
-    poseOk: (v) => v >= 0 && v <= 1,
+    poseOk: (v) => v >= 0 && v < 1,
     keyOk: null,
     inertAtSetup: false,
     outside: null,
@@ -705,22 +733,27 @@ export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
     // above 1 is a run-away, finite until the velocity overflows (step 1,065
     // for a setup of 2 at 60 fps), so it is behavioural by the line
     // `PhysicsBoundBasis` draws — the card that asked for the bases (#798)
-    // counted it arithmetic, and the walk says otherwise.
-    basis: [DAMPING_ABOVE_1, DAMPING_BELOW_0],
-    states: 'inside [0, 1]',
-    statesKeyed: 'inside [0, 1]',
-    // 🔑 The interval is CLOSED (issue #794). `1 ** x` is 1 and `0 ** x` is 0
-    // for every positive exponent, so both ends are finite at every `fps` and
-    // both are rigs somebody can mean: 1 holds the jiggle, 0 follows the bone
-    // with no overshoot. [measured] through spine-core on the generated physics
-    // fixture, 120 steps from `Physics.reset` at 60, 45 and 30 fps under a
-    // displacing animation, as a setup value and as a key: every pose value
-    // finite, the velocity never 0 at 1 and 0 after every step at 0. And 1 is
-    // not only a choice: it is 4.2's own parser default for an omitted
+    // counted it arithmetic, and the walk says otherwise. 1 itself is
+    // behavioural too: finite on every step, and never decaying.
+    basis: [DAMPING_ABOVE_1, DAMPING_AT_1, DAMPING_BELOW_0],
+    states: 'inside [0, 1)',
+    statesKeyed: 'inside [0, 1)',
+    // 🔑 The interval is HALF-OPEN (issue #1422): 0 is in and 1 is out. `0 ** x`
+    // is 0 for every positive exponent, so 0 follows the bone with no overshoot
+    // at every `fps` — a rig somebody can mean. 1 was inside from #794 to #1422,
+    // on the argument that `1 ** x` is 1 and finite at every rate, a jiggle held
+    // rather than a fault. Finite it is — [measured] through spine-core on the
+    // generated physics fixture, 120 steps from `Physics.reset` at 60, 45 and
+    // 30 fps, every pose value finite and the velocity never 0 — and that is why
+    // its arm is behavioural. What the argument missed is that a step whose
+    // decay is 1 has its eigenvalues on the unit circle, so nothing that excites
+    // it ever dies out, and a chain of such links resonates: `DAMPING_AT_1` has
+    // the measurement. ⚠️ 1 is also 4.2's own parser default for an omitted
     // `damping` (`SkeletonJson.js:242` in 4.2.120,
     // `getValue(constraintMap, "damping", 1)`; 4.3.13 reads 0.85 at `:308`), so a
-    // rig migrated from 4.2 that keys "the default" writes 1 and the editor
-    // exports it as it is. The open interval this replaced refused that rig.
+    // rig migrated from 4.2 that keys "the default" writes 1 and is refused; at
+    // #1422 none of the public recipes, the gallery, the twelve example exports,
+    // the trailer rig or the parts recipes states it, at rest or keyed.
     //
     // ⚠️ The frame-rate half is why the bound cannot be checked by playing a rig
     // at 60 fps (issue #748): `step` is `1 / fps`, the constraint's own rate, so
@@ -734,9 +767,9 @@ export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
       "every rate — finite on every step until the velocity overflows, so refusing it is rigc's call rather than the " +
       "runtime's. Below 0 the result depends on `fps`: where `60 / fps` is a " +
       'whole number a negative base stays finite — at 60 fps it is the velocity\'s sign flipped each step, which can ' +
-      `look like a jiggle settling — and ${DAMPING_BELOW_0.expression} (\`(-0.5) ** (60 / 45)\`), so a rig tried only at 60 fps never shows the failure. The two ends are ` +
-      'values the runtime plays at every rate: at 1 the velocity never decays, so the jiggle holds for as long as it ' +
-      'runs, and at 0 every velocity is zeroed on every step, so the offset follows the bone with no overshoot',
+      `look like a jiggle settling — and ${DAMPING_BELOW_0.expression} (\`(-0.5) ** (60 / 45)\`), so a rig tried only at 60 fps never shows the failure. ` +
+      `And ${DAMPING_AT_1.does} — finite on every step as well, so that refusal is rigc's call too. 0 is inside: ` +
+      'at 0 every velocity is zeroed on every step, so the offset follows the bone with no overshoot',
   },
 ];
 
@@ -746,11 +779,11 @@ export interface PhysicsStepStability {
   readonly k: number;
   /** The per-step velocity decay, `damping ** (60 * step)` — the runtime's own expression. */
   readonly d: number;
-  /** `2 · (1 + d)`: the step is stable exactly when `k` is below it. */
+  /** `2 · (1 + d)`: for `d` below 1 the step is stable exactly when `k` is below it. */
   readonly bound: number;
   /** The largest magnitude among the step map's two eigenvalues — what one step multiplies an undisturbed offset by, at most. */
   readonly growth: number;
-  /** `k < bound`, strictly. */
+  /** `k < bound` and `d < 1`, both strictly. */
   readonly stable: boolean;
 }
 
@@ -766,9 +799,22 @@ export interface PhysicsStepStability {
  * additive — wind and gravity set how far the offset goes, never whether it
  * comes back — so with `u = v·step` the step is the linear map
  * `[offset; u] ← [[1 − k, 1], [−k·d, d]]·[offset; u]`, `k = strength·m·step`:
- * trace `1 − k + d`, determinant `d`. For `d` in `[0, 1]` (the damping row's own
- * bound) both eigenvalues lie inside the unit circle exactly when
- * `0 < k < 2·(1 + d)`. The lower end is the strength row's; this is the upper.
+ * trace `1 − k + d`, determinant `d`. For `d` in `[0, 1)` both eigenvalues lie
+ * inside the unit circle exactly when `0 < k < 2·(1 + d)`. The lower end is the
+ * strength row's; this is the upper.
+ *
+ * ⚠️ **Not at `d = 1`** — this comment said `[0, 1]` until issue #1422, and it
+ * was false at that end. The determinant is `d`, so at `d = 1` the product of the
+ * two eigenvalues is 1, and for every `0 < k < 4` they are a complex pair of
+ * modulus `√d` = 1: on the circle, not inside it. One such link never decays
+ * (marginal), and two on one chain stepping alike resonate and grow without
+ * limit — measured on #1422, and the reason the damping row now ends below 1
+ * (`DAMPING_AT_1`). `d` is 1 for a `damping` of 1 at every rate, and — in the
+ * runtime's own doubles — for a `damping` a hair under 1 at a high enough rate:
+ * [measured] the largest double below 1 gives `d` exactly 1 from fps 121 on,
+ * while the largest float32 below 1, which is all a key can hold, needs about
+ * 6.4·10¹⁰. The runtime then multiplies every velocity by exactly 1, so `stable`
+ * requires `d < 1` as well, and A23 names that case by the decay it reached.
  *
  * ⚠️ **Strict.** At `k = 2·(1 + d)` one eigenvalue is exactly −1: the offset
  * flips sign every step and never settles, and at `d = 1` the two coincide and
@@ -798,7 +844,7 @@ export function physicsStepStability(strength: number, massInverse: number, damp
   const trace = 1 - k + d;
   const disc = trace * trace - 4 * d;
   const growth = disc >= 0 ? Math.max(Math.abs(trace + Math.sqrt(disc)), Math.abs(trace - Math.sqrt(disc))) / 2 : Math.sqrt(d);
-  return { k, d, bound, growth, stable: k < bound };
+  return { k, d, bound, growth, stable: k < bound && d < 1 };
 }
 
 /**

package/src/transform.ts

@@ -287,6 +287,26 @@ export function toWorld(m: BoneTransform, localX: number, localY: number): [numb
   return [m.a * localX + m.b * localY + m.worldX, m.c * localX + m.d * localY + m.worldY];
 }
 
+/**
+ * The direction of a displacement, in degrees CCW from +x, y up, in (-180, 180]
+ * — radians to degrees by the exact frame's division (`EXACT_FRAME_ARITHMETIC`),
+ * so an angle read here off `computeExactFrameTransforms` and that frame's own
+ * `worldRotation` are one arithmetic. Not rounded, for `toWorld`'s reason.
+ */
+export function directionDegrees(dx: number, dy: number): number {
+  return EXACT_FRAME_ARITHMETIC.degreesOf(Math.atan2(dy, dx));
+}
+
+/**
+ * A world displacement's direction in a bone's local space — the rotation a
+ * child of that bone states to point along it. `toBoneLocalVector`, then
+ * `directionDegrees`; a stop's frame (`src/stop.ts`) is aimed with it.
+ */
+export function localDirectionDegrees(m: BoneTransform, worldDX: number, worldDY: number): number {
+  const [lx, ly] = toBoneLocalVector(m, worldDX, worldDY);
+  return directionDegrees(lx, ly);
+}
+
 /**
  * Normalise degrees into (-180, 180], which is how an editor shows a rotation.
  *

package/src/types.ts

@@ -352,14 +352,15 @@ export type BoneProperty =
  * export; `PHYSICS_TRACKS` in `compile.ts` carries the argument.
  *
  * 🔒 **Four of them have a compile-time range** (issue #610): `mass` must be
- * `> 0`, `damping` inside the closed `[0, 1]`, and `mix` and `strength` `0` or
- * more. The bounds are `PHYSICS_POSE_RULES` in `src/timelines.ts`, and each row's
+ * `> 0`, `damping` inside the half-open `[0, 1)` (issue #1422; closed from #794),
+ * and `mix` and `strength` `0` or more. The bounds are `PHYSICS_POSE_RULES` in `src/timelines.ts`, and each row's
  * `basis` says, per way out, whose they are (issue #798). Two are the
  * runtime's arithmetic: a `mass` of 0 is an infinite `massInverse` and NaN from
  * the first step, and a `damping` below 0 is a negative base under a fractional
- * exponent at any `fps` where `60 / fps` is not whole. The other six are rigc's
+ * exponent at any `fps` where `60 / fps` is not whole. The other seven are rigc's
  * call — the rig runs, finitely, and runs wrongly: `mass` below 0 and
  * `strength` below 0 run away, `damping` above 1 diverges until it overflows,
+ * `damping` at 1 never decays and resonates on a chain,
  * `mix` below 0 is the jiggle inverted, and a setup `mix` or `strength` of 0 is
  * a constraint muted or pulled back by nothing. `inertia`, `wind`, `gravity`
  * and the top of `mix` are bounded nowhere, because the runtime documents

package/src/viewportpin.ts

@@ -0,0 +1,168 @@
+/**
+ * A render's box given rather than fitted — `rigc render --viewport` and
+ * `rigc render --viewport-from` (issue #1414) — and what the frames leave out of it.
+ *
+ * ⭐ **Why a box is given.** `render` fits its box to the rig it draws, so two
+ * candidates — a rig before and after a polish — land on two grids (377×480 against
+ * 385×480 on the run that asked for this), and a comparison of their pixels needs a
+ * transform written by hand. A given box puts both on one grid: the same world box
+ * and the same pixel size, so a world point lands on the same pixel in both.
+ *
+ * Two ways to give it, and only two:
+ *
+ * - `--viewport <x,y,w,h>` — a world box, y up, `x,y` its bottom-left corner: the
+ *   spelling `check --viewport` and `inspect --viewport` already take, and the
+ *   numbers `frames.json`'s `viewport` records. Its pixel size follows from `--max`
+ *   as a fitted box's does.
+ * - `--viewport-from <frames.json | render root>` — an earlier render's grid exactly:
+ *   its box, its scale and its pixel size as that `frames.json` records them, so the
+ *   second render is on the first one's pixels to the bit. `--max` is refused beside
+ *   it, because the file already fixes the pixel size.
+ *
+ * ⚠️ **Nothing is cropped silently.** A given box can leave part of the rig out,
+ * which a fitted box — measured over the rig's own poses at 60 fps and padded —
+ * is built not to. Each frame is the box — what lies past it is not
+ * drawn — so every slot whose drawn geometry reaches past it is named, by set and
+ * frame, with how far and on which side, and `frames.json` records the same list
+ * under `pinned` (`outsideViewport`).
+ *
+ * Pure: no clock, no randomness, no runtime.
+ */
+import { indexRuns } from './folds.ts';
+import { FRAMES_SPEC, type Frame, type PinnedViewport, type Viewport, unionBounds, viewportOfSize } from './render_shared.ts';
+
+/** A given box that cannot be used — said by name. */
+export class ViewportError extends Error {}
+
+/** `--viewport`'s value: four numbers, `x,y,w,h`, the world box, y up — refused by name otherwise. Shared by `render`, `check` and `inspect`. */
+export function readViewportBox(raw: string): { x: number; y: number; width: number; height: number } {
+  const parts = raw.split(',').map((s) => Number(s.trim()));
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+    throw new ViewportError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+  }
+  if (parts[2] <= 0 || parts[3] <= 0) throw new ViewportError('--viewport width and height must be positive');
+  return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+}
+
+/**
+ * The grid a `frames.json` records — `value` is the parsed file, `where` its path —
+ * as the viewport a second render draws on: the box, the scale and the pixel size
+ * exactly as written (`viewportOfSize`, the reading `check` takes of the same
+ * block). Refused naming the field and its value where the file is not a frame
+ * set's sidecar or its `viewport` is not a grid.
+ */
+export function viewportOfFramesFile(value: unknown, where: string): Viewport {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new ViewportError(`--viewport-from ${where}: the file is not a JSON object`);
+  const file = value as Record<string, unknown>;
+  if (file.spec !== FRAMES_SPEC) {
+    throw new ViewportError(`--viewport-from ${where}: spec is ${JSON.stringify(file.spec)}, and the grid is read off a frame set's ${FRAMES_SPEC} sidecar — the frames.json \`render\` writes`);
+  }
+  const v = file.viewport;
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) throw new ViewportError(`--viewport-from ${where}: no viewport object`);
+  const box = v as Record<string, unknown>;
+  const field = (name: string, rule: 'finite' | 'positive' | 'pixels'): number => {
+    const n = box[name];
+    const ok =
+      typeof n === 'number' &&
+      Number.isFinite(n) &&
+      (rule === 'finite' || n > 0) &&
+      (rule !== 'pixels' || Number.isInteger(n));
+    if (!ok) {
+      const need = rule === 'finite' ? 'a finite number' : rule === 'positive' ? 'a number above 0' : 'a whole number of pixels above 0';
+      throw new ViewportError(`--viewport-from ${where}: viewport.${name} is ${JSON.stringify(n) ?? 'absent'}; it must be ${need}`);
+    }
+    return n as number;
+  };
+  return viewportOfSize(
+    field('x', 'finite'),
+    field('y', 'finite'),
+    field('width', 'positive'),
+    field('height', 'positive'),
+    field('scale', 'positive'),
+    field('pixelWidth', 'pixels'),
+    field('pixelHeight', 'pixels'),
+  );
+}
+
+/** The four sides of a box, world terms, y up, in the order a line names them. */
+export const SIDES = ['left', 'right', 'bottom', 'top'] as const;
+export type Side = (typeof SIDES)[number];
+
+/** One slot that reaches past the box on one set: the frames, how far at most (world units) and on which sides. */
+export interface OutsideReading {
+  set: string;
+  slot: string;
+  frames: number[];
+  /** The farthest any of its vertices reaches past the box, on any frame and side, world units. */
+  most: number;
+  sides: Side[];
+}
+
+/**
+ * A wrong reading the suite plants to see its control go red (issue #1414):
+ * `ownBox` measures each set against the box its own frames fill rather than the
+ * given one — a reading that ignores the viewport.
+ */
+export interface OutsidePlant {
+  ownBox?: true;
+}
+
+/**
+ * Every slot whose drawn geometry reaches past `viewport` — a piece's posed
+ * vertex strictly outside the box, as the framing measures a piece — per set in
+ * `sets`' order, the slots in the order they first reach past it. Read off the
+ * frames as drawn: a slot `--slot`/`--hide` leaves out draws no piece and is not
+ * read, and a clip's cut is what is read.
+ */
+export function outsideViewport(sets: ReadonlyMap<string, readonly Frame[]>, viewport: Viewport, plant: OutsidePlant = {}): OutsideReading[] {
+  const out: OutsideReading[] = [];
+  for (const [set, frames] of sets) {
+    const box = plant.ownBox === true ? unionBounds([[...frames]]) : viewport;
+    const bySlot = new Map<string, { frames: Set<number>; most: number; sides: Set<Side> }>();
+    for (const frame of frames) {
+      for (const piece of frame.pieces) {
+        for (let i = 0; i + 1 < piece.world.length; i += 2) {
+          const x = piece.world[i];
+          const y = piece.world[i + 1];
+          const past: Array<[Side, number]> = [
+            ['left', box.minX - x],
+            ['right', x - box.maxX],
+            ['bottom', box.minY - y],
+            ['top', y - box.maxY],
+          ];
+          for (const [side, by] of past) {
+            if (!(by > 0)) continue;
+            let slot = bySlot.get(piece.slot);
+            if (slot === undefined) {
+              slot = { frames: new Set(), most: 0, sides: new Set() };
+              bySlot.set(piece.slot, slot);
+            }
+            slot.frames.add(frame.index);
+            slot.most = Math.max(slot.most, by);
+            slot.sides.add(side);
+          }
+        }
+      }
+    }
+    for (const [slot, read] of bySlot) {
+      out.push({ set, slot, frames: [...read.frames].sort((a, b) => a - b), most: read.most, sides: SIDES.filter((s) => read.sides.has(s)) });
+    }
+  }
+  return out;
+}
+
+/** `frames.json`'s `pinned` record for a given box and its reading. */
+export function pinnedRecord(by: PinnedViewport['by'], outside: readonly OutsideReading[]): PinnedViewport {
+  return { by, outside: outside.map(({ set, slot, frames }) => ({ set, slot, frames })) };
+}
+
+/**
+ * The printed line for one slot past the box: the set, the slot, the frames, how
+ * far at most and on which sides — and what happens to what lies past it.
+ */
+export function outsideLine(r: OutsideReading, fps: number): string {
+  return (
+    `${JSON.stringify(r.set)}: slot ${JSON.stringify(r.slot)} reaches past the box on ${r.frames.length} frame(s) [${indexRuns(r.frames)}] at ${fps} fps, ` +
+    `by up to ${r.most.toFixed(2)} units (${r.sides.join(', ')}) — what lies past the box is not drawn: each frame is the box`
+  );
+}