@rig-c/parts 1.24.0 → 1.26.0

package/src/rig.ts

@@ -132,11 +132,11 @@
  * touches the disk, and the same inputs give the same bytes (key order is the
  * order the objects are built in, and every number is rounded by `pyRound`).
  */
-import { type AutoSpec, type BoneEntry, type WeightRule, type CharacterConfig, type ConfigConstraint, CONSTRAINT_FOLLOWS, constraintForRig, type ContourSpec, type Point, type RibsSpec, ROOT_BONE, weightsABone } from './config.ts';
+import { type AutoSpec, type BoneEntry, type WeightRule, type CharacterConfig, type ConfigConstraint, type ConfigStop, CONSTRAINT_FOLLOWS, constraintForRig, type ContourSpec, type Point, type RibsSpec, ROOT_BONE, stopForRig, weightsABone } from './config.ts';
 import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toWorld } from './coords.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { eyeLineDegrees } from './headframe.ts';
-import type { RigBoneInherit } from 'rig-c/src/rig.ts';
+import type { RigBoneInherit, RigStop } from 'rig-c/src/rig.ts';
 import { f32 } from 'rig-c/compile';
 import type { MeshCounts, MeshQualityReport, MeshReductionInput, MotionAmplitude, ReducedMesh, Termination } from 'rig-c/mesh';
 import { type AmplitudeRow, amplitudeRow, partAmplitude, withAmplitude } from './autoamplitude.ts';
@@ -388,6 +388,57 @@ export function roundShares(list: readonly Influence[]): Influence[] {
   return kept;
 }
 
+/**
+ * Issue #392: on a lattice mesh whose segments include sibling branch chains
+ * forked from the same chain link with `r >= grid` (`split.hold_tip: true`),
+ * the distance rule still concentrates weights along the fork row where the
+ * trunk splits into branches and across adjacent trees' ruffled hem steps.
+ * Four Laplacian passes (`FORK_SMOOTH_PASSES`, self share 0.5, floor 0.005, cap
+ * 8 influences) diffuse each vertex's shares across its triangle neighbours
+ * before rounding with {@link roundShares}.
+ */
+export const FORK_SMOOTH_PASSES = 4;
+export const FORK_SMOOTH_SELF = 0.5;
+export const FORK_SMOOTH_FLOOR = 0.005;
+export const FORK_SMOOTH_MAX_INFLUENCES = 8;
+
+export function smoothForkShares(raw: ReadonlyArray<readonly Influence[]>, triangles: readonly number[]): Influence[][] {
+  const adj: number[][] = raw.map(() => []);
+  const addEdge = (u: number, v: number): void => {
+    if (!adj[u].includes(v)) adj[u].push(v);
+    if (!adj[v].includes(u)) adj[v].push(u);
+  };
+  for (let i = 0; i + 2 < triangles.length; i += 3) {
+    const a = triangles[i];
+    const b = triangles[i + 1];
+    const c = triangles[i + 2];
+    addEdge(a, b);
+    addEdge(b, c);
+    addEdge(c, a);
+  }
+  let cur: Influence[][] = raw.map((s) => [...s]);
+  for (let p = 0; p < FORK_SMOOTH_PASSES; p++) {
+    cur = cur.map((own, vi) => {
+      const nb = adj[vi];
+      if (nb.length === 0) return own;
+      const m = new Map<string, number>();
+      for (const { bone, weight } of own) m.set(bone, weight * FORK_SMOOTH_SELF);
+      const nbShare = (1 - FORK_SMOOTH_SELF) / nb.length;
+      for (const u of nb) {
+        for (const { bone, weight } of cur[u]) m.set(bone, (m.get(bone) ?? 0) + weight * nbShare);
+      }
+      const kept = [...m.entries()]
+        .filter(([, w]) => w >= FORK_SMOOTH_FLOOR)
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .slice(0, FORK_SMOOTH_MAX_INFLUENCES);
+      const sum = kept.reduce((s, [, w]) => s + w, 0);
+      return roundShares(kept.map(([bone, w]) => ({ bone, weight: w / sum })));
+    });
+  }
+  return cur;
+}
+
+
 interface Bone {
   name: string;
   parent: string | null;
@@ -450,6 +501,12 @@ export interface RigSpec {
    * when the config has the field.
    */
   constraints?: Array<Record<string, unknown>>;
+  /**
+   * `config.stops` (issue #404), in the order written, each with its `links`
+   * expanded from `chain` when omitted and its records and annotations left out
+   * ({@link stopForRig}). Written only when the config has the field.
+   */
+  stops?: RigStop[];
   /**
    * `idleDrivesMeshes`: written only under `idleKeys: 'direct'`, and only when
    * the idle keys a mesh-driving bone. `detached`: written only when a
@@ -951,7 +1008,8 @@ export function buildRig(
       }
       e.points.forEach(([x, y], k) => {
         const n = `${e.chain}${k}`;
-        B.set(n, { name: n, parent: k === 0 ? e.parent : names[names.length - 1], x, y });
+        const inherit = e.link_inherit?.[n];
+        B.set(n, { name: n, parent: k === 0 ? e.parent : names[names.length - 1], x, y, ...(inherit === undefined ? {} : { inherit }) });
         if (names.length > 0) child.set(names[names.length - 1], [x, y]);
         names.push(n);
       });
@@ -1033,6 +1091,17 @@ export function buildRig(
     if (!byPart.has(part)) fail('RIG_PART_PRESENT', `config.regions.${part}`, `names the part "${part}", which is not in parts.json; ${where(part)}`);
     if (!B.has(bone)) fail('RIG_NAME_RESOLVES', `config.regions.${part}`, `names the bone "${bone}", which config.bones does not declare`);
   }
+  if (cfg.stops !== undefined) {
+    cfg.stops.forEach((s, i) => {
+      const at = `config.stops[${i}]`;
+      if (!chains.has(s.chain)) fail('RIG_NAME_RESOLVES', `${at}.chain`, `names the chain "${s.chain}", which config.bones does not declare`);
+      const links = s.links ?? chains.get(s.chain) ?? [];
+      links.forEach((l, k) => {
+        if (!B.has(l)) fail('RIG_NAME_RESOLVES', `${at}.links[${k}]`, `names the bone "${l}", which config.bones does not declare`);
+      });
+      if (!B.has(s.against)) fail('RIG_NAME_RESOLVES', `${at}.against`, `names the bone "${s.against}", which config.bones does not declare`);
+    });
+  }
   for (const p of parts.parts) {
     const inM = p.name in cfg.meshes;
     const inR = p.name in cfg.regions;
@@ -1377,6 +1446,31 @@ export function buildRig(
       return [{ chain, points: line.map(([x, y]) => [x - ox, y - oy] as [number, number]), stations: declared.stations }];
     });
   };
+  // Issue #417: on a declared dress (a topwear mesh carrying chest, hip and hip-rooted skirt tree chains, as
+  // cloth.bottomwear.part drafts), skirt tree links carry no weight on vertices above the hip line (wy < hip.y): the
+  // bodice is weighted by the torso's own bones (chest, hip, and any local region like a bust) at any influences cap;
+  // below the hip line nothing changes.
+  const hipChainLinks = new Set<string>();
+  for (const links of chains.values()) {
+    for (const l of links) {
+      let cur: string | null = B.get(l)?.parent ?? null;
+      while (cur !== null && cur !== 'hip' && cur !== 'chest') cur = B.get(cur)?.parent ?? null;
+      if (cur === 'hip') hipChainLinks.add(l);
+    }
+  }
+  const dressSegsAt = (p: PartsFile['parts'][number], segs: Segment[]): ((wy: number) => Segment[]) => {
+    const hipBone = B.get('hip');
+    if (hipBone === undefined) return () => segs;
+    const isDress =
+      tagOf(p.from) === 'topwear' &&
+      segs.some((s) => s.bone === 'chest') &&
+      segs.some((s) => s.bone === 'hip') &&
+      segs.some((s) => hipChainLinks.has(s.bone));
+    if (!isDress) return () => segs;
+    const torso = segs.filter((s) => !hipChainLinks.has(s.bone));
+    if (torso.length === 0) return () => segs;
+    return (wy: number): Segment[] => (wy < hipBone.y ? torso : segs);
+  };
   // A contour mesh (issue #84): `src/contour.ts` over the padded image, every refusal collected with the others;
   // the weights by `src/localweights.ts`; slot, uvs, bind positions and by-name weights written as the lattice's.
   // The config's region numbers are rig px; the part image's are rig px less (p.x − PAD, p.y − PAD) — a
@@ -1420,6 +1514,7 @@ export function buildRig(
       out.push(...heat);
       return null;
     }
+    const segsAt = dressSegsAt(p, segs);
     const weights: WeightEntry[][] = [];
     const reached = regions.map(() => 0);
     const whole = regions.map(() => 0);
@@ -1431,7 +1526,8 @@ export function buildRig(
     cm.vertices.forEach(([vx, vy], vi) => {
       const wx = vx + ox;
       const wy = vy + oy;
-      const li = localInfluences([wx, wy], segs, r, regions, limits, exponent ?? DISTANCE_EXPONENT, heat === null ? undefined : heatInfluences(heat, [vx, vy], limits));
+      const vSegs = segsAt(wy);
+      const li = localInfluences([wx, wy], vSegs, r, regions, limits, exponent ?? DISTANCE_EXPONENT, heat === null ? undefined : heatInfluences(heat, [vx, vy], limits));
       if ('first' in li) {
         if (!overlapped) {
           out.push({
@@ -1445,7 +1541,7 @@ export function buildRig(
       }
       if (li.influences.length === 0) {
         // issue #284: a declared cut that keeps no bone (nothingKeptProblem says when that can be); a region's bone would be kept.
-        if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], segs, r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx, vy], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
+        if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], vSegs, r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx, vy], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
         else emptiedMore++;
         return;
       }
@@ -1551,7 +1647,7 @@ export function buildRig(
       out.push(...heat);
       return null;
     }
-    const sw = sourceWeights(source.vertices, ox, oy, segs, r, spec, exponent ?? DISTANCE_EXPONENT, heat);
+    const sw = sourceWeights(source.vertices, ox, oy, segs, r, spec, exponent ?? DISTANCE_EXPONENT, heat, dressSegsAt(p, segs));
     if ('overlap' in sw) {
       out.push({
         code: 'RIG_CONTOUR_REGIONS_OVERLAP',
@@ -1807,19 +1903,41 @@ export function buildRig(
     let maxInfl = 0;
     // issue #284: the mesh's declared cap and floor form, or DEFAULT_LIMITS itself when it declares none.
     const limits: InfluenceLimits = meshLimits(mesh.influences);
+    const segsAt = dressSegsAt(p, segs);
     let emptied: { vertex: number; at: Point; capped: Influence[] } | null = null;
     let emptiedMore = 0;
+    const rawShares: Influence[][] = [];
     for (const [vi, [vx0, vy0]] of lm.vertices.entries()) {
       const wx = vx0 + ox;
       const wy = vy0 + oy;
-      const shares = heat === null ? influences([wx, wy], segs, mesh.r, limits, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], limits);
+      const vSegs = segsAt(wy);
+      const shares = heat === null ? influences([wx, wy], vSegs, mesh.r, limits, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], limits);
       if (shares.length === 0) {
         // issue #284: a declared cut that keeps no bone (nothingKeptProblem says when that can be).
-        if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], segs, mesh.r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
+        if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], vSegs, mesh.r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
         else emptiedMore++;
         continue;
       }
-      const ent: WeightEntry[] = (limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares)).map(({ bone, weight }) => {
+      rawShares.push(limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
+    }
+    if (emptied !== null) {
+      problems.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
+      continue;
+    }
+    const allChainLinks = new Set([...chains.values()].flat());
+    const forkCounts = new Map<string, number>();
+    for (const sp of mesh.segments) {
+      if (typeof sp !== 'string') continue;
+      const links = chains.get(sp);
+      const par = links !== undefined && links.length > 0 ? (B.get(links[0])?.parent ?? null) : null;
+      if (par !== null && allChainLinks.has(par)) forkCounts.set(par, (forkCounts.get(par) ?? 0) + 1);
+    }
+    const heldFork = heat === null && mesh.r >= mesh.grid && mesh.influences === undefined && [...forkCounts.values()].some((c) => c >= 2);
+    const finalShares = heldFork ? smoothForkShares(rawShares, lm.triangles) : rawShares;
+    for (const [vi, [vx0, vy0]] of lm.vertices.entries()) {
+      const wx = vx0 + ox;
+      const wy = vy0 + oy;
+      const ent: WeightEntry[] = finalShares[vi].map(({ bone, weight }) => {
         const [x, y] = toBoneLocal(world.get(bone) as BoneTransform, spineX(wx), spineY(wy));
         return { bone, x: places(x), y: places(y), weight };
       });
@@ -1827,10 +1945,6 @@ export function buildRig(
       infl += ent.length;
       maxInfl = Math.max(maxInfl, ent.length);
     }
-    if (emptied !== null) {
-      problems.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
-      continue;
-    }
     const uvs: number[] = [];
     for (const [x, y] of lm.vertices) uvs.push(pyRound(x / w, 6), pyRound(y / h, 6));
     skin[p.name] = { [p.name]: { type: 'mesh', image: file, width: w, height: h, uvs, triangles: lm.triangles, hull: lm.hull, weights } };
@@ -1852,6 +1966,10 @@ export function buildRig(
     });
   }
   refuseIfAny(problems);
+  // ---- leg stops (issue #404) --------------------------------------------
+  // Only when the config has `stops`: each link after the first (and any bone hanging from a stopped link) hangs
+  // from the drawn link `<link>_d` above it, and slots and weights on a stopped link bind `<link>_d`.
+  const stops = cfg.stops === undefined ? null : applyStops(cfg.stops, chains, bones, slots, skin);
   // ---- the turn control (issue #251) -------------------------------------
   // Only when the config has `turn`: every other build adds nothing here, so no byte moves.
   const turned = cfg.turn === undefined ? null : applyTurn(cfg.turn, parts.parts.map((p) => p.name), bones, slots, skin, cfg.constraints ?? []);
@@ -1868,6 +1986,7 @@ export function buildRig(
   };
   if (cfg.constraints !== undefined) rig.constraints = cfg.constraints.map(constraintForRig);
   if (turned !== null) rig.constraints = [...(rig.constraints ?? []), ...turned.constraints];
+  if (stops !== null) rig.stops = stops;
   const detached = [...detachedRules(cfg.constraints ?? []), ...(turned?.detached ?? [])];
   if (idleKeys === 'direct' && meshKeyed.length > 0) rig.invariants = { idleDrivesMeshes: { why: IDLE_DRIVES_MESHES_WHY } };
   if (detached.length > 0) rig.invariants = { ...rig.invariants, detached };
@@ -1880,6 +1999,49 @@ export function buildRig(
   return { rig, motion, meshReport, images: outImages, controls, meshKeyed, idleKeys, loopPasses, autoMotion, faceAxis, turn: turned?.rows ?? null };
 }
 
+/**
+ * Re-parent every bone that hangs from a stopped link onto that link's drawn
+ * link `<link>_d`, move slots and mesh weights from a stopped link onto
+ * `<link>_d`, and return `rig.json`'s `stops` array (issue #404). At the setup
+ * pose `<link>_d` has the same world origin and rotation as `<link>`, so every
+ * local offset and bind coordinate is unchanged.
+ */
+function applyStops(
+  stops: readonly ConfigStop[],
+  chains: ReadonlyMap<string, readonly string[]>,
+  bones: RigBone[],
+  slots: RigSpec['slots'],
+  skin: RigSpec['skins']['default'],
+): RigStop[] {
+  const out: RigStop[] = [];
+  const drawn = new Map<string, string>();
+  for (const s of stops) {
+    const links = s.links ?? chains.get(s.chain) ?? [];
+    for (const l of links) drawn.set(l, `${l}_d`);
+    out.push(stopForRig(s, links));
+  }
+  for (const b of bones) {
+    const d = b.parent === undefined ? undefined : drawn.get(b.parent);
+    if (d !== undefined) b.parent = d;
+  }
+  for (const s of slots) {
+    const d = drawn.get(s.bone);
+    if (d !== undefined) s.bone = d;
+  }
+  for (const atts of Object.values(skin)) {
+    for (const att of Object.values(atts)) {
+      if (!('type' in att)) continue;
+      for (const v of att.weights) {
+        for (const w of v) {
+          const d = drawn.get(w.bone);
+          if (d !== undefined) w.bone = d;
+        }
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * The JSON text of a rig output file. One space of indent, as the reference
  * wrote, and a closing newline; the key order is the order the objects were
@@ -1926,7 +2088,10 @@ export function rigJsonText(value: unknown): string {
  */
 export function flattenRig(rig: RigSpec, sense: 1 | -1 = 1): RigSpec {
   const problems: Problem[] = [];
-  const read = rig.bones.map((b) => ({ ...b, rotation: (b.rotation ?? 0) * sense }));
+  const undrawn = new Map<string, string>();
+  for (const s of rig.stops ?? []) for (const l of s.links) undrawn.set(`${l}_d`, l);
+  const realBone = (n: string): string => undrawn.get(n) ?? n;
+  const read = rig.bones.map((b) => ({ ...b, ...(b.parent === undefined ? {} : { parent: realBone(b.parent) }), rotation: (b.rotation ?? 0) * sense }));
   const world = computeExactFrameTransforms(read);
   const turn = new Map<string, number>();
   // A bone with a declared inherit mode (issue #348) is read off rig-c's poser, which honours the mode; every other is the sum, as before.
@@ -1934,11 +2099,11 @@ export function flattenRig(rig: RigSpec, sense: 1 | -1 = 1): RigSpec {
     turn.set(
       b.name,
       b.inherit === undefined
-        ? placed((b.parent === undefined ? 0 : (turn.get(b.parent) as number)) + (b.rotation ?? 0), OFFSET_PLACES)
+        ? placed((b.parent === undefined ? 0 : (turn.get(realBone(b.parent)) as number)) + (b.rotation ?? 0), OFFSET_PLACES)
         : placed(normaliseDegrees((world.get(b.name) as BoneTransform).worldRotation), OFFSET_PLACES),
     );
   }
-  const origin = (bone: string): BoneTransform => world.get(bone) as BoneTransform;
+  const origin = (bone: string): BoneTransform => world.get(realBone(bone)) as BoneTransform;
   const out = (m: BoneTransform, x: number, y: number): [number, number] => {
     const [wx, wy] = toWorld(m, x, y);
     return [placed(wx - m.worldX, FLAT_PLACES), placed(wy - m.worldY, FLAT_PLACES)];
@@ -1962,12 +2127,12 @@ export function flattenRig(rig: RigSpec, sense: 1 | -1 = 1): RigSpec {
         })) };
         continue;
       }
-      const left = normaliseDegrees((turn.get(bone) as number) + (att.rotation ?? 0));
+      const left = normaliseDegrees((turn.get(realBone(bone)) as number) + (att.rotation ?? 0));
       if (Math.abs(left) > 1e-6) {
         problems.push({
           code: 'FLATTEN_REGION_UPRIGHT',
           object: `skins.default.${slot}.${name}`,
-          detail: `rides "${bone}", turned ${turn.get(bone)} degrees, with rotation ${att.rotation ?? 'absent'}, so it is drawn turned ${placed(left, OFFSET_PLACES)} degrees; the flat form draws every region upright, so the region's rotation must cancel its bone's turn`,
+          detail: `rides "${bone}", turned ${turn.get(realBone(bone))} degrees, with rotation ${att.rotation ?? 'absent'}, so it is drawn turned ${placed(left, OFFSET_PLACES)} degrees; the flat form draws every region upright, so the region's rotation must cancel its bone's turn`,
         });
         continue;
       }
@@ -1989,6 +2154,9 @@ export function flattenRig(rig: RigSpec, sense: 1 | -1 = 1): RigSpec {
       return { ...c, properties: { ...props, rotate: { ...rotate, offset: placed(offset - turned, OFFSET_PLACES) } } };
     });
   }
+  if (rig.stops !== undefined) {
+    flat.stops = rig.stops.map((s) => ({ ...s, at: out(origin(s.against), s.at[0], s.at[1]) }));
+  }
   if (rig.invariants?.axes !== undefined) {
     const { axes: _axes, ...rest } = rig.invariants;
     if (Object.keys(rest).length > 0) flat.invariants = rest;

package/src/scene.ts

@@ -16,12 +16,13 @@
  * `rig/images/`, `parts.json` and `check/check.json`:
  *
  * - **Names, totally.** Every bone, slot, attachment (skin entry), constraint
- *   (its name and every bone or slot it names), `invariants.detached` bone,
+ *   (its name and every bone or slot it names), `stops` entry (its `chain`,
+ *   its `links` and its `against`; issue #431), `invariants.detached` bone,
  *   `invariants.axes` entry (its name, its `through` and its `bones`; issue #239),
  *   track, group and easing of character `<id>` is renamed `<id>:<name>`
  *   ({@link prefixed}); `root` is the one shared root. A name resolves to
  *   exactly one character, and nothing resolves across characters without its
- *   prefix: a constraint naming a bone its own build does not declare is
+ *   prefix: a constraint or stop naming a bone its own build does not declare is
  *   refused (`SCENE_NAME_PREFIXED` when another character has it,
  *   `SCENE_NAME_RESOLVES` when none does).
  * - **Images are the one name that cannot carry `:`.** rig-c names an
@@ -44,8 +45,8 @@
  *   is local to a bone the shift already moved. In Spine's axes it is the
  *   character's stage corner carried to the canvas's ({@link rootShift}),
  *   through `src/coords.ts`. The root is shared, so a character whose idle
- *   keys it, or whose constraint names it, is refused (`SCENE_ROOT_SHARED`):
- *   it would move every character.
+ *   keys it, or whose constraint or stop names it, is refused
+ *   (`SCENE_ROOT_SHARED`): it would move every character.
  * - **The scale, with the offset (issue #197).** `characters[].scale`, a
  *   positive number and 1 when absent, sizes the character about its stage's
  *   top-left corner: a point p of its root frame lands at `scale * p + shift`
@@ -53,7 +54,8 @@
  *   Spine's own loader multiplies by its `scale` (`SkeletonJson.js`): bone
  *   `x`, `y`, `length`; region `x`, `y` (and its drawn size, through
  *   `scaleX`/`scaleY`); each weight's bind `x`, `y`; the constraints' lengths
- *   ({@link scaledConstraint}); the translate keys and their curves'
+ *   ({@link scaledConstraint}); each stop's `at` offset in its `against` bone's
+ *   local frame ({@link scaledStop}; issue #431); the translate keys and their curves'
  *   values. Spine also scales the skeleton's `referenceScale`, which the
  *   composed skeleton holds once for every character, so a physics
  *   constraint with a nonzero `wind` or `gravity` cannot be scaled per
@@ -91,6 +93,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import type { RigStop } from 'rig-c/src/rig.ts';
 import { checkStage, gateThroughRigc, type Log } from './build.ts';
 import { ACCEPTABLE_BARS, barsNotMet, type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackMode, requirementsNotPass, type RigcRunner } from './check.ts';
 import { CONSTRAINT_BONE_FIELDS, ROOT_BONE } from './config.ts';
@@ -382,7 +385,9 @@ export interface CharacterBuild {
 const BONE_KEYS = ['name', 'parent', 'length', 'rotation', 'x', 'y'];
 const SLOT_KEYS = ['name', 'bone', 'attachment'];
 const ATTACHMENT_KEYS = ['type', 'image', 'width', 'height', 'uvs', 'triangles', 'hull', 'weights', 'x', 'y', 'rotation'];
-const RIG_KEYS = ['spec', 'name', 'images', 'skeleton', 'bones', 'slots', 'skins', 'constraints', 'invariants'];
+const RIG_KEYS = ['spec', 'name', 'images', 'skeleton', 'bones', 'slots', 'skins', 'constraints', 'stops', 'invariants'];
+const STOP_KEYS = ['chain', 'links', 'against', 'at', 'inward', 'outward', 'lower'];
+const STOP_LOWER_KEYS = ['inward', 'outward'];
 const INVARIANT_KEYS = ['idleDrivesMeshes', 'detached', 'axes'];
 const MOTION_KEYS = ['spec', 'archetype', 'cut', 'easings', 'groups', 'animations'];
 const IDLE_KEYS = ['duration', 'loop', 'note', 'tracks'];
@@ -501,6 +506,48 @@ export function readCharacterBuild(c: SceneCharacter, problems: Problem[], accep
         problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} rig.json bones[0]`, detail: `is ${show(root)}; {"name": "${ROOT_BONE}", "x": 0, "y": 0}, as the rig stage writes it, is required — the composed root is shared, so a character's root must carry no transform of its own` });
       }
       (Array.isArray(r.slots) ? r.slots : []).forEach((s, i) => unknown(`rig.json slots[${i}]`, s, SLOT_KEYS));
+      if ('stops' in r) {
+        if (!Array.isArray(r.stops)) {
+          problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} rig.json stops`, detail: `is ${show(r.stops)}; an array of stop entries is required` });
+        } else {
+          r.stops.forEach((st, i) => {
+            const where = `rig.json stops[${i}]`;
+            unknown(where, st, STOP_KEYS);
+            if (!isRecord(st)) return;
+            if (typeof st.chain !== 'string' || st.chain === '') {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.chain`, detail: `is ${show(st.chain)}; a non-empty chain name is required` });
+            }
+            if (!(Array.isArray(st.links) && st.links.length > 0 && st.links.every((l) => typeof l === 'string' && l !== ''))) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.links`, detail: `is ${show(st.links)}; a non-empty list of bone names is required` });
+            }
+            if (!('against' in st)) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.against`, detail: 'is absent; a bone name is required' });
+            }
+            if (!(Array.isArray(st.at) && st.at.length === 2 && st.at.every((n) => typeof n === 'number' && Number.isFinite(n)))) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.at`, detail: `is ${show(st.at)}; [x, y], two finite numbers in against's local frame, is required` });
+            }
+            const checkBounds = (bWhere: string, bObj: Record<string, unknown>): void => {
+              const inOk = typeof bObj.inward === 'number' && Number.isFinite(bObj.inward);
+              const outOk = typeof bObj.outward === 'number' && Number.isFinite(bObj.outward);
+              if (!inOk) problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${bWhere}.inward`, detail: `is ${show(bObj.inward)}; a finite number of degrees is required` });
+              if (!outOk) problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${bWhere}.outward`, detail: `is ${show(bObj.outward)}; a finite number of degrees is required` });
+              if (inOk && outOk && (bObj.inward as number) > (bObj.outward as number)) {
+                problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${bWhere}.inward`, detail: `is ${String(bObj.inward)}, above outward ${String(bObj.outward)}; inward <= outward is required` });
+              }
+            };
+            checkBounds(where, st);
+            if ('lower' in st) {
+              unknown(`${where}.lower`, st.lower, STOP_LOWER_KEYS);
+              if (isRecord(st.lower)) checkBounds(`${where}.lower`, st.lower);
+              if (Array.isArray(st.links) && st.links.length === 1) {
+                problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.lower`, detail: `is ${show(st.lower)} on a 1-link stop; lower holds the links below the first, so leave lower out when links has 1 bone` });
+              }
+            } else if (Array.isArray(st.links) && st.links.length > 1) {
+              problems.push({ code: 'SCENE_BUILD_FIELD_KNOWN', object: `${who} ${where}.lower`, detail: `is absent and required when the stop holds ${st.links.length} links (more than 1); state lower: { inward, outward } for the links below the first` });
+            }
+          });
+        }
+      }
       if (isRecord(r.invariants)) unknown('rig.json invariants', r.invariants, INVARIANT_KEYS);
       const skins = isRecord(r.skins) ? r.skins : {};
       unknown('rig.json skins', skins, ['default']);
@@ -732,6 +779,12 @@ export function scaledConstraint(con: Record<string, unknown>, s: number): Recor
   return out;
 }
 
+/** A stop of a character at scale `s` (issue #431): its `at` offset in `against`'s local frame scaled by `s`, its degree bounds unchanged; `s` 1 returns `stop` as given. */
+export function scaledStop(stop: RigStop, s: number): RigStop {
+  if (s === 1) return stop;
+  return { ...stop, at: [scaledBy(stop.at[0], s), scaledBy(stop.at[1], s)] };
+}
+
 /** A bone track's keys at scale `s`: a length property's values, and its curve's value control points, scaled; any other track as given. */
 function scaledTrack<T extends { property: string; keys: unknown[] }>(t: T, s: number): T {
   if (s === 1 || !SCALED_TRACK_PROPERTIES.includes(t.property)) return t;
@@ -962,6 +1015,11 @@ export function composeScene(
         fail('SCENE_NAME_RESOLVES', `${where}.slot`, `names the slot "${con.slot}", which character "${b.id}" does not declare`);
       }
     });
+    (b.rig.stops ?? []).forEach((st, k) => {
+      const where = `character "${b.id}" rig.json stops[${k}] (stop "${String(st.chain)}")`;
+      st.links.forEach((n, j) => ownBone(b.id, n, `${where}.links[${j}]`));
+      ownBone(b.id, st.against, `${where}.against`);
+    });
     for (const [k, d] of (b.rig.invariants?.detached ?? []).entries()) {
       ownBone(b.id, d.bone, `character "${b.id}" rig.json invariants.detached[${k}].bone`);
       ownBone(b.id, d.notUnder, `character "${b.id}" rig.json invariants.detached[${k}].notUnder`);
@@ -988,6 +1046,11 @@ export function composeScene(
       });
       if (named.includes(ROOT_BONE)) fail('SCENE_ROOT_SHARED', `${where} rig.json constraints[${k}] (${String(con.type)} "${String(con.name)}")`, `names "${ROOT_BONE}", which the scene shares by every character; a constraint on it, or following it, would reach every character — name a bone of the character's own`);
     });
+    (b.rig.stops ?? []).forEach((st, k) => {
+      if ([...st.links, st.against].includes(ROOT_BONE)) {
+        fail('SCENE_ROOT_SHARED', `${where} rig.json stops[${k}] (stop "${String(st.chain)}")`, `names "${ROOT_BONE}", which the scene shares by every character; a stop on it, or against it, would reach every character — name a bone of the character's own`);
+      }
+    });
   }
   const whys = [...new Set(ready.map((b) => b.rig.invariants?.idleDrivesMeshes?.why).filter((w): w is string => w !== undefined))];
   if (whys.length > 1) {
@@ -1034,6 +1097,7 @@ export function composeScene(
     images.push([PLATE_IMAGE, plate.bytes]);
   }
   const constraints: Array<Record<string, unknown>> = [];
+  const stops: RigStop[] = [];
   const detached: NonNullable<NonNullable<RigSpec['invariants']>['detached']> = [];
   const axes: NonNullable<NonNullable<RigSpec['invariants']>['axes']> = [];
   scene.characters.forEach((c) => {
@@ -1043,7 +1107,8 @@ export function composeScene(
     const [dx, dy] = rootShift(b.rig.skeleton, stage, c.offset, s);
     // At a scale other than 1 every length the character carries is scaled (issue #197): each bone's x, y and length,
     // each region's x, y (and its drawn size, by scaleX/scaleY), each weight's bind x, y, the constraints' lengths
-    // (scaledConstraint) and the translate keys (scaledTrack); what sits in root's own frame is then shifted.
+    // (scaledConstraint), each stop's at offset in against's local frame (scaledStop; issue #431) and the translate keys
+    // (scaledTrack); what sits in root's own frame is then shifted.
     for (const bone of b.rig.bones) {
       if (bone.name === ROOT_BONE) continue;
       const first = bone.parent === ROOT_BONE;
@@ -1095,6 +1160,15 @@ export function composeScene(
       if (type === 'path' && typeof con.slot === 'string') out.slot = prefixed(id, con.slot);
       constraints.push(out);
     }
+    for (const st of b.rig.stops ?? []) {
+      const scaled = scaledStop(st, s);
+      stops.push({
+        ...scaled,
+        chain: prefixed(id, st.chain),
+        links: st.links.map((l) => P(id, l)),
+        against: P(id, st.against),
+      });
+    }
     for (const d of b.rig.invariants?.detached ?? []) detached.push({ ...d, bone: P(id, d.bone), notUnder: P(id, d.notUnder) });
     // An axis entry's name is unique within one rig, and two characters each carry a "face": the name is prefixed too.
     for (const ax of b.rig.invariants?.axes ?? []) axes.push({ name: prefixed(id, ax.name), through: [P(id, ax.through[0]), P(id, ax.through[1])], bones: ax.bones.map((n) => P(id, n)), tolerance: ax.tolerance });
@@ -1106,6 +1180,7 @@ export function composeScene(
   const name = ids.join('+');
   const rig: RigSpec = { spec: 'rigc-rig/1', name, images: 'images', skeleton: stage, bones, slots, skins: { default: skin as unknown as RigSpec['skins']['default'] } };
   if (constraints.length > 0) rig.constraints = constraints;
+  if (stops.length > 0) rig.stops = stops;
   const invariants: NonNullable<RigSpec['invariants']> = {};
   if (whys.length === 1) invariants.idleDrivesMeshes = { why: whys[0] };
   if (detached.length > 0) invariants.detached = detached;
@@ -1251,6 +1326,11 @@ export function unprefixedNames(rig: RigSpec, motion: MotionSpec, ids: readonly
     }
     if (c.type === 'path') name(`constraint ${String(c.name)} slot`, c.slot, false);
   }
+  for (const s of rig.stops ?? []) {
+    name('stop chain', s.chain, false);
+    for (const l of s.links) name(`stop ${s.chain} link`, l, false);
+    name(`stop ${s.chain} against`, s.against, false);
+  }
   for (const d of rig.invariants?.detached ?? []) {
     name('invariants.detached bone', d.bone, false);
     name('invariants.detached notUnder', d.notUnder, false);