spine-rigc 2.51.1 → 2.53.0

package/docs/AUTHORING.md

@@ -3119,7 +3119,7 @@ beside it say how a distance becomes a share.
 | --- | --- |
 | `cell` | **required.** The lattice's square, in the part's pixels — a whole number of at least 1. No default: it is a length on this art, and how fine a mesh the part needs is not something rigc can read off it |
 | `bones` | **required, at least one entry.** Which segments may pull the part. An entry is one of three forms, below |
-| `falloff` | **required**, because `radius` is: `{ "power"?, "radius", "maxBones"?, "minWeight"? }` |
+| `falloff` | **required unless `influence` is stated**, because `radius` is: `{ "power"?, "radius", "maxBones"?, "minWeight"? }`. Stated beside `influence`, refused — the two are two models of one share |
 | `radius` | **required.** Added to every distance before the power is taken, in the part's pixels, so a vertex ON a segment has a finite pull and the blend between two segments is about this wide. Positive |
 | `power` | the exponent a pull falls off by: `w = 1 / (d + radius)^power`. Positive. Default `2` |
 | `maxBones` | at most this many bones pull one vertex — the strongest ones. A whole number of at least 1. Default `4` |
@@ -3127,6 +3127,8 @@ beside it say how a distance becomes a share.
 | `alpha` | the alpha at or above which a pixel counts as art, `1`..`255`. Default `1` — `contour`'s own |
 | `anchor` | where the **slot bone** sits in the part's pixels, `[x, y]`, y down. Default the window's centre — the placement every generator on this route uses (the ⭐ above). State it when the art is not drawn centred on its bone: unlike a pinned generator, this one's weights depend on where the art is relative to the bones |
 
+| `influence` | instead of `falloff`: a pull that **reaches zero** at its own `radius` — `{ "radius", "across", "max", "shape" }`, every field required. Below |
+
 **The three forms of a `bones` entry**, each resolved by name against the rig:
 
 | Entry | Its segment(s) |
@@ -3154,6 +3156,70 @@ of each segment, the strongest `maxBones` kept and normalised, any share under
 `minWeight` dropped, the rest normalised again — so every vertex closes at 1 by
 construction. The emitted mesh is a weighted one, bound by name.
 
+##### `influence` — a vertex follows every link near it (cloth)
+
+`falloff`'s pull, `1 / (d + radius)^power`, is positive at **every** distance: a
+wider blend needs a larger `radius`, which flattens the blend everywhere at once,
+and a blend only ends where `minWeight` drops a share. A cloth surface wants the
+other model — each vertex blends the springs of the chains around it, so the
+sheet bends as one surface rather than as strips — and that needs a pull that
+falls to **exactly zero** at a stated distance. `influence` is that model.
+
+```json
+"generator": {
+  "kind": "segments",
+  "cell": 8,
+  "bones": [["skirt_0_0", "skirt_0_1", "skirt_0_2"], ["skirt_1_0", "skirt_1_1", "skirt_1_2"]],
+  "influence": { "radius": 40, "across": true, "max": 6, "shape": "smooth" }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `radius` | **required.** How far a link reaches, in the part's pixels (on this route, the skeleton's units): a link whose segment is `radius` or farther from a vertex never pulls it. Positive. No default — a length on this art |
+| `across` | **required.** `true`: every link of every `bones` entry within `radius` pulls. `false`: only the links of **one** entry — the entry holding the link nearest the vertex, the earlier entry on a tie — so a chain moves its own strip and nothing across. No default: whether a chain may pull its neighbour's cloth is the decision |
+| `max` | **required.** At most this many links pull one vertex — the strongest; equal pulls keep the order `bones` first names their bones. A whole number of at least 1 |
+| `shape` | **required.** How a pull falls from 1 at `d = 0` to 0 at `d = radius`, with `x = d / radius`: `"linear"` is `1 - x`; `"smooth"` is `1 - x²(3 - 2x)`, which also arrives at both ends with zero slope, so a link enters and leaves a vertex's blend without a crease |
+
+Per vertex, in order: `d` is the distance to each link's **segment** — its
+nearest point, the reading `falloff` takes — at the setup pose; with `across:
+false` only the nearest entry's links stay; each link with `d < radius` pulls
+`shape(d / radius)` (a bone two segments name keeps the nearer, and a link whose
+pull is not above 0 in doubles — a hair inside the reach — pulls nothing); the
+strongest `max` are kept and normalised; a share the 6-decimal grid would write
+as 0 is dropped and the rest normalised again; the strongest closes the vertex
+at exactly 1. **The distance is to the segment, not to the bone's origin**,
+because a vertex on the middle of a link *is* on that link: an origin distance
+would put it half a link away, and hand the joint at the link's tip to the child
+whose origin sits there.
+
+🔸 **One bone order by construction.** Every vertex lists its bones in the order
+`bones` names them, so the attachment has one order and
+`A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER` holds without the compiler's
+ascending rewrite (§5.2) moving a byte — the order in the file is the spec's.
+
+`build` prints a `reach` line under the `influence` line: the block as stated,
+how many vertices had **more links in reach than `max`** — the vertices the cap
+dropped a link from — and the most links in reach at one vertex (`widest`),
+which is the `max` that would drop none:
+
+```
+        influence  max 6 bone(s) per vertex, mean 4.87, 0 of 450 vertices (0.00%) on a single bone
+        reach      radius 40px, smooth, across entries, max 6: 146 of 450 vertices had more links in reach than max (widest 10)
+```
+
+⚠️ **What a tight cap costs, measured.** On the selftest's `skirt_probe`
+(`fixtures/public.ts`: six chains of five links, a physics constraint on every
+link, the hip swayed) with `radius: 40`, `rotate` physics on and `render --folds`
+at 30 fps, `max: 2` turned 106 of the 816 triangles over on its worst frame and
+`max: 6` turned 4; `max: 6` with `radius: 20` (no vertex capped) turned 105, and
+`across: false` 91. With the physics removed the same sway folds none at either
+cap. So on that piece the folds followed how many neighbouring links a vertex
+blends — a narrow reach and a tight cap over a wide reach both fold — and a
+wide reach with a cap that drops few links folded least. One piece and one
+sway: it says what to look at with `render --folds` on your own, not what `max`
+your cloth needs.
+
 `build` and `explain` print what it measured, under the mesh's line. This is
 the selftest's own `segments_probe` (`fixtures/public.ts` in the repository) —
 one 96x64 plate of two islands under two two-link chains, `cell: 8`,
@@ -3199,6 +3265,9 @@ rows.
 | a chain link at its next link's origin | `… the two bones share their setup origin (…), so the link has no length and no direction to weight along` |
 | an empty chain, a span with a malformed end, an entry of none of the three forms | `is an empty chain`; `both ends are [x, y] in the part's pixels`; `an entry is a bone name, a chain as a list of bone names, or { "bone", "from", "to" }` |
 | no `falloff`, a `radius` or `power` at or below 0, a malformed `anchor`, a `cell` under 1, no `image` | each named by its field — `radius` has no default because it is a length on this art |
+| both `falloff` and `influence` | `the "segments" generator states both "falloff" and "influence" … a mesh is weighted by one of them: remove the other` |
+| an `influence` field absent or out of range — `radius` at or below 0, `across` not a boolean, `max` not a whole number of at least 1, `shape` not `"linear"` or `"smooth"` | each named with the value found and the one required: `"influence.max" is 0; it is how many links may pull one vertex …`, `"influence.shape" is "cubic"; one of "linear", "smooth" …` |
+| a vertex no link reaches under `influence` | `vertex 0, at (0, 0) in the part's pixels, is reached by no link — the nearest is "skirt_0_0" at 17.8885, and "influence.radius" is 4` — **refused, not handed the nearest link**: raise `radius` over that distance, or name a segment nearer that part of the art |
 | a part on a packed page that declares a `scale:` | refused: `cell` and `radius` are the part's pixels and this generator does not convert them to a page's texels. Build from the loose part, or a pack at scale 1 |
 
 #### 3.4.8 A skin that switches bones and constraints on
@@ -4953,6 +5022,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.51.1",
+  "version": "2.53.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/cli/shared.ts

@@ -458,6 +458,11 @@ export function meshInfluenceNote(m: CompileResult['meshes'][number]): string {
     `\n        influence  max ${inf.maxBones} bone(s) per vertex, mean ${inf.meanBones.toFixed(2)}, ` +
     `${inf.singleBone} of ${m.vertices} vertices (${single.toFixed(2)}%) on a single bone` +
     (unbound.length ? `; named and bound by no vertex: ${unbound.join(', ')}` : '') +
+    (inf.reach === undefined
+      ? ''
+      : `\n        reach      radius ${inf.reach.radius}px, ${inf.reach.shape}, ` +
+        `${inf.reach.across ? 'across entries' : 'nearest entry only'}, max ${inf.reach.max}: ` +
+        `${inf.reach.capped} of ${m.vertices} vertices had more links in reach than max (widest ${inf.reach.widest})`) +
     `\n        lattice    cell ${inf.cell}px, ${inf.cols}x${inf.rows} cells, ${inf.artCells} with art, ${inf.keptCells} kept` +
     (inf.islands > 1 || joined > 0
       ? ` (${inf.islands} island(s) joined into one outline, ${joined} cell(s) added that hold no art)`

package/src/compile.ts

@@ -63,6 +63,8 @@ import {
   type RigEvent,
   type RigLinkedMeshAttachment,
   type RigMeshAttachment,
+  type RigSegmentsFalloff,
+  RIG_INFLUENCE_SHAPES,
   type RigMeshBinding,
   type RigPathAttachment,
   type RigRegionAttachment,
@@ -87,9 +89,12 @@ import {
   ringControlAngles,
   buildSegmentsLattice,
   segmentShares,
+  influenceShares,
   traceOutline,
   type MeshBoneRef,
-  type WorldSegment,
+  type EntrySegment,
+  type SegmentsInfluence,
+  type SegmentsFalloff,
   type MeshFitReport,
   type MeshGeometry,
   type MeshVertexWeight,
@@ -6502,6 +6507,95 @@ function finitePair(v: unknown): [number, number] | null {
     : null;
 }
 
+/** The `falloff` block's four numbers, each refused by name when it cannot be one. */
+function segmentsFalloffOf(f: RigSegmentsFalloff, where: string): SegmentsFalloff {
+  if (typeof f.radius !== 'number' || !Number.isFinite(f.radius) || !(f.radius > 0)) {
+    throw new CompileError(
+      `${where}: "falloff.radius" is ${JSON.stringify(f.radius)}; it is added to every distance before the power is ` +
+        "taken, a positive number of the part's pixels — at 0 a vertex on a segment would carry an infinite pull",
+    );
+  }
+  const power = f.power ?? SEGMENTS_DEFAULTS.power;
+  if (typeof power !== 'number' || !Number.isFinite(power) || !(power > 0)) {
+    throw new CompileError(
+      `${where}: "falloff.power" is ${JSON.stringify(power)}; it is the exponent a pull falls off with distance by, ` +
+        'a positive number — at 0 or below the far segment pulls as hard as the near one, or harder',
+    );
+  }
+  const maxBones = f.maxBones ?? SEGMENTS_DEFAULTS.maxBones;
+  if (typeof maxBones !== 'number' || !Number.isInteger(maxBones) || maxBones < 1) {
+    throw new CompileError(
+      `${where}: "falloff.maxBones" is ${JSON.stringify(maxBones)}; it is how many bones may pull one vertex, a ` +
+        'whole number of at least 1',
+    );
+  }
+  const minWeight = f.minWeight ?? SEGMENTS_DEFAULTS.minWeight;
+  if (typeof minWeight !== 'number' || !Number.isFinite(minWeight) || minWeight < SEGMENTS_WEIGHT_STEP || minWeight >= 1) {
+    throw new CompileError(
+      `${where}: "falloff.minWeight" is ${JSON.stringify(minWeight)}; it is the share under which a bone's pull ` +
+        `is dropped, so it lies in ${SEGMENTS_WEIGHT_STEP}..1 with 1 excluded — at 1 or above every share is dropped, ` +
+        `and under ${SEGMENTS_WEIGHT_STEP}, one step of the 6-decimal grid weights are written on, a kept binding ` +
+        'could be written as 0',
+    );
+  }
+  return { power, radius: f.radius, maxBones, minWeight };
+}
+
+/**
+ * The `influence` block's four fields (issue #1415), each refused by name: none
+ * has a default, because the reach and the cap are judgements about this
+ * cloth and the shape decides how a link enters a vertex's blend. Stated
+ * beside `falloff` it is refused too — the two are two models of one share.
+ */
+function segmentsInfluenceOf(
+  generator: Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'segments' }>,
+  where: string,
+): SegmentsInfluence {
+  const spec: unknown = generator.influence;
+  if (generator.falloff !== undefined) {
+    throw new CompileError(
+      `${where}: the "segments" generator states both "falloff" and "influence". Both turn a distance into a ` +
+        'share — "falloff" as 1 / (d + radius)^power over every segment, "influence" as a pull that reaches zero at ' +
+        'its "radius" — and a mesh is weighted by one of them: remove the other',
+    );
+  }
+  if (typeof spec !== 'object' || spec === null || Array.isArray(spec)) {
+    throw new CompileError(
+      `${where}: "influence" is ${JSON.stringify(spec)}; it is { "radius", "across", "max", "shape" }, every one required`,
+    );
+  }
+  const i = spec as Partial<Record<keyof SegmentsInfluence, unknown>>;
+  if (typeof i.radius !== 'number' || !Number.isFinite(i.radius) || !(i.radius > 0)) {
+    throw new CompileError(
+      `${where}: "influence.radius" is ${JSON.stringify(i.radius) ?? 'absent'}; it is how far a link reaches, in ` +
+        "the part's pixels, a positive number with no default — a length on this art: a link whose segment is that " +
+        'far from a vertex or farther never pulls it',
+    );
+  }
+  if (typeof i.across !== 'boolean') {
+    throw new CompileError(
+      `${where}: "influence.across" is ${JSON.stringify(i.across) ?? 'absent'}; it is true (every link within ` +
+        '"radius" pulls, across the entries of "bones") or false (only the links of the entry nearest the vertex), ' +
+        "with no default — whether a chain may pull its neighbour's cloth is the decision this field is",
+    );
+  }
+  if (typeof i.max !== 'number' || !Number.isInteger(i.max) || i.max < 1) {
+    throw new CompileError(
+      `${where}: "influence.max" is ${JSON.stringify(i.max) ?? 'absent'}; it is how many links may pull one vertex, ` +
+        'the strongest kept, a whole number of at least 1 with no default',
+    );
+  }
+  const shape = RIG_INFLUENCE_SHAPES.find((name) => name === i.shape);
+  if (shape === undefined) {
+    throw new CompileError(
+      `${where}: "influence.shape" is ${JSON.stringify(i.shape) ?? 'absent'}; one of ` +
+        `${RIG_INFLUENCE_SHAPES.map((name) => JSON.stringify(name)).join(', ')} — how a pull falls from 1 on a link ` +
+        'to 0 at "radius", with no default: "linear" is 1 - d/radius, "smooth" arrives at both ends with zero slope',
+    );
+  }
+  return { radius: i.radius, across: i.across, max: i.max, shape };
+}
+
 /**
  * Build a `segments` mesh: a lattice over the part's alpha, weighted by distance
  * to the bone segments `bones` names.
@@ -6550,45 +6644,18 @@ function buildSegmentsAttachment(
     );
   }
 
-  // -- the falloff -----------------------------------------------------------
+  // -- the influence (issue #1415), or else the falloff ----------------------
+  const influence = generator.influence === undefined ? null : segmentsInfluenceOf(generator, where);
   const falloffSpec: unknown = generator.falloff;
-  if (typeof falloffSpec !== 'object' || falloffSpec === null || Array.isArray(falloffSpec)) {
+  if (influence === null && (typeof falloffSpec !== 'object' || falloffSpec === null || Array.isArray(falloffSpec))) {
     throw new CompileError(
       `${where}: the "segments" generator states no "falloff" block. Its "radius" — added to every distance, in ` +
         "the part's pixels — has no default, because it is a length on this art: " +
-        '"falloff": { "radius": <pixels> } is the least it takes',
-    );
-  }
-  const f = generator.falloff;
-  if (typeof f.radius !== 'number' || !Number.isFinite(f.radius) || !(f.radius > 0)) {
-    throw new CompileError(
-      `${where}: "falloff.radius" is ${JSON.stringify(f.radius)}; it is added to every distance before the power is ` +
-        "taken, a positive number of the part's pixels — at 0 a vertex on a segment would carry an infinite pull",
-    );
-  }
-  const power = f.power ?? SEGMENTS_DEFAULTS.power;
-  if (typeof power !== 'number' || !Number.isFinite(power) || !(power > 0)) {
-    throw new CompileError(
-      `${where}: "falloff.power" is ${JSON.stringify(power)}; it is the exponent a pull falls off with distance by, ` +
-        'a positive number — at 0 or below the far segment pulls as hard as the near one, or harder',
-    );
-  }
-  const maxBones = f.maxBones ?? SEGMENTS_DEFAULTS.maxBones;
-  if (typeof maxBones !== 'number' || !Number.isInteger(maxBones) || maxBones < 1) {
-    throw new CompileError(
-      `${where}: "falloff.maxBones" is ${JSON.stringify(maxBones)}; it is how many bones may pull one vertex, a ` +
-        'whole number of at least 1',
-    );
-  }
-  const minWeight = f.minWeight ?? SEGMENTS_DEFAULTS.minWeight;
-  if (typeof minWeight !== 'number' || !Number.isFinite(minWeight) || minWeight < SEGMENTS_WEIGHT_STEP || minWeight >= 1) {
-    throw new CompileError(
-      `${where}: "falloff.minWeight" is ${JSON.stringify(minWeight)}; it is the share under which a bone's pull ` +
-        `is dropped, so it lies in ${SEGMENTS_WEIGHT_STEP}..1 with 1 excluded — at 1 or above every share is dropped, ` +
-        `and under ${SEGMENTS_WEIGHT_STEP}, one step of the 6-decimal grid weights are written on, a kept binding ` +
-        'could be written as 0',
+        '"falloff": { "radius": <pixels> } is the least it takes (or an "influence" block, whose pull reaches zero ' +
+        'at its own "radius")',
     );
   }
+  const falloff = influence === null ? segmentsFalloffOf(generator.falloff!, where) : null;
   const threshold = generator.alpha ?? SEGMENTS_DEFAULTS.alpha;
 
   // -- the lattice -----------------------------------------------------------
@@ -6650,7 +6717,7 @@ function buildSegmentsAttachment(
   const parentOf = new Map(ctx.bones.map((b) => [b.name, b.parent ?? null]));
   const named: string[] = [];
   const refs: MeshBoneRef[] = [];
-  const segments: WorldSegment[] = [];
+  const segments: EntrySegment[] = [];
   const boneOf = (name: unknown, at: string): { index: number; transform: BoneTransform } => {
     if (typeof name !== 'string' || !parentOf.has(name)) {
       throw new CompileError(`${where}: ${at} names mesh bone ${JSON.stringify(name)}, which is not in the rig's bone list`);
@@ -6680,7 +6747,7 @@ function buildSegmentsAttachment(
     const at = `"bones"[${i}]`;
     if (typeof entry === 'string') {
       const { index, transform } = boneOf(entry, at);
-      segments.push({ bone: index, a: [transform.worldX, transform.worldY], b: tipOf(entry, transform, at, false) });
+      segments.push({ bone: index, entry: i, a: [transform.worldX, transform.worldY], b: tipOf(entry, transform, at, false) });
       return;
     }
     if (Array.isArray(entry)) {
@@ -6692,7 +6759,7 @@ function buildSegmentsAttachment(
         const name = link.name as string;
         const origin: [number, number] = [link.transform.worldX, link.transform.worldY];
         if (k === links.length - 1) {
-          segments.push({ bone: link.index, a: origin, b: tipOf(name, link.transform, `${at}[${k}]`, true) });
+          segments.push({ bone: link.index, entry: i, a: origin, b: tipOf(name, link.transform, `${at}[${k}]`, true) });
           return;
         }
         const next = links[k + 1];
@@ -6714,7 +6781,7 @@ function buildSegmentsAttachment(
               `"${nextName}" its own position, or name "${name}" alone with a "length"`,
           );
         }
-        segments.push({ bone: link.index, a: origin, b });
+        segments.push({ bone: link.index, entry: i, a: origin, b });
       });
       return;
     }
@@ -6729,7 +6796,7 @@ function buildSegmentsAttachment(
             `${JSON.stringify(from === null ? span.from : span.to)}; both ends are [x, y] in the part's pixels, y down`,
         );
       }
-      segments.push({ bone: index, a: measuredAt(from[0], from[1]), b: measuredAt(to[0], to[1]) });
+      segments.push({ bone: index, entry: i, a: measuredAt(from[0], from[1]), b: measuredAt(to[0], to[1]) });
       return;
     }
     throw new CompileError(
@@ -6739,10 +6806,27 @@ function buildSegmentsAttachment(
   });
 
   // -- the weights -----------------------------------------------------------
-  const falloff = { power, radius: f.radius, maxBones, minWeight };
+  let capped = 0;
+  let widest = 0;
   const weights: MeshVertexWeight[][] = lattice.points.map(([px, py], v) => {
-    const got = segmentShares(measuredAt(px, py), segments, falloff);
+    if (influence !== null) {
+      const reached = influenceShares(measuredAt(px, py), segments, influence);
+      if ('weights' in reached) {
+        if (reached.inReach > influence.max) capped++;
+        widest = Math.max(widest, reached.inReach);
+        return reached.weights;
+      }
+      throw new CompileError(
+        `${where}: vertex ${v}, at (${px}, ${py}) in the part's pixels, is reached by no link — the nearest is ` +
+          `"${named[reached.nearest.bone]}" at ${reached.nearest.distance.toFixed(4)}, and "influence.radius" is ` +
+          `${influence.radius}${influence.across ? '' : ' (with "across": false, the nearest entry\'s links only)'}. ` +
+          'A vertex needs a link, and rigc will not hand it one the reach does not: raise "radius" over that distance, ' +
+          'or name a segment nearer this part of the art',
+      );
+    }
+    const got = segmentShares(measuredAt(px, py), segments, falloff!);
     if ('weights' in got) return got.weights;
+    const { maxBones, minWeight } = falloff!;
     throw new CompileError(
       `${where}: vertex ${v}, at (${px}, ${py}) in the part's pixels, keeps no bone — the ${got.dropped.length} ` +
         `strongest pull(s) share it as ${got.dropped.map((d) => `"${named[d.bone]}" ${d.share.toFixed(4)}`).join(', ')}, ` +
@@ -6803,6 +6887,7 @@ function buildSegmentsAttachment(
       artCells: lattice.report.artCells,
       keptCells: lattice.report.keptCells,
       islands: lattice.report.islands,
+      ...(influence === null ? {} : { reach: { ...influence, capped, widest } }),
     },
   });
   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/mesh.ts

@@ -2432,3 +2432,139 @@ export function segmentShares(
   });
   return { weights };
 }
+
+// ---------------------------------------------------------------------------
+// influence — a falloff that reaches zero at a stated distance (issue #1415)
+// ---------------------------------------------------------------------------
+//
+// `segmentShares` above never lets a segment go: `1 / (d + r)^p` is positive at
+// every distance, so the only way to widen a blend is a larger `r`, which
+// flattens it everywhere at once, and the only way to end one is `minWeight`,
+// a share rather than a distance. A cloth surface wants the other model: a
+// vertex follows every link NEAR it, by a pull that falls to exactly zero at a
+// stated reach, so a link enters and leaves a vertex's blend continuously.
+//
+//   1. **Distance.** `d` is the distance from the vertex to each link's
+//      segment — its nearest point, `segmentDistance`, the same reading the
+//      falloff takes — at the setup pose. To the segment rather than to the
+//      bone's origin: a vertex on the middle of a link IS on that link, and an
+//      origin metric would put it half a link away while handing the joint at
+//      the link's tip to the child whose origin sits there.
+//   2. **Across.** With `across: false` only the entry (a chain, a bone, a
+//      span) holding the nearest link is kept — the earlier entry on a tie.
+//   3. **Reach.** A link with `d < radius` pulls `shape(d / radius)`, and one
+//      whose pull is not above 0 — a hair inside the reach, in doubles — pulls
+//      nothing and is out of reach; a bone two segments name keeps the nearer.
+//      A vertex no link reaches is refused by the caller, naming the nearest
+//      distance.
+//   4. **Cap.** The strongest `max` pulls are kept — equal pulls in the order
+//      the bones were first named — and normalised; a share the 6-decimal grid
+//      would write as 0 is dropped and the rest normalised again.
+//   5. **Order.** The kept bones are written in the order they were first
+//      named, on every vertex, so an attachment has one bone order by
+//      construction (`A52_WEIGHTED_VERTICES_SHARE_ONE_BONE_ORDER`); the
+//      strongest closes the vertex at exactly 1 on the grid.
+
+/** One candidate segment with the `bones` entry it came from — what `across: false` chooses between. */
+export interface EntrySegment extends WorldSegment {
+  /** Index of the `bones` entry this segment belongs to. */
+  entry: number;
+}
+
+/** The four fields an `influence` block states — every one of them required by the caller. */
+export interface SegmentsInfluence {
+  radius: number;
+  across: boolean;
+  max: number;
+  shape: 'linear' | 'smooth';
+}
+
+/** A pull at `x = d / radius` in `[0, 1]`: 1 at the segment, 0 at the reach. */
+export function influencePull(shape: SegmentsInfluence['shape'], x: number): number {
+  return shape === 'linear' ? 1 - x : 1 - x * x * (3 - 2 * x);
+}
+
+/** The steps a selftest plant may switch off, one key each — never passed by a build. */
+export interface InfluencePlant {
+  ignoreCap?: true;
+  ignoreReach?: true;
+  ignoreAcross?: true;
+  skipNormalise?: true;
+}
+
+/** What `influenceShares` found at one vertex. */
+export type InfluenceShares =
+  | {
+      /** The bindings, in first-named bone order, closing at exactly 1 on the 6-decimal grid. */
+      weights: MeshVertexWeight[];
+      /** How many bones were in reach before the cap — over `max` means the cap dropped some. */
+      inReach: number;
+    }
+  | {
+      /** No link is within `radius`: the nearest one's distance, and its bone. */
+      nearest: { bone: number; distance: number };
+    };
+
+/**
+ * The shares on one vertex under an `influence` block — see the section header.
+ * `plant` exists for the selftest's negative controls: each key switches one
+ * step off, so a control can show its own check going red on weights that
+ * break exactly that step. A build never passes it.
+ */
+export function influenceShares(
+  p: readonly [number, number],
+  segments: readonly EntrySegment[],
+  influence: SegmentsInfluence,
+  plant: InfluencePlant = {},
+): InfluenceShares {
+  const distances = segments.map((s) => segmentDistance(p, s.a, s.b));
+  let home = -1;
+  let homeD = Infinity;
+  let nearestBone = 0;
+  distances.forEach((d, i) => {
+    if (d < homeD) {
+      homeD = d;
+      home = segments[i].entry;
+      nearestBone = segments[i].bone;
+    }
+  });
+  const byBone = new Map<number, number>();
+  segments.forEach((s, i) => {
+    if (!influence.across && plant.ignoreAcross === undefined && s.entry !== home) return;
+    const d = distances[i];
+    if (!(d < influence.radius) && plant.ignoreReach === undefined) return;
+    const was = byBone.get(s.bone);
+    if (was === undefined || d < was) byBone.set(s.bone, d);
+  });
+  // Strongest first; equal pulls by the order the bones were first named. A link a hair inside the reach can
+  // pull 0 — or a rounding's worth under it — in doubles (`1 - x²(3 - 2x)` at x one ulp under 1): it pulls
+  // nothing, so it is out of reach like the links past it, and no share is ever made up for it.
+  const pulls = [...byBone.entries()]
+    .map(([bone, d]) => ({ bone, pull: influencePull(influence.shape, Math.min(d / influence.radius, 1)) }))
+    .filter((e) => e.pull > 0 || plant.ignoreReach !== undefined)
+    .sort((x, y) => y.pull - x.pull || x.bone - y.bone);
+  if (pulls.length === 0) return { nearest: { bone: nearestBone, distance: homeD } };
+  const inReach = pulls.length;
+  const capped = plant.ignoreCap === undefined ? pulls.slice(0, influence.max) : pulls;
+  // Only the planted `ignoreReach` keeps a pull of 0 (a link at or past the reach): it is given one grid step,
+  // so the plant still binds that link, which is the plant's whole point.
+  const raw = capped.map((e) => ({ bone: e.bone, pull: e.pull > 0 ? e.pull : 0.000001 }));
+  let sum = 0;
+  for (const e of raw) sum += e.pull;
+  const normalise = plant.skipNormalise === undefined;
+  const first = raw.map((e) => ({ bone: e.bone, share: normalise ? e.pull / sum : e.pull }));
+  const kept = first.filter((e) => r6(e.share) !== 0);
+  let sum2 = 0;
+  for (const e of kept) sum2 += e.share;
+  const rounded = kept.map((e) => r6(normalise ? e.share / sum2 : e.share));
+  // `kept[0]` is the strongest — the filter keeps the order — and it closes the vertex at exactly 1.
+  if (normalise) {
+    let others = 0;
+    for (let k = 1; k < rounded.length; k++) others += rounded[k];
+    rounded[0] = r6(1 - others);
+  }
+  const weights: MeshVertexWeight[] = kept
+    .map((e, k) => ({ bone: 'control' as const, control: e.bone, weight: rounded[k] }))
+    .sort((x, y) => x.control - y.control);
+  return { weights, inReach };
+}

package/src/rig.ts

@@ -683,6 +683,53 @@ export interface RigSegmentsFalloff {
   minWeight?: number;
 }
 
+/** The two curves an `influence` pull falls to zero along — see `RigSegmentsInfluence.shape`. */
+export const RIG_INFLUENCE_SHAPES = ['linear', 'smooth'] as const;
+
+/**
+ * A falloff that **reaches zero** at a stated distance, so a vertex follows
+ * every chain link near it and no link far from it (issue #1415) — the model a
+ * cloth surface needs, where a vertex between two chains blends the springs of
+ * both and the surface bends as one sheet rather than as strips.
+ *
+ * Per vertex: `d` is the distance to each link's **segment** (its nearest
+ * point, the same distance `falloff` measures), read at the setup pose. A link
+ * with `d < radius` pulls `shape(d / radius)` — one whose pull is not above 0
+ * in doubles, a hair inside the reach, pulls nothing; the strongest `max` pulls are
+ * kept — equal pulls in the order `bones` first names their bones — and
+ * normalised; a share the 6-decimal grid would write as 0 is dropped and the
+ * rest normalised again. Each vertex lists its bones in the order `bones`
+ * names them, so the attachment has one bone order by construction (A52).
+ *
+ * ⭐ Every number is a field and none has a default: the reach and the cap are
+ * judgements about this cloth, and the shape is the one thing that decides
+ * how a link enters a vertex's blend.
+ */
+export interface RigSegmentsInfluence {
+  /**
+   * **Required.** How far a link reaches, in the part's pixels (the skeleton's
+   * units on this generator's route): a link whose segment is `radius` or
+   * farther from a vertex never pulls it. Positive.
+   */
+  radius: number;
+  /**
+   * **Required.** `true`: every link of every `bones` entry within `radius`
+   * pulls. `false`: only the links of ONE entry — the entry holding the link
+   * nearest the vertex, the earlier entry on a tie — so a chain moves its own
+   * strip and nothing across.
+   */
+  across: boolean;
+  /** **Required.** At most this many links pull one vertex — the strongest. A whole number of at least 1. */
+  max: number;
+  /**
+   * **Required.** How a pull falls from 1 at `d = 0` to 0 at `d = radius`, with
+   * `x = d / radius`: `"linear"` is `1 - x`; `"smooth"` is `1 - x²(3 - 2x)`,
+   * which also arrives at both ends with zero slope, so a link enters and leaves
+   * a vertex's blend without a crease.
+   */
+  shape: (typeof RIG_INFLUENCE_SHAPES)[number];
+}
+
 /**
  * A lattice over the part's alpha, weighted by distance to named bone segments
  * (`buildSegmentsLattice` and `segmentWeights` in [`mesh.ts`](mesh.ts)).
@@ -703,8 +750,14 @@ export interface RigSegmentsGenerator {
    * or a `RigSegmentSpan` stated outright.
    */
   bones: Array<string | string[] | RigSegmentSpan>;
-  /** The falloff — see `RigSegmentsFalloff`. `radius` is required, so the block is too. */
-  falloff: RigSegmentsFalloff;
+  /**
+   * The falloff — see `RigSegmentsFalloff`. Exactly one of `falloff` and
+   * `influence` is stated: both turn a distance into a share, in two models,
+   * and a mesh weighted by both would be weighted by neither.
+   */
+  falloff?: RigSegmentsFalloff;
+  /** A falloff that reaches zero at a stated distance — see `RigSegmentsInfluence`. */
+  influence?: RigSegmentsInfluence;
   /** Alpha at or above which a pixel counts as art, 1..255. Default 1 — `contour`'s own. */
   alpha?: number;
   /**
@@ -1965,8 +2018,9 @@ export const RIG_KEYS = {
   RigRibbonGenerator: ['kind', 'size', 'rows', 'chain'],
   RigContourGenerator: ['kind', 'tolerance', 'margin', 'maxVertices', 'alpha', 'depth', 'soft'],
   RigGridGenerator: ['kind', 'us', 'vs', 'cols', 'rows', 'depth', 'soft'],
-  RigSegmentsGenerator: ['kind', 'cell', 'bones', 'falloff', 'alpha', 'anchor'],
+  RigSegmentsGenerator: ['kind', 'cell', 'bones', 'falloff', 'influence', 'alpha', 'anchor'],
   RigSegmentsFalloff: ['power', 'radius', 'maxBones', 'minWeight'],
+  RigSegmentsInfluence: ['radius', 'across', 'max', 'shape'],
   RigSegmentSpan: ['bone', 'from', 'to'],
   RigMeshBias: ['axis_deg', 'ramp'],
   RigDepthMap: ['image', 'near', 'zScale', 'gamma', 'contrast', 'bias'],
@@ -2101,8 +2155,11 @@ export const RIG_TYPES = {
     soft: 'object',
   },
   RigGridGenerator: { kind: 'enum', us: 'number[]', vs: 'number[]', cols: 'number', rows: 'number', depth: 'object', soft: 'object' },
-  RigSegmentsGenerator: { kind: 'enum', cell: 'number', bones: 'mixed', falloff: 'object', alpha: 'number', anchor: 'number[]' },
+  RigSegmentsGenerator: {
+    kind: 'enum', cell: 'number', bones: 'mixed', falloff: 'object', influence: 'object', alpha: 'number', anchor: 'number[]',
+  },
   RigSegmentsFalloff: { power: 'number', radius: 'number', maxBones: 'number', minWeight: 'number' },
+  RigSegmentsInfluence: { radius: 'number', across: 'boolean', max: 'number', shape: 'enum' },
   RigSegmentSpan: { bone: 'string', from: 'number[]', to: 'number[]' },
   RigMeshBias: { axis_deg: 'number', ramp: 'number[]' },
   RigDepthMap: { image: 'string', near: 'enum', zScale: 'number', gamma: 'number', contrast: 'number', bias: 'number' },
@@ -2170,6 +2227,7 @@ export const RIG_ENUMS = {
   RigContourGenerator: { kind: { owner: 'checkRigSpecKeys' } },
   RigGridGenerator: { kind: { owner: 'checkRigSpecKeys' } },
   RigSegmentsGenerator: { kind: { owner: 'checkRigSpecKeys' } },
+  RigSegmentsInfluence: { shape: { owner: 'segmentsInfluenceOf' } },
   RigDepthMap: { near: { owner: 'sampleMeshDepth' } },
 } as const satisfies SpecEnumTable<typeof RIG_TYPES>;
 
@@ -2438,6 +2496,7 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{
         at(gen.depth, 'RigDepthMap', `${who} generator.depth`, [...here, 'generator', 'depth']);
         at(gen.soft, 'RigSoftRegion', `${who} generator.soft`, [...here, 'generator', 'soft']);
         at(gen.falloff, 'RigSegmentsFalloff', `${who} generator.falloff`, [...here, 'generator', 'falloff']);
+        at(gen.influence, 'RigSegmentsInfluence', `${who} generator.influence`, [...here, 'generator', 'influence']);
         for (const [i, entry] of (Array.isArray(gen.bones) ? gen.bones : []).entries()) {
           at(entry, 'RigSegmentSpan', `${who} generator.bones[${i}]`, [...here, 'generator', 'bones', i]);
         }

package/src/types.ts

@@ -1679,6 +1679,20 @@ export interface CompileResult {
       artCells: number;
       keptCells: number;
       islands: number;
+      /**
+       * Present only when the mesh is weighted by an `influence` block (issue
+       * #1415): the block as stated, how many vertices had more links in reach
+       * than `max` — the vertices the cap dropped a link from — and the most
+       * links in reach at any one vertex, which is the `max` that would drop none.
+       */
+      reach?: {
+        radius: number;
+        across: boolean;
+        max: number;
+        shape: 'linear' | 'smooth';
+        capped: number;
+        widest: number;
+      };
     };
     /**
      * What a depth map put on this mesh's vertices, when one was named.