spine-rigc 2.52.0 → 2.54.0

package/src/cli/core_commands.ts

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

package/src/cli/shared.ts

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

package/src/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/raw.ts

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