spine-rigc 2.52.0 → 2.54.0

package/README.md

@@ -601,7 +601,7 @@ commands take it and what its default is.
 | `repack <dir> --out <dir> --keep-pages` | **`skeleton.model.json` alone, for the pages already in place** — for a player that reads the document beside an atlas and pages that already shipped. The same read and stage rules, then `build --atlas-in` over the input atlas in place of the lift and the pack; it writes the document, and nothing else, only after its `pages` are shown to state the atlas as it stands, the rebuilt skeleton byte-identical to the one on disk (so `spine.sha256` names it — no acceptance flag here) and the gate green. `--out` is usually the build's own directory and must not already hold a `skeleton.model.json`; a page or region line the document has no field for is refused by name ([AUTHORING §0.4](docs/AUTHORING.md)) |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles, their world box and their setup-pose area. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |

package/docs/AUTHORING.md

@@ -246,6 +246,7 @@ What the flags mean:
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
 | `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index, with their world box and setup-pose area. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
+| `--environment` | `render` only: the wind and gravity the rig's physics constraints answer, in time — a schedule file `{ "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`, x right and **y down**, each step holding from its `t` until the next. Both posers set each change before the step that poses the first frame at or after its `t`, and draw the same frames, `geometry.json` and `frames.json` (`RE01`). `frames.json` and `geometry.json` record it, and the framing reads it. A malformed file, a half no physics constraint answers, two steps on one frame and a step after every set's last frame are refused by name, exit 2, nothing written; `check` refuses a frame set drawn under one as a reference. Without it every file is the bytes it always was. An inspection of the response the rig states, not a scene — **§8.4** |
 | `--poser` | `render`, `inspect`, `check` and `explain`: `core` or `spine` — on `render`, `inspect` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`, `RC34`). On the entry that links none of spine-core — the installed `rigc` without the runtime beside it, `bun cli_core.ts` in a clone — that refusal ends on the route to the entry that does (``the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts` ``); a runtime that is installed and fails to load is refused without it, since installing it is not what that reader has to do. On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1), ending on the same route where the entry links none of it |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
@@ -3119,7 +3120,7 @@ beside it say how a distance becomes a share.
 | --- | --- |
 | `cell` | **required.** The lattice's square, in the part's pixels — a whole number of at least 1. No default: it is a length on this art, and how fine a mesh the part needs is not something rigc can read off it |
 | `bones` | **required, at least one entry.** Which segments may pull the part. An entry is one of three forms, below |
-| `falloff` | **required**, because `radius` is: `{ "power"?, "radius", "maxBones"?, "minWeight"? }` |
+| `falloff` | **required unless `influence` is stated**, because `radius` is: `{ "power"?, "radius", "maxBones"?, "minWeight"? }`. Stated beside `influence`, refused — the two are two models of one share |
 | `radius` | **required.** Added to every distance before the power is taken, in the part's pixels, so a vertex ON a segment has a finite pull and the blend between two segments is about this wide. Positive |
 | `power` | the exponent a pull falls off by: `w = 1 / (d + radius)^power`. Positive. Default `2` |
 | `maxBones` | at most this many bones pull one vertex — the strongest ones. A whole number of at least 1. Default `4` |
@@ -3127,6 +3128,8 @@ beside it say how a distance becomes a share.
 | `alpha` | the alpha at or above which a pixel counts as art, `1`..`255`. Default `1` — `contour`'s own |
 | `anchor` | where the **slot bone** sits in the part's pixels, `[x, y]`, y down. Default the window's centre — the placement every generator on this route uses (the ⭐ above). State it when the art is not drawn centred on its bone: unlike a pinned generator, this one's weights depend on where the art is relative to the bones |
 
+| `influence` | instead of `falloff`: a pull that **reaches zero** at its own `radius` — `{ "radius", "across", "max", "shape" }`, every field required. Below |
+
 **The three forms of a `bones` entry**, each resolved by name against the rig:
 
 | Entry | Its segment(s) |
@@ -3154,6 +3157,70 @@ of each segment, the strongest `maxBones` kept and normalised, any share under
 `minWeight` dropped, the rest normalised again — so every vertex closes at 1 by
 construction. The emitted mesh is a weighted one, bound by name.
 
+##### `influence` — a vertex follows every link near it (cloth)
+
+`falloff`'s pull, `1 / (d + radius)^power`, is positive at **every** distance: a
+wider blend needs a larger `radius`, which flattens the blend everywhere at once,
+and a blend only ends where `minWeight` drops a share. A cloth surface wants the
+other model — each vertex blends the springs of the chains around it, so the
+sheet bends as one surface rather than as strips — and that needs a pull that
+falls to **exactly zero** at a stated distance. `influence` is that model.
+
+```json
+"generator": {
+  "kind": "segments",
+  "cell": 8,
+  "bones": [["skirt_0_0", "skirt_0_1", "skirt_0_2"], ["skirt_1_0", "skirt_1_1", "skirt_1_2"]],
+  "influence": { "radius": 40, "across": true, "max": 6, "shape": "smooth" }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `radius` | **required.** How far a link reaches, in the part's pixels (on this route, the skeleton's units): a link whose segment is `radius` or farther from a vertex never pulls it. Positive. No default — a length on this art |
+| `across` | **required.** `true`: every link of every `bones` entry within `radius` pulls. `false`: only the links of **one** entry — the entry holding the link nearest the vertex, the earlier entry on a tie — so a chain moves its own strip and nothing across. No default: whether a chain may pull its neighbour's cloth is the decision |
+| `max` | **required.** At most this many links pull one vertex — the strongest; equal pulls keep the order `bones` first names their bones. A whole number of at least 1 |
+| `shape` | **required.** How a pull falls from 1 at `d = 0` to 0 at `d = radius`, with `x = d / radius`: `"linear"` is `1 - x`; `"smooth"` is `1 - x²(3 - 2x)`, which also arrives at both ends with zero slope, so a link enters and leaves a vertex's blend without a crease |
+
+Per vertex, in order: `d` is the distance to each link's **segment** — its
+nearest point, the reading `falloff` takes — at the setup pose; with `across:
+false` only the nearest entry's links stay; each link with `d < radius` pulls
+`shape(d / radius)` (a bone two segments name keeps the nearer, and a link whose
+pull is not above 0 in doubles — a hair inside the reach — pulls nothing); the
+strongest `max` are kept and normalised; a share the 6-decimal grid would write
+as 0 is dropped and the rest normalised again; the strongest closes the vertex
+at exactly 1. **The distance is to the segment, not to the bone's origin**,
+because a vertex on the middle of a link *is* on that link: an origin distance
+would put it half a link away, and hand the joint at the link's tip to the child
+whose origin sits there.
+
+🔸 **One bone order by construction.** Every vertex lists its bones in the order
+`bones` names them, so the attachment has one order and
+`A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER` holds without the compiler's
+ascending rewrite (§5.2) moving a byte — the order in the file is the spec's.
+
+`build` prints a `reach` line under the `influence` line: the block as stated,
+how many vertices had **more links in reach than `max`** — the vertices the cap
+dropped a link from — and the most links in reach at one vertex (`widest`),
+which is the `max` that would drop none:
+
+```
+        influence  max 6 bone(s) per vertex, mean 4.87, 0 of 450 vertices (0.00%) on a single bone
+        reach      radius 40px, smooth, across entries, max 6: 146 of 450 vertices had more links in reach than max (widest 10)
+```
+
+⚠️ **What a tight cap costs, measured.** On the selftest's `skirt_probe`
+(`fixtures/public.ts`: six chains of five links, a physics constraint on every
+link, the hip swayed) with `radius: 40`, `rotate` physics on and `render --folds`
+at 30 fps, `max: 2` turned 106 of the 816 triangles over on its worst frame and
+`max: 6` turned 4; `max: 6` with `radius: 20` (no vertex capped) turned 105, and
+`across: false` 91. With the physics removed the same sway folds none at either
+cap. So on that piece the folds followed how many neighbouring links a vertex
+blends — a narrow reach and a tight cap over a wide reach both fold — and a
+wide reach with a cap that drops few links folded least. One piece and one
+sway: it says what to look at with `render --folds` on your own, not what `max`
+your cloth needs.
+
 `build` and `explain` print what it measured, under the mesh's line. This is
 the selftest's own `segments_probe` (`fixtures/public.ts` in the repository) —
 one 96x64 plate of two islands under two two-link chains, `cell: 8`,
@@ -3199,6 +3266,9 @@ rows.
 | a chain link at its next link's origin | `… the two bones share their setup origin (…), so the link has no length and no direction to weight along` |
 | an empty chain, a span with a malformed end, an entry of none of the three forms | `is an empty chain`; `both ends are [x, y] in the part's pixels`; `an entry is a bone name, a chain as a list of bone names, or { "bone", "from", "to" }` |
 | no `falloff`, a `radius` or `power` at or below 0, a malformed `anchor`, a `cell` under 1, no `image` | each named by its field — `radius` has no default because it is a length on this art |
+| both `falloff` and `influence` | `the "segments" generator states both "falloff" and "influence" … a mesh is weighted by one of them: remove the other` |
+| an `influence` field absent or out of range — `radius` at or below 0, `across` not a boolean, `max` not a whole number of at least 1, `shape` not `"linear"` or `"smooth"` | each named with the value found and the one required: `"influence.max" is 0; it is how many links may pull one vertex …`, `"influence.shape" is "cubic"; one of "linear", "smooth" …` |
+| a vertex no link reaches under `influence` | `vertex 0, at (0, 0) in the part's pixels, is reached by no link — the nearest is "skirt_0_0" at 17.8885, and "influence.radius" is 4` — **refused, not handed the nearest link**: raise `radius` over that distance, or name a segment nearer that part of the art |
 | a part on a packed page that declares a `scale:` | refused: `cell` and `radius` are the part's pixels and this generator does not convert them to a page's texels. Build from the loose part, or a pack at scale 1 |
 
 #### 3.4.8 A skin that switches bones and constraints on
@@ -4931,6 +5001,35 @@ file can be read; it is a **key** outside its bound that `build` refuses (§4.4)
 number: a non-number would reach the file as `null`, which the runtime reads as
 **zero**, so `"mass": "heavy"` would ship a constraint that never settles.
 
+🧮 **Each value inside its bound is not enough: the step has to settle**
+(issue #1416). With `step = 1 / fps`, a constraint that drives anything must
+satisfy
+
+    strength · massInverse · step²  <  2 · (1 + damping^(60 · step))
+
+strictly, where `massInverse` is `1 / mass`. Each substep of the integrator is a
+linear map whose two eigenvalues lie inside the unit circle exactly then; at or
+past it the offset never dies out, and past it any push — wind, gravity, a key,
+the bone moving — grows without limit. [measured] on 270 generated rigs, all 115
+past the line ran past 10⁶ units under a unit gust (most with no gust at all),
+all 145 under it stayed bounded, and the 10 exactly on it were still growing or
+swinging their tip the bone's full length when a 6 s walk ended, spine-core
+identically — and every one of the 270 passed every gate before this clause.
+The runtime's defaults
+(`strength` 100, `mass` 1, `damping` 0.85) sit far under it at 60 fps (0.028
+against 3.70) and over it at `fps: 5` (4.00 against 2.28). `A23` refuses the
+setup values, and — for each animation that keys `strength`, `mass` or `damping`
+on the constraint — the largest strength, the lightest mass and the smallest
+damping that animation can pose, read together (a value the animation keys first
+after t = 0 includes the setup value, which is what plays before that key). That
+joint is an upper bound: an animation that raises strength and mass together is
+judged at its stiffest strength against its lightest mass. **To fix it, lower
+`strength`, raise `mass`, raise `fps` or raise `damping`** — the first three move
+the left side down, the last moves the right side up (a higher `damping` number
+keeps more velocity per step, yet it is what widens the bound: from 2 at `0` to
+4 at `1`); the refusal prints both sides so you can see how far each lever has
+to go.
+
 ⚠️ **What `rigc render` draws a spring with is not a player's clock to the bit.** A
 constraint integrates whole steps of `1 / fps` and shows the rest as a lag weight, so
 a frame lasting a whole number of steps (12, 20, 30 or 60 fps against the default
@@ -4977,6 +5076,10 @@ poses, to the bit (`CO56`). Two consequences an author has to know:
   value: that would make the export pose differently in the runtime than in
   the core.
 
+To look at the response before a player exists, `render --environment` (§8.4)
+draws the rig under a schedule of those same four numbers, on the core and on
+spine-core alike.
+
 Moving the rig is the consumer's too: `physicsTranslate(x, y)` and
 `physicsRotate(x, y, degrees)` on a live track are the runtime's methods of
 those names — the whole rig moved or turned since the last pose, in the
@@ -6632,7 +6735,7 @@ Fix A00 and run it again.
 | <a id="A20_MESH_WEIGHTS_COHERENT"></a>`A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. On a rig spec's `"boneIndexing": "raw"` mesh an index out of range or a run that does not decode is refused at compile first (§5.1, issue #917), so here it names a skeleton rigc did not compile. Under `rig-play` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not. Fix the rig spec's `controls`/`chain`, a `segments` generator's `bones` (its `influence` line names a bone no vertex binds), or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment |
 | <a id="A21_MESH_RIM_PINNED"></a>`A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, a ribbon's entry row, or a contour's outline (which is all of it) is not pinned to its anchor bone at weight 1. **SKIPs** by name on authored or linked geometry and on a `segments` mesh, whose outline is weighted by distance like the rest of it — none of them claims a pinned rim |
 | <a id="A22_MESH_UVS_IN_UNIT_RANGE"></a>`A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment |
-| <a id="A23_PHYSICS_CONSTRAINT_EFFECTIVE"></a>`A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | a physics constraint that drives no component, rests at `mix: 0` with **no timeline in any animation keying that `mix` above 0**, has `mass: 0`, has `strength` at or below 0 — `0` says `nothing pulls it back`, below 0 says the offset `is pushed away and grows with every step`, both read off the row's `outside` arms, which the key's refusal quotes too — or has `damping` outside `[0, 1]`, which says `` physics "C" has damping 1.5; must be inside [0, 1] — the per-step decay is `damping ** (60 * step)`, and the runtime runs this value finitely, so refusing it is rigc's call rather than the runtime's: above 1 every velocity grows on every step and the offset diverges ``, the bound read off the row the key's refusal reads; `1` and `0` are inside, since both are finite at every rate — **at rest, and on every physics timeline key**. The timeline arm reads each key through the runtime's own `PhysicsConstraint*Timeline.set`, so a keyed `mass` is judged as the `massInverse` it becomes, and the detail names the animation, the constraint, the key time, the value and the bound. Two differences between the two arms, and the runtime is the reason for both: a **key** of `mix: 0` is accepted, because `update` opens with `if (mix === 0) return;` and muting a constraint for a stretch is what a mix timeline is for — the editor's own `sack-pro` example keys it there on 24 of its 36 mix keys — and a **key** of `strength: 0` is accepted, because it releases the constraint for the span with `damping` and `inertia` still applied and the next key pulls the offset back, measured through spine-core at no NaN, a coast to a limit and a return in 54 steps. As a **setup** value `strength: 0` is still refused by the arm above, and `mix: 0` is refused only when nothing keys it above 0. The `mix` branch above is why `mix` is the one setup value a key can answer for: at rest the constraint is **inert** rather than broken, so a rig that rests muted and is keyed above 0 is refused by nothing, while a rig resting at `mass: 0` is `massInverse` Infinity before anything plays and no key reaches back into that. The detail of the refusal says both halves and how many animations were searched: `` physics "C" has mix 0 and none of the 3 animations keys its mix above 0; the runtime runs this value finitely, so refusing it is rigc's call rather than the runtime's: at 0 `update` returns before it does anything (`PhysicsConstraint.js:109-111`), so the constraint is muted — rest it above 0, or key its mix above 0 in an animation ``. ⚠️ Every reason A23 prints for a setup value is that value's row `basis` arm (§4.4's table) — an arithmetic arm names its expression (`physics "C" has massInverse Infinity; mass must be > 0 — at 0 …`), a behavioural one says it is rigc's call and what the value does. A setup `mix` **below** 0 is told the jiggle is applied inverted, not that it is muted: such a constraint is measured moving its bone by exactly the opposite of a positive mix. The search counts the unnamed global timeline for every constraint whose own `mixGlobal` is set, reads each key through the runtime's accessor, counts every sample of a Bezier between two keys as a value the timeline poses — so two keys of 0 joined by a curve lifted above 0 are a rescue, measured to move the bone — and takes an animation a slider applies like any other. It is the one reading `A36` and `A37` use as well. `inertia`, `wind`, `gravity` and the top of `mix` are bounded nowhere, at rest or keyed. `ingest` does not carry a constraint that drives no component into the spec it writes: it omits it with its timelines and reports `PHYSICS_DRIVES_NOTHING` ([INGEST §2.0](INGEST.md)), so this sentence is met on a file, never on a decompiled rebuild. 🦴 **A lever drive on a bone with no lever** (issue #1195): a constraint driving `rotate`, `shearX` or `scaleX` on a bone whose `length` is 0 (or states none) is refused, at rest, with one sentence per reading. `rotate` and `shearX` chase the bone's tip, so with no tip the solver aims the bone at a **world** direction — measured through rigc's poser on a chain held still for 3 s, a length-0 bone turns 53.204° from a 90° rest and holds there, where length 0.01 moves 0.0000: `` physics "C" drives rotate on bone "B" whose length is 0 — with no tip the solver aims the bone at world angle 0 and holds it there; give "B" a length or drive x/y instead ``. The rest angle is not read: a bone resting at world 0° does not move, but only until a key or a parent turns it. `scaleX` divides the motion along the bone by its length and adds nothing at 0, so the drive does nothing: `` physics "C" drives scaleX on bone "B" whose length is 0, which the solver divides the motion by, so it drives nothing; give "B" a length ``. Fix in the **rig spec**: give the bone its `length` (§3.2), measured off the art it carries, or, for the first sentence, drive the constraint in `x`/`y` in the **motion spec** instead. `x` and `y` read the bone's origin and never its tip, so a constraint driving only those on a length-0 bone is not refused; the editor's own example exports carry them there. The Spine editor's export drops `rotate`, `scaleX` and `shearX` from a physics constraint on a zero-length bone and keeps them on any bone with a length — measured on 4.3.23 and 4.3.26, issue #1196 — so what this clause refuses is also what the editor would silently lose. **SKIP** when the skeleton declares no physics constraint — the same sentence `A36` and `A37` print for their own constraint types |
+| <a id="A23_PHYSICS_CONSTRAINT_EFFECTIVE"></a>`A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | a physics constraint that drives no component, rests at `mix: 0` with **no timeline in any animation keying that `mix` above 0**, has `mass: 0`, has `strength` at or below 0 — `0` says `nothing pulls it back`, below 0 says the offset `is pushed away and grows with every step`, both read off the row's `outside` arms, which the key's refusal quotes too — or has `damping` outside `[0, 1]`, which says `` physics "C" has damping 1.5; must be inside [0, 1] — the per-step decay is `damping ** (60 * step)`, and the runtime runs this value finitely, so refusing it is rigc's call rather than the runtime's: above 1 every velocity grows on every step and the offset diverges ``, the bound read off the row the key's refusal reads; `1` and `0` are inside, since both are finite at every rate — **at rest, and on every physics timeline key**. The timeline arm reads each key through the runtime's own `PhysicsConstraint*Timeline.set`, so a keyed `mass` is judged as the `massInverse` it becomes, and the detail names the animation, the constraint, the key time, the value and the bound. Two differences between the two arms, and the runtime is the reason for both: a **key** of `mix: 0` is accepted, because `update` opens with `if (mix === 0) return;` and muting a constraint for a stretch is what a mix timeline is for — the editor's own `sack-pro` example keys it there on 24 of its 36 mix keys — and a **key** of `strength: 0` is accepted, because it releases the constraint for the span with `damping` and `inertia` still applied and the next key pulls the offset back, measured through spine-core at no NaN, a coast to a limit and a return in 54 steps. As a **setup** value `strength: 0` is still refused by the arm above, and `mix: 0` is refused only when nothing keys it above 0. The `mix` branch above is why `mix` is the one setup value a key can answer for: at rest the constraint is **inert** rather than broken, so a rig that rests muted and is keyed above 0 is refused by nothing, while a rig resting at `mass: 0` is `massInverse` Infinity before anything plays and no key reaches back into that. The detail of the refusal says both halves and how many animations were searched: `` physics "C" has mix 0 and none of the 3 animations keys its mix above 0; the runtime runs this value finitely, so refusing it is rigc's call rather than the runtime's: at 0 `update` returns before it does anything (`PhysicsConstraint.js:109-111`), so the constraint is muted — rest it above 0, or key its mix above 0 in an animation ``. ⚠️ Every reason A23 prints for a setup value is that value's row `basis` arm (§4.4's table) — an arithmetic arm names its expression (`physics "C" has massInverse Infinity; mass must be > 0 — at 0 …`), a behavioural one says it is rigc's call and what the value does. A setup `mix` **below** 0 is told the jiggle is applied inverted, not that it is muted: such a constraint is measured moving its bone by exactly the opposite of a positive mix. The search counts the unnamed global timeline for every constraint whose own `mixGlobal` is set, reads each key through the runtime's accessor, counts every sample of a Bezier between two keys as a value the timeline poses — so two keys of 0 joined by a curve lifted above 0 are a rescue, measured to move the bone — and takes an animation a slider applies like any other. It is the one reading `A36` and `A37` use as well. `inertia`, `wind`, `gravity` and the top of `mix` are bounded nowhere, at rest or keyed. `ingest` does not carry a constraint that drives no component into the spec it writes: it omits it with its timelines and reports `PHYSICS_DRIVES_NOTHING` ([INGEST §2.0](INGEST.md)), so this sentence is met on a file, never on a decompiled rebuild. 🦴 **A lever drive on a bone with no lever** (issue #1195): a constraint driving `rotate`, `shearX` or `scaleX` on a bone whose `length` is 0 (or states none) is refused, at rest, with one sentence per reading. `rotate` and `shearX` chase the bone's tip, so with no tip the solver aims the bone at a **world** direction — measured through rigc's poser on a chain held still for 3 s, a length-0 bone turns 53.204° from a 90° rest and holds there, where length 0.01 moves 0.0000: `` physics "C" drives rotate on bone "B" whose length is 0 — with no tip the solver aims the bone at world angle 0 and holds it there; give "B" a length or drive x/y instead ``. The rest angle is not read: a bone resting at world 0° does not move, but only until a key or a parent turns it. `scaleX` divides the motion along the bone by its length and adds nothing at 0, so the drive does nothing: `` physics "C" drives scaleX on bone "B" whose length is 0, which the solver divides the motion by, so it drives nothing; give "B" a length ``. Fix in the **rig spec**: give the bone its `length` (§3.2), measured off the art it carries, or, for the first sentence, drive the constraint in `x`/`y` in the **motion spec** instead. `x` and `y` read the bone's origin and never its tip, so a constraint driving only those on a length-0 bone is not refused; the editor's own example exports carry them there. The Spine editor's export drops `rotate`, `scaleX` and `shearX` from a physics constraint on a zero-length bone and keeps them on any bone with a length — measured on 4.3.23 and 4.3.26, issue #1196 — so what this clause refuses is also what the editor would silently lose. 🧮 **A step that does not settle** (issue #1416): a constraint that drives anything, every value inside its own row, is refused when `strength·massInverse·step² ≥ 2·(1 + damping^(60·step))` with `step = 1 / fps` — the integrator's step map then has an eigenvalue on or outside the unit circle, and [measured] of 270 generated rigs, all 115 past the bound ran past 10⁶ units under a unit gust, all 145 under it stayed bounded, and the 10 exactly on it were still growing or swinging their tip the bone's full length when a 6 s walk ended. It reads the setup values, and for each animation keying `strength`, `mass` or `damping` on the constraint, the stiffest strength, the lightest mass and the smallest damping that animation poses (each key, each Bézier sample, and the setup value where the animation keys that value first after t = 0), judged together — an upper bound on any pose the animation reaches. Both sides are formed in the runtime's own order (`m = step · massInverse`, `damping ** (60 · step)`) and printed apart: `` physics "C" has strength 100, mass 1 (massInverse 1), fps 5, damping 0.85 — strength·massInverse·step² = 4.0000 must be < 2·(1 + damping^(60·step)) = 2.2845: at or past that bound the step stops settling — one step can multiply the offset by 2.807 every 1/5 s — so a push (wind, gravity, a key, the bone moving) never dies out, and past the bound it grows without limit; lower strength, raise mass, raise fps or raise damping ``; a keyed combination opens `` animation "A" can pose physics "C" at strength … `` and names the key each value came from. Fix in the **motion spec**'s physics table or its keys (§4.6). **SKIP** when the skeleton declares no physics constraint — the same sentence `A36` and `A37` print for their own constraint types |
 | <a id="A24_AXIS_SPACE_STROKE"></a>`A24_AXIS_SPACE_STROKE` | archetype | a bone under the rig's `axisBone` was keyed with a screen-space Y component, or the axis bone itself was keyed. **SKIP** when the rig declares no axis bone, and also when no animation keys that bone or anything under it |
 | <a id="A25_DETACHED_BONE_PARENTAGE"></a>`A25_DETACHED_BONE_PARENTAGE` | archetype | a bone the rig declares `detached` is a descendant of the bone it must never hang under |
 | <a id="A26_SLOT_DRAW_ORDER"></a>`A26_SLOT_DRAW_ORDER` | archetype | the emitted slots are not the rig's slot table — a slot is out of order, is not in the table at all, or is in the table and missing from the skeleton (§3.3). **SKIP** when the rig declares no canonical slot order. ⚠️ A skeleton with **no** slot beside a rig that declares some is **not** a skip, and it is the one rule in this family where an empty loop is not a vacuous pass: the completeness clause reads it as every declared slot lost and names them |
@@ -7487,6 +7590,100 @@ worst frame framed to it:
 fills the folded triangles at that pose, frames the picture to their box, and lists
 them with the same box and area in its legend (§13).
 
+### 8.4 The world the physics answers — `render --environment`
+
+A physics constraint's `wind` and `gravity` are its **response** (§4.6); the world
+it responds to — the two directions spine-core keeps on its `Skeleton` — belongs to
+whoever plays the rig. A render has no player, so without this flag it draws every
+frame in the runtime's initial world, wind `[1, 0]` and gravity `[0, 1]`.
+`--environment` hands it one:
+
+```bash
+bun cli.ts render --candidate path/to/spine --environment gust.json [--animation …] [--geometry] [--poser core|spine]
+```
+
+```json
+{
+  "spec": "rigc-environment/1",
+  "steps": [
+    { "t": 0, "wind": [0, 0] },
+    { "t": 1, "wind": [1.5, -0.4] },
+    { "t": 2, "wind": [0, 0] }
+  ]
+}
+```
+
+**What a step means.** From its `t`, in seconds, until the next step, the world is
+changed by the halves it states — `wind`, `gravity`, or both — and a half it leaves
+out keeps the one standing, as a live track's `setEnvironment` keeps it. Both are
+the runtime's own fields in the runtime's convention: x to the right, **y down** (a
+positive y pulls toward the bottom of the frame, as gravity `[0, 1]` does). Before
+the first step the world is the runtime's initial one, so a calm start is stated —
+`"wind": [0, 0]` at `t` 0 — rather than assumed. Each set starts the schedule at its
+own frame 0.
+
+**When it lands.** A step's change is set before the step that poses the first
+frame `i` whose time `i / fps` is at or after its `t`, so the physics integrates the
+new world over that frame's whole interval and the frame before it is untouched.
+Frame 0 is the reset pose; a step at `t` 0 is set before it. A `t` that is a frame's
+own time — `k / fps` — lands on frame `k`.
+
+**Both posers, one world.** The core sets each change on its physics before the
+walk's step; spine-core's poser sets the same values on its `Skeleton` (`windX,
+windY, gravityX, gravityY`) before the same update. The repository's selftest
+renders three rigs — one answering wind and gravity on every branch of the physics
+step, gallery/look with its whip answering wind, and a fixture answering gravity
+alone — under a calm → gust → calm schedule through both, and holds every PNG,
+`geometry.json` and `frames.json` equal (`RE01`); holds that the gust moves the rig
+from its own frame and no earlier (`RE02`); and plants on the core the readings the
+mapping rejects — the schedule ignored, its y read up, each change a frame late or
+early — each red against spine-core (`RE03`).
+
+**The files.** `frames.json` and each `geometry.json` record the schedule as
+`environment`, its steps as read, `t`, `wind`, `gravity` in that order. The
+framing reads it too: a gust can carry a coat past the box a still rig fills, so
+the box is the box of what the frames under the schedule draw — and the grid can
+differ from the same render without the flag. Compare the two in world units, in
+`geometry.json`. Without the flag nothing is set and every file is the bytes it
+always was; the runtime's own world stated at `t` 0 draws the same pixels and
+geometry as no flag at all (`RE04`). `check` poses its candidate in no world but
+the runtime's, so a frame set drawn under a schedule is refused as a reference by
+name rather than scored.
+
+**Refused by name**, exit 2, nothing written — each is a render that would print a
+plausible frame set showing nothing the schedule asked for (`RE05`):
+
+- a path with nothing at it: `--environment <path>: nothing at <abs path>`;
+- a file that is not one: `not JSON — …`, `the file holds <what>, not an object …`,
+  `"spec" is <found>; render reads "rigc-environment/1"`, `the file names "<key>",
+  which is not one of [spec, steps]`, `"steps" is <found>, not a non-empty array …`;
+- an entry, by its index: `entry <i> of "steps" names "<key>", which is not one of
+  [t, wind, gravity]`; `…'s "t" is <found>, not a finite time in seconds at or above
+  0`; `…'s "t" is <found>, not after entry <i-1>'s <t> — steps are listed in
+  ascending time, each holding until the next`; `…'s "wind" is <found>, not a pair
+  of finite numbers [x, y] (x to the right, y down)` (`gravity` alike; a number the
+  JSON reader makes infinite, `1e999`, is shown as `Infinity`); `… states neither
+  "wind" nor "gravity", so it changes nothing`;
+- a schedule this rig would not draw: a skeleton with no animation (its one frame
+  is the setup pose, where no physics step runs) or no physics constraint; a half
+  the schedule changes that no physics constraint answers — `entry <i> changes
+  wind, and no physics constraint answers it — [<names>] each state wind 0 and no
+  animation keys it`; two steps on one frame of the render's grid —
+  `entries [<i>, <j>] (t …) land on one frame at <fps> fps — frame <k>, t=…s — so
+  entry <i> would never be posed`; and a step after the last frame of every set
+  drawn.
+
+**What it is, and what it is not.** It is an inspection of the response the rig
+states — what the Spine export carries, posed in a world you chose, on either
+poser. It is not a scene: when a gust blows, how strong, and what else moves is the
+consumer's to compose, and a schedule here is a probe of the object, not a
+direction of it. Moving the rig is left out on purpose: `physicsTranslate` and
+`physicsRotate` are a displacement since the last pose, which a step held over a
+span would have to restate as a velocity — a second meaning the live track does
+not have — and a render draws the rig where it stands, so the picture would show
+a coat trailing a rig that never moves. The live track holds both to spine-core
+(`CO56`), and a player forwards them as §4.6 says.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.52.0",
+  "version": "2.54.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/assertions/bodies/a23.ts

@@ -24,7 +24,9 @@ import {
   physicsKeyRefusal,
   physicsOutsideSays,
   physicsRuleFor,
+  physicsStepStability,
   type PhysicsPoseRule,
+  type PhysicsStepStability,
 } from '../../timelines.ts';
 
 /**
@@ -165,6 +167,9 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
     });
   }
   let mutedUntilKeyed = 0;
+  // Each constraint whose setup values the stability clause read, by position — the
+  // floor every animation's combination is taken from below.
+  const setupCombos = new Map<number, StabilityCombo>();
   facts.constraints.forEach((constraint, index) => {
     const physics = constraint.physics;
     if (physics === undefined) return;
@@ -245,6 +250,24 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
     if (physics.step <= 0 || !Number.isFinite(physics.step)) {
       fail('A23_PHYSICS_CONSTRAINT_EFFECTIVE', `${where} has step ${physics.step} (fps must be > 0)`);
     }
+    // --- the step itself has to settle (issue #1416, part B) ------------------
+    //
+    // The rows above judge each value against its own interval; this is the one
+    // joint condition, `physicsStepStability`'s. It is read only where the rows
+    // it combines all hold — a value its own row refuses is named there, and a
+    // second line about the same number would be the same fault twice — and
+    // only on a constraint that drives something, which the first clause names
+    // otherwise.
+    if (components.length && stableInputs(pose, physics.step)) {
+      const setupCombo: StabilityCombo = {
+        strength: { value: pose.strength, from: 'setup' },
+        massInverse: { value: pose.massInverse, from: 'setup' },
+        damping: { value: pose.damping, from: 'setup' },
+      };
+      const at = physicsStepStability(pose.strength, pose.massInverse, pose.damping, physics.step);
+      if (!at.stable) fail('A23_PHYSICS_CONSTRAINT_EFFECTIVE', `${where} has ${runawaySays(setupCombo, physics.step, at)}`);
+      setupCombos.set(index, setupCombo);
+    }
   });
   // What the PASS would otherwise not say: this rig rests with physics off
   // on that many constraints and an animation is what switches them on. A
@@ -302,4 +325,155 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
     }
   }
   stats.physicsTimelineKeys = keysRead;
+
+  // --- the step has to settle on every pose an animation reaches (#1416) ----
+  //
+  // 🔑 **Which combinations are read.** Per animation and per constraint its
+  // `strength`, `mass` or `damping` timelines reach (a named one, or each a
+  // global one reaches): the LARGEST strength, the LARGEST massInverse and the
+  // SMALLEST damping that animation can pose on that constraint, judged
+  // together. A value's candidates are every key and every Bézier sample of
+  // every such timeline, as the pose field it lands in (`posed`) — and the
+  // setup value as well wherever the animation keys that value not at all, or
+  // keys it first after t = 0, because before its first key a timeline poses the
+  // setup value. Each extreme is exact for its own value: the runtime moves
+  // a value linearly between those points, `massInverse` is monotone in the
+  // mass it inverts, and the bound is monotone in damping.
+  //
+  // ⚠️ The JOINT is an upper bound rather than a time-aligned pose: an
+  // animation that raises strength while it raises mass, so the ratio holds,
+  // is judged at the larger strength against the smaller mass. That is the
+  // conservative direction — no pose this animation reaches is less stable
+  // than the combination read — and it was chosen over evaluating the three
+  // curves at shared times because the facts carry each curve's values and
+  // not its sample times, and because a single held key crossing the bound is
+  // already a runaway. A line names which key or setup supplied each value, so
+  // a refusal of that kind says so.
+  //
+  // A combination equal to the setup's is not repeated: the setup line names
+  // it already. A value its own row refuses is left out of the extremes — it
+  // was named above, by its key.
+  const keyed = new Map<string, Map<number, Partial<Record<StabilityWord, Candidate[]>>>>();
+  for (const timeline of facts.timelines) {
+    if (timeline.kind !== 'physics' || !isStabilityWord(timeline.word)) continue;
+    const rule = physicsRuleFor(timeline.word);
+    if (rule === undefined) continue;
+    const word = timeline.word;
+    const values = timeline.channelValues(0);
+    const firstTime = timeline.frames[0]?.time ?? 0;
+    const candidates: Candidate[] = [];
+    // `channelValues` lists each key and then the Bézier samples of the segment
+    // it opens, so the next key's value is that key and anything else is the
+    // curve leaving the key before it.
+    let next = 0;
+    for (const value of values) {
+      const frame = timeline.frames[next];
+      const isKey = frame !== undefined && frame.value === value;
+      if (isKey) next++;
+      const posedValue = timeline.posed === undefined ? rule.toPose(value) : timeline.posed(value);
+      if (physicsKeyRefusal(rule, value, posedValue) !== null) continue;
+      candidates.push({
+        value: posedValue,
+        from: isKey ? `the key at t=${frame.time.toFixed(6)}s` : `the curve after the key at t=${(timeline.frames[next - 1]?.time ?? 0).toFixed(6)}s`,
+      });
+    }
+    const byConstraint = keyed.get(timeline.animation) ?? new Map<number, Partial<Record<StabilityWord, Candidate[]>>>();
+    keyed.set(timeline.animation, byConstraint);
+    for (const index of timeline.reach) {
+      const setup = setupCombos.get(index);
+      if (setup === undefined) continue;
+      const slot = byConstraint.get(index) ?? {};
+      byConstraint.set(index, slot);
+      const list = slot[word] ?? [];
+      list.push(...candidates);
+      // Before the first key the timeline poses the setup value.
+      if (firstTime > 0) list.push(setup[STABILITY_FIELD[word]]);
+      slot[word] = list;
+    }
+  }
+  for (const [animation, byConstraint] of keyed) {
+    for (const [index, slot] of byConstraint) {
+      const setup = setupCombos.get(index);
+      const physics = facts.constraints[index]?.physics;
+      if (setup === undefined || physics === undefined) continue;
+      const pick = (word: StabilityWord, worse: (a: number, b: number) => boolean): Candidate => {
+        const list = slot[word];
+        // A value this animation never keys, or keys only with values refused above, stays at setup.
+        if (list === undefined || list.length === 0) return setup[STABILITY_FIELD[word]];
+        return list.reduce((best, one) => (worse(one.value, best.value) ? one : best));
+      };
+      const combo: StabilityCombo = {
+        strength: pick('strength', (a, b) => a > b),
+        massInverse: pick('mass', (a, b) => a > b),
+        damping: pick('damping', (a, b) => a < b),
+      };
+      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;
+      fail(
+        'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
+        `animation "${animation}" can pose physics "${facts.constraints[index]?.name ?? `#${index}`}" at ${runawaySays(combo, physics.step, at)}`,
+      );
+    }
+  }
+}
+
+/** The three timelines whose values the stability clause combines. */
+type StabilityWord = 'strength' | 'mass' | 'damping';
+const STABILITY_FIELD: Record<StabilityWord, keyof StabilityCombo> = { strength: 'strength', mass: 'massInverse', damping: 'damping' };
+function isStabilityWord(word: string): word is StabilityWord {
+  return word === 'strength' || word === 'mass' || word === 'damping';
+}
+
+/** One value the stability clause read, and where it came from: `setup`, or a key or curve of the animation. */
+interface Candidate {
+  readonly value: number;
+  readonly from: string;
+}
+
+/** The three pose values the stability clause judges together. */
+interface StabilityCombo {
+  readonly strength: Candidate;
+  readonly massInverse: Candidate;
+  readonly damping: Candidate;
+}
+
+/** Whether every value the stability clause combines is inside its own row, so the joint condition is the only one left to read. */
+function stableInputs(pose: PhysicsSetup, step: number): boolean {
+  if (!(step > 0) || !Number.isFinite(step)) return false;
+  return PHYSICS_POSE_RULES.every((rule) => rule.timeline === 'mix' || rule.poseOk(pose[rule.field]));
+}
+
+/** A number as an author typed it: `1 / (1 / 45)` prints 45 rather than its last-bit neighbour. */
+function plain(value: number): string {
+  return String(Number(value.toPrecision(12)));
+}
+
+/**
+ * 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.
+ */
+function runawaySays(combo: StabilityCombo, step: number, at: PhysicsStepStability): string {
+  const src = (c: Candidate): string => (c.from === 'setup' ? '' : ` (${c.from})`);
+  const fps = plain(1 / step);
+  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)}, ` +
+    `fps ${fps}, damping ${combo.damping.value}${src(combo.damping)} — strength·massInverse·step² = ${at.k.toFixed(places)} must be < ` +
+    `2·(1 + damping^(60·step)) = ${at.bound.toFixed(places)}: at or past that bound the step stops settling — one step can ` +
+    `multiply the offset by ${at.growth.toFixed(apart(at.growth, 1, 3))} every 1/${fps} s — so a push (wind, gravity, a key, the ` +
+    'bone moving) never dies out, and past the bound it grows without limit; lower strength, raise mass, raise fps or raise damping'
+  );
+}
+
+/**
+ * The fewest decimal places, from `min`, at which `a` and `b` print apart — so
+ * a value one part in 10⁹ past the bound does not print as equal to it. Two
+ * equal numbers print at `min`.
+ */
+function apart(a: number, b: number, min: number): number {
+  if (a === b) return min;
+  for (let places = min; places < 17; places++) if (a.toFixed(places) !== b.toFixed(places)) return places;
+  return 17;
 }

package/src/check.ts

@@ -1286,6 +1286,18 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         `${options.skin === undefined ? 'with no --skin' : `with --skin ${JSON.stringify(options.skin)}`}.`,
     );
   }
+  // A frame set drawn under `render --environment` (issue #1416) is a picture of the rig in a world `check` does not
+  // pose: it poses the candidate under the runtime's own wind and gravity, so the score would be a number about the
+  // difference between two worlds. Refused by name, as a subset is, rather than scored.
+  const referenceEnvironment = located.sidecar?.environment;
+  if (referenceEnvironment !== undefined) {
+    throw new CheckError(
+      `${FRAMES_SIDECAR} records that these frames were rendered under an environment schedule (\`rigc render ` +
+        `--environment\`, ${Array.isArray(referenceEnvironment) ? referenceEnvironment.length : 0} step(s)), and check poses the candidate ` +
+        "under none — the runtime's own wind [1, 0] and gravity [0, 1] — so the comparison would be a number about the " +
+        'difference between two worlds. Render the reference frames without --environment.',
+    );
+  }
   if (referenceSkin === null && options.skin !== undefined) {
     notes.push(
       `the candidate is posed under skin ${JSON.stringify(options.skin)} and the reference frames record no skin ` +