spine-rigc 2.54.0 → 2.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.54.0",
+  "version": "2.56.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/anglerange.ts

@@ -0,0 +1,190 @@
+/**
+ * How far one bone turns against another over an animation — the reading behind
+ * `rigc render --angle-range <bone>:<relative-to>[,…]` (issue #1414).
+ *
+ * ⭐ **A reading, not a gate**, as `--folds` and `--pass-through` are. A physics
+ * value has no scale an author can see: §4.6 lists `inertia`, `strength` and the
+ * rest with their bounds, and nothing said what `inertia` 0.5 does to a 54-unit
+ * chain under a hip swing — the first try on a real rig was four times too big.
+ * The answer is a number the pose already holds: how far the link turned against
+ * the bone it hangs from. So this reads it off the frames `render` draws and
+ * decides nothing.
+ *
+ * ## What the range is
+ *
+ * At each frame the bones are posed by whichever poser draws the frames, and each
+ * bone's **world direction** is that poser's own `rotationX` — the direction its x
+ * axis points, degrees counter-clockwise, y up (`BoneSnapshot`), never a second
+ * opinion recomputed from the matrix here. The relative angle is
+ *
+ *     rotationX(bone) − rotationX(relative-to)
+ *
+ * taken into (−180, 180] on the first frame read, and then **followed**: each
+ * later frame's difference is moved by whole turns to within half a turn of the
+ * frame before it. So a link that sweeps 200° reads 200°, not −160°, and one that
+ * sways through ±180° does not read a jump of a whole turn. Following assumes no
+ * two consecutive frames are half a turn or more apart, which a frame grid that
+ * coarse could not show anyway.
+ *
+ * ⚠️ It is the angle **drawn**, not the bone's local `rotation`. The two agree for
+ * a child of the other bone when the parent carries no non-uniform scale or shear;
+ * otherwise they differ, and the drawn one is what a viewer sees.
+ *
+ * The range is over the frames on the render's own grid — `--fps`, from t = 0 to
+ * the animation's last frame — so a peak between two frames is not read. A bone
+ * the posed skin leaves unposed, or one scaled to nothing, has no direction: its
+ * world matrix is zero, and the reading is refused naming the bone and the frame
+ * rather than read as 0°.
+ *
+ * Pure: no clock, no randomness, no runtime. The bone snapshots are handed in by
+ * whichever poser drew the frames.
+ */
+import type { BoneSnapshot } from './render_shared.ts';
+
+/** One pair as the flag names it: the bone whose angle is read, and the bone it is read against. */
+export interface BonePair {
+  bone: string;
+  relativeTo: string;
+}
+
+/** A malformed `--angle-range` value, or a pose the reading has no angle for — said by name. */
+export class AngleRangeError extends Error {}
+
+/**
+ * `--angle-range`'s value — `<bone>:<relative-to>[,<bone>:<relative-to>…]` —
+ * read against the skeleton's bones, or refused naming the entry: an empty
+ * entry, one without exactly one `:`, an empty name, a bone the skeleton does not
+ * have (with the bones it does), a bone read against itself (always 0°), and a
+ * pair named twice.
+ */
+export function readBonePairs(raw: string, bones: readonly string[]): BonePair[] {
+  const form = '<bone>:<relative-to>[,<bone>:<relative-to>…]';
+  const pairs: BonePair[] = [];
+  const entries = raw.split(',');
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i].trim();
+    if (entry === '') throw new AngleRangeError(`--angle-range ${JSON.stringify(raw)}: entry ${i} is empty — it takes ${form}`);
+    const parts = entry.split(':');
+    if (parts.length !== 2) {
+      throw new AngleRangeError(`--angle-range: entry ${i} ${JSON.stringify(entry)} has ${parts.length - 1} ":" — it takes ${form}, one ":" per pair`);
+    }
+    const [bone, relativeTo] = parts.map((p) => p.trim());
+    for (const [role, name] of [['bone', bone], ['relative-to bone', relativeTo]] as const) {
+      if (name === '') throw new AngleRangeError(`--angle-range: entry ${i} ${JSON.stringify(entry)} names no ${role} — it takes ${form}`);
+      if (!bones.includes(name)) {
+        throw new AngleRangeError(`--angle-range: entry ${i} names ${role} ${JSON.stringify(name)}, which this skeleton does not have; its bones are [${bones.join(', ')}]`);
+      }
+    }
+    if (bone === relativeTo) {
+      throw new AngleRangeError(`--angle-range: entry ${i} reads bone ${JSON.stringify(bone)} against itself, which is 0° on every frame — name a second bone`);
+    }
+    const again = pairs.findIndex((p) => p.bone === bone && p.relativeTo === relativeTo);
+    if (again >= 0) throw new AngleRangeError(`--angle-range: entry ${i} names "${bone}:${relativeTo}" again — entry ${again} already reads it`);
+    pairs.push({ bone, relativeTo });
+  }
+  return pairs;
+}
+
+/** One sampled frame: its index, its time, and every bone's world transform. */
+export interface AngleFrame {
+  index: number;
+  time: number;
+  bones: readonly BoneSnapshot[];
+}
+
+/** One extreme of a range: the angle, degrees, and the frame that reached it first. */
+export interface AngleExtreme {
+  degrees: number;
+  index: number;
+  time: number;
+}
+
+/** One pair's reading over one set. */
+export interface AngleRangeReading {
+  bone: string;
+  relativeTo: string;
+  /** Frames read — every frame of the set. */
+  frames: number;
+  low: AngleExtreme;
+  high: AngleExtreme;
+}
+
+/**
+ * Wrong readings the suite plants to see its controls go red (issue #1414):
+ * `worldAngle` reads the bone's own world direction and ignores the bone it is
+ * read against; `noFollow` leaves each frame's difference in (−180, 180] rather
+ * than following it from the frame before.
+ */
+export interface AnglePlant {
+  worldAngle?: true;
+  noFollow?: true;
+}
+
+/** `d` taken into (−180, 180]. */
+function wrapped(d: number): number {
+  let r = d % 360;
+  if (r <= -180) r += 360;
+  if (r > 180) r -= 360;
+  return r;
+}
+
+/** A world matrix with no direction — every entry zero: an unposed bone, or one scaled to nothing. */
+function directionless(b: BoneSnapshot): boolean {
+  return b.a === 0 && b.b === 0 && b.c === 0 && b.d === 0;
+}
+
+/**
+ * Each pair's range over `frames`, in the pairs' order — refused by
+ * `AngleRangeError`, naming the bone and the frame, where a bone has no
+ * direction (`directionless`), and naming the bone where a frame carries no
+ * snapshot of it at all (frames sampled without `{ bones: true }`).
+ */
+export function angleRangesOf(pairs: readonly BonePair[], frames: readonly AngleFrame[], where: string, plant: AnglePlant = {}): AngleRangeReading[] {
+  return pairs.map(({ bone, relativeTo }) => {
+    let previous: number | null = null;
+    let low: AngleExtreme | null = null;
+    let high: AngleExtreme | null = null;
+    for (const frame of frames) {
+      const at = (name: string): BoneSnapshot => {
+        const found = frame.bones.find((b) => b.name === name);
+        if (found === undefined) throw new AngleRangeError(`--angle-range, ${where} frame ${frame.index}: no world transform for bone ${JSON.stringify(name)} was sampled`);
+        if (directionless(found)) {
+          throw new AngleRangeError(
+            `--angle-range, ${where} frame ${frame.index} (t=${frame.time.toFixed(4)}s): bone ${JSON.stringify(name)} has no direction — its world matrix is zero ` +
+              '(a bone the posed skin leaves unposed, or one scaled to nothing), so it has no angle to read',
+          );
+        }
+        return found;
+      };
+      const a = at(bone);
+      const b = at(relativeTo);
+      const difference = plant.worldAngle === true ? a.rotationX : a.rotationX - b.rotationX;
+      let angle = wrapped(difference);
+      if (previous !== null && plant.noFollow !== true) angle += 360 * Math.round((previous - angle) / 360);
+      previous = angle;
+      if (low === null || angle < low.degrees) low = { degrees: angle, index: frame.index, time: frame.time };
+      if (high === null || angle > high.degrees) high = { degrees: angle, index: frame.index, time: frame.time };
+    }
+    if (low === null || high === null) throw new AngleRangeError(`--angle-range, ${where}: no frame was sampled`);
+    return { bone, relativeTo, frames: frames.length, low, high };
+  });
+}
+
+/** Degrees to four places, with a rounding to zero printed as `0.0000` rather than `-0.0000`. */
+export function degreesText(d: number): string {
+  const text = d.toFixed(4);
+  return text === '-0.0000' ? '0.0000' : text;
+}
+
+/**
+ * The printed line: the set, the pair, the low and the high with the frame each
+ * was first reached on, the span, and the grid it was read on.
+ */
+export function angleRangeLine(animation: string | null, fps: number, r: AngleRangeReading): string {
+  const where = animation === null ? 'the setup pose' : JSON.stringify(animation);
+  return (
+    `${where}: bone ${JSON.stringify(r.bone)} against ${JSON.stringify(r.relativeTo)} ranges ${degreesText(r.low.degrees)}° to ${degreesText(r.high.degrees)}° ` +
+    `(a span of ${degreesText(r.high.degrees - r.low.degrees)}°) over ${r.frames} frame(s) at ${fps} fps; ` +
+    `lowest at frame ${r.low.index} (t=${r.low.time.toFixed(4)}s), highest at frame ${r.high.index} (t=${r.high.time.toFixed(4)}s)`
+  );
+}

package/src/assertions/bodies/a23.ts

@@ -74,7 +74,8 @@ const SETUP_POSE_SAYS: Record<string, (pose: PhysicsSetup, animations: number, r
   // on the arm's own words, which `T100` holds.
   strength: (pose, _animations, rule) => `has strength ${pose.strength}; ${setupBasisSays(rule, pose.strength)}`,
   // The bound is read off the row, so the setup pose and a key cannot state two
-  // intervals; the reason is the arm the value took, since the ends are inside (#794).
+  // intervals; the reason is the arm the value took — above 1, at 1 (issue
+  // #1422, inside from #794 until then) or below 0.
   damping: (pose, _animations, rule) =>
     `has damping ${pose.damping}; must be ${rule.states} — the per-step decay is \`damping ** (60 * step)\`, and ` +
     setupBasisSays(rule, pose.damping),
@@ -92,10 +93,11 @@ function setupBasisSays(rule: PhysicsPoseRule, poseValue: number): string {
 
 // Every failure mode here is silent. The five component fields default to
 // 0, so a constraint can drive nothing at all; `mix` 0 mutes it; `mass` 0
-// becomes an infinite massInverse; and `damping` above 1 never settles, which
-// on a mesh-driving bone means the canvas re-rasterises forever. 1 itself is
-// inside the bound since issue #794: it never decays, which is finite and a
-// choice, and what it costs a consumer's frame is the consumer's to judge.
+// becomes an infinite massInverse; and `damping` at or above 1 never settles,
+// which on a mesh-driving bone means the canvas re-rasterises forever. 1 itself
+// was inside the bound from issue #794 to #1422, as a jiggle held rather than a
+// fault; it is out because a decay of 1 puts the step's eigenvalues on the unit
+// circle, and a chain of such links was measured resonating without limit.
 //
 // 🔑 **Two arms, one criterion.** The second arm below reads every physics
 // TIMELINE key, and it is written against `PHYSICS_POSE_RULES` — the table
@@ -410,12 +412,72 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
       if (combo.strength.value === setup.strength.value && combo.massInverse.value === setup.massInverse.value && combo.damping.value === setup.damping.value) continue;
       const at = physicsStepStability(combo.strength.value, combo.massInverse.value, combo.damping.value, physics.step);
       if (at.stable) continue;
+      // A decay rounded to 1 by the setup damping itself is the setup line's, whatever else this animation keys.
+      if (!(at.d < 1) && at.k < at.bound && combo.damping.from === 'setup') continue;
       fail(
         'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
         `animation "${animation}" can pose physics "${facts.constraints[index]?.name ?? `#${index}`}" at ${runawaySays(combo, physics.step, at)}`,
       );
     }
   }
+
+  // --- strength held at 0 for as long as an animation plays (issue #1422) ---
+  //
+  // A strength KEY of 0 is accepted (issue #727) because it releases the
+  // constraint for a span and a later key pulls the offset back. An animation
+  // whose strength timelines pose 0 at EVERY time has no later key: [measured on
+  // #1422, x drive, the runtime's default world, spine-core and rigc's core
+  // identical bit for bit] the offset grows exactly linearly while it plays —
+  // 1.33e4 at 60 s, 5.33e4 at 240 s, 1.33e5 at 600 s — and A10's walk of
+  // max(duration, 1) s sees a finite number and passes it.
+  //
+  // 🔑 **"Every time it plays", not "looped".** Whether an animation loops is
+  // not in the artifact: skeleton JSON has no loop flag, the motion spec's
+  // `loop` is a player hint the compiler never reads (`MotionAnimation.loop`),
+  // and an editor export carries neither — and when it plays, and for how long,
+  // is the consumer's. The criterion that needs none of that is the one the
+  // runtime makes true either way: looped, the animation never leaves its
+  // values; played once, a track holds its last frame, which is 0. So the
+  // clause reads the timeline alone — every key and every Bézier sample, as
+  // the pose field it lands in, and the first key at t = 0, since before a
+  // later first key the timeline poses the setup value, which the strength row
+  // holds above 0.
+  //
+  // Per animation and constraint: when two strength timelines reach one
+  // constraint in one animation (a named one and the global one), it is held
+  // only if both are — a timeline that lifts it is a later key for the other.
+  // A constraint driving nothing is named by the first clause, and one resting
+  // at strength 0 or below by its row, so neither is read here.
+  const strengthRule = physicsRuleFor('strength');
+  const heldAtZero = new Map<string, Map<number, { keys: number; held: boolean }>>();
+  for (const timeline of facts.timelines) {
+    if (timeline.kind !== 'physics' || timeline.word !== 'strength') continue;
+    const first = timeline.frames[0];
+    const posed = (value: number): number => (timeline.posed === undefined ? value : timeline.posed(value));
+    const held = first !== undefined && first.time <= 0 && timeline.channelValues(0).every((value) => posed(value) === 0);
+    const byConstraint = heldAtZero.get(timeline.animation) ?? new Map<number, { keys: number; held: boolean }>();
+    heldAtZero.set(timeline.animation, byConstraint);
+    for (const index of timeline.reach) {
+      const was = byConstraint.get(index);
+      byConstraint.set(index, { keys: (was?.keys ?? 0) + timeline.frames.length, held: (was?.held ?? true) && held });
+    }
+  }
+  for (const [animation, byConstraint] of heldAtZero) {
+    for (const [index, { keys, held }] of byConstraint) {
+      const constraint = facts.constraints[index];
+      const physics = constraint?.physics;
+      if (!held || constraint === undefined || physics === undefined || strengthRule === undefined) continue;
+      if (!PHYSICS_COMPONENTS.some((k) => physics.components[k] > 0) || !strengthRule.poseOk(physics.setup.strength)) continue;
+      fail(
+        'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
+        `animation "${animation}" poses physics "${constraint.name}" strength 0 at every time it plays — ${keys} key(s) from t=0, ` +
+          `every one 0 and no curve between them lifting it, so ${physicsOutsideSays(strengthRule, 0)}: a strength key of 0 is ` +
+          'accepted for a span because a later key pulls the offset back, and this animation has none, so for as long as it ' +
+          'plays, looped or held on its last frame, a push (wind, gravity, the bone moving) carries the offset away and it ' +
+          'grows without limit; key strength above 0 somewhere in the animation, or remove the timeline',
+      );
+    }
+  }
 }
 
 /** The three timelines whose values the stability clause combines. */
@@ -453,10 +515,23 @@ function plain(value: number): string {
  * The stability clause's sentence: the four authored numbers, `k` and the bound
  * as the runtime forms them, what the step does at that pose, and the four
  * levers that move it back under the bound.
+ *
+ * ⚠️ One pose fails with `k` under the bound: a damping the row accepts — below
+ * 1 — whose decay `damping ** (60 * step)` the runtime's doubles round to exactly
+ * 1 (issue #1422: the largest double below 1 does from fps 121 on). That is the
+ * damping row's own fault, a velocity that never decays, reached through the
+ * rate, so it says so rather than printing a `k` that is under its bound.
  */
 function runawaySays(combo: StabilityCombo, step: number, at: PhysicsStepStability): string {
   const src = (c: Candidate): string => (c.from === 'setup' ? '' : ` (${c.from})`);
   const fps = plain(1 / step);
+  if (!(at.d < 1)) {
+    return (
+      `damping ${combo.damping.value}${src(combo.damping)} at fps ${fps} — damping^(60·step) = ${at.d} as the runtime forms it, ` +
+      'so although the damping is below 1 no velocity ever decays: the step\'s eigenvalues lie on the unit circle, the fault ' +
+      'the damping row refuses 1 for, reached here by rounding; lower damping or lower fps'
+    );
+  }
   const places = apart(at.k, at.bound, 4);
   return (
     `strength ${combo.strength.value}${src(combo.strength)}, mass ${plain(1 / combo.massInverse.value)} (massInverse ${combo.massInverse.value})${src(combo.massInverse)}, ` +