spine-rigc 2.53.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 |
@@ -5000,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
@@ -5046,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
@@ -6701,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 |
@@ -7556,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.53.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 ` +

package/src/cli/core_commands.ts

@@ -32,6 +32,7 @@ import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
 import { type InspectCompare, type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readBonePatterns, readShow, readTimes, readZoom } from '../inspect.ts';
 import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine } from '../folds.ts';
+import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
@@ -472,6 +473,72 @@ function readPositiveNumber(flags: Record<string, string>, key: string, fallback
   return value;
 }
 
+/**
+ * `--environment <schedule.json>` read (issue #1416, `../environment.ts`), or
+ * refused as a usage error before anything is read off the candidate: a path
+ * with nothing at it, a file that is not a schedule, and every malformed entry,
+ * by its index, its field, the value found and what is required.
+ */
+function readEnvironmentFlag(flags: Record<string, string>): { path: string; steps: EnvironmentStep[] } | undefined {
+  const given = flags.environment;
+  if (given === undefined) return undefined;
+  const path = resolve(given);
+  if (!existsSync(path) || !statSync(path).isFile()) throw new UsageError(`--environment ${given}: nothing at ${path} — it takes a schedule file { "spec": "rigc-environment/1", "steps": [...] }`);
+  try {
+    return { path, steps: readEnvironmentSchedule(readFileSync(path, 'utf8'), given) };
+  } catch (err) {
+    if (err instanceof EnvironmentError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
+/**
+ * The refusals of a well-formed schedule that this candidate, at this rate,
+ * would quietly not draw (issue #1416) — each one a render that would print a
+ * plausible frame set showing nothing the schedule asked for:
+ *
+ * - a skeleton with no animation, whose one frame is the setup pose, where no
+ *   physics step runs;
+ * - a half the schedule changes that no physics constraint answers — none
+ *   states it non-zero and no animation keys it — so every frame would draw as
+ *   without the flag;
+ * - two steps on one frame of the render's grid, the first never posed;
+ * - a step after the last frame of every set drawn.
+ *
+ * `durations` are the poser's, of the sets this run draws.
+ */
+function environmentRefusal(given: string, steps: readonly EnvironmentStep[], skeletonText: string, fps: number, durations: ReadonlyArray<{ name: string; duration: number }>): string | null {
+  if (durations.length === 0) return `--environment ${given}: the skeleton has no animation — its one frame is the setup pose, where no physics step runs, so no environment moves it`;
+  const response = environmentResponse(skeletonText);
+  if (response.declared.length === 0) return `--environment ${given}: the skeleton declares no physics constraint, so no environment moves anything in it`;
+  for (const half of ['wind', 'gravity'] as const) {
+    const changing = steps.map((step, i) => (step[half] === undefined ? -1 : i)).filter((i) => i >= 0);
+    if (changing.length > 0 && response[half].length === 0) {
+      return (
+        `--environment ${given}: entry ${changing[0]} changes ${half}, and no physics constraint answers it — [${response.declared.map((n) => JSON.stringify(n)).join(', ')}] each state ${half} 0 and no animation keys it — ` +
+        `so every frame would draw as it does without the schedule. A constraint's own ${half} is its response (AUTHORING §4.6)`
+      );
+    }
+  }
+  const collision = environmentCollisions(steps, fps)[0];
+  if (collision !== undefined) {
+    return (
+      `--environment ${given}: entries [${collision.entries.join(', ')}] (t ${collision.entries.map((i) => steps[i].t).join(', ')}) land on one frame at ${fps} fps — frame ${collision.frame}, ` +
+      `t=${(collision.frame / fps).toFixed(4)}s — so entry ${collision.entries[0]} would never be posed. Raise --fps, or merge them`
+    );
+  }
+  const lastFrames = durations.map(({ name, duration }) => ({ name, last: Math.round(duration * fps) }));
+  const longest = lastFrames.reduce((a, b) => (b.last > a.last ? b : a));
+  const late = steps.findIndex((step) => environmentFrame(step.t, fps) > longest.last);
+  if (late >= 0) {
+    return (
+      `--environment ${given}: entry ${late}'s t ${steps[late].t} falls after the last frame of every set drawn — the longest, "${longest.name}", ends at frame ${longest.last}, ` +
+      `t=${(longest.last / fps).toFixed(4)}s at ${fps} fps — so it would change nothing`
+    );
+  }
+  return null;
+}
+
 /**
  * render — the frame series, drawn by the same rasteriser `check` measures with.
  *
@@ -487,6 +554,8 @@ export function cmdRender(flags: Record<string, string>): void {
   const { skeletonPath, atlasPath, atlasText } = resolveDrawable(flags.candidate, flags.atlas);
   const atlasDir = dirname(atlasPath);
   const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
+  // Read before anything is read off the candidate, so a malformed schedule is refused before a line is printed.
+  const environment = readEnvironmentFlag(flags);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
@@ -532,8 +601,9 @@ export function cmdRender(flags: Record<string, string>): void {
   // core poses — `skeleton.model.json` beside the pair — reads its names, its
   // subset roster and its pages without loading spine-core at all, and with a
   // rigc-compiled/2 document without its atlas either (issue #1020).
+  const skeletonText = readSkeletonText(skeletonPath);
   const { choice, facts, pages } = loadCandidate(
-    { skeletonText: readSkeletonText(skeletonPath), atlasText, atlasDir, label: skeletonPath },
+    { skeletonText, atlasText, atlasDir, label: skeletonPath },
     { skeleton: skeletonPath, atlas: atlasPath },
     posersAsked(flags),
   );
@@ -546,12 +616,17 @@ export function cmdRender(flags: Record<string, string>): void {
   // `src/render.ts` has one of its own. The inferred shape is the render one.
   // The subset rides on the same object and `framingViewport` takes it off, so
   // the frames draw the subset and the box is still the whole rig's.
+  // The environment rides on the same object for the same reason (issue #1416): the framing reads it, so the box holds
+  // what the frames under it draw.
   const pose =
-    skin === undefined && subset === undefined
+    skin === undefined && subset === undefined && environment === undefined
       ? undefined
-      : { ...(skin === undefined ? {} : { skin }), ...subsetFields(subset) };
+      : { ...(skin === undefined ? {} : { skin }), ...subsetFields(subset), ...(environment === undefined ? {} : { environment: environment.steps }) };
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
+  if (environment !== undefined && facts.animations.length === 0) {
+    throw new UsageError(environmentRefusal(flags.environment, environment.steps, skeletonText, fps, []) ?? '');
+  }
 
   // Rigc's own core when the candidate is a rigc build, and spine-core
   // otherwise, or where the core refuses the input by name. Never silently:
@@ -565,6 +640,13 @@ export function cmdRender(flags: Record<string, string>): void {
   // re-poses the whole input on spine-core rather than leaving half of a frame
   // set drawn by each.
   const posed = throughPoser(choice, (poser, roster) => {
+    // A schedule this candidate would not draw is refused before anything is posed, off the durations of the poser that
+    // poses it (issue #1416) — a fallback re-runs this with the other poser's, which the core holds equal.
+    if (environment !== undefined) {
+      const drawn = poser.animations.filter((a) => only === undefined || a.name === only);
+      const refusal = environmentRefusal(flags.environment, environment.steps, skeletonText, fps, drawn);
+      if (refusal !== null) throw new UsageError(refusal);
+    }
     // `null` is a skeleton that posed no vertex at all. One that posed a vertex
     // it cannot frame — Infinity or NaN — is thrown from the framing as a
     // `GeometryError` naming the number (issue #873), and one whose every vertex
@@ -598,7 +680,7 @@ export function cmdRender(flags: Record<string, string>): void {
     if (geometry) {
       for (const [name, frames] of sampled) {
         const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
-        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin)));
+        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin, environment?.steps)));
       }
     }
     // The fold reading, off the very attachments the frames were drawn from, against the rest table the geometry
@@ -616,6 +698,13 @@ export function cmdRender(flags: Record<string, string>): void {
   });
   const { viewport, sampled, geometryTexts, foldReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
+  if (environment !== undefined) {
+    const response = environmentResponse(skeletonText);
+    console.log(
+      `  ..    world    ${environment.steps.length} step(s) from ${environment.path} (x right, y down; the runtime's wind [1, 0] and gravity [0, 1] before the first) — ` +
+        `wind answered by ${response.wind.join(', ') || 'none'}; gravity by ${response.gravity.join(', ') || 'none'}`,
+    );
+  }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
@@ -682,6 +771,8 @@ export function cmdRender(flags: Record<string, string>): void {
     // Written only when a subset was asked for, for the same reason: a render of
     // every slot says nothing and stays the bytes it always was (issue #835).
     ...subsetFields(subset),
+    // Written only when a schedule was given (issue #1416): a render without one says nothing and stays the bytes it was.
+    ...(environment === undefined ? {} : { environment: environment.steps }),
     background: BACKGROUND,
     // The one spelling `geometry.json` repeats, so the two files cannot state
     // two boxes for one grid.

package/src/cli/shared.ts

@@ -1013,6 +1013,13 @@ const FLAG_MEANINGS: Record<string, string> = {
     'with where they are (the world box of their posed vertices) and how big (their setup-pose area, and its share of the mesh\'s). ' +
     'One 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. Not with --slot/--hide: it reads every mesh the pose shows',
+  environment:
+    'the world the rig\'s physics answers, in time: a 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 and set ' +
+    'before the step that poses the first frame at or after it, on either poser. Before the first step the world is the ' +
+    'runtime\'s, wind [1, 0] and gravity [0, 1]. 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. An inspection of what the rig offers, not a scene',
   poser:
     "`render`, `inspect` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
     'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
@@ -1194,6 +1201,7 @@ const FLAG_VALUES: Record<string, string> = {
   'pack-shape': 'rect|polygon',
   'texture-from': '<path>',
   poser: 'core|spine',
+  environment: '<schedule.json>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
   bones: `<correspondence.json|${IDENTITY_CORRESPONDENCE}>`,
@@ -1599,8 +1607,9 @@ export const COMMANDS: CommandDoc[] = [
     usage: [
       'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
+      'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'folds', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'folds', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },

package/src/core/raw.ts

@@ -499,8 +499,26 @@ export function poseRawAnimation(doc: CompiledDocument, animation: string, steps
  * (`physicsClockStep` below, issue #1380); the track time and
  * the animation time are the steps' running sum either way.
  */
-export function poseRawAnimationEach(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, visit: (pose: RawPose, index: number) => void, clock?: (dt: number) => number): void {
-  walkEach(doc, animation, steps, plant, reset, clock === undefined ? RAW_MODE : { ...RAW_MODE, clock: (dt) => clock(dt) }, RAW_SHAPE, visit);
+export function poseRawAnimationEach(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, visit: (pose: RawPose, index: number) => void, clock?: (dt: number) => number, environment?: StepEnvironment): void {
+  walkEach(doc, animation, steps, plant, reset, clock === undefined ? RAW_MODE : { ...RAW_MODE, clock: (dt) => clock(dt) }, RAW_SHAPE, visit, environment);
+}
+
+/**
+ * What a batch walk sets on its physics before a pose (issue #1416, part C):
+ * pose `index`'s change to the world every physics constraint answers — either
+ * half, merged over the one standing as a live track's `setEnvironment` merges
+ * it (`setEnvironmentOn`) — or `undefined` for none. Pose 0 is the reset pose;
+ * pose `k + 1` is the one step `k` makes. `rigc render --environment` is the
+ * caller (`src/render_core.ts`), and spine-core's poser sets the same values on
+ * its `Skeleton` before the same update (`src/render.ts`), so the two posers
+ * see one world at every step.
+ */
+export type StepEnvironment = (index: number) => Partial<PhysicsEnvironment> | undefined;
+
+/** `environment`'s change for pose `index`, set on `ctx` as a live track sets one — validated and merged by `setEnvironmentOn`. */
+function setStepEnvironment(ctx: PhysicsStepContext, environment: StepEnvironment | undefined, index: number): void {
+  const change = environment?.(index);
+  if (change !== undefined) setEnvironmentOn(ctx, change, `the walk's, at pose ${index},`);
 }
 
 /**
@@ -755,10 +773,12 @@ function animationOf(doc: CompiledDocument, animation: string): CompiledDocument
  * `reset: 'setup'` pose 0 is the setup pose, reset; under `animation` it is the
  * animation applied at 0 and reset there, a step of 0 (`stepWalk`'s `first`).
  */
-function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations'][number], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, adjust?: LocalAdjust): { track: TrackState<P>; first: P } {
+function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations'][number], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, adjust?: LocalAdjust, before?: (ctx: PhysicsStepContext) => void): { track: TrackState<P>; first: P } {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
   const ctx = freshStepContext(plant.physicsStep);
+  // What the caller sets before pose 0 (issue #1416, part C): the batch walk's environment for the reset pose.
+  before?.(ctx);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
   const track: TrackState<P> = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, adjust, trackTime: 0, last: -1 };
   if (reset === 'setup') {
@@ -890,14 +910,17 @@ export function openRawTracksPath(doc: CompiledDocument, plant: TimelinePlant):
 }
 
 /** `walkIn`'s walk, each pose assembled in `shape` and handed to `visit` in order as it is posed (`poseRawAnimationEach`): the walk opened, then stepped over `steps`. */
-function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, visit: (pose: P, index: number) => void): void {
+function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, visit: (pose: P, index: number) => void, environment?: StepEnvironment): void {
   const anim = animationOf(doc, animation);
   const bad = steps.findIndex((s) => !Number.isFinite(s) || s < 0);
   if (bad >= 0) throw new CoreInputError(`step ${bad} is ${steps[bad]}, not a finite time at or above 0`);
-  const { track, first } = openWalk(doc, anim, plant, reset, mode, shape);
+  const { track, first } = openWalk(doc, anim, plant, reset, mode, shape, undefined, environment === undefined ? undefined : (ctx) => setStepEnvironment(ctx, environment, 0));
   let visited = 0;
   visit(first, visited++);
-  for (const dt of steps) visit(stepWalk(track, dt), visited++);
+  for (const dt of steps) {
+    setStepEnvironment(track.ctx, environment, visited);
+    visit(stepWalk(track, dt), visited++);
+  }
 }
 
 /**

package/src/environment.ts

@@ -0,0 +1,193 @@
+/**
+ * The world a render's physics answers, in time — `rigc render --environment`
+ * (issue #1416, part C).
+ *
+ * A rig's physics constraints state how much each one answers wind and
+ * gravity (their own `wind` and `gravity`, AUTHORING §4.6). The world they
+ * answer is the consumer's: the two direction vectors spine-core keeps on its
+ * `Skeleton` (`windX, windY`, `gravityX, gravityY`), which a live track sets
+ * with `setEnvironment` (`./core/track.ts`). A render has no consumer, so this
+ * file is one: a list of steps in time, each changing the world from its `t`
+ * until the next, which both render posers set before the step that poses each
+ * frame (`src/render_core.ts`, `src/render.ts`).
+ *
+ * ⭐ It inspects what the rig offers; it does not compose a scene. Which gust
+ * blows when is the consumer's, and a schedule here is a probe of the response
+ * — the same probe on both posers, so the export's answer to it is held to the
+ * core's (the render-environment suite).
+ *
+ * The coordinates are the runtime's own and the live track's: x to the right,
+ * **y down** (a positive y pulls toward the bottom of the screen, as the
+ * runtime's initial gravity `[0, 1]` does). Until the first step the world is
+ * the runtime's initial one, wind `[1, 0]` and gravity `[0, 1]`, which is what a
+ * render without the flag answers — so a calm start has to be stated.
+ *
+ * Nothing here links spine-core, and nothing here reads a clock: the schedule
+ * is resolved onto a frame grid by arithmetic on the frame index alone.
+ */
+import type { PhysicsEnvironment } from './core/constraints_physics.ts';
+
+/** The tag a schedule file states, refused by name when it states another. */
+export const ENVIRONMENT_SPEC = 'rigc-environment/1';
+
+/** One pose's change to the world: either half, the other kept as it stands. */
+export type EnvironmentChange = Partial<PhysicsEnvironment>;
+
+/** One step of a schedule: from `t` seconds on, until the next step, the world is changed by `wind` and/or `gravity`. */
+export interface EnvironmentStep {
+  t: number;
+  wind?: [number, number];
+  gravity?: [number, number];
+}
+
+/** A schedule refused — by entry index, field, the value found and what is required. */
+export class EnvironmentError extends Error {}
+
+const TOP_KEYS = ['spec', 'steps'] as const;
+const STEP_KEYS = ['t', 'wind', 'gravity'] as const;
+const PAIR = 'a pair of finite numbers [x, y] (x to the right, y down)';
+
+/** A value as a refusal shows it: JSON, except that a number that is not finite is written as itself rather than as `null`. */
+function shown(value: unknown): string {
+  if (typeof value === 'number') return String(value);
+  if (Array.isArray(value)) return `[${value.map(shown).join(', ')}]`;
+  if (value === undefined) return 'nothing';
+  return JSON.stringify(value);
+}
+
+/** What a value is, for the refusal of a file or an entry that is not an object. */
+function kindOf(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `${typeof value === 'object' ? 'an' : 'a'} ${typeof value} ${typeof value === 'object' ? '' : shown(value)}`.trimEnd();
+}
+
+/**
+ * A schedule file's text read, or refused by name before anything is posed.
+ * `where` is how the refusal names the file. Every step is returned with its
+ * keys in one order — `t`, `wind`, `gravity` — whatever order the file wrote
+ * them in, so what a render records of it does not depend on the spelling.
+ */
+export function readEnvironmentSchedule(text: string, where: string): EnvironmentStep[] {
+  const refuse = (what: string): EnvironmentError => new EnvironmentError(`--environment ${where}: ${what}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw refuse(`not JSON — ${(err as Error).message}`);
+  }
+  const shape = `{ "spec": "${ENVIRONMENT_SPEC}", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`;
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw refuse(`the file holds ${kindOf(parsed)}, not an object ${shape}`);
+  const top = parsed as Record<string, unknown>;
+  for (const key of Object.keys(top)) {
+    if (!(TOP_KEYS as readonly string[]).includes(key)) throw refuse(`the file names "${key}", which is not one of [${TOP_KEYS.join(', ')}]`);
+  }
+  if (top.spec !== ENVIRONMENT_SPEC) throw refuse(`"spec" is ${shown(top.spec)}; render reads "${ENVIRONMENT_SPEC}"`);
+  const steps = top.steps;
+  if (!Array.isArray(steps) || steps.length === 0) throw refuse(`"steps" is ${shown(steps)}, not a non-empty array of { "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }`);
+  const out: EnvironmentStep[] = [];
+  steps.forEach((entry: unknown, i) => {
+    const at = `entry ${i} of "steps"`;
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) throw refuse(`${at} is ${kindOf(entry)}, not an object { "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }`);
+    const given = entry as Record<string, unknown>;
+    for (const key of Object.keys(given)) {
+      if (!(STEP_KEYS as readonly string[]).includes(key)) throw refuse(`${at} names "${key}", which is not one of [${STEP_KEYS.join(', ')}]`);
+    }
+    const t = given.t;
+    if (typeof t !== 'number' || !Number.isFinite(t) || t < 0) throw refuse(`${at}'s "t" is ${shown(t)}, not a finite time in seconds at or above 0`);
+    const previous = out[i - 1];
+    if (previous !== undefined && !(t > previous.t)) {
+      throw refuse(`${at}'s "t" is ${shown(t)}, not after entry ${i - 1}'s ${shown(previous.t)} — steps are listed in ascending time, each holding until the next`);
+    }
+    const pair = (key: 'wind' | 'gravity'): [number, number] | undefined => {
+      const v = given[key];
+      if (v === undefined) return undefined;
+      if (!Array.isArray(v) || v.length !== 2 || v.some((n) => typeof n !== 'number' || !Number.isFinite(n))) throw refuse(`${at}'s "${key}" is ${shown(v)}, not ${PAIR}`);
+      return [v[0] as number, v[1] as number];
+    };
+    const wind = pair('wind');
+    const gravity = pair('gravity');
+    if (wind === undefined && gravity === undefined) throw refuse(`${at} (t ${shown(t)}) states neither "wind" nor "gravity", so it changes nothing`);
+    out.push({ t, ...(wind === undefined ? {} : { wind }), ...(gravity === undefined ? {} : { gravity }) });
+  });
+  return out;
+}
+
+/**
+ * The frame a step at `t` seconds is first posed on at `fps`: the first frame
+ * `i` whose time `i / fps` is at or after `t`. Its change is set before the
+ * step that poses that frame, so the physics integrates the new world over the
+ * frame's whole interval. Exact for the predicate as written: `i / fps` is the
+ * division correctly rounded, so a `t` that names a frame's time lands on it.
+ */
+export function environmentFrame(t: number, fps: number): number {
+  let i = Math.max(0, Math.ceil(t * fps));
+  while (i > 0 && (i - 1) / fps >= t) i--;
+  while (i / fps < t) i++;
+  return i;
+}
+
+/**
+ * A schedule on the frame grid of `fps`: each frame's change, or `undefined`.
+ * Steps landing on one frame are merged in order, a later half over an
+ * earlier — which only the framing meets (`FRAMING_FPS`), since `render`
+ * refuses a schedule two of whose steps share a frame of its own grid
+ * (`environmentCollisions`).
+ */
+export function environmentAt(steps: readonly EnvironmentStep[], fps: number): (index: number) => EnvironmentChange | undefined {
+  const byFrame = new Map<number, EnvironmentChange>();
+  for (const step of steps) {
+    const frame = environmentFrame(step.t, fps);
+    const before = byFrame.get(frame) ?? {};
+    byFrame.set(frame, { ...before, ...(step.wind === undefined ? {} : { wind: step.wind }), ...(step.gravity === undefined ? {} : { gravity: step.gravity }) });
+  }
+  return (index) => byFrame.get(index);
+}
+
+/** The steps that share a frame of the `fps` grid, by frame — each group's first step would never be posed. */
+export function environmentCollisions(steps: readonly EnvironmentStep[], fps: number): Array<{ frame: number; entries: number[] }> {
+  const groups = new Map<number, number[]>();
+  steps.forEach((step, i) => {
+    const frame = environmentFrame(step.t, fps);
+    groups.set(frame, [...(groups.get(frame) ?? []), i]);
+  });
+  return [...groups].filter(([, entries]) => entries.length > 1).map(([frame, entries]) => ({ frame, entries }));
+}
+
+/**
+ * Which physics constraints of a Spine 4.3 skeleton answer each half of the
+ * world: `declared` every physics constraint by name; `wind` and `gravity` the
+ * ones stating a non-zero `wind` or `gravity` (the runtime reads an absent one
+ * as 0) and, as `"<constraint>" keyed by "<animation>"`, every physics
+ * timeline keying that field (`""` keys every constraint). Read off the
+ * skeleton's JSON as plain JSON, the same text both posers pose.
+ */
+export interface EnvironmentResponse {
+  declared: string[];
+  wind: string[];
+  gravity: string[];
+}
+
+function objectOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+export function environmentResponse(skeletonText: string): EnvironmentResponse {
+  const root = objectOf(JSON.parse(skeletonText));
+  const constraints = Array.isArray(root.constraints) ? root.constraints.map(objectOf).filter((c) => c.type === 'physics') : [];
+  const declared = constraints.map((c) => String(c.name));
+  const out: EnvironmentResponse = { declared, wind: [], gravity: [] };
+  for (const half of ['wind', 'gravity'] as const) {
+    for (const c of constraints) {
+      const v = c[half];
+      if (typeof v === 'number' && v !== 0) out[half].push(`"${String(c.name)}" (${half} ${v})`);
+    }
+    for (const [animation, body] of Object.entries(objectOf(root.animations))) {
+      for (const [target, timelines] of Object.entries(objectOf(objectOf(body).physics))) {
+        const keys = objectOf(timelines)[half];
+        if (Array.isArray(keys) && keys.length > 0) out[half].push(`${target === '' ? 'every constraint' : `"${target}"`} keyed by "${animation}"`);
+      }
+    }
+  }
+  return out;
+}

package/src/render.ts

@@ -130,6 +130,7 @@ import { dirname, join } from 'node:path';
 import { Plate, readPlate } from '../tools/plate.ts';
 import { clipSourceOf, corePoser, inactiveBoneSnapshot, physicsClockStep, subsetOver, unposedBones } from './render_core.ts';
 import { type PosedVertices, type WorldTransform } from './nonfinite.ts';
+import type { EnvironmentChange } from './environment.ts';
 import {
   atlasScales,
   choosePosers,
@@ -500,7 +501,7 @@ export function spinePoser(data: SkeletonData): Poser {
     slots: data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
     subset: (opts, skin) => slotSubsetOf(data, opts, skin),
     setup: (skin) => spinePosed(setupPosed(data, skin)),
-    animation: (name, skin, fps, count, visit) => {
+    animation: (name, skin, fps, count, visit, environment) => {
       const skeleton = skeletonUnderSkin(data, skin);
       const state = new AnimationState(new AnimationStateData(data));
       // Not looping: the last frame sits at the animation's duration, and a looping
@@ -515,10 +516,12 @@ export function spinePoser(data: SkeletonData): Poser {
         if (i > 0) {
           state.update(step);
           state.apply(skeleton);
+          setSkeletonEnvironment(skeleton, environment?.(i));
           skeleton.update(clock);
           skeleton.updateWorldTransform(Physics.update);
         } else {
           state.apply(skeleton);
+          setSkeletonEnvironment(skeleton, environment?.(i));
           skeleton.update(0);
           skeleton.updateWorldTransform(Physics.reset);
         }
@@ -529,6 +532,17 @@ export function spinePoser(data: SkeletonData): Poser {
   };
 }
 
+/**
+ * `render --environment`'s change for one frame (issue #1416), set on spine-core's own `Skeleton` before the update that
+ * poses the frame: `wind` is `windX, windY` and `gravity` is `gravityX, gravityY`, both in the runtime's convention, x
+ * right and y down — the live track's `setEnvironment` mapping, held to these four fields by the core suite's `CO56`. A
+ * half left out keeps the one standing, as the core merges it.
+ */
+function setSkeletonEnvironment(skeleton: Skeleton, change: EnvironmentChange | undefined): void {
+  if (change?.wind !== undefined) [skeleton.windX, skeleton.windY] = change.wind;
+  if (change?.gravity !== undefined) [skeleton.gravityX, skeleton.gravityY] = change.gravity;
+}
+
 /** A spine-core skeleton as it stands posed, read through the seam's `Posed`. */
 function spinePosed(skeleton: Skeleton): Posed {
   return {

package/src/render_core.ts

@@ -100,7 +100,7 @@ import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
 import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
-import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
+import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
 import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
@@ -363,10 +363,14 @@ export function keptPieceArrays(): PieceArrays {
  * one pose is held at a time rather than the animation's whole series. A plant
  * passes another (`RC44`).
  */
-export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void) => void;
+export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, environment?: StepEnvironment) => void;
 
-/** The walk `corePoser` steps with unless a plant passes another: one pose posed, drawn and released before the next, the physics clock moved by `physicsClockStep` (issue #1380). */
-export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep);
+/**
+ * The walk `corePoser` steps with unless a plant passes another: one pose posed, drawn and released before the next, the
+ * physics clock moved by `physicsClockStep` (issue #1380), and `render --environment`'s change for each pose set before it
+ * is posed (issue #1416, `StepEnvironment`).
+ */
+export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit, environment) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment);
 
 /**
  * The render's physics clock (issue #1380): defined beside the walk that takes it (`./core/raw.ts`), where the mesh
@@ -750,7 +754,7 @@ export function corePoser(
       const input = inputOf(skin);
       return corePosed(input, poseRawSetup(input.doc, { through }), through);
     },
-    animation: (name, skin, fps, count, visit) => {
+    animation: (name, skin, fps, count, visit, environment) => {
       const input = inputOf(skin);
       const step = 1 / fps;
       // Each pose is drawn as it is posed and released before the next (issue #1180), so the walk holds one pose and not
@@ -765,7 +769,7 @@ export function corePoser(
         } catch (thrown) {
           drawFailed.push(thrown);
         }
-      });
+      }, environment);
       if (drawFailed.length > 0) throw drawFailed[0];
     },
     rest: (skin, shown) => {

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

@@ -740,6 +740,67 @@ export const PHYSICS_POSE_RULES: PhysicsPoseRule[] = [
   },
 ];
 
+/** 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)`: the step is stable exactly when `k` is below it. */
+  readonly bound: number;
+  /** The largest magnitude among the step map's two eigenvalues — what one step multiplies an undisturbed offset by, at most. */
+  readonly growth: number;
+  /** `k < bound`, strictly. */
+  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]` (the damping row's own
+ * bound) both eigenvalues lie inside the unit circle exactly when
+ * `0 < k < 2·(1 + d)`. The lower end is the strength row's; this is the upper.
+ *
+ * ⚠️ **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 };
+}
+
 /**
  * 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