spine-rigc 2.55.0 → 2.57.0

package/src/motion.ts

@@ -147,10 +147,11 @@ export const MOTION_KEYS = {
   MotionDrawOrderOffset: ['slot', 'offset'],
   MotionEventKey: ['t', 'name', 'int', 'float', 'string', 'volume', 'balance'],
   TrackDeriveTurn: ['kind', 'degrees', 'depth', 'carried', 'about'],
-  DeformTurn: ['kind', 'radius', 'depth', 'degrees', 'about'],
-  DeformAffine: ['kind', 'scale', 'about'],
-  DeformWave: ['kind', 'amplitude', 'wavelength', 'phase', 'along', 'axis'],
-  DeformBend: ['kind', 'amount', 'from', 'to', 'power', 'along', 'axis'],
+  DeformTurn: ['kind', 'radius', 'depth', 'degrees', 'about', 'envelope'],
+  DeformAffine: ['kind', 'scale', 'about', 'envelope'],
+  DeformWave: ['kind', 'amplitude', 'wavelength', 'phase', 'along', 'axis', 'envelope'],
+  DeformBend: ['kind', 'amount', 'from', 'to', 'power', 'along', 'axis', 'envelope'],
+  DeformEnvelope: ['axis', 'from', 'to', 'shape', 'mask'],
 } as const satisfies Record<string, readonly string[]>;
 
 /**
@@ -220,10 +221,16 @@ export const MOTION_TYPES = {
     t: 'number', name: 'string', int: 'number', float: 'number', string: 'string', volume: 'number', balance: 'number',
   },
   TrackDeriveTurn: { kind: 'enum', degrees: 'number', depth: 'mixed', carried: 'number', about: 'number' },
-  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number' },
-  DeformAffine: { kind: 'enum', scale: 'number[]', about: 'number[]' },
-  DeformWave: { kind: 'enum', amplitude: 'number', wavelength: 'number', phase: 'number', along: 'enum', axis: 'enum' },
-  DeformBend: { kind: 'enum', amount: 'number', from: 'number', to: 'number', power: 'number', along: 'enum', axis: 'enum' },
+  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number', envelope: 'object' },
+  DeformAffine: { kind: 'enum', scale: 'number[]', about: 'number[]', envelope: 'object' },
+  DeformWave: {
+    kind: 'enum', amplitude: 'number', wavelength: 'number', phase: 'number', along: 'enum', axis: 'enum', envelope: 'object',
+  },
+  DeformBend: {
+    kind: 'enum', amount: 'number', from: 'number', to: 'number', power: 'number', along: 'enum', axis: 'enum',
+    envelope: 'object',
+  },
+  DeformEnvelope: { axis: 'number[]', from: 'number', to: 'number', shape: 'enum', mask: 'string' },
 } as const satisfies MotionTypeTable;
 
 /**
@@ -242,6 +249,7 @@ export const MOTION_ENUMS = {
   DeformAffine: { kind: { owner: 'evaluateDeformTransform' } },
   DeformWave: { kind: { owner: 'evaluateDeformTransform' }, along: { owner: 'evaluateDeformTransform' }, axis: { owner: 'evaluateDeformTransform' } },
   DeformBend: { kind: { owner: 'evaluateDeformTransform' }, along: { owner: 'evaluateDeformTransform' }, axis: { owner: 'evaluateDeformTransform' } },
+  DeformEnvelope: { shape: { owner: 'evaluateDeformEnvelope' } },
 } as const satisfies SpecEnumTable<typeof MOTION_TYPES>;
 
 /** A deform key's `transform` kinds, and the shape each one's keys come from. */
@@ -587,6 +595,10 @@ function parseDeform(raw: unknown, where: string, at: string): void {
       if (isObj(parsed.transform)) {
         const shape = DEFORM_TRANSFORM_SHAPE[String(parsed.transform.kind)];
         if (shape !== undefined) known(parsed.transform, shape, where, `${at}.transform`);
+        // The envelope is one shape under all five kinds (issue #1413); which
+        // of its two forms it states, and whether the fields agree, is
+        // `evaluateDeformEnvelope`'s to say.
+        known(parsed.transform.envelope, 'DeformEnvelope', where, `${at}.transform.envelope`);
       }
     }
   }

package/src/render_shared.ts

@@ -115,6 +115,17 @@ export const SETUP_POSE_DIR = 'setup';
  * rate writes `<animation>/`, and any other rate writes `<animation>@<fps>fps/`.
  */
 export const PROTOCOL_FPS = 12;
+
+/**
+ * The directory a frame set of `animation` sampled at `fps` is written to under
+ * the render root: the animation's own name at the protocol rate, and
+ * `<animation>@<fps>fps` at any other — so two rates of one animation sit side by
+ * side. `render` and `bench/render_reference.ts` both name their sets through
+ * it, and `render --help` and AUTHORING §0 say what it does (issue #1414).
+ */
+export function frameSetDir(animation: string, fps: number): string {
+  return fps === PROTOCOL_FPS ? animation : `${animation}@${fps}fps`;
+}
 /** The rate the framing box is measured at, whatever `--fps` writes frames at. */
 export const FRAMING_FPS = 60;
 
@@ -222,6 +233,18 @@ export interface FramesSidecar {
    * it as a reference by name.
    */
   environment?: EnvironmentStep[];
+  /**
+   * The box was given rather than fitted, when `render --viewport` or
+   * `render --viewport-from` gave it (issue #1414): which flag, and every slot
+   * that reaches past the box, by set and frame — what lies past it is not in
+   * the frames, since each frame is the box.
+   *
+   * ⭐ Absent on a fitted render, for `skin`'s reason: every frame set written
+   * before the field existed says the same, and a fitted box is measured over
+   * the rig's own poses (every animation at `FRAMING_FPS`), padded, rather than
+   * stated by anyone.
+   */
+  pinned?: PinnedViewport;
   /** The colour the frames were cleared to, straight RGBA 0..255. */
   background: RGBA;
   viewport: {
@@ -238,6 +261,13 @@ export interface FramesSidecar {
   sets: FrameSet[];
 }
 
+/** How a given box was given, and what it leaves out — `FramesSidecar.pinned`. */
+export interface PinnedViewport {
+  by: '--viewport' | '--viewport-from';
+  /** Every slot whose drawn geometry reaches past the box, per set, in the order the sets were drawn and the slots first reached past it. */
+  outside: Array<{ set: string; slot: string; frames: number[] }>;
+}
+
 // ---------------------------------------------------------------------------
 // posing
 // ---------------------------------------------------------------------------

package/src/rig.ts

@@ -32,6 +32,9 @@
  * - `invariants` — the structural facts skeleton JSON cannot state about itself,
  *   which the validator's archetype assertions read. Nothing in the file says
  *   "this bone carries the cut's axis" or "this parentage is forbidden".
+ * - `stops` — a swinging chain held off a leg, one declaration for the network
+ *   of bones and constraints it stands for (`RigStop`), expanded into plain
+ *   bones and constraints before anything else reads the rig.
  *
  * ## What a field's PRESENCE means
  *
@@ -61,6 +64,7 @@
  */
 import { ikShapeFault } from './assertions/bodies/a47.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
+import { expandStops } from './stop.ts';
 import { dottedPath, refuseNumbersTheFileCannotCarry, refuseUnknownKeys, refuseValuesOfTheWrongType, refuseValuesOutsideTheirSet } from './keys.ts';
 import type { ShapeVisit, SpecEnumTable, SpecValueType } from './keys.ts';
 
@@ -1887,6 +1891,69 @@ export interface RigDeformFoldExemption {
   why: string;
 }
 
+// ---------------------------------------------------------------------------
+// stops — a swinging chain held off a leg (issue #1413)
+// ---------------------------------------------------------------------------
+
+/**
+ * One chain held off a leg: the network [`src/stop.ts`](stop.ts) expands it to,
+ * written once instead of by hand. Spine has no collider and no angle limit, so
+ * a physics-driven skirt chain swings its hem through the thigh it hangs in
+ * front of; this holds the chain's DRAWN links — the bones its mesh is
+ * weighted to — so they may swing away from the leg and not toward it past
+ * their rest angle.
+ *
+ * It expands, before anything else reads the rig, to exactly:
+ *
+ *   - `<chain>_touch` — a point bone, child of `against`, at `at`;
+ *   - `<chain>_stop` — a frame hung where the first link hangs (its parent,
+ *     `x`, `y` and `length`), aimed at the point by the ik constraint
+ *     `<chain>_stop_aim`;
+ *   - `<link>_rel` — a child of the frame that the transform constraint
+ *     `<link>_rel_copy` gives the first link's world rotation;
+ *   - `<link>_d` — the first link's drawn link, a child of the frame, which the
+ *     transform constraint `<link>_clamp` gives `_rel`'s turn in the frame,
+ *     clamped to the range;
+ *   - for each link below the first, `<link>_d` — its drawn link, a sibling
+ *     with its stated transform — and `<link>_clamp`, which gives it the link's
+ *     own turn, clamped to `lower`.
+ *
+ * So a chain's next link hangs from the drawn link above it: author the chain
+ * with each link's parent below `<previous link>_d`, and weight the mesh to the
+ * `_d` bones. What the expansion derives, it derives from the setup pose this
+ * file states (`src/stop.ts` lists it); nothing is measured off the art.
+ */
+export interface RigStop {
+  /** The name the point, the frame and the aim are called after. */
+  chain: string;
+  /**
+   * The chain's swinging links, root first: each one written by a constraint
+   * in `constraints` (its swing), each below the first hanging from the drawn
+   * link of the one above. Resolved by name.
+   */
+  links: string[];
+  /** The bone the point rides on — the leg. Resolved by name. */
+  against: string;
+  /** The point, `[x, y]` in `against`'s local space. Required: the compiler places no point. */
+  at: [number, number];
+  /**
+   * The first drawn link's range, as its two ends: degrees from its rest angle
+   * to the aim line, counted positive AWAY from the point. `inward: 0,
+   * outward: 60` — never past rest toward the leg, up to 60° away from it.
+   * Both required, `inward` not above `outward`.
+   */
+  inward: number;
+  outward: number;
+  /** Each lower drawn link's range off its own rest bend, the same way round. Required when `links` has more than one. */
+  lower?: RigStopLower;
+}
+
+/** A lower link's range — `RigStop.lower`. */
+export interface RigStopLower {
+  inward: number;
+  outward: number;
+}
+
 // ---------------------------------------------------------------------------
 // the file
 // ---------------------------------------------------------------------------
@@ -1932,6 +1999,12 @@ export interface RigSpec {
    */
   events?: Record<string, RigEvent>;
   invariants?: RigInvariants;
+  /**
+   * Chains held off a leg — see `RigStop`. Expanded by `parseRigSpec` into
+   * bones and constraints before anything else reads them; kept as written,
+   * and emitted nowhere.
+   */
+  stops?: RigStop[];
 }
 
 // ---------------------------------------------------------------------------
@@ -1960,7 +2033,9 @@ function isObj(v: unknown): v is Record<string, unknown> {
  * fault.
  */
 export const RIG_KEYS = {
-  RigSpec: ['spec', 'name', 'note', 'skeleton', 'images', 'bones', 'slots', 'skins', 'constraints', 'events', 'invariants'],
+  RigSpec: ['spec', 'name', 'note', 'skeleton', 'images', 'bones', 'slots', 'skins', 'constraints', 'events', 'invariants', 'stops'],
+  RigStop: ['chain', 'links', 'against', 'at', 'inward', 'outward', 'lower'],
+  RigStopLower: ['inward', 'outward'],
   RigSkeletonHeader: ['x', 'y', 'width', 'height', 'fps', 'referenceScale', 'images', 'audio', 'stageBox'],
   RigStageBox: ['slot', 'attachment'],
   RigBone: ['name', 'parent', 'length', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY', 'inherit', 'skin', 'color', 'icon', 'from'],
@@ -2060,8 +2135,10 @@ type RigTypeTable = {
 export const RIG_TYPES = {
   RigSpec: {
     spec: 'enum', name: 'string', note: 'string', skeleton: 'object', images: 'string', bones: 'object[]', slots: 'object[]',
-    skins: 'map of object', constraints: 'object[]', events: 'map of object', invariants: 'object',
+    skins: 'map of object', constraints: 'object[]', events: 'map of object', invariants: 'object', stops: 'object[]',
   },
+  RigStop: { chain: 'string', links: 'string[]', against: 'string', at: 'number[]', inward: 'number', outward: 'number', lower: 'object' },
+  RigStopLower: { inward: 'number', outward: 'number' },
   RigSkeletonHeader: {
     x: 'number', y: 'number', width: 'number | null', height: 'number | null', fps: 'number', referenceScale: 'number',
     images: 'string', audio: 'string | null', stageBox: 'object',
@@ -2405,6 +2482,12 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): Array<{
     at(event, 'RigEvent', `event "${name}"`, ['events', name]);
   }
 
+  for (const [i, stop] of (Array.isArray(raw.stops) ? raw.stops : []).entries()) {
+    const who = isObj(stop) && typeof stop.chain === 'string' ? `stop "${stop.chain}"` : `stops[${i}]`;
+    at(stop, 'RigStop', who, ['stops', i]);
+    if (isObj(stop)) at(stop.lower, 'RigStopLower', `${who}'s "lower"`, ['stops', i, 'lower']);
+  }
+
   if (isObj(raw.invariants)) {
     at(raw.invariants, 'RigInvariants', '"invariants"', ['invariants']);
     for (const [i, rule] of (Array.isArray(raw.invariants.detached) ? raw.invariants.detached : []).entries()) {
@@ -2528,6 +2611,11 @@ function rigPlace(raw: Record<string, unknown>): (path: ReadonlyArray<string | n
       if (head === 'bones') return `${named(raw.bones, second, 'bone', 'bones')}${rest(path.slice(2))}`;
       if (head === 'slots') return `${named(raw.slots, second, 'slot', 'slots')}${rest(path.slice(2))}`;
       if (head === 'constraints') return `${named(raw.constraints, second, 'constraint', 'constraints')}${rest(path.slice(2))}`;
+      if (head === 'stops') {
+        const node = Array.isArray(raw.stops) ? raw.stops[second] : undefined;
+        const who = isObj(node) && typeof node.chain === 'string' ? `stop ${JSON.stringify(node.chain)}` : `stops[${second}]`;
+        return `${who}${rest(path.slice(2))}`;
+      }
     }
     if (head === 'events' && typeof second === 'string') return `event ${JSON.stringify(second)}${rest(path.slice(2))}`;
     if (head === 'skins' && typeof second === 'string') {
@@ -2609,7 +2697,11 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
     throw new CompileError(`${where}: a rig spec needs a "slots" array (it may be empty; its ORDER is the draw order)`);
   }
 
-  const spec = raw as unknown as RigSpec;
+  // `stops` first, ahead of every name this function resolves: a chain's next
+  // link hangs from the drawn link a stop generates, so the bones below are
+  // read as the expansion lays them out — and every reader after this one sees
+  // ordinary bones and constraints (`src/stop.ts`).
+  const spec = expandStops(raw as unknown as RigSpec, where);
 
   // The stage, stated or stated absent. Half a statement is refused here rather
   // than resolved in `compile`, because which half was meant is not derivable