spine-rigc 2.52.0 → 2.54.0

package/src/environment.ts

@@ -0,0 +1,193 @@
+/**
+ * The world a render's physics answers, in time — `rigc render --environment`
+ * (issue #1416, part C).
+ *
+ * A rig's physics constraints state how much each one answers wind and
+ * gravity (their own `wind` and `gravity`, AUTHORING §4.6). The world they
+ * answer is the consumer's: the two direction vectors spine-core keeps on its
+ * `Skeleton` (`windX, windY`, `gravityX, gravityY`), which a live track sets
+ * with `setEnvironment` (`./core/track.ts`). A render has no consumer, so this
+ * file is one: a list of steps in time, each changing the world from its `t`
+ * until the next, which both render posers set before the step that poses each
+ * frame (`src/render_core.ts`, `src/render.ts`).
+ *
+ * ⭐ It inspects what the rig offers; it does not compose a scene. Which gust
+ * blows when is the consumer's, and a schedule here is a probe of the response
+ * — the same probe on both posers, so the export's answer to it is held to the
+ * core's (the render-environment suite).
+ *
+ * The coordinates are the runtime's own and the live track's: x to the right,
+ * **y down** (a positive y pulls toward the bottom of the screen, as the
+ * runtime's initial gravity `[0, 1]` does). Until the first step the world is
+ * the runtime's initial one, wind `[1, 0]` and gravity `[0, 1]`, which is what a
+ * render without the flag answers — so a calm start has to be stated.
+ *
+ * Nothing here links spine-core, and nothing here reads a clock: the schedule
+ * is resolved onto a frame grid by arithmetic on the frame index alone.
+ */
+import type { PhysicsEnvironment } from './core/constraints_physics.ts';
+
+/** The tag a schedule file states, refused by name when it states another. */
+export const ENVIRONMENT_SPEC = 'rigc-environment/1';
+
+/** One pose's change to the world: either half, the other kept as it stands. */
+export type EnvironmentChange = Partial<PhysicsEnvironment>;
+
+/** One step of a schedule: from `t` seconds on, until the next step, the world is changed by `wind` and/or `gravity`. */
+export interface EnvironmentStep {
+  t: number;
+  wind?: [number, number];
+  gravity?: [number, number];
+}
+
+/** A schedule refused — by entry index, field, the value found and what is required. */
+export class EnvironmentError extends Error {}
+
+const TOP_KEYS = ['spec', 'steps'] as const;
+const STEP_KEYS = ['t', 'wind', 'gravity'] as const;
+const PAIR = 'a pair of finite numbers [x, y] (x to the right, y down)';
+
+/** A value as a refusal shows it: JSON, except that a number that is not finite is written as itself rather than as `null`. */
+function shown(value: unknown): string {
+  if (typeof value === 'number') return String(value);
+  if (Array.isArray(value)) return `[${value.map(shown).join(', ')}]`;
+  if (value === undefined) return 'nothing';
+  return JSON.stringify(value);
+}
+
+/** What a value is, for the refusal of a file or an entry that is not an object. */
+function kindOf(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `${typeof value === 'object' ? 'an' : 'a'} ${typeof value} ${typeof value === 'object' ? '' : shown(value)}`.trimEnd();
+}
+
+/**
+ * A schedule file's text read, or refused by name before anything is posed.
+ * `where` is how the refusal names the file. Every step is returned with its
+ * keys in one order — `t`, `wind`, `gravity` — whatever order the file wrote
+ * them in, so what a render records of it does not depend on the spelling.
+ */
+export function readEnvironmentSchedule(text: string, where: string): EnvironmentStep[] {
+  const refuse = (what: string): EnvironmentError => new EnvironmentError(`--environment ${where}: ${what}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw refuse(`not JSON — ${(err as Error).message}`);
+  }
+  const shape = `{ "spec": "${ENVIRONMENT_SPEC}", "steps": [{ "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }, …] }`;
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw refuse(`the file holds ${kindOf(parsed)}, not an object ${shape}`);
+  const top = parsed as Record<string, unknown>;
+  for (const key of Object.keys(top)) {
+    if (!(TOP_KEYS as readonly string[]).includes(key)) throw refuse(`the file names "${key}", which is not one of [${TOP_KEYS.join(', ')}]`);
+  }
+  if (top.spec !== ENVIRONMENT_SPEC) throw refuse(`"spec" is ${shown(top.spec)}; render reads "${ENVIRONMENT_SPEC}"`);
+  const steps = top.steps;
+  if (!Array.isArray(steps) || steps.length === 0) throw refuse(`"steps" is ${shown(steps)}, not a non-empty array of { "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }`);
+  const out: EnvironmentStep[] = [];
+  steps.forEach((entry: unknown, i) => {
+    const at = `entry ${i} of "steps"`;
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) throw refuse(`${at} is ${kindOf(entry)}, not an object { "t": <seconds>, "wind"?: [x, y], "gravity"?: [x, y] }`);
+    const given = entry as Record<string, unknown>;
+    for (const key of Object.keys(given)) {
+      if (!(STEP_KEYS as readonly string[]).includes(key)) throw refuse(`${at} names "${key}", which is not one of [${STEP_KEYS.join(', ')}]`);
+    }
+    const t = given.t;
+    if (typeof t !== 'number' || !Number.isFinite(t) || t < 0) throw refuse(`${at}'s "t" is ${shown(t)}, not a finite time in seconds at or above 0`);
+    const previous = out[i - 1];
+    if (previous !== undefined && !(t > previous.t)) {
+      throw refuse(`${at}'s "t" is ${shown(t)}, not after entry ${i - 1}'s ${shown(previous.t)} — steps are listed in ascending time, each holding until the next`);
+    }
+    const pair = (key: 'wind' | 'gravity'): [number, number] | undefined => {
+      const v = given[key];
+      if (v === undefined) return undefined;
+      if (!Array.isArray(v) || v.length !== 2 || v.some((n) => typeof n !== 'number' || !Number.isFinite(n))) throw refuse(`${at}'s "${key}" is ${shown(v)}, not ${PAIR}`);
+      return [v[0] as number, v[1] as number];
+    };
+    const wind = pair('wind');
+    const gravity = pair('gravity');
+    if (wind === undefined && gravity === undefined) throw refuse(`${at} (t ${shown(t)}) states neither "wind" nor "gravity", so it changes nothing`);
+    out.push({ t, ...(wind === undefined ? {} : { wind }), ...(gravity === undefined ? {} : { gravity }) });
+  });
+  return out;
+}
+
+/**
+ * The frame a step at `t` seconds is first posed on at `fps`: the first frame
+ * `i` whose time `i / fps` is at or after `t`. Its change is set before the
+ * step that poses that frame, so the physics integrates the new world over the
+ * frame's whole interval. Exact for the predicate as written: `i / fps` is the
+ * division correctly rounded, so a `t` that names a frame's time lands on it.
+ */
+export function environmentFrame(t: number, fps: number): number {
+  let i = Math.max(0, Math.ceil(t * fps));
+  while (i > 0 && (i - 1) / fps >= t) i--;
+  while (i / fps < t) i++;
+  return i;
+}
+
+/**
+ * A schedule on the frame grid of `fps`: each frame's change, or `undefined`.
+ * Steps landing on one frame are merged in order, a later half over an
+ * earlier — which only the framing meets (`FRAMING_FPS`), since `render`
+ * refuses a schedule two of whose steps share a frame of its own grid
+ * (`environmentCollisions`).
+ */
+export function environmentAt(steps: readonly EnvironmentStep[], fps: number): (index: number) => EnvironmentChange | undefined {
+  const byFrame = new Map<number, EnvironmentChange>();
+  for (const step of steps) {
+    const frame = environmentFrame(step.t, fps);
+    const before = byFrame.get(frame) ?? {};
+    byFrame.set(frame, { ...before, ...(step.wind === undefined ? {} : { wind: step.wind }), ...(step.gravity === undefined ? {} : { gravity: step.gravity }) });
+  }
+  return (index) => byFrame.get(index);
+}
+
+/** The steps that share a frame of the `fps` grid, by frame — each group's first step would never be posed. */
+export function environmentCollisions(steps: readonly EnvironmentStep[], fps: number): Array<{ frame: number; entries: number[] }> {
+  const groups = new Map<number, number[]>();
+  steps.forEach((step, i) => {
+    const frame = environmentFrame(step.t, fps);
+    groups.set(frame, [...(groups.get(frame) ?? []), i]);
+  });
+  return [...groups].filter(([, entries]) => entries.length > 1).map(([frame, entries]) => ({ frame, entries }));
+}
+
+/**
+ * Which physics constraints of a Spine 4.3 skeleton answer each half of the
+ * world: `declared` every physics constraint by name; `wind` and `gravity` the
+ * ones stating a non-zero `wind` or `gravity` (the runtime reads an absent one
+ * as 0) and, as `"<constraint>" keyed by "<animation>"`, every physics
+ * timeline keying that field (`""` keys every constraint). Read off the
+ * skeleton's JSON as plain JSON, the same text both posers pose.
+ */
+export interface EnvironmentResponse {
+  declared: string[];
+  wind: string[];
+  gravity: string[];
+}
+
+function objectOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+export function environmentResponse(skeletonText: string): EnvironmentResponse {
+  const root = objectOf(JSON.parse(skeletonText));
+  const constraints = Array.isArray(root.constraints) ? root.constraints.map(objectOf).filter((c) => c.type === 'physics') : [];
+  const declared = constraints.map((c) => String(c.name));
+  const out: EnvironmentResponse = { declared, wind: [], gravity: [] };
+  for (const half of ['wind', 'gravity'] as const) {
+    for (const c of constraints) {
+      const v = c[half];
+      if (typeof v === 'number' && v !== 0) out[half].push(`"${String(c.name)}" (${half} ${v})`);
+    }
+    for (const [animation, body] of Object.entries(objectOf(root.animations))) {
+      for (const [target, timelines] of Object.entries(objectOf(objectOf(body).physics))) {
+        const keys = objectOf(timelines)[half];
+        if (Array.isArray(keys) && keys.length > 0) out[half].push(`${target === '' ? 'every constraint' : `"${target}"`} keyed by "${animation}"`);
+      }
+    }
+  }
+  return out;
+}

package/src/mesh.ts

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

package/src/render.ts

@@ -130,6 +130,7 @@ import { dirname, join } from 'node:path';
 import { Plate, readPlate } from '../tools/plate.ts';
 import { clipSourceOf, corePoser, inactiveBoneSnapshot, physicsClockStep, subsetOver, unposedBones } from './render_core.ts';
 import { type PosedVertices, type WorldTransform } from './nonfinite.ts';
+import type { EnvironmentChange } from './environment.ts';
 import {
   atlasScales,
   choosePosers,
@@ -500,7 +501,7 @@ export function spinePoser(data: SkeletonData): Poser {
     slots: data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
     subset: (opts, skin) => slotSubsetOf(data, opts, skin),
     setup: (skin) => spinePosed(setupPosed(data, skin)),
-    animation: (name, skin, fps, count, visit) => {
+    animation: (name, skin, fps, count, visit, environment) => {
       const skeleton = skeletonUnderSkin(data, skin);
       const state = new AnimationState(new AnimationStateData(data));
       // Not looping: the last frame sits at the animation's duration, and a looping
@@ -515,10 +516,12 @@ export function spinePoser(data: SkeletonData): Poser {
         if (i > 0) {
           state.update(step);
           state.apply(skeleton);
+          setSkeletonEnvironment(skeleton, environment?.(i));
           skeleton.update(clock);
           skeleton.updateWorldTransform(Physics.update);
         } else {
           state.apply(skeleton);
+          setSkeletonEnvironment(skeleton, environment?.(i));
           skeleton.update(0);
           skeleton.updateWorldTransform(Physics.reset);
         }
@@ -529,6 +532,17 @@ export function spinePoser(data: SkeletonData): Poser {
   };
 }
 
+/**
+ * `render --environment`'s change for one frame (issue #1416), set on spine-core's own `Skeleton` before the update that
+ * poses the frame: `wind` is `windX, windY` and `gravity` is `gravityX, gravityY`, both in the runtime's convention, x
+ * right and y down — the live track's `setEnvironment` mapping, held to these four fields by the core suite's `CO56`. A
+ * half left out keeps the one standing, as the core merges it.
+ */
+function setSkeletonEnvironment(skeleton: Skeleton, change: EnvironmentChange | undefined): void {
+  if (change?.wind !== undefined) [skeleton.windX, skeleton.windY] = change.wind;
+  if (change?.gravity !== undefined) [skeleton.gravityX, skeleton.gravityY] = change.gravity;
+}
+
 /** A spine-core skeleton as it stands posed, read through the seam's `Posed`. */
 function spinePosed(skeleton: Skeleton): Posed {
   return {

package/src/render_core.ts

@@ -100,7 +100,7 @@ import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
 import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
 import { activeBones, CoreInputError, readModel, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
-import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
+import { PHYSICS_CLOCK_LEAD, physicsClockStep, poseRawAnimationEach, poseRawSetup, type RawDrawn, type RawPose, type StepEnvironment } from './core/raw.ts';
 import type { TimelinePlant } from './core/animation.ts';
 import { CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
 import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
@@ -363,10 +363,14 @@ export function keptPieceArrays(): PieceArrays {
  * one pose is held at a time rather than the animation's whole series. A plant
  * passes another (`RC44`).
  */
-export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void) => void;
+export type CoreRawWalk = (doc: CompiledDocument, animation: string, steps: readonly number[], plant: TimelinePlant, visit: (pose: RawPose, index: number) => void, environment?: StepEnvironment) => void;
 
-/** The walk `corePoser` steps with unless a plant passes another: one pose posed, drawn and released before the next, the physics clock moved by `physicsClockStep` (issue #1380). */
-export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep);
+/**
+ * The walk `corePoser` steps with unless a plant passes another: one pose posed, drawn and released before the next, the
+ * physics clock moved by `physicsClockStep` (issue #1380), and `render --environment`'s change for each pose set before it
+ * is posed (issue #1416, `StepEnvironment`).
+ */
+export const CORE_RAW_WALK: CoreRawWalk = (doc, animation, steps, plant, visit, environment) => poseRawAnimationEach(doc, animation, steps, plant, 'animation', visit, physicsClockStep, environment);
 
 /**
  * The render's physics clock (issue #1380): defined beside the walk that takes it (`./core/raw.ts`), where the mesh
@@ -750,7 +754,7 @@ export function corePoser(
       const input = inputOf(skin);
       return corePosed(input, poseRawSetup(input.doc, { through }), through);
     },
-    animation: (name, skin, fps, count, visit) => {
+    animation: (name, skin, fps, count, visit, environment) => {
       const input = inputOf(skin);
       const step = 1 / fps;
       // Each pose is drawn as it is posed and released before the next (issue #1180), so the walk holds one pose and not
@@ -765,7 +769,7 @@ export function corePoser(
         } catch (thrown) {
           drawFailed.push(thrown);
         }
-      });
+      }, environment);
       if (drawFailed.length > 0) throw drawFailed[0];
     },
     rest: (skin, shown) => {

package/src/render_shared.ts

@@ -38,6 +38,7 @@ import {
 import { spinePosingFor, type SpineSkeletonData } from './spine_side.ts';
 import { walkTimelines } from './timelines.ts';
 import { firstNonFinite, type PosedVertices, type WorldTransform } from './nonfinite.ts';
+import { environmentAt, type EnvironmentChange, type EnvironmentStep } from './environment.ts';
 
 // ---------------------------------------------------------------------------
 // the Spine side, through the seam (issue #1052)
@@ -211,6 +212,16 @@ export interface FramesSidecar {
   slots?: string[];
   /** The slots these frames leave out, when `render --hide` named them — see `slots`. */
   hidden?: string[];
+  /**
+   * The schedule the physics answered, when `render --environment` gave one
+   * (issue #1416) — its steps as read, each `{ t, wind?, gravity? }`.
+   *
+   * ⭐ Absent on a render without it, for `skin`'s reason: every frame set
+   * written before the field existed says the same. A frame set carrying it is
+   * a picture of the rig in a world `check` does not pose, so `check` refuses
+   * it as a reference by name.
+   */
+  environment?: EnvironmentStep[];
   /** The colour the frames were cleared to, straight RGBA 0..255. */
   background: RGBA;
   viewport: {
@@ -391,6 +402,19 @@ export interface PoseOptions {
    * second render writes.
    */
   unclipped?: boolean;
+  /**
+   * The world the physics answers, in time — `render --environment` (issue
+   * #1416, `./environment.ts`): each step's change set before the step that
+   * poses the first frame at or after its `t`, on the sampler's own frame grid,
+   * on whichever poser draws. Absent, nothing is set and every pose is the one
+   * it always was.
+   *
+   * ⭐ **It is part of the shot, so the framing reads it.** Unlike `slots` and
+   * `hidden`, which say which pixels are drawn of one pose, an environment
+   * changes the pose — a gust can carry a coat past the box a still rig fills —
+   * so `framingViewport` keeps it and the box holds what the frames draw.
+   */
+  environment?: readonly EnvironmentStep[];
 }
 
 /**
@@ -1025,8 +1049,10 @@ export interface Poser {
   /**
    * Animation `name` under `skin`, not looping: `visit(i, posed)` for every
    * `i` from 0 to `count`, the pose at `i/fps`. The caller has checked `name`.
+   * `environment(i)`, when given, is the change to the world the physics
+   * answers set before the step that poses frame `i` (issue #1416).
    */
-  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void): void;
+  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }
@@ -1091,7 +1117,12 @@ export function sampleAnimation(source: PoseSource, name: string, fps: number, o
   const count = Math.round(animation.duration * fps);
   const draw = drawResolver(poser, opts);
   const frames: Frame[] = [];
-  poser.animation(name, opts?.skin, fps, count, (i, posed) => frames.push(frameOf(i, i * step, posed, draw(), opts)));
+  const visit = (i: number, posed: Posed): void => {
+    frames.push(frameOf(i, i * step, posed, draw(), opts));
+  };
+  // Without an environment the call is the one it always was, so a poser that takes none is asked nothing new.
+  if (opts?.environment === undefined) poser.animation(name, opts?.skin, fps, count, visit);
+  else poser.animation(name, opts.skin, fps, count, visit, environmentAt(opts.environment, fps));
   return frames;
 }
 
@@ -1411,6 +1442,8 @@ export interface GeometryFile {
   /** The animation, or `null` for a skeleton with none (its one frame is the setup pose). */
   animation: string | null;
   skin?: string;
+  /** The schedule the physics answered (`render --environment`, issue #1416) — `frames.json`'s own `environment`; absent without it. */
+  environment?: EnvironmentStep[];
   fps: number;
   /** The box the PNG frames beside this file were drawn over — `frames.json`'s own `viewport`. */
   viewport: FramesSidecar['viewport'];
@@ -1470,6 +1503,7 @@ export function geometryFileOf(
   frames: Frame[],
   viewport: Viewport,
   skin: string | undefined,
+  environment?: EnvironmentStep[],
 ): GeometryFile {
   const geometryFrame = (frame: Frame, where: string): Omit<GeometryFrame, 'index' | 'time'> => {
     if (frame.bones === undefined || frame.attachments === undefined) {
@@ -1493,6 +1527,7 @@ export function geometryFileOf(
     coordinates: GEOMETRY_COORDINATES,
     animation,
     ...(skin === undefined ? {} : { skin }),
+    ...(environment === undefined ? {} : { environment }),
     fps,
     viewport: sidecarViewport(viewport),
     bones: poser.bones.map(({ name, parent }) => ({ name, parent })),

package/src/rig.ts

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