spine-rigc 2.52.0 → 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

package/package.json

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