spine-rigc 2.53.0 → 2.55.0

package/src/assertions/bodies/a23.ts

@@ -24,7 +24,9 @@ import {
   physicsKeyRefusal,
   physicsOutsideSays,
   physicsRuleFor,
+  physicsStepStability,
   type PhysicsPoseRule,
+  type PhysicsStepStability,
 } from '../../timelines.ts';
 
 /**
@@ -72,7 +74,8 @@ const SETUP_POSE_SAYS: Record<string, (pose: PhysicsSetup, animations: number, r
   // on the arm's own words, which `T100` holds.
   strength: (pose, _animations, rule) => `has strength ${pose.strength}; ${setupBasisSays(rule, pose.strength)}`,
   // The bound is read off the row, so the setup pose and a key cannot state two
-  // intervals; the reason is the arm the value took, since the ends are inside (#794).
+  // intervals; the reason is the arm the value took — above 1, at 1 (issue
+  // #1422, inside from #794 until then) or below 0.
   damping: (pose, _animations, rule) =>
     `has damping ${pose.damping}; must be ${rule.states} — the per-step decay is \`damping ** (60 * step)\`, and ` +
     setupBasisSays(rule, pose.damping),
@@ -90,10 +93,11 @@ function setupBasisSays(rule: PhysicsPoseRule, poseValue: number): string {
 
 // Every failure mode here is silent. The five component fields default to
 // 0, so a constraint can drive nothing at all; `mix` 0 mutes it; `mass` 0
-// becomes an infinite massInverse; and `damping` above 1 never settles, which
-// on a mesh-driving bone means the canvas re-rasterises forever. 1 itself is
-// inside the bound since issue #794: it never decays, which is finite and a
-// choice, and what it costs a consumer's frame is the consumer's to judge.
+// becomes an infinite massInverse; and `damping` at or above 1 never settles,
+// which on a mesh-driving bone means the canvas re-rasterises forever. 1 itself
+// was inside the bound from issue #794 to #1422, as a jiggle held rather than a
+// fault; it is out because a decay of 1 puts the step's eigenvalues on the unit
+// circle, and a chain of such links was measured resonating without limit.
 //
 // 🔑 **Two arms, one criterion.** The second arm below reads every physics
 // TIMELINE key, and it is written against `PHYSICS_POSE_RULES` — the table
@@ -165,6 +169,9 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
     });
   }
   let mutedUntilKeyed = 0;
+  // Each constraint whose setup values the stability clause read, by position — the
+  // floor every animation's combination is taken from below.
+  const setupCombos = new Map<number, StabilityCombo>();
   facts.constraints.forEach((constraint, index) => {
     const physics = constraint.physics;
     if (physics === undefined) return;
@@ -245,6 +252,24 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
     if (physics.step <= 0 || !Number.isFinite(physics.step)) {
       fail('A23_PHYSICS_CONSTRAINT_EFFECTIVE', `${where} has step ${physics.step} (fps must be > 0)`);
     }
+    // --- the step itself has to settle (issue #1416, part B) ------------------
+    //
+    // The rows above judge each value against its own interval; this is the one
+    // joint condition, `physicsStepStability`'s. It is read only where the rows
+    // it combines all hold — a value its own row refuses is named there, and a
+    // second line about the same number would be the same fault twice — and
+    // only on a constraint that drives something, which the first clause names
+    // otherwise.
+    if (components.length && stableInputs(pose, physics.step)) {
+      const setupCombo: StabilityCombo = {
+        strength: { value: pose.strength, from: 'setup' },
+        massInverse: { value: pose.massInverse, from: 'setup' },
+        damping: { value: pose.damping, from: 'setup' },
+      };
+      const at = physicsStepStability(pose.strength, pose.massInverse, pose.damping, physics.step);
+      if (!at.stable) fail('A23_PHYSICS_CONSTRAINT_EFFECTIVE', `${where} has ${runawaySays(setupCombo, physics.step, at)}`);
+      setupCombos.set(index, setupCombo);
+    }
   });
   // What the PASS would otherwise not say: this rig rests with physics off
   // on that many constraints and an animation is what switches them on. A
@@ -302,4 +327,228 @@ export function a23PhysicsConstraintEffective({ fail, skip, stats }: Verdicts, f
     }
   }
   stats.physicsTimelineKeys = keysRead;
+
+  // --- the step has to settle on every pose an animation reaches (#1416) ----
+  //
+  // 🔑 **Which combinations are read.** Per animation and per constraint its
+  // `strength`, `mass` or `damping` timelines reach (a named one, or each a
+  // global one reaches): the LARGEST strength, the LARGEST massInverse and the
+  // SMALLEST damping that animation can pose on that constraint, judged
+  // together. A value's candidates are every key and every Bézier sample of
+  // every such timeline, as the pose field it lands in (`posed`) — and the
+  // setup value as well wherever the animation keys that value not at all, or
+  // keys it first after t = 0, because before its first key a timeline poses the
+  // setup value. Each extreme is exact for its own value: the runtime moves
+  // a value linearly between those points, `massInverse` is monotone in the
+  // mass it inverts, and the bound is monotone in damping.
+  //
+  // ⚠️ The JOINT is an upper bound rather than a time-aligned pose: an
+  // animation that raises strength while it raises mass, so the ratio holds,
+  // is judged at the larger strength against the smaller mass. That is the
+  // conservative direction — no pose this animation reaches is less stable
+  // than the combination read — and it was chosen over evaluating the three
+  // curves at shared times because the facts carry each curve's values and
+  // not its sample times, and because a single held key crossing the bound is
+  // already a runaway. A line names which key or setup supplied each value, so
+  // a refusal of that kind says so.
+  //
+  // A combination equal to the setup's is not repeated: the setup line names
+  // it already. A value its own row refuses is left out of the extremes — it
+  // was named above, by its key.
+  const keyed = new Map<string, Map<number, Partial<Record<StabilityWord, Candidate[]>>>>();
+  for (const timeline of facts.timelines) {
+    if (timeline.kind !== 'physics' || !isStabilityWord(timeline.word)) continue;
+    const rule = physicsRuleFor(timeline.word);
+    if (rule === undefined) continue;
+    const word = timeline.word;
+    const values = timeline.channelValues(0);
+    const firstTime = timeline.frames[0]?.time ?? 0;
+    const candidates: Candidate[] = [];
+    // `channelValues` lists each key and then the Bézier samples of the segment
+    // it opens, so the next key's value is that key and anything else is the
+    // curve leaving the key before it.
+    let next = 0;
+    for (const value of values) {
+      const frame = timeline.frames[next];
+      const isKey = frame !== undefined && frame.value === value;
+      if (isKey) next++;
+      const posedValue = timeline.posed === undefined ? rule.toPose(value) : timeline.posed(value);
+      if (physicsKeyRefusal(rule, value, posedValue) !== null) continue;
+      candidates.push({
+        value: posedValue,
+        from: isKey ? `the key at t=${frame.time.toFixed(6)}s` : `the curve after the key at t=${(timeline.frames[next - 1]?.time ?? 0).toFixed(6)}s`,
+      });
+    }
+    const byConstraint = keyed.get(timeline.animation) ?? new Map<number, Partial<Record<StabilityWord, Candidate[]>>>();
+    keyed.set(timeline.animation, byConstraint);
+    for (const index of timeline.reach) {
+      const setup = setupCombos.get(index);
+      if (setup === undefined) continue;
+      const slot = byConstraint.get(index) ?? {};
+      byConstraint.set(index, slot);
+      const list = slot[word] ?? [];
+      list.push(...candidates);
+      // Before the first key the timeline poses the setup value.
+      if (firstTime > 0) list.push(setup[STABILITY_FIELD[word]]);
+      slot[word] = list;
+    }
+  }
+  for (const [animation, byConstraint] of keyed) {
+    for (const [index, slot] of byConstraint) {
+      const setup = setupCombos.get(index);
+      const physics = facts.constraints[index]?.physics;
+      if (setup === undefined || physics === undefined) continue;
+      const pick = (word: StabilityWord, worse: (a: number, b: number) => boolean): Candidate => {
+        const list = slot[word];
+        // A value this animation never keys, or keys only with values refused above, stays at setup.
+        if (list === undefined || list.length === 0) return setup[STABILITY_FIELD[word]];
+        return list.reduce((best, one) => (worse(one.value, best.value) ? one : best));
+      };
+      const combo: StabilityCombo = {
+        strength: pick('strength', (a, b) => a > b),
+        massInverse: pick('mass', (a, b) => a > b),
+        damping: pick('damping', (a, b) => a < b),
+      };
+      if (combo.strength.value === setup.strength.value && combo.massInverse.value === setup.massInverse.value && combo.damping.value === setup.damping.value) continue;
+      const at = physicsStepStability(combo.strength.value, combo.massInverse.value, combo.damping.value, physics.step);
+      if (at.stable) continue;
+      // A decay rounded to 1 by the setup damping itself is the setup line's, whatever else this animation keys.
+      if (!(at.d < 1) && at.k < at.bound && combo.damping.from === 'setup') continue;
+      fail(
+        'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
+        `animation "${animation}" can pose physics "${facts.constraints[index]?.name ?? `#${index}`}" at ${runawaySays(combo, physics.step, at)}`,
+      );
+    }
+  }
+
+  // --- strength held at 0 for as long as an animation plays (issue #1422) ---
+  //
+  // A strength KEY of 0 is accepted (issue #727) because it releases the
+  // constraint for a span and a later key pulls the offset back. An animation
+  // whose strength timelines pose 0 at EVERY time has no later key: [measured on
+  // #1422, x drive, the runtime's default world, spine-core and rigc's core
+  // identical bit for bit] the offset grows exactly linearly while it plays —
+  // 1.33e4 at 60 s, 5.33e4 at 240 s, 1.33e5 at 600 s — and A10's walk of
+  // max(duration, 1) s sees a finite number and passes it.
+  //
+  // 🔑 **"Every time it plays", not "looped".** Whether an animation loops is
+  // not in the artifact: skeleton JSON has no loop flag, the motion spec's
+  // `loop` is a player hint the compiler never reads (`MotionAnimation.loop`),
+  // and an editor export carries neither — and when it plays, and for how long,
+  // is the consumer's. The criterion that needs none of that is the one the
+  // runtime makes true either way: looped, the animation never leaves its
+  // values; played once, a track holds its last frame, which is 0. So the
+  // clause reads the timeline alone — every key and every Bézier sample, as
+  // the pose field it lands in, and the first key at t = 0, since before a
+  // later first key the timeline poses the setup value, which the strength row
+  // holds above 0.
+  //
+  // Per animation and constraint: when two strength timelines reach one
+  // constraint in one animation (a named one and the global one), it is held
+  // only if both are — a timeline that lifts it is a later key for the other.
+  // A constraint driving nothing is named by the first clause, and one resting
+  // at strength 0 or below by its row, so neither is read here.
+  const strengthRule = physicsRuleFor('strength');
+  const heldAtZero = new Map<string, Map<number, { keys: number; held: boolean }>>();
+  for (const timeline of facts.timelines) {
+    if (timeline.kind !== 'physics' || timeline.word !== 'strength') continue;
+    const first = timeline.frames[0];
+    const posed = (value: number): number => (timeline.posed === undefined ? value : timeline.posed(value));
+    const held = first !== undefined && first.time <= 0 && timeline.channelValues(0).every((value) => posed(value) === 0);
+    const byConstraint = heldAtZero.get(timeline.animation) ?? new Map<number, { keys: number; held: boolean }>();
+    heldAtZero.set(timeline.animation, byConstraint);
+    for (const index of timeline.reach) {
+      const was = byConstraint.get(index);
+      byConstraint.set(index, { keys: (was?.keys ?? 0) + timeline.frames.length, held: (was?.held ?? true) && held });
+    }
+  }
+  for (const [animation, byConstraint] of heldAtZero) {
+    for (const [index, { keys, held }] of byConstraint) {
+      const constraint = facts.constraints[index];
+      const physics = constraint?.physics;
+      if (!held || constraint === undefined || physics === undefined || strengthRule === undefined) continue;
+      if (!PHYSICS_COMPONENTS.some((k) => physics.components[k] > 0) || !strengthRule.poseOk(physics.setup.strength)) continue;
+      fail(
+        'A23_PHYSICS_CONSTRAINT_EFFECTIVE',
+        `animation "${animation}" poses physics "${constraint.name}" strength 0 at every time it plays — ${keys} key(s) from t=0, ` +
+          `every one 0 and no curve between them lifting it, so ${physicsOutsideSays(strengthRule, 0)}: a strength key of 0 is ` +
+          'accepted for a span because a later key pulls the offset back, and this animation has none, so for as long as it ' +
+          'plays, looped or held on its last frame, a push (wind, gravity, the bone moving) carries the offset away and it ' +
+          'grows without limit; key strength above 0 somewhere in the animation, or remove the timeline',
+      );
+    }
+  }
+}
+
+/** The three timelines whose values the stability clause combines. */
+type StabilityWord = 'strength' | 'mass' | 'damping';
+const STABILITY_FIELD: Record<StabilityWord, keyof StabilityCombo> = { strength: 'strength', mass: 'massInverse', damping: 'damping' };
+function isStabilityWord(word: string): word is StabilityWord {
+  return word === 'strength' || word === 'mass' || word === 'damping';
+}
+
+/** One value the stability clause read, and where it came from: `setup`, or a key or curve of the animation. */
+interface Candidate {
+  readonly value: number;
+  readonly from: string;
+}
+
+/** The three pose values the stability clause judges together. */
+interface StabilityCombo {
+  readonly strength: Candidate;
+  readonly massInverse: Candidate;
+  readonly damping: Candidate;
+}
+
+/** Whether every value the stability clause combines is inside its own row, so the joint condition is the only one left to read. */
+function stableInputs(pose: PhysicsSetup, step: number): boolean {
+  if (!(step > 0) || !Number.isFinite(step)) return false;
+  return PHYSICS_POSE_RULES.every((rule) => rule.timeline === 'mix' || rule.poseOk(pose[rule.field]));
+}
+
+/** A number as an author typed it: `1 / (1 / 45)` prints 45 rather than its last-bit neighbour. */
+function plain(value: number): string {
+  return String(Number(value.toPrecision(12)));
+}
+
+/**
+ * The stability clause's sentence: the four authored numbers, `k` and the bound
+ * as the runtime forms them, what the step does at that pose, and the four
+ * levers that move it back under the bound.
+ *
+ * ⚠️ One pose fails with `k` under the bound: a damping the row accepts — below
+ * 1 — whose decay `damping ** (60 * step)` the runtime's doubles round to exactly
+ * 1 (issue #1422: the largest double below 1 does from fps 121 on). That is the
+ * damping row's own fault, a velocity that never decays, reached through the
+ * rate, so it says so rather than printing a `k` that is under its bound.
+ */
+function runawaySays(combo: StabilityCombo, step: number, at: PhysicsStepStability): string {
+  const src = (c: Candidate): string => (c.from === 'setup' ? '' : ` (${c.from})`);
+  const fps = plain(1 / step);
+  if (!(at.d < 1)) {
+    return (
+      `damping ${combo.damping.value}${src(combo.damping)} at fps ${fps} — damping^(60·step) = ${at.d} as the runtime forms it, ` +
+      'so although the damping is below 1 no velocity ever decays: the step\'s eigenvalues lie on the unit circle, the fault ' +
+      'the damping row refuses 1 for, reached here by rounding; lower damping or lower fps'
+    );
+  }
+  const places = apart(at.k, at.bound, 4);
+  return (
+    `strength ${combo.strength.value}${src(combo.strength)}, mass ${plain(1 / combo.massInverse.value)} (massInverse ${combo.massInverse.value})${src(combo.massInverse)}, ` +
+    `fps ${fps}, damping ${combo.damping.value}${src(combo.damping)} — strength·massInverse·step² = ${at.k.toFixed(places)} must be < ` +
+    `2·(1 + damping^(60·step)) = ${at.bound.toFixed(places)}: at or past that bound the step stops settling — one step can ` +
+    `multiply the offset by ${at.growth.toFixed(apart(at.growth, 1, 3))} every 1/${fps} s — so a push (wind, gravity, a key, the ` +
+    'bone moving) never dies out, and past the bound it grows without limit; lower strength, raise mass, raise fps or raise damping'
+  );
+}
+
+/**
+ * The fewest decimal places, from `min`, at which `a` and `b` print apart — so
+ * a value one part in 10⁹ past the bound does not print as equal to it. Two
+ * equal numbers print at `min`.
+ */
+function apart(a: number, b: number, min: number): number {
+  if (a === b) return min;
+  for (let places = min; places < 17; places++) if (a.toFixed(places) !== b.toFixed(places)) return places;
+  return 17;
 }

package/src/check.ts

@@ -1286,6 +1286,18 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
         `${options.skin === undefined ? 'with no --skin' : `with --skin ${JSON.stringify(options.skin)}`}.`,
     );
   }
+  // A frame set drawn under `render --environment` (issue #1416) is a picture of the rig in a world `check` does not
+  // pose: it poses the candidate under the runtime's own wind and gravity, so the score would be a number about the
+  // difference between two worlds. Refused by name, as a subset is, rather than scored.
+  const referenceEnvironment = located.sidecar?.environment;
+  if (referenceEnvironment !== undefined) {
+    throw new CheckError(
+      `${FRAMES_SIDECAR} records that these frames were rendered under an environment schedule (\`rigc render ` +
+        `--environment\`, ${Array.isArray(referenceEnvironment) ? referenceEnvironment.length : 0} step(s)), and check poses the candidate ` +
+        "under none — the runtime's own wind [1, 0] and gravity [0, 1] — so the comparison would be a number about the " +
+        'difference between two worlds. Render the reference frames without --environment.',
+    );
+  }
   if (referenceSkin === null && options.skin !== undefined) {
     notes.push(
       `the candidate is posed under skin ${JSON.stringify(options.skin)} and the reference frames record no skin ` +

package/src/cli/core_commands.ts

@@ -32,6 +32,8 @@ 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 { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.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 +474,88 @@ 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;
+}
+
+/**
+ * `--pass-through <cloth>:<leg>[,…]` read against the skeleton's slots (issue
+ * #1413, `../passthrough.ts`), or refused as a usage error before anything is
+ * posed: a malformed list, an empty name, a slot the skeleton does not have, a
+ * pair named twice — each by its entry. `undefined` without the flag.
+ */
+function readPassThroughFlag(raw: string | undefined, facts: SkeletonFacts): PassPair[] | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    return readPassPairs(raw, facts.slots.map((slot) => slot.name));
+  } catch (err) {
+    if (err instanceof PassThroughError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
 /**
  * render — the frame series, drawn by the same rasteriser `check` measures with.
  *
@@ -487,6 +571,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;
@@ -511,6 +597,8 @@ export function cmdRender(flags: Record<string, string>): void {
       }
     }
   }
+  // The pass-through reading (issue #1413) is its own flag for --folds' reason: without it, every file is the bytes it was.
+  const passThrough = flags['pass-through'];
   // The same refusal for the same reason: the reading is of every mesh the pose shows, whatever a picture leaves out.
   if (folds) {
     for (const flag of ['slot', 'hide'] as const) {
@@ -524,6 +612,19 @@ export function cmdRender(flags: Record<string, string>): void {
     }
   }
 
+  // And for the pass-through reading: it reads the two slots as the frame draws them, and a subset changes which draw.
+  if (passThrough !== undefined) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--pass-through takes no --${flag}: it reads the cloth and the leg as the whole rig draws them, which a subset of the ` +
+            `drawn slots would change. Run \`rigc render --pass-through\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --pass-through for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
+
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
   console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
@@ -532,26 +633,33 @@ 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),
   );
   const only = readAnimationFlag(flags, [...facts.animations]);
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
+  const passPairs = readPassThroughFlag(passThrough, facts);
   // One object, so the framing and the frames cannot be posed under two
   // different skins — which would frame one shot with another shot's box.
   // Not annotated `PoseOptions`: that name is `src/pose.ts`'s in this file, and
   // `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 +673,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
@@ -587,7 +702,7 @@ export function cmdRender(flags: Record<string, string>): void {
     // `--geometry` rides on the SAME call (issue #864): the bones and the whole
     // attachments are read off the skeleton at the step that drew each frame, so
     // the export's grid is this frame set's by construction.
-    const sampling = geometry ? { ...pose, bones: true, geometry: true } : folds ? { ...pose, geometry: true } : pose;
+    const sampling = geometry ? { ...pose, bones: true, geometry: true } : folds || passPairs !== undefined ? { ...pose, geometry: true } : pose;
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -598,7 +713,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
@@ -612,10 +727,45 @@ export function cmdRender(flags: Record<string, string>): void {
         foldReadings.set(name, foldsFileOf(animation, fps, skin, foldsOf(poser.rest(skin, shown), read)));
       }
     }
-    return { viewport, sampled, geometryTexts, foldReadings };
+    // The pass-through reading, off the very pieces the frames are drawn from, in their draw order — one per set, every
+    // pair the flag names. A pair whose slot draws on no frame of any set drawn is refused rather than read as 0.
+    const passReadings = new Map<string, ReturnType<typeof passThroughFileOf>>();
+    if (passPairs !== undefined) {
+      const draws = new Set<string>();
+      for (const frames of sampled.values()) for (const frame of frames) for (const piece of frame.pieces) draws.add(piece.slot);
+      for (const pair of passPairs) {
+        for (const slot of [pair.cloth, pair.leg]) {
+          if (!draws.has(slot)) {
+            throw new UsageError(
+              `--pass-through: slot ${JSON.stringify(slot)} draws on no frame of [${[...sampled.keys()].join(', ')}]${skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`} ` +
+                '— it shows no region or mesh there, so it has no drawn outline to read',
+            );
+          }
+        }
+      }
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const shown = frames.map((frame) => frame.attachments ?? []);
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, pieces: frame.pieces, attachments: frame.attachments ?? [] }));
+        try {
+          passReadings.set(name, passThroughFileOf(animation, fps, skin, passThroughOf(passPairs, poser.rest(skin, shown), read, pages)));
+        } catch (err) {
+          if (err instanceof PassThroughError) throw new UsageError(`--pass-through, ${JSON.stringify(name)}: ${err.message}`);
+          throw err;
+        }
+      }
+    }
+    return { viewport, sampled, geometryTexts, foldReadings, passReadings };
   });
-  const { viewport, sampled, geometryTexts, foldReadings } = posed.value;
+  const { viewport, sampled, geometryTexts, foldReadings, passReadings } = 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}`);
 
@@ -644,6 +794,8 @@ export function cmdRender(flags: Record<string, string>): void {
     if (geometryOut !== undefined) writeFileSync(join(dir, GEOMETRY_FILE), geometryOut);
     const foldReading = foldReadings.get(name);
     if (foldReading !== undefined) writeFileSync(join(dir, FOLDS_FILE), foldsText(foldReading));
+    const passReading = passReadings.get(name);
+    if (passReading !== undefined) writeFileSync(join(dir, PASS_THROUGH_FILE), passThroughText(passReading));
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
@@ -657,7 +809,9 @@ export function cmdRender(flags: Record<string, string>): void {
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
     const foldNote = foldReading === undefined ? '' : ` + ${FOLDS_FILE} (${folding} of ${foldReading.meshes.length} mesh(es) fold)`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}`;
+    const passing = passReading?.pairs.filter((p) => p.frames.length > 0).length ?? 0;
+    const passNote = passReading === undefined ? '' : ` + ${PASS_THROUGH_FILE} (${passing} of ${passReading.pairs.length} pair(s) pass through)`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
@@ -667,6 +821,10 @@ export function cmdRender(flags: Record<string, string>): void {
       const line = foldLine(foldReading?.animation ?? null, fps, mesh);
       if (line !== null) console.log(`  ..    folds    ${line}`);
     }
+    for (const pair of passReading?.pairs ?? []) {
+      console.log(`  ..    pass     ${passSummaryLine(passReading?.animation ?? null, fps, pair)}`);
+      for (const frame of pair.frames) console.log(`  ..    pass     ${passFrameLine(passReading?.animation ?? null, pair, frame)}`);
+    }
   }
 
   // The sidecar is what makes this a frame SET rather than a pile of pictures:
@@ -682,6 +840,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.