spine-rigc 2.51.0 → 2.52.0

package/NOTICE.md

@@ -40,8 +40,8 @@ Software's terms, not a licence term of this project:
    development dependency for its own gate, and so does an install with
    `spine-core` added beside it. Validation is not optional on either: the gate
    runs through the runtime where it is installed and through rigc's own validator
-   where it is not, and the two are held to the same verdicts in CI on 48 of the
-   49 assertions — the official parser's own parse runs only where the runtime is.
+   where it is not, and the two are held to the same verdicts in CI on 49 of the
+   50 assertions — the official parser's own parse runs only where the runtime is.
 
 > **If a product integrates a Spine Runtime to play rigc's output, that integration
 > is subject to the terms above** — rigc neither creates those terms nor removes

package/README.md

@@ -65,12 +65,12 @@ it cuts both ways:
   is a development dependency: this repository uses it to hold rigc's own validator
   to the round trip's verdicts — in CI, on the public example recipes and every
   selftest call, and on a private corpus of production rigs measured before each
-  release. Of the 49 assertions, 48 run on both; `A00_ROUNDTRIP_PARSE`, the official
+  release. Of the 50 assertions, 49 run on both; `A00_ROUNDTRIP_PARSE`, the official
   parser's own parse, runs only where the runtime is installed and is reported as a
   SKIP elsewhere. There, in the parse's place, the report also carries the model
   side's own two parse rules, `A00_MODEL_READ` and `A00_MODEL_REGIONS_ON_PAGES`,
   which no round-trip rule matches and the registry does not hold — so its summary
-  totals 51 on the core entry, and its last line counts 42 rules on the model side
+  totals 52 on the core entry, and its last line counts 42 rules on the model side
   ([AUTHORING §5.2](docs/AUTHORING.md) has a row for each). Install it beside rigc
   (`bun add -d @esotericsoftware/spine-core`) and the same `rigc` runs the round
   trip on every build. The
@@ -618,9 +618,9 @@ first three work on any reference you have, and `bench` is a repository workflow
 and `bun run fetch-examples`. The reasoning behind them is in
 [the benchmark dossier](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md).
 
-`build` and `validate` both default to `--profile spine` — the 35 validity rules, which
+`build` and `validate` both default to `--profile spine` — the 36 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile rig-play`
-adds all 49: the other 14 are one renderer's policy and one canvas budget's, and they
+adds all 50: the other 14 are one renderer's policy and one canvas budget's, and they
 fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
 ⇒ **That reason is about foreign data and does not carry to a rig you are authoring
 yourself: author under `--profile rig-play` and read the extra 14 as findings, and
@@ -764,7 +764,12 @@ and so is a build with no atlas or an atlas that is a directory, or an
 `--exported` file that is not one JSON object.
 
 ⛔ **Run the round trip by hand, on a machine that has the editor.** CI has no
-editor, so no automated check runs it.
+editor, so no automated check runs it. The by-hand measurement before a landing
+trips the production rigs and one **parts-built** rig, the exam's task-01
+painting through `@rig-c/parts`. The production rigs were authored in the editor,
+so they are already in the editor's own shape. A refusal that only a generated
+rig carries cannot show up on them. Issue #1407 was such a refusal: a green build
+whose meshes listed their bones in two orders, which the editor would not import.
 
 ⚠️ Build with `--copy-images`. An ordinary build's atlas names its pages by a
 relative path back to the art directory, and the round trip copies that atlas to
@@ -782,7 +787,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | **the Spine 4.3 format, field by field.** Every key the 4.3 JSON parser and atlas reader take, what each defaults to, and the parser line it comes from — the rows rigc's refusals cite by part number. Ships in the package too |
-| 🎓 **[the benchmark dossier](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 49 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
+| 🎓 **[the benchmark dossier](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 50 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/rig-c/core/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/rig-c/core/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/rig-c/core/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
 | 🔬 [SURVEY_2026-08-22.md](https://github.com/rig-c/core/blob/main/docs/SURVEY_2026-08-22.md) | the survey the ladder was climbed by: rigc and the official examples as measured on 2026-08-22, and the gap list ordered by rung. A dated record, not kept current. Repository material |
 | 🧬 [GENERATIONS.md](https://github.com/rig-c/core/blob/main/docs/GENERATIONS.md) | **Spine data from another generation.** Why a 3.8–4.2 file read as 4.3 fails in silence, the policy that follows (detect from `skeleton.spine`, never guess, play on the matching runtime), what `A16` and `ingest` do with such a file, and the editor as the migration path. Repository material |
@@ -832,7 +837,7 @@ quality."* All six, with their verdicts, are in
 [docs/LADDER.md](https://github.com/rig-c/core/blob/main/docs/LADDER.md).
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 49 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 50 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/rig-c/core/blob/main/docs/LADDER.md).

package/docs/AUTHORING.md

@@ -165,7 +165,7 @@ side over the document — its own two parse rules first, `A00_MODEL_READ` and
 `A00_MODEL_REGIONS_ON_PAGES`, which stand where spine-core's parse stands and are
 not in the registry, then the registry's rules that read the model — and the round
 trip's own rules restated over the text the emitter wrote (A01, A02, A05, A07, A16,
-A31, A35, and A18 over a second compile's three files), and it does not run `A00_ROUNDTRIP_PARSE`, which reports **SKIP**
+A31, A35, A52, and A18 over a second compile's three files), and it does not run `A00_ROUNDTRIP_PARSE`, which reports **SKIP**
 naming spine-core. Its report ends on a line saying which rules ran there and
 which did not, and it writes only when none of them fails (§5.2).
 
@@ -239,7 +239,7 @@ What the flags mean:
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
-| `--profile` | `spine` = the 35 validity rules (**the default**) · `rig-play` = all 49, opt-in. `spine-html`, the profile's former name, is read as `rig-play` until the next minor release and prints a deprecation line on stderr naming `rig-play` |
+| `--profile` | `spine` = the 36 validity rules (**the default**) · `rig-play` = all 50, opt-in. `spine-html`, the profile's former name, is read as `rig-play` until the next minor release and prints a deprecation line on stderr naming `rig-play` |
 | `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
 | `--candidate` | `check`, `bench`, `render`, `inspect`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
@@ -2252,6 +2252,22 @@ rigc therefore refuses a weighted `vertices` run unless the attachment says
 `"boneIndexing": "raw"` out loud — an opt-in, because what is being opted into is
 the silence.
 
+🔢 **The order a vertex lists its bones in is free, until two vertices disagree.**
+The Spine editor refuses to import a weighted attachment whose vertices admit no
+single bone order — one vertex listing `link_a, link_b` and another
+`link_b, link_a`, three listing `a, b` · `b, c` · `c, a`, or one listing a bone
+twice — on a mesh, a bounding box, a clipping polygon and a path alike
+(`Error reading attachment: <name>` · `Index -2 out of bounds`), while spine-core
+reads every one of them. Weights written heaviest-first are exactly that shape. So
+`build` writes such an attachment with **every vertex's influences in ascending
+bone order** — in `skeleton.json` and in the model document, its `deform` runs
+moved with their influences (§4.11) — and leaves every other attachment in the
+order you gave it: one order per attachment is what the editor needs, and a
+descending one imports. `A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER` (§5.2) holds
+the file to it. Nothing about the pose changes but the order a vertex's
+influences are summed in, which is measured at ≤ 2 ulp of a posed vertex and no
+pixel (issue #1407).
+
 ⚠️ `vertices` carries **no encoding flag** of its own, which is why the length rule
 above is load-bearing: if `vertices.length` equals `uvs.length` the parser reads
 unweighted x/y pairs, otherwise it reads the weighted run. A coincidental length
@@ -4937,6 +4953,41 @@ agreeing with `render` — and left out, a track steps the physics by the step i
 exactly as before. Which clock a player with a real clock uses is the player's
 question, and rigc does not answer it.
 
+🌬️ **`wind` and `gravity` are the constraint's response; the world is the
+consumer's** (issue #1416). In 4.3 the two are not forces but how strongly the
+constraint answers two directions the *skeleton* carries — `Skeleton.windX,
+windY` and `gravityX, gravityY`, which start at `1, 0` and `0, 1` — so a
+constraint stating `wind: 20` is pushed along whatever direction the player
+sets, times 20 (and on `x` and `y` times `referenceScale`; on a rotation, at
+a lever of the bone's `length` over `referenceScale`). A live track of the
+core entry sets that direction with `setEnvironment({ wind: [x, y], gravity:
+[x, y] })` — x to the right, **y down**, either half left out to keep the one
+that stands — and the Spine export carries only the response, so an official
+runtime whose `Skeleton` is given the same four numbers poses what the core
+poses, to the bit (`CO56`). Two consequences an author has to know:
+
+- **A constraint stating `wind: 0` feels no wind**, whatever the player sets.
+  State a `wind` on every link that should answer a gust; leave it 0 on one
+  that should not.
+- **Until the player sets one, `wind` pushes to the right.** The initial
+  direction is the runtime's `[1, 0]`, not `[0, 0]`, so a rig stating `wind`
+  leans at rest on every player that never calls `setEnvironment` — the
+  official runtimes included. A player that wants calm at rest sets `wind:
+  [0, 0]` and blows by setting it back. rigc does not change the initial
+  value: that would make the export pose differently in the runtime than in
+  the core.
+
+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
+skeleton's world (y up, degrees counter-clockwise) — and every constraint's
+next update sees its bone move by that much, so a rig walked across the screen
+trails its coat. A player forwards what spine-core's `SkeletonPhysicsMovement`
+forwards: its display object's change of position since the last frame in the
+skeleton's units and axes, and its change of rotation as `physicsRotate(0, 0,
+Δ)`, before the `step` that poses the frame. Nothing set, every pose is the
+one the track posed before these existed (`CO57`).
+
 `mix` is a player-side `AnimationStateData` config and is **not** emitted into
 skeleton JSON, so the parser is the only check it gets: it is
 `{ "default": <seconds>, "pairs"?: [["<from>", "<to>", <seconds>], …] }`, and a
@@ -5291,7 +5342,11 @@ back on load; on a weighted one zero *is* "unmoved".
 on a weighted one.** Its length is `vertices.length` in the first case and
 `vertices.length / 3 * 2` in the second, because a weighted attachment stores
 `x, y, weight` per influence. A vertex with three bones on it therefore occupies
-**three** pairs, each in that bone's own bind space. This is the whole reason
+**three** pairs, each in that bone's own bind space, in the order the spec lists
+the vertex's bones. Write a run against that order: where `build` rewrites an
+attachment's bone order (§3.4 — vertices that admit no single order), it moves
+each run's pairs with their influences, writing a 0 where the moved run has a gap.
+This is the whole reason
 `fromVertex` exists and the whole reason it is sometimes refused:
 
 - on an **unweighted** attachment `fromVertex` always works — vertex *v* is array
@@ -6538,9 +6593,9 @@ prints six rows and is one failure here.
 `A00_MODEL_READ` and `A00_MODEL_REGIONS_ON_PAGES` — the first two rows of the
 table below — which stand where `A00_ROUNDTRIP_PARSE`'s parse stands and have no
 round-trip counterpart, so they are not in the registry. That is the whole of the
-difference between the two totals: `<N>` is 51 on the core entry and 49 on `cli.ts build`,
+difference between the two totals: `<N>` is 52 on the core entry and 50 on `cli.ts build`,
 and the core report's last line states the split — 42 rules on the model side,
-which are the 40 registry assertions the model side runs and those two; the 8 restated over the emitted text;
+which are the 40 registry assertions the model side runs and those two; the 9 restated over the emitted text;
 and `A00_ROUNDTRIP_PARSE`, which it reports as a SKIP.
 
 🚨 **When `A00_ROUNDTRIP_PARSE` fails, read the report as a report about A00 and
@@ -6604,6 +6659,7 @@ Fix A00 and run it again.
 | <a id="A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP"></a>`A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP` | renderer | two regions on one page whose rectangles overlap **and** whose footprints overlap — so one drawing samples texels that are the other's. A region's **footprint** is what samples it: a region a mesh names (its `path`, else its name, every frame of a `sequence` included) draws the mesh's hull loop and its triangles, its UVs placed on the page as `MeshAttachment.computeUVs` places them (a **linked mesh** draws its source's); a region a region attachment names, or that nothing names, draws its whole rectangle — and so does a mesh region whose UVs leave 0..1, whose hull or triangles do not index its vertices, or that is turned by `rotate:`, and every region when a `sequence` cannot be read. For two rectangles that is exactly the clause `A06` held until issue #1099 — an editor alias, a sequence frame, two rectangles moved over the same texels are refused as they were — and it accepts what `--pack-shape polygon` writes: a neighbour inside a mesh's rectangle where the hull is not (§0.1). **Touching is not overlapping**: interiors are compared, every comparison `FOOTPRINT_SLACK` (1e-6 texels) in favour of apart. `regions "ear_l" (341,696 112x420) and "mouth" (332,709 96x48) overlap on page "skeleton.png", and so do their footprints — "ear_l" draws the hull of mesh "ear_l" (skin "default", slot "ear_l"), "mouth" draws its whole rectangle, which region attachment "mouth" (skin "default", slot "mouth") draws; what they draw overlaps by 1916.5512 texel(s) of area inside 347,709 81x48. One drawing samples texels that are the other's: move one region clear of the other's footprint, or pack the page again` — `gallery/nod`'s polygon pack with `mouth` moved onto a triangle of the `ear_l` mesh (`PK88`). Nothing about the **padding** is read — the atlas and the model document do not state it — and the `2 · padding` the packer keeps is the packer's own (`PK81`). A renderer rule because two regions over the same texels is what an editor's packer writes for an alias or a sequence: 49 pairs on four of the ten atlases in `examples/`. **SKIP** when the atlas declares no page or no region, and when no page carries two regions — every unpacked build |
 | <a id="A50_STAGE_BOX_IS_THE_STAGE"></a>`A50_STAGE_BOX_IS_THE_STAGE` | both | the stage box a rig asked for (`skeleton.stageBox`, §3.1) is not the stage the model document states. Read on the data a consumer reads and on the pose it reads: the slot carries, in the `default` skin under the asked name, an unweighted bounding box of four vertices whose **stored** vertices are the stage's corners exactly — `(x, y)`, `(x + w, y)`, `(x + w, y + h)`, `(x, y + h)`, as the float32 the runtime loads — and whose **world** vertices at the setup pose (constraints applied, no physics, no skin set) are those corners as the runtime poses them on an unrotated root, compared on the header's 1e-6 grid at float32. `the stage box (slot "stage", attachment "stage"): vertex 1 is stored as (65, 0) and the stage's corner is (64, 0) — the stage 0,0 64x48, bottom-left first and counter-clockwise`; a root moved at setup reads *vertex 0 poses at (1, 0) at the setup pose and the stage's corner poses at (0, 0) on an unrotated root, on the header's grid — something moves the box's bone at setup (a constraint, or a pose the root does not state)*; a slot the skeleton lacks, no attachment of that name, another type, or a weighted box are each named too. Through spine-core it reads `findSlot`, `defaultSkin.getAttachment` and `computeWorldVertices` on a fresh skeleton after `setupPose()` and `updateWorldTransform(Physics.none)`; on the model side the document's record and rigc's core poser, held to spine-core's poses at tolerance 0 (`PG06`, `PG07`). **SKIP** where nothing asks: *nothing asks for a stage box: no rigc-compiled/3 model document beside this skeleton states one …* — a rig without the field, and any skeleton with no `/3` document beside it, an export among them |
 | <a id="A51_BONES_LIE_ALONG_THEIR_DECLARED_AXIS"></a>`A51_BONES_LIE_ALONG_THEIR_DECLARED_AXIS` | both | a bone the rig holds to a line (`invariants.axes`, §3.7) whose world x axis at the setup pose — constraints applied, no physics, no skin set, the pose `A50` reads — is more than the entry's `tolerance` off the line through its two `through` bones' world origins, compared as lines (0° to 90°): `axis "face" (through "eye_r"→"eye_l", 30.0000°): bone "brow_l" world x axis at 36.0000°, 6.0000° off, tolerance 5° — rotate the bone in the rig spec onto the line and counter-rotate its attachments so the setup pose stays put`. Every angle is Spine world degrees (y up), counter-clockwise from +x. **Fix it in the rig spec**: set the bone's `rotation` so its world x axis lands on the axis angle the line prints, counter-rotate its attachments by the same angle so the setup pose does not move, and restate its children in its new frame. Also fails, by the entry's name: two `through` bones on one world origin (*share the world origin (x, y) at the setup pose, so they draw no line* — move one, or name another pair); a bone with no world x axis (a scale of 0); a bone inactive with no skin set (*so the setup pose places it nowhere*); a bone the skeleton does not have. Held whether or not an animation keys the bone: a consumer writes it at run time. Through spine-core it reads `appliedPose` on a fresh skeleton after `setupPose()` and `updateWorldTransform(Physics.none)`; on the model side rigc's core poser, held to spine-core's poses at tolerance 0 (`AX01`–`AX05`). **SKIP** when the rig declares no axes — *the rig "X" declares no axes (invariants.axes)* — and on a bare directory with no rig |
+| <a id="A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER"></a>`A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER` | both | a weighted mesh, bounding box, clipping polygon or path whose vertices list their bones in no single order — `mesh "default/hair/hair": no one bone order fits its vertices — vertex 0 lists bone 11 before 18 (its bones: 11, 18), vertex 9 lists bone 18 before 11 (its bones: 18, 11)`, or three vertices in a cycle (`a` before `b`, `b` before `c`, `c` before `a`), or one vertex that lists a bone twice. The numbers are bone indices in the skeleton's `bones` array, and the vertex numbers count from 0 in the run. spine-core loads all of these; the Spine editor refuses the import (`Error reading attachment: <name>` · `Index -2 out of bounds`, measured on 4.3.26 on all four types), so this is the one place the round trip cannot see the fault. A descending order, or any order shared by every vertex, is accepted: four of the twelve editor exports in the example corpus are out of ascending order and pass. **A `build` never fails it** — the compiler writes an attachment with no single order in ascending bone order (§3.4); it fires on a Spine file written or edited by something else. **Fix it in the file**: list every vertex's `(index, x, y, weight)` tuples in one order — ascending index is one — and move each deform key's pairs with them; or rebuild through `rigc build`. **SKIP** when the skeleton has no weighted vertex attachment. Under `cli_core.ts build` the same clause runs over the text the emitter wrote and prints this line in the same words (`RC28`). |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.51.0",
+  "version": "2.52.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/a52.ts

@@ -0,0 +1,146 @@
+/**
+ * A52 (issue #1407): every weighted vertex attachment lists its bones in one
+ * order — the order the Spine editor needs and spine-core does not. Run over
+ * the skeleton JSON by both entries: `validate()` in `src/validate.ts` over
+ * the text it hands spine-core, and the entry that links none of the runtime
+ * over the text rigc wrote (`../emitted/index.ts`), so the selftest's `RC28`
+ * holds the two to the same lines on every recipe and on this assertion's
+ * mutant.
+ *
+ * ⭐ **The rule is a cycle, measured, and not "ascending".** With Spine 4.3.26
+ * Professional (`tools/editor_roundtrip.ts`), the import refuses an attachment
+ * when one vertex lists bones `a, b` and another `b, a`, when three vertices
+ * list `a, b` · `b, c` · `c, a` with no pair reversed, and when one vertex
+ * lists a bone twice — `Error reading attachment: <name>` · `Index -2 out of
+ * bounds` — on a mesh, a bounding box, a clipping polygon and a path alike.
+ * The same rig with every vertex in DESCENDING index order imports, exports,
+ * validates and checks; and four of the twelve editor exports in the example
+ * corpus list bones out of ascending order, each in one order per attachment.
+ * So "strictly ascending" would refuse Esoteric's own files, and this refuses
+ * exactly the shape the editor refuses. spine-core reads every one of these
+ * without a word, which is why it is an assertion: the round trip passes it.
+ *
+ * Re-derived from the emitted indices on purpose, with nothing shared with
+ * `compile.ts`, which makes the build's order hold this — the gate does not
+ * check the compiler with the compiler's code.
+ *
+ * Links nothing from the runtime.
+ */
+import type { Verdicts } from '../harness.ts';
+import { isObj, type Json } from '../values.ts';
+
+const CODE = 'A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER';
+
+/** The four attachment types a weighted vertex run can belong to. */
+const VERTEX_TYPES = new Set(['mesh', 'boundingbox', 'clipping', 'path']);
+
+/** One vertex's bone indices, in the order the run lists them. */
+type Listed = { vertex: number; bones: number[] };
+
+/**
+ * A weighted run's vertices, each with the bone indices it lists — or `null`
+ * when the attachment is unweighted or its run does not decode (A04, A20 and
+ * A33 own that shape; this measures order, not encoding).
+ */
+function weightedVertices(att: Json): Listed[] | null {
+  const type = typeof att.type === 'string' ? att.type : 'region';
+  if (!VERTEX_TYPES.has(type) || !Array.isArray(att.vertices)) return null;
+  const length = type === 'mesh' ? (Array.isArray(att.uvs) ? att.uvs.length : null) : typeof att.vertexCount === 'number' ? att.vertexCount * 2 : null;
+  const run = att.vertices as unknown[];
+  if (length === null || run.length === length) return null;
+  const out: Listed[] = [];
+  for (let i = 0; i < run.length; ) {
+    const n = run[i++];
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || i + n * 4 > run.length) return null;
+    const bones: number[] = [];
+    for (let k = 0; k < n; k++) {
+      const bone = run[i + k * 4];
+      if (typeof bone !== 'number') return null;
+      bones.push(bone);
+    }
+    out.push({ vertex: out.length, bones });
+    i += n * 4;
+  }
+  return out;
+}
+
+/** `vertex 3 lists bone 18 before 11 (its bones: 18, 11)`. */
+function step(listed: Listed, from: number, to: number): string {
+  return `vertex ${listed.vertex} lists bone ${from} before ${to} (its bones: ${listed.bones.join(', ')})`;
+}
+
+/**
+ * Why no one order fits these vertices, in the vertices' own words — or
+ * `null` when one does. A vertex naming a bone twice is its own reason; a
+ * cycle is found by a depth-first walk over "listed directly before", in
+ * the order the run first lists each bone, and every edge of it is named by
+ * the first vertex that lists it.
+ */
+function noOneOrder(vertices: Listed[]): string | null {
+  for (const listed of vertices) {
+    const twice = listed.bones.find((bone, k) => listed.bones.indexOf(bone) !== k);
+    if (twice !== undefined) return `vertex ${listed.vertex} lists bone ${twice} twice (its bones: ${listed.bones.join(', ')})`;
+  }
+  /** bone -> the bones listed directly after it, each with the first vertex that does. */
+  const after = new Map<number, Map<number, Listed>>();
+  for (const listed of vertices) {
+    for (let k = 1; k < listed.bones.length; k++) {
+      const from = listed.bones[k - 1];
+      if (!after.has(from)) after.set(from, new Map());
+      const next = after.get(from)!;
+      if (!next.has(listed.bones[k])) next.set(listed.bones[k], listed);
+    }
+  }
+  const state = new Map<number, 'open' | 'done'>();
+  const path: number[] = [];
+  const walk = (bone: number): number[] | null => {
+    state.set(bone, 'open');
+    path.push(bone);
+    for (const next of after.get(bone)?.keys() ?? []) {
+      if (state.get(next) === 'open') return [...path.slice(path.indexOf(next)), next];
+      if (!state.has(next)) {
+        const cycle = walk(next);
+        if (cycle !== null) return cycle;
+      }
+    }
+    path.pop();
+    state.set(bone, 'done');
+    return null;
+  };
+  for (const bone of after.keys()) {
+    if (state.has(bone)) continue;
+    const cycle = walk(bone);
+    if (cycle === null) continue;
+    const steps: string[] = [];
+    for (let k = 1; k < cycle.length; k++) steps.push(step(after.get(cycle[k - 1])!.get(cycle[k])!, cycle[k - 1], cycle[k]));
+    return steps.join(', ');
+  }
+  return null;
+}
+
+export function a52WeightedVerticesShareOneBoneOrder({ fail, skip }: Verdicts, raw: Json | null): void {
+  if (!raw) return skip(CODE, 'the skeleton JSON did not parse (A00 owns that failure)');
+  let measured = 0;
+  for (const skin of Array.isArray(raw.skins) ? (raw.skins as unknown[]) : []) {
+    if (!isObj(skin) || !isObj(skin.attachments)) continue;
+    const skinName = typeof skin.name === 'string' ? skin.name : '(unnamed)';
+    for (const [slot, perSlot] of Object.entries(skin.attachments)) {
+      if (!isObj(perSlot)) continue;
+      for (const [name, att] of Object.entries(perSlot)) {
+        if (!isObj(att)) continue;
+        const vertices = weightedVertices(att);
+        if (vertices === null) continue;
+        measured++;
+        const why = noOneOrder(vertices);
+        if (why === null) continue;
+        fail(
+          CODE,
+          `${String(att.type)} "${skinName}/${slot}/${name}": no one bone order fits its vertices — ${why}. ` +
+            'spine-core reads it; the Spine editor refuses the import ("Index -2 out of bounds"). ' +
+            'List every vertex\'s bones in one order — ascending bone index is one, and the order `rigc build` writes',
+        );
+      }
+    }
+  }
+  if (measured === 0) return skip(CODE, 'no weighted vertex attachment to measure');
+}

package/src/assertions/emitted/index.ts

@@ -3,14 +3,15 @@
  * step 4e of #380) — the half of the gate the entry that links none of
  * spine-core runs beside the model side (`../model/index.ts`).
  *
- * ⭐ **Every one of the 50 is accounted for, by name.** The model side runs
+ * ⭐ **Every assertion in the registry is accounted for, by name.** The model side runs
  * the moved assertions (`MOVED_ASSERTIONS`) over the document. What is left —
  * the complement, read off `ASSERTION_KIND` rather than listed — is the
- * round trip's own: A00, A01, A02, A05, A07, A16, A18, A31, A35 at the time of
+ * round trip's own: A00, A01, A02, A05, A07, A16, A18, A31, A35, A52 at the time of
  * writing. Each of those but one reads the raw text, not what spine-core
  * loaded: the atlas's line layout (A07), the skeleton JSON's draw-order
- * offsets, deform runs, version label, legacy arrays, legacy bone key and
- * curve arrays (A31, A35, A16, A01, A02, A05), and A18's second compile. So
+ * offsets, deform runs, weighted runs' bone order, version label, legacy arrays,
+ * legacy bone key and curve arrays (A31, A35, A52, A16, A01, A02, A05), and A18's
+ * second compile. So
  * each is restated here over the same text, by a body under `../bodies/` that
  * is the round trip's clause word for word, and prints the round trip's line
  * (`RC28` holds the two on every recipe and on each assertion's mutants).
@@ -35,6 +36,7 @@ import { a16SkeletonVersion43 } from '../bodies/a16.ts';
 import { a18DeterministicEmit } from '../bodies/a18.ts';
 import { a31DrawOrderOffsetsResolve } from '../bodies/a31.ts';
 import { a35DeformKeysFitTheAttachment } from '../bodies/a35.ts';
+import { a52WeightedVerticesShareOneBoneOrder } from '../bodies/a52.ts';
 import { parseAtlasText } from '../../atlas.ts';
 
 /** What the restated rules read: the emitted texts, the document written beside them, and a second compile's three. */
@@ -72,6 +74,7 @@ export const EMITTED_TEXT_RULES: ReadonlyArray<{ code: string; run: (v: Verdicts
   { code: 'A07_ATLAS_TEXT_SHAPE', run: (v, t) => a07AtlasTextShape(v, t.input.atlasText) },
   { code: 'A31_DRAW_ORDER_OFFSETS_RESOLVE', run: (v, t) => a31DrawOrderOffsetsResolve(v, t.raw) },
   { code: 'A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', run: (v, t) => a35DeformKeysFitTheAttachment(v, t.raw) },
+  { code: 'A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER', run: (v, t) => a52WeightedVerticesShareOneBoneOrder(v, t.raw) },
   { code: A00, run: (v) => v.skip(A00, SKIP_NO_ROUND_TRIP) },
   { code: 'A16_SKELETON_VERSION_4_3', run: (v, t) => a16SkeletonVersion43(v, t.raw) },
   { code: 'A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS', run: (v, t) => a01NoLegacyToplevelConstraintArrays(v, t.raw) },

package/src/assertions/kinds.ts

@@ -128,6 +128,7 @@ export const ASSERTION_KIND: Readonly<Record<string, AssertionKind>> = {
   A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP: 'renderer',
   A50_STAGE_BOX_IS_THE_STAGE: 'validity',
   A51_BONES_LIE_ALONG_THEIR_DECLARED_AXIS: 'validity',
+  A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER: 'validity',
 };
 
 /** Whether `profile` runs a rule of `kind`: `spine` runs validity alone, `rig-play` every kind. */

package/src/cli/shared.ts

@@ -1337,7 +1337,7 @@ export const COMMANDS: CommandDoc[] = [
           'trip through spine-core, which this entry links none of. What runs instead: the model',
           'side over the document (every assertion moved off the round trip), and the round',
           'trip\'s own rules restated over the text the emitter wrote — A01, A02, A05, A07, A16,',
-          'A31, A35, and A18 over a second, independent compile\'s skeleton, atlas and document.',
+          'A31, A35, A52, and A18 over a second, independent compile\'s skeleton, atlas and document.',
           'What does not run is A00_ROUNDTRIP_PARSE, spine-core\'s parse: it reports SKIP naming',
           'spine-core. The report\'s last line says which ran here and which did not. A00 runs',
           'in build and validate on the entry that links spine-core: installed, the same `rigc`',

package/src/compile.ts

@@ -162,6 +162,7 @@ import {
   type ModelSlot,
   type ModelStage,
   type ModelTimelines,
+  type ModelVertexAttachment,
   type ModelVertices,
   type SkinTable,
   type SkinTableEntry,
@@ -3695,6 +3696,10 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     if (!boneNames.has(slot.bone)) throw new CompileError(`slot "${slot.name}" has no bone`);
   }
 
+  // One bone order per weighted attachment (issue #1407), on the finished
+  // model, so the document, both posers and the Spine file read one order.
+  oneBoneOrderPerAttachment(bones, skins, animations, deformTransforms);
+
   // The fields the model carries as `CompileResult` carries them, by reference:
   // one object, so the result and its model cannot say two different things.
   const carried: CarriedFromCompileResult = {
@@ -4451,6 +4456,142 @@ function bindRawRun(run: readonly number[], bones: readonly ModelBone[], where:
   return out;
 }
 
+/**
+ * Whether one bone order fits every vertex of a weighted attachment: no vertex
+ * lists a bone twice, and no two vertices — directly or through a chain of
+ * others — list two bones in opposite orders. Read off the bindings by name;
+ * `A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER` re-derives the same question
+ * from the emitted indices, on purpose with its own code.
+ */
+function bindingsShareOneBoneOrder(bindings: readonly ModelBinding[][]): boolean {
+  const after = new Map<string, Set<string>>();
+  for (const vertex of bindings) {
+    if (new Set(vertex.map((b) => b.bone)).size !== vertex.length) return false;
+    for (let i = 1; i < vertex.length; i++) {
+      const from = vertex[i - 1].bone;
+      if (!after.has(from)) after.set(from, new Set());
+      after.get(from)!.add(vertex[i].bone);
+    }
+  }
+  const state = new Map<string, 'open' | 'done'>();
+  const acyclicFrom = (bone: string): boolean => {
+    state.set(bone, 'open');
+    for (const next of after.get(bone) ?? []) {
+      const seen = state.get(next);
+      if (seen === 'open') return false;
+      if (seen === undefined && !acyclicFrom(next)) return false;
+    }
+    state.set(bone, 'done');
+    return true;
+  };
+  for (const bone of after.keys()) if (!state.has(bone) && !acyclicFrom(bone)) return false;
+  return true;
+}
+
+/**
+ * Write every weighted attachment whose vertices admit no single bone order
+ * with each vertex's influences in ascending bone order (issue #1407) — the
+ * one rewrite of a spec's binding order the compiler makes, and the reason it
+ * makes it.
+ *
+ * ⭐ **What the Spine editor refuses is a cycle, not a descending pair.**
+ * Measured with Spine 4.3.26 Professional through `tools/editor_roundtrip.ts`:
+ * an attachment where one vertex lists bones `a, b` and another `b, a` — or
+ * three vertices `a, b` · `b, c` · `c, a`, or one vertex `a, a` — is refused
+ * on import (`Error reading attachment: <name>` · `Index -2 out of bounds`),
+ * on a mesh, a bounding box, a clipping polygon and a path alike; the same
+ * rig with every vertex in DESCENDING order imports, exports and checks, and
+ * four of the twelve editor exports in this tree's example corpus list bones
+ * out of ascending order, every one of them in a single order per attachment.
+ * So an attachment that already has one order keeps the spec's, and its bytes
+ * do not move; one that has none takes ascending order, which every vertex
+ * shares by construction.
+ *
+ * 🔒 **On the model, not in the emitter.** The document, rigc's poser and the
+ * Spine file must read one order: a weighted vertex is `Σ wᵢ·Mᵢ·bindᵢ`, and
+ * summed in two orders its last bits differ — sorting in the emitter alone
+ * was measured to put the two posers 1–2 ulp apart on a parts-built rig.
+ *
+ * 🔸 A deform key on such an attachment is one `x, y` per INFLUENCE, in the
+ * influences' order, so each key's run is moved with them: spread over the
+ * deform array, permuted pair by pair, and cut back to the first and last
+ * index it covers, an index it does not cover written as the 0 the runtime
+ * reads there. The report of a generated run (`expanded`) is moved the same
+ * way, so it still carries what was emitted.
+ */
+function oneBoneOrderPerAttachment(
+  bones: readonly ModelBone[],
+  skins: readonly ModelSkin[],
+  animations: ReadonlyMap<string, CompiledAnimation>,
+  deformTransforms: CompileResult['deformTransforms'],
+): void {
+  const position = new Map(bones.map((bone, i) => [bone.name, i] as const));
+  /** Per reordered attachment record: where each influence went, old influence index -> new. */
+  const moved = new Map<ModelVertexAttachment, number[]>();
+  for (const skin of skins) {
+    for (const perSlot of Object.values(skin.attachments)) {
+      for (const record of Object.values(perSlot)) {
+        if (!isModelVertexAttachment(record) || !record.vertices.weighted || moved.has(record)) continue;
+        if (bindingsShareOneBoneOrder(record.vertices.bindings)) continue;
+        const to: number[] = [];
+        let at = 0;
+        const bindings = record.vertices.bindings.map((vertex) => {
+          const order = vertex.map((_, i) => i).sort((p, q) => position.get(vertex[p].bone)! - position.get(vertex[q].bone)! || p - q);
+          const rank = new Array<number>(vertex.length);
+          order.forEach((from, k) => (rank[from] = k));
+          for (let i = 0; i < vertex.length; i++) to.push(at + rank[i]);
+          at += vertex.length;
+          return order.map((i) => vertex[i]);
+        });
+        record.vertices = { weighted: true, bindings };
+        moved.set(record, to);
+      }
+    }
+  }
+  if (moved.size === 0) return;
+  /** A run moved with its influences: `start` and `run` over a deform array of `to.length` pairs. */
+  const movedRun = (start: number, run: readonly number[], to: readonly number[]): { start: number; run: number[] } => {
+    const spread = new Map<number, number>();
+    run.forEach((value, i) => {
+      const index = start + i;
+      spread.set(to[index >> 1] * 2 + (index & 1), value);
+    });
+    const indices = [...spread.keys()];
+    const first = Math.min(...indices);
+    const last = Math.max(...indices);
+    const out: number[] = [];
+    for (let i = first; i <= last; i++) out.push(spread.get(i) ?? 0);
+    return { start: first, run: out };
+  };
+  const recordOf = (skin: string, slot: string, placeholder: string): ModelVertexAttachment | undefined => {
+    const record = skins.find((s) => s.name === skin)?.attachments[slot]?.[placeholder];
+    return record !== undefined && isModelVertexAttachment(record) && moved.has(record) ? record : undefined;
+  };
+  for (const animation of animations.values()) {
+    for (const [skin, bySlot] of animation.attachments) {
+      for (const [slot, byPlaceholder] of bySlot) {
+        for (const [placeholder, timelines] of byPlaceholder) {
+          const record = recordOf(skin, slot, placeholder);
+          if (record === undefined || timelines.deform === undefined) continue;
+          const to = moved.get(record)!;
+          timelines.deform = timelines.deform.map((key) => {
+            if (!Array.isArray(key.vertices) || key.vertices.length === 0) return key;
+            const { start, run } = movedRun(typeof key.offset === 'number' ? key.offset : 0, key.vertices as number[], to);
+            // The key's fields in the order `compileDeformTrack` inserts them: `time`, `offset`, `vertices`, then the curve.
+            const rest = Object.fromEntries(Object.entries(key).filter(([field]) => field !== 'time' && field !== 'offset' && field !== 'vertices'));
+            return { time: key.time, ...(start !== 0 ? { offset: start } : {}), vertices: run, ...rest };
+          });
+        }
+      }
+    }
+  }
+  for (const report of deformTransforms) {
+    const record = recordOf(report.skin, report.slot, report.attachment);
+    if (record === undefined || report.expanded === undefined) continue;
+    report.expanded = movedRun(0, report.expanded, moved.get(record)!).run;
+  }
+}
+
 /** Every number of a weighted binding list on the float32 grid — what `.map(f32)` did to the run. */
 function bindingsOnF32(vertices: Extract<ModelVertices, { weighted: true }>): Extract<ModelVertices, { weighted: true }> {
   return {

package/src/core/constraints_physics.ts

@@ -189,6 +189,34 @@
  * reading is rejected as a schedule no player runs; the core suite's `SC`
  * controls plant it and turn the probe red on the steps after the key.
  *
+ * ## The environment (issue #1416)
+ *
+ * A constraint's `wind` and `gravity` are not forces: they are how strongly it
+ * answers two directions the SKELETON carries — spine-core 4.3.13's
+ * `Skeleton.windX, windY` and `gravityX, gravityY`, initially `1, 0` and `0,
+ * 1` (`DEFAULT_PHYSICS_ENVIRONMENT`). The step weighs them as the runtime
+ * does: for `x` and `y`, `ax = (wind·windX + gravity·gravityX)·R` and `ay =
+ * (wind·windY + gravity·gravityY)·R`, `velocity += (ax − offset·strength)·…`
+ * on `x` and `−= (ay + offset·strength)·…` on `y`; for the rotation and the
+ * scale the same two sums without `R`, `(ax·sin + ay·cos)·length/R` and `ax·cos
+ * − ay·sin` in place of the wind and gravity terms above. The skeleton's own
+ * scale, which the runtime multiplies the `x` and `y` sums by, is 1 here. So
+ * the environment's y points DOWN — `[0, 1]` pulls toward the bottom of the
+ * screen — and with the initial values every expression is the one this file
+ * computed before the environment existed: `wind·1 + gravity·0` is `wind` for
+ * every finite `gravity` (a `wind` of −0 aside, which it reads as +0, as the
+ * runtime does), and the render and emit bases did not move.
+ *
+ * The consumer sets it (`setEnvironment` on a live track, `./track.ts`), and
+ * moves the rig from outside with `translatePhysics` and `rotatePhysics` —
+ * `Skeleton.physicsTranslate` and `physicsRotate`, which shift what each
+ * constraint last saw (`ux, uy, cx, cy`) so its next update reads the bone as
+ * having moved. A constraint with no state yet is pending, and its first
+ * update overwrites both, so it is left alone, as the runtime's translation of
+ * it is read by nothing. The core suite's `CO56` holds all of it to spine-core
+ * given the same values at tolerance 0, and `CO57` that nothing set poses what
+ * was posed before.
+ *
  * ## What is not exact, and why
  *
  * Over 3,000 random rigs of three shapes (all five inherit modes; ik and
@@ -215,6 +243,9 @@
  */
 import { channelAt, keyIndexAt, poseAnimations, sampleTime, type CoreAnimationPose, type CoreCurve, type CoreKey, type SamplePhase, type TimelinePlant } from './animation.ts';
 import { RUNTIME_PI, type CoreWorld } from './world.ts';
+
+/** Degrees to radians as the runtime converts them (`MathUtils.degRad`, `pi / 180` with the runtime's pi). */
+const RUNTIME_RAD = RUNTIME_PI / 180;
 import { previousPassSlotBones, type CoreConstraintRecord } from './constraints.ts';
 import { activeBones, type CompiledDocument } from './index.ts';
 
@@ -577,6 +608,71 @@ export interface PhysicsStepContext {
   keyedNow?: Set<string>;
   /** A plant only (issue #1049, `sliderPhysicsFromCurrent: false`): each physics record's setup values, before the step's own animation. */
   setupRecords?: Map<string, CorePhysicsRecord>;
+  /**
+   * The world every constraint answers (issue #1416, the header's *The
+   * environment*): the skeleton's wind and gravity directions, as a caller set
+   * them on the live track. Absent, spine-core's own initial values
+   * (`DEFAULT_PHYSICS_ENVIRONMENT`), which is every walk but a live one a
+   * caller set it on.
+   */
+  env?: PhysicsEnvironment;
+}
+
+/**
+ * The world a physics constraint answers (issue #1416): spine-core 4.3.13's
+ * four skeleton fields `windX`, `windY`, `gravityX` and `gravityY`, as
+ * `wind: [windX, windY]` and `gravity: [gravityX, gravityY]` — the
+ * DIRECTIONS the constraints' own `wind` and `gravity` act along, which are
+ * each constraint's response to them (the header's *The environment*). In the
+ * runtime's convention: x to the right, **y down** — a positive y component
+ * pulls a constraint toward the bottom of the screen, as `gravity: [0, 1]`
+ * does.
+ */
+export interface PhysicsEnvironment {
+  readonly wind: readonly [number, number];
+  readonly gravity: readonly [number, number];
+}
+
+/** spine-core 4.3.13's initial `Skeleton.windX, windY, gravityX, gravityY` — `1, 0, 0, 1` — the world of every walk nobody set one on. */
+export const DEFAULT_PHYSICS_ENVIRONMENT: PhysicsEnvironment = Object.freeze({ wind: Object.freeze([1, 0] as const), gravity: Object.freeze([0, 1] as const) });
+
+/**
+ * `Skeleton.physicsTranslate(x, y)` on the states in `ctx` (issue #1416): every
+ * constraint's next update sees its bone moved by `(x, y)` in the skeleton's
+ * world (y up) — the consumer moved the whole rig by that much since the last
+ * pose. A constraint with no state yet has not been updated, and its first
+ * update is pending, so the runtime's translation of it is read by nothing.
+ */
+export function translatePhysics(ctx: PhysicsStepContext, x: number, y: number): void {
+  for (const s of ctx.states.values()) {
+    s.ux -= x;
+    s.uy -= y;
+    s.cx -= x;
+    s.cy -= y;
+  }
+}
+
+/**
+ * `Skeleton.physicsRotate(x, y, degrees)` on the states in `ctx` (issue
+ * #1416): every constraint's next update sees its bone turned by `degrees`
+ * (counter-clockwise, the runtime's pi) about `(x, y)` in the skeleton's world —
+ * a translation of each constraint by how far that turn carries the origin it
+ * last saw, as `PhysicsConstraint.rotate` computes it.
+ */
+export function rotatePhysics(ctx: PhysicsStepContext, x: number, y: number, degrees: number): void {
+  const r = degrees * RUNTIME_RAD;
+  const cos = Math.cos(r);
+  const sin = Math.sin(r);
+  for (const s of ctx.states.values()) {
+    const dx = s.cx - x;
+    const dy = s.cy - y;
+    const tx = dx * cos - dy * sin - dx;
+    const ty = dx * sin + dy * cos - dy;
+    s.ux -= tx;
+    s.uy -= ty;
+    s.cx -= tx;
+    s.cy -= ty;
+  }
 }
 
 /** A constraint's state in `ctx`, created fresh on its first update. */
@@ -634,6 +730,7 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
   s.lastTime = ctx.time;
   const bx = w.worldX;
   const by = w.worldY;
+  const env = ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
   let z = 0;
   if (s.pending) {
     s.pending = false;
@@ -664,16 +761,19 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
         const e = r.strength;
         const wind = r.wind * f;
         const g = r.gravity * f;
+        // The environment's directions (issue #1416), as the runtime weighs them; the skeleton's scale is 1 here, so its factor is left out.
+        const ax = wind * env.wind[0] + g * env.gravity[0];
+        const ay = wind * env.wind[1] + g * env.gravity[1];
         const xs = s.xOffset;
         const ys = s.yOffset;
         do {
           if (x) {
-            s.xVelocity += (wind - s.xOffset * e) * m;
+            s.xVelocity += (ax - s.xOffset * e) * m;
             s.xOffset += s.xVelocity * t;
             s.xVelocity *= d;
           }
           if (y) {
-            s.yVelocity -= (g + s.yOffset * e) * m;
+            s.yVelocity -= (ay + s.yOffset * e) * m;
             s.yOffset += s.yVelocity * t;
             s.yVelocity *= d;
           }
@@ -720,20 +820,20 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
         if (d === -1) d = Math.pow(r.damping, 60 * t);
         const m = r.massInverse * t;
         const e = r.strength;
-        const wind = r.wind;
-        const g = r.gravity;
+        const ax = r.wind * env.wind[0] + r.gravity * env.gravity[0];
+        const ay = r.wind * env.wind[1] + r.gravity * env.gravity[1];
         const h = l / f;
         const rs = s.rotateOffset;
         const ss = s.scaleOffset;
         for (;;) {
           a -= t;
           if (scaleX) {
-            s.scaleVelocity += (wind * c - g * sn - s.scaleOffset * e) * m;
+            s.scaleVelocity += (ax * c - ay * sn - s.scaleOffset * e) * m;
             s.scaleOffset += s.scaleVelocity * t;
             s.scaleVelocity *= d;
           }
           if (rotateOrShearX) {
-            s.rotateVelocity -= ((wind * sn + g * c) * h + s.rotateOffset * e) * m;
+            s.rotateVelocity -= ((ax * sn + ay * c) * h + s.rotateOffset * e) * m;
             s.rotateOffset += s.rotateVelocity * t;
             s.rotateVelocity *= d;
             if (a < t) break;

package/src/core/entry.ts

@@ -18,7 +18,9 @@
  * ⚠️ A symbol is listed here only because a dependant was seen using it,
  * or asked for it in writing before it could be (`openTrack`, issue #1276;
  * `openTracks`, issue #1336; `physicsClockStep` and `PHYSICS_CLOCK_LEAD`,
- * the clock a live track's `clock` option takes, issue #1396).
+ * the clock a live track's `clock` option takes, issue #1396;
+ * `PhysicsEnvironment`, what a live track's `setEnvironment` takes, issue
+ * #1416).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
@@ -28,7 +30,7 @@ export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setup
 export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } from './track.ts';
-export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust } from './track.ts';
+export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust, PhysicsEnvironment } from './track.ts';
 export { openTracks } from './tracks.ts';
 export type { LiveTracks, TracksOptions, MixOptions, QueueOptions, TrackEntryView } from './tracks.ts';
 export type { WalkPose } from './walk.ts';

package/src/core/raw.ts

@@ -116,7 +116,7 @@
 import { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
 import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type CoreAnimationTimelines, type LocalAdjust, type TimelinePlant } from './animation.ts';
 import { constraintsAbsentWhy, pathAnimationsWhy } from './constraints.ts';
-import { freshStepContext, steppedPreviousPassWhy } from './constraints_physics.ts';
+import { freshStepContext, rotatePhysics, steppedPreviousPassWhy, translatePhysics, DEFAULT_PHYSICS_ENVIRONMENT, type PhysicsEnvironment, type PhysicsStepContext } from './constraints_physics.ts';
 import { attachmentStates } from './deform.ts';
 import { drawOrderAt, type CoreDrawOrderKey } from './draw_order.ts';
 import { eventsFired, type CoreEventRow } from './events.ts';
@@ -575,6 +575,53 @@ export function checkedClock(clock: (dt: number) => number, who: string): (dt: n
   };
 }
 
+/**
+ * A live track's `setEnvironment` (issue #1416, `./track.ts` and `./tracks.ts`):
+ * the world every physics constraint answers from the next pose on, set on the
+ * track's physics context — `wind` and `gravity` each a pair of finite numbers,
+ * either left out to keep the one that stands, and nothing else — or refused by
+ * name, before anything moves. The pair is copied: the caller's array changed
+ * later moves nothing.
+ */
+export function setEnvironmentOn(ctx: PhysicsStepContext, env: unknown, who: string): void {
+  if (typeof env !== 'object' || env === null || Array.isArray(env)) throw new CoreInputError(`${who} setEnvironment was given ${env === null ? 'null' : Array.isArray(env) ? 'an array' : typeof env}, not an object { wind?: [x, y], gravity?: [x, y] }`);
+  const given = env as Record<string, unknown>;
+  for (const key of Object.keys(given)) {
+    if (key !== 'wind' && key !== 'gravity') throw new CoreInputError(`${who} setEnvironment names "${key}", which is not one of [wind, gravity]`);
+  }
+  const pair = (key: 'wind' | 'gravity'): readonly [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 new CoreInputError(`${who} setEnvironment's ${key} is ${JSON.stringify(v)}, not a pair of finite numbers [x, y] (x to the right, y down)`);
+    return Object.freeze([v[0] as number, v[1] as number] as const);
+  };
+  const wind = pair('wind');
+  const gravity = pair('gravity');
+  const standing = ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
+  ctx.env = Object.freeze({ wind: wind ?? standing.wind, gravity: gravity ?? standing.gravity });
+}
+
+/** The environment a live track's physics answers now (`setEnvironmentOn`): spine-core's initial one where none was set. */
+export function environmentOf(ctx: PhysicsStepContext): PhysicsEnvironment {
+  return ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
+}
+
+/** A live track's `physicsTranslate` (issue #1416): `x` and `y` finite, or refused by name before anything moves; then `translatePhysics`. */
+export function translateOn(ctx: PhysicsStepContext, x: number, y: number, who: string): void {
+  for (const [k, v] of [['x', x], ['y', y]] as const) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) throw new CoreInputError(`${who} physicsTranslate's ${k} is ${String(v)}, not a finite distance in the skeleton's world`);
+  }
+  translatePhysics(ctx, x, y);
+}
+
+/** A live track's `physicsRotate` (issue #1416): `x`, `y` and `degrees` finite, or refused by name before anything moves; then `rotatePhysics`. */
+export function rotateOn(ctx: PhysicsStepContext, x: number, y: number, degrees: number, who: string): void {
+  for (const [k, v] of [['x', x], ['y', y], ['degrees', degrees]] as const) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) throw new CoreInputError(`${who} physicsRotate's ${k} is ${String(v)}, not a finite number`);
+  }
+  rotatePhysics(ctx, x, y, degrees);
+}
+
 /**
  * The animation time a looping track applies its animation at (`./walk.ts`,
  * *The time*): the track time wrapped by the duration, and 0 over a duration

package/src/core/track.ts

@@ -174,6 +174,36 @@
  * `AnimationState` updated by the step and its `Skeleton` by the clock), and
  * `CO55` that the times and the events are those of the walk without it.
  *
+ * ## The environment, and the rig moved from outside (issue #1416)
+ *
+ * The rig states how each physics constraint answers the world — its `wind`
+ * and `gravity` — and the consumer states the world. `setEnvironment({ wind,
+ * gravity })` sets it from the next pose on and it stands until set again,
+ * as spine-core's four `Skeleton` fields do: `wind` is `[windX, windY]`,
+ * `gravity` is `[gravityX, gravityY]`, x to the right and **y down**, and
+ * until set it is the runtime's own `{ wind: [1, 0], gravity: [0, 1] }`
+ * (`./constraints_physics.ts`, *The environment*). Either half may be left
+ * out to keep the one that stands. So a gust is the consumer setting `wind`
+ * to `[0, 0]` at rest and `[k, 0]` while it blows, and a constraint that
+ * states `wind: 0` does not feel it — the response is the rig's, the gust the
+ * scene's.
+ *
+ * `physicsTranslate(x, y)` and `physicsRotate(x, y, degrees)` are the
+ * runtime's `Skeleton` methods of those names: the consumer moved or turned
+ * the whole rig since the last pose — in the skeleton's world, y up, degrees
+ * counter-clockwise — and every constraint's next update sees its bone move
+ * by that much, so a rig walked across the screen trails what hangs from it.
+ * A player forwards what spine-core's `SkeletonPhysicsMovement` forwards: the
+ * change of its display object's position since the last frame, converted into
+ * the skeleton's units and axes, and the change of its rotation about the
+ * skeleton's origin, `physicsRotate(0, 0, Δ)`, both before the `step` that
+ * poses the frame.
+ *
+ * `CO56` holds the poses to spine-core 4.3.13 given the same values on its
+ * `Skeleton`, and holds red the readings the mapping rejects; `CO57` holds that
+ * nothing set — or the runtime's own values set on every step and a move of 0
+ * — poses what the track posed before the methods existed, bit for bit.
+ *
  * ## The oracle chain
  *
  * Nothing here is held to spine-core directly but the events: the live track
@@ -192,9 +222,11 @@
  * history, so a seek is "open, then step to the time".
  */
 import { CoreInputError, type CompiledDocument } from './index.ts';
-import { checkedClock, openRawTrack, stepRawTrack, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.ts';
+import { checkedClock, environmentOf, openRawTrack, rotateOn, setEnvironmentOn, stepRawTrack, translateOn, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.ts';
 import type { LocalAdjust, TimelinePlant } from './animation.ts';
+import type { PhysicsEnvironment } from './constraints_physics.ts';
 export type { AdjustableLocals, BoneLocals, LocalAdjust } from './animation.ts';
+export type { PhysicsEnvironment } from './constraints_physics.ts';
 
 /** How a live track is opened: whether it loops, and where its physics is reset (`RawReset`) — both the caller's, neither with a default — the caller's adjustment of every pose's bone locals (the header's *The adjustment*), and what each step moves the physics clock by (the header's *The physics clock*). */
 export interface TrackOptions {
@@ -217,6 +249,14 @@ export interface LiveTrack {
   readonly animationTime: number;
   /** The runtime's duration of the animation (`CoreAnimationTimelines.duration`). */
   readonly duration: number;
+  /** Sets the world every physics constraint answers from the next pose on (the header's *The environment*): `wind` and `gravity` as spine-core's `Skeleton.windX, windY` and `gravityX, gravityY` — x right, y down — either left out to keep the one that stands. Until set, `{ wind: [1, 0], gravity: [0, 1] }`, the runtime's own. */
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void;
+  /** The environment the next pose answers. */
+  readonly environment: PhysicsEnvironment;
+  /** spine-core's `Skeleton.physicsTranslate`: the consumer moved the whole rig by `(x, y)` in the skeleton's world (y up) since the last pose, and every physics constraint's next update sees it. */
+  physicsTranslate(x: number, y: number): void;
+  /** spine-core's `Skeleton.physicsRotate`: the consumer turned the whole rig by `degrees` (counter-clockwise) about `(x, y)` in the skeleton's world since the last pose. */
+  physicsRotate(x: number, y: number, degrees: number): void;
 }
 
 /** The two modes: a track that holds at its duration is the raw entry's walk; a looping one fires its events across the wrap and cuts its clipped rows (`live`). Neither keeps a non-finite value. */
@@ -264,6 +304,30 @@ class Track implements LiveTrack {
     return this.track.duration;
   }
 
+  get environment(): PhysicsEnvironment {
+    return environmentOf(this.track.ctx);
+  }
+
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void {
+    this.live('setEnvironment');
+    setEnvironmentOn(this.track.ctx, environment, 'the live track\'s');
+  }
+
+  physicsTranslate(x: number, y: number): void {
+    this.live('physicsTranslate');
+    translateOn(this.track.ctx, x, y, 'the live track\'s');
+  }
+
+  physicsRotate(x: number, y: number, degrees: number): void {
+    this.live('physicsRotate');
+    rotateOn(this.track.ctx, x, y, degrees, 'the live track\'s');
+  }
+
+  /** A refused track refuses every call that would move it, naming the step it was refused at. */
+  private live(call: string): void {
+    if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again (${call} not made)`);
+  }
+
   step(dt: number): RawPose {
     const n = this.steps + 1;
     if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again`);

package/src/core/tracks.ts

@@ -164,7 +164,8 @@ import { activeBones, CoreInputError, rawNumber, readColour, shownAttachment, ty
 import { channelAt, keyIndexAt, SLOT_COLOUR_TIMELINES, slotRowsFrom, steppedLocalsWorld, type BoneTimelineKind, type CoreKey, type LocalAdjust, type SlotBase, type SlotColourKind, type TimelinePlant } from './animation.ts';
 import { deformAt, setupArray, type CoreAttachmentTimeline } from './deform.ts';
 import { eventsFired, type CoreEventKey, type CoreEventRow } from './events.ts';
-import { checkedClock, openRawTracksPath, type RawPose, type RawReset, type RawTracksPath } from './raw.ts';
+import { checkedClock, environmentOf, openRawTracksPath, rotateOn, setEnvironmentOn, translateOn, type RawPose, type RawReset, type RawTracksPath } from './raw.ts';
+import type { PhysicsEnvironment } from './constraints_physics.ts';
 import { slotTimelinesApply } from './skins.ts';
 
 /** How the live tracks are opened: where the physics is reset (`RawReset`, the caller's, no default), the caller's adjustment of every pose's bone locals, and what each step moves the physics clock by (the header's *The physics clock*). */
@@ -228,6 +229,14 @@ export interface LiveTracks {
   current(track: number): TrackEntryView | null;
   /** The running sum of the steps taken, 0 before the first. */
   readonly trackTime: number;
+  /** Sets the world every physics constraint answers from the next pose on, as `LiveTrack.setEnvironment` (`./track.ts`, *The environment*). */
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void;
+  /** The environment the next pose answers. */
+  readonly environment: PhysicsEnvironment;
+  /** spine-core's `Skeleton.physicsTranslate`, as `LiveTrack.physicsTranslate`. */
+  physicsTranslate(x: number, y: number): void;
+  /** spine-core's `Skeleton.physicsRotate`, as `LiveTrack.physicsRotate`. */
+  physicsRotate(x: number, y: number, degrees: number): void;
 }
 
 /**
@@ -1333,6 +1342,25 @@ class Tracks implements LiveTracks {
     return this.time;
   }
 
+  get environment(): PhysicsEnvironment {
+    return environmentOf(this.path.ctx);
+  }
+
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void {
+    this.live('setEnvironment');
+    setEnvironmentOn(this.path.ctx, environment, 'the live tracks\'');
+  }
+
+  physicsTranslate(x: number, y: number): void {
+    this.live('physicsTranslate');
+    translateOn(this.path.ctx, x, y, 'the live tracks\'');
+  }
+
+  physicsRotate(x: number, y: number, degrees: number): void {
+    this.live('physicsRotate');
+    rotateOn(this.path.ctx, x, y, degrees, 'the live tracks\'');
+  }
+
   private live(call: string): void {
     if (this.refused !== null) throw new CoreInputError(`the live tracks were refused at ${this.refused}, after their entries and physics had moved; open them again (${call} not made)`);
   }

package/src/validate.ts

@@ -156,6 +156,7 @@ import type { ConstraintTargetFacts, TargetAnimation, TargetKeyArray } from './a
 import { a34ConstraintTimelineTargets } from './assertions/bodies/a34.ts';
 import { a40SlidersComposeOnASharedTarget } from './assertions/bodies/a40.ts';
 import { a10NoNanAfterStepping } from './assertions/bodies/a10.ts';
+import { a52WeightedVerticesShareOneBoneOrder } from './assertions/bodies/a52.ts';
 import type { SteppedFrame, SteppedPoseFacts } from './assertions/facts/stepped_poses.ts';
 
 export type { Failure } from './assertions/harness.ts';
@@ -2460,6 +2461,11 @@ export function validate(input: ValidateInput): ValidateReport {
     }
   });
 
+  // A52 (issue #1407) reads the raw text as A31 and A35 do: the order a weighted
+  // run lists its bones in is a fact of the file the Spine editor refuses and
+  // spine-core loads, so it runs whether or not the round trip does.
+  check('A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER', () => a52WeightedVerticesShareOneBoneOrder(verdicts, raw));
+
   // --- A: the round trip ----------------------------------------------------
   // The two loaded objects come back OUT of the assertion rather than being
   // assigned into it. Everything below reads them, and a `let` written inside a