spine-rigc 2.53.0 → 2.55.0

package/src/render_shared.ts

@@ -38,6 +38,7 @@ import {
 import { spinePosingFor, type SpineSkeletonData } from './spine_side.ts';
 import { walkTimelines } from './timelines.ts';
 import { firstNonFinite, type PosedVertices, type WorldTransform } from './nonfinite.ts';
+import { environmentAt, type EnvironmentChange, type EnvironmentStep } from './environment.ts';
 
 // ---------------------------------------------------------------------------
 // the Spine side, through the seam (issue #1052)
@@ -211,6 +212,16 @@ export interface FramesSidecar {
   slots?: string[];
   /** The slots these frames leave out, when `render --hide` named them — see `slots`. */
   hidden?: string[];
+  /**
+   * The schedule the physics answered, when `render --environment` gave one
+   * (issue #1416) — its steps as read, each `{ t, wind?, gravity? }`.
+   *
+   * ⭐ Absent on a render without it, for `skin`'s reason: every frame set
+   * written before the field existed says the same. A frame set carrying it is
+   * a picture of the rig in a world `check` does not pose, so `check` refuses
+   * it as a reference by name.
+   */
+  environment?: EnvironmentStep[];
   /** The colour the frames were cleared to, straight RGBA 0..255. */
   background: RGBA;
   viewport: {
@@ -391,6 +402,19 @@ export interface PoseOptions {
    * second render writes.
    */
   unclipped?: boolean;
+  /**
+   * The world the physics answers, in time — `render --environment` (issue
+   * #1416, `./environment.ts`): each step's change set before the step that
+   * poses the first frame at or after its `t`, on the sampler's own frame grid,
+   * on whichever poser draws. Absent, nothing is set and every pose is the one
+   * it always was.
+   *
+   * ⭐ **It is part of the shot, so the framing reads it.** Unlike `slots` and
+   * `hidden`, which say which pixels are drawn of one pose, an environment
+   * changes the pose — a gust can carry a coat past the box a still rig fills —
+   * so `framingViewport` keeps it and the box holds what the frames draw.
+   */
+  environment?: readonly EnvironmentStep[];
 }
 
 /**
@@ -1025,8 +1049,10 @@ export interface Poser {
   /**
    * Animation `name` under `skin`, not looping: `visit(i, posed)` for every
    * `i` from 0 to `count`, the pose at `i/fps`. The caller has checked `name`.
+   * `environment(i)`, when given, is the change to the world the physics
+   * answers set before the step that poses frame `i` (issue #1416).
    */
-  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void): void;
+  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }
@@ -1091,7 +1117,12 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
   const count = Math.round(animation.duration * fps);
   const draw = drawResolver(poser, opts);
   const frames: Frame[] = [];
-  poser.animation(name, opts?.skin, fps, count, (i, posed) => frames.push(frameOf(i, i * step, posed, draw(), opts)));
+  const visit = (i: number, posed: Posed): void => {
+    frames.push(frameOf(i, i * step, posed, draw(), opts));
+  };
+  // Without an environment the call is the one it always was, so a poser that takes none is asked nothing new.
+  if (opts?.environment === undefined) poser.animation(name, opts?.skin, fps, count, visit);
+  else poser.animation(name, opts.skin, fps, count, visit, environmentAt(opts.environment, fps));
   return frames;
 }
 
@@ -1411,6 +1442,8 @@ export interface GeometryFile {
   /** The animation, or `null` for a skeleton with none (its one frame is the setup pose). */
   animation: string | null;
   skin?: string;
+  /** The schedule the physics answered (`render --environment`, issue #1416) — `frames.json`'s own `environment`; absent without it. */
+  environment?: EnvironmentStep[];
   fps: number;
   /** The box the PNG frames beside this file were drawn over — `frames.json`'s own `viewport`. */
   viewport: FramesSidecar['viewport'];
@@ -1470,6 +1503,7 @@ export function geometryFileOf(
   frames: Frame[],
   viewport: Viewport,
   skin: string | undefined,
+  environment?: EnvironmentStep[],
 ): GeometryFile {
   const geometryFrame = (frame: Frame, where: string): Omit<GeometryFrame, 'index' | 'time'> => {
     if (frame.bones === undefined || frame.attachments === undefined) {
@@ -1493,6 +1527,7 @@ export function geometryFileOf(
     coordinates: GEOMETRY_COORDINATES,
     animation,
     ...(skin === undefined ? {} : { skin }),
+    ...(environment === undefined ? {} : { environment }),
     fps,
     viewport: sidecarViewport(viewport),
     bones: poser.bones.map(({ name, parent }) => ({ name, parent })),

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,12 +767,86 @@ 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',
   },
 ];
 
+/** What `physicsStepStability` reads off one pose of a physics constraint. */
+export interface PhysicsStepStability {
+  /** `strength · massInverse · step²`, as the step's own products form it: `strength * (step * massInverse) * step`. */
+  readonly k: number;
+  /** The per-step velocity decay, `damping ** (60 * step)` — the runtime's own expression. */
+  readonly d: number;
+  /** `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` and `d < 1`, both strictly. */
+  readonly stable: boolean;
+}
+
+/**
+ * Whether one pose of a physics constraint integrates to rest or runs away
+ * (issue #1416, part B) — a joint condition on three of the four values
+ * `PHYSICS_POSE_RULES` bounds one at a time, and on the constraint's `step`.
+ *
+ * 🔑 Every substep of `stepPhysics` (`src/core/constraints_physics.ts`, held to
+ * spine-core's `PhysicsConstraint.update` at tolerance 0) is, on each driven
+ * component, `v += (force − offset·strength)·m; offset += v·step; v *= d` with
+ * `m = step · massInverse` and `d = damping ** (60·step)`. The force is
+ * 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)` 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
+ * it grows linearly.
+ *
+ * 📏 [measured, issue #1416's comment of 2026-10-14] on 270 generated rigs —
+ * x, y, rotate, scaleX and shearX drives; strength 10/100/1000; mass 0.1/1; fps
+ * 5/15/60; damping 0/0.85/1 — 115 of 115 with `k > bound` ran past 10⁶ units
+ * under a unit gust along the drive (92 of them in the runtime's default world
+ * with nothing set), 145 of 145 with `k < bound` stayed bounded, core and
+ * spine-core identical bit for bit. The 10 exactly on it (damping 1, k = 4)
+ * stayed under 10⁶ in the 6 s walk, which is why the 6 s classifier cannot
+ * stand for this edge: the x, y and scaleX ones ended the walk at their peak,
+ * still growing, and rotate and shearX swung their tip the bone's full length.
+ * All 270 passed every gate before this, because each value was inside its
+ * own row.
+ *
+ * The products are formed in the runtime's own order (`m = t * massInverse`,
+ * `d = damping ** (60 * t)`), so the number printed is the runtime's `k`
+ * rather than a re-association of it.
+ */
+export function physicsStepStability(strength: number, massInverse: number, damping: number, step: number): PhysicsStepStability {
+  const m = step * massInverse;
+  const k = strength * m * step;
+  const d = damping ** (60 * step);
+  const bound = 2 * (1 + d);
+  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 && d < 1 };
+}
+
 /**
  * What `A23`'s setup arm says about a pose value its rule refuses: the arm of
  * `outside` that holds for it, or the bound itself where the row has no arms or

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