spine-rigc 1.2.2 → 1.3.0

package/src/rig.ts

@@ -557,6 +557,72 @@ export interface RigGridGenerator {
   soft?: RigSoftRegion;
 }
 
+/**
+ * One segment stated outright, for a pull that no bone's own span describes.
+ *
+ * `from` and `to` are in the part's own pixels, y down — the frame every other
+ * point a generator takes is in (`ring.center`, `ring.hull`). The bone is
+ * resolved by name like everything else; the two points belong to this mesh
+ * alone, which is the case a bone's `length` cannot cover: two meshes over one
+ * bone that each want it to pull along a different line.
+ */
+export interface RigSegmentSpan {
+  bone: string;
+  from: [number, number];
+  to: [number, number];
+}
+
+/**
+ * How distance to a segment becomes a weight: `w = 1 / (d + radius)^power`
+ * per candidate bone, the strongest `maxBones` kept and normalised, any share
+ * under `minWeight` dropped, the rest normalised again.
+ */
+export interface RigSegmentsFalloff {
+  /** The exponent. Default 2. */
+  power?: number;
+  /**
+   * **Required.** Added to every distance, in the part's pixels, so a vertex
+   * ON a segment has a finite weight and the blend between two segments is as
+   * wide as this says. No default: it is a length on this part's art.
+   */
+  radius: number;
+  /** At most this many bones pull one vertex. Default 4. */
+  maxBones?: number;
+  /** A normalised share under this is dropped. Default 0.03. */
+  minWeight?: number;
+}
+
+/**
+ * A lattice over the part's alpha, weighted by distance to named bone segments
+ * (`buildSegmentsLattice` and `segmentWeights` in [`mesh.ts`](mesh.ts)).
+ *
+ * ⭐ The one authoring decision is `bones` — which segments may pull this part.
+ * The geometry comes off the attachment's own `image`, the segments off the
+ * skeleton's setup pose, and the weights off the distance between the two, so
+ * nothing else here is a judgement about the art.
+ */
+export interface RigSegmentsGenerator {
+  kind: 'segments';
+  /** **Required.** The lattice's cell, in the part's pixels, a whole number of at least 1. */
+  cell: number;
+  /**
+   * **Required, at least one entry.** Each is a bone name (origin to its
+   * `length` tip), a chain — a list of bone names, root first, each link
+   * running from its origin to the next link's (the last to its `length` tip) —
+   * or a `RigSegmentSpan` stated outright.
+   */
+  bones: Array<string | string[] | RigSegmentSpan>;
+  /** The falloff — see `RigSegmentsFalloff`. `radius` is required, so the block is too. */
+  falloff: RigSegmentsFalloff;
+  /** Alpha at or above which a pixel counts as art, 1..255. Default 1 — `contour`'s own. */
+  alpha?: number;
+  /**
+   * Where the slot bone sits in the part's pixels, y down. Default the window's
+   * centre — the placement every generator on this route uses.
+   */
+  anchor?: [number, number];
+}
+
 /**
  * Which builder in `src/mesh.ts` makes this mesh's geometry, and its parameters.
  *
@@ -570,10 +636,15 @@ export interface RigGridGenerator {
  * and measured art lives in the manifest. `generator` is for a skeleton with no
  * manifest behind it.
  */
-export type RigMeshGenerator = RigRingGenerator | RigRibbonGenerator | RigContourGenerator | RigGridGenerator;
+export type RigMeshGenerator =
+  | RigRingGenerator
+  | RigRibbonGenerator
+  | RigContourGenerator
+  | RigGridGenerator
+  | RigSegmentsGenerator;
 
-/** The four `kind` names a generator may carry, and the order `RIG_KEYS` takes them in. */
-export const RIG_GENERATOR_KINDS = ['ring', 'ribbon', 'contour', 'grid'] as const;
+/** The five `kind` names a generator may carry, and the order `RIG_KEYS` takes them in. */
+export const RIG_GENERATOR_KINDS = ['ring', 'ribbon', 'contour', 'grid', 'segments'] as const;
 
 /**
  * The attachment's own NAME, as distinct from the placeholder key it is filed
@@ -1591,6 +1662,35 @@ export interface RigInvariants {
    * left to measure, and on the build's stats line when something is.
    */
   consumerDrivenMix?: RigConsumerDrivenMix[];
+  /**
+   * The rig's `idle` deforms meshes **on purpose**, so
+   * `A15_IDLE_NO_MESH_BONE_KEYS` reports the renderer cost instead of refusing
+   * each keyed bone (issues #855, #858).
+   *
+   * 🔑 **What A15 assumes, and the genre that breaks it.** The rule exists for a
+   * renderer that skips redrawing a mesh nothing moved, so an `idle` keying a
+   * mesh-driving bone spends that skip on every frame — right for a rig whose
+   * meshes are mostly static, wrong for a painting rig: one illustration
+   * decomposed into layers, most of them weighted meshes over bone chains, with
+   * an `idle` whose whole job is to move them (hair, sleeves, breathing). The
+   * only way through without this field was a same-origin parent above every
+   * keyed bone — 42 extra bones on the first such rig, the same pose, the rule's
+   * wording met and its purpose not.
+   *
+   * 🚨 **An opt-OUT, held to `deformMayFold`'s standard.** The shape is
+   * `{ "why": … }` and a missing, blank or non-string `why` is refused by name.
+   * What it buys is a **SKIP, never a pass**, and the SKIP carries the cost —
+   * the keyed bones, how many mesh attachments they drive and how many vertices
+   * those hold. A declaration on a rig whose `idle` keys no mesh-driving bone is
+   * refused at the gate: it would switch off nothing while reading like it did.
+   */
+  idleDrivesMeshes?: RigIdleDrivesMeshes;
+}
+
+/** The rig's `idle` is meant to deform meshes — `invariants.idleDrivesMeshes` (`A15`). */
+export interface RigIdleDrivesMeshes {
+  /** Required, and blank is refused by name — see `idleDrivesMeshes`. */
+  why: string;
 }
 
 /** One constraint whose mix the consumer drives — `invariants.consumerDrivenMix`. */
@@ -1696,7 +1796,8 @@ export const RIG_KEYS = {
   RigBoneFrom: ['anchor', 'slotWindow', 'meshCenter', 'rotation'],
   RigSlot: ['name', 'bone', 'attachment', 'color', 'dark', 'blend'],
   RigEvent: ['int', 'float', 'string', 'audio', 'volume', 'balance'],
-  RigInvariants: ['meshSlots', 'meshTriangles', 'axisBone', 'massBone', 'detached', 'deformMayFold', 'editorRoundTrip', 'consumerDrivenMix'],
+  RigInvariants: ['meshSlots', 'meshTriangles', 'axisBone', 'massBone', 'detached', 'deformMayFold', 'editorRoundTrip', 'consumerDrivenMix', 'idleDrivesMeshes'],
+  RigIdleDrivesMeshes: ['why'],
   RigDetachedRule: ['bone', 'notUnder', 'why'],
   RigDeformFoldExemption: ['slot', 'why'],
   RigConsumerDrivenMix: ['constraint', 'type', 'why'],
@@ -1745,6 +1846,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'],
+  RigSegmentsFalloff: ['power', 'radius', 'maxBones', 'minWeight'],
+  RigSegmentSpan: ['bone', 'from', 'to'],
   RigMeshBias: ['axis_deg', 'ramp'],
   RigDepthMap: ['image', 'near', 'zScale', 'gamma', 'contrast', 'bias'],
   RigSoftRegion: ['bone', 'mask'],
@@ -1781,6 +1885,7 @@ const GENERATOR_SHAPE: Record<string, keyof typeof RIG_KEYS> = {
   ribbon: 'RigRibbonGenerator',
   contour: 'RigContourGenerator',
   grid: 'RigGridGenerator',
+  segments: 'RigSegmentsGenerator',
 };
 
 /**
@@ -1926,6 +2031,7 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
     for (const [i, rule] of (Array.isArray(raw.invariants.consumerDrivenMix) ? raw.invariants.consumerDrivenMix : []).entries()) {
       at(rule, 'RigConsumerDrivenMix', `invariants.consumerDrivenMix[${i}]`);
     }
+    at(raw.invariants.idleDrivesMeshes, 'RigIdleDrivesMeshes', 'invariants.idleDrivesMeshes');
   }
 
   for (const [skinName, skin] of Object.entries(isObj(raw.skins) ? raw.skins : {})) {
@@ -1985,6 +2091,10 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
         at(gen.bias, 'RigMeshBias', `${who} generator.bias`);
         at(gen.depth, 'RigDepthMap', `${who} generator.depth`);
         at(gen.soft, 'RigSoftRegion', `${who} generator.soft`);
+        at(gen.falloff, 'RigSegmentsFalloff', `${who} generator.falloff`);
+        for (const [i, entry] of (Array.isArray(gen.bones) ? gen.bones : []).entries()) {
+          at(entry, 'RigSegmentSpan', `${who} generator.bones[${i}]`);
+        }
       }
     }
   }
@@ -2134,9 +2244,9 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
     }
   }
 
-  // `invariants.deformMayFold` — one of the two fields in this file that TURN A
-  // CHECK OFF (`consumerDrivenMix`, below, is the other), so its own shape is
-  // checked harder than the fields that turn one on. A
+  // `invariants.deformMayFold` — one of the three fields in this file that TURN
+  // A CHECK OFF (`consumerDrivenMix` and `idleDrivesMeshes`, below, are the
+  // others), so its own shape is checked harder than the fields that turn one on. A
   // typo in a slot name here would silently exempt nothing and gate everything,
   // which reads exactly like the check working; and an exemption with no reason
   // is unreviewable six months later. Both are refused by name.
@@ -2265,6 +2375,29 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
     }
   }
 
+  // `invariants.idleDrivesMeshes` — the third field that TURNS A CHECK OFF
+  // (issues #855, #858), so it is held to the same standard: the one shape it
+  // accepts is `{ "why": … }`, and a `why` that is missing, blank or not a
+  // string is refused by name. `true` is refused too, even though it reads like
+  // the obvious spelling — a switch with no reason attached is exactly the
+  // exemption nobody can review later. Whether the declaration switches off
+  // anything is a question about the emitted `idle`, so it is the gate's (A15
+  // refuses a stale one), not this parser's.
+  const idleDrives = spec.invariants?.idleDrivesMeshes;
+  if (idleDrives !== undefined) {
+    const shape = '{ "why": "<why this idle deforms meshes on purpose>" }';
+    if (!isObj(idleDrives)) {
+      throw new CompileError(`${where}: invariants.idleDrivesMeshes is ${JSON.stringify(idleDrives)}, expected ${shape}`);
+    }
+    if (typeof idleDrives.why !== 'string' || idleDrives.why.trim().length === 0) {
+      throw new CompileError(
+        `${where}: invariants.idleDrivesMeshes needs a "why" (a non-blank string), got ` +
+          `${idleDrives.why === undefined ? 'none' : JSON.stringify(idleDrives.why)} — expected ${shape}. This field switches ` +
+          'A15_IDLE_NO_MESH_BONE_KEYS off, and an exemption nobody can date or justify is how a defect ships as a decision',
+      );
+    }
+  }
+
   // --- skins: the attachment table, and what the skin ACTIVATES --------------
   //
   // The lists resolve by name like everything else in this format, and the

package/src/types.ts

@@ -1414,6 +1414,14 @@ export interface RigInfo {
    * muted constraint as before (issue #784).
    */
   consumerDrivenMix: Array<{ type: 'ik' | 'transform'; constraint: string; why: string }>;
+  /**
+   * The `why` of `invariants.idleDrivesMeshes`, or null when the rig does not
+   * declare that its `idle` deforms meshes on purpose. Declared, `A15` SKIPs
+   * with the renderer cost it measured, or FAILs when the `idle` keys no
+   * mesh-driving bone and the declaration switches off nothing. A bare
+   * `validate <dir>` has no rig, so null, and A15 refuses per bone as before.
+   */
+  idleDrivesMeshes: string | null;
   /**
    * The atlas region(s) the build names as its base plate — the one image
    * `A19_OVERLAY_PNGS_HAVE_ALPHA` lets be opaque — in compile order.
@@ -1557,6 +1565,28 @@ export interface CompileResult {
      * and a nose does not wobble.
      */
     soft?: { mask: string; digest: string; bone: string; carried: number; ramped: number };
+    /**
+     * How a `segments` mesh's bones share its vertices — the figures `build`
+     * and `explain` print under its line. Only `segments` has one: it is the
+     * generator whose weights are the whole point, and every other generator's
+     * weighting is fixed by its kind.
+     */
+    influence?: {
+      /** Most bones any one vertex binds, and the mean over the mesh. */
+      maxBones: number;
+      meanBones: number;
+      /** Vertices bound to exactly one bone. */
+      singleBone: number;
+      /** The bones some vertex binds, in the order `bones` names them. */
+      bound: string[];
+      /** The lattice: its cell, cells across and down, cells with art, cells kept, islands joined. */
+      cell: number;
+      cols: number;
+      rows: number;
+      artCells: number;
+      keptCells: number;
+      islands: number;
+    };
     /**
      * What a depth map put on this mesh's vertices, when one was named.
      *

package/src/validate.ts

@@ -2317,23 +2317,57 @@ export function validate(input: ValidateInput): ValidateReport {
     });
 
     // --- A15: idle must not key a mesh-driving bone (dirty-skip lever) -----
+    //
+    // 🔑 The rule assumes meshes are mostly static: the renderer it serves skips
+    // redrawing a mesh nothing moved, and an `idle` keying one of its bones spends
+    // that skip on every frame. A painting rig is the genre where the assumption
+    // is false by design (issues #855, #858) — one illustration in layers, most
+    // of them weighted meshes, and an `idle` whose job is to move them — so the
+    // rig can say so in `invariants.idleDrivesMeshes`, and the rule then reports
+    // what the declaration costs instead of refusing each bone.
     check('A15_IDLE_NO_MESH_BONE_KEYS', () => {
-      const meshBoneNames = new Set<string>();
-      for (const slotIndex of meshSlots) meshBoneNames.add(data.slots[slotIndex].boneData.name);
-      // The slot's own bone is not the whole story once weights exist: a ring
-      // mesh is driven by its CONTROL bone, which is a different bone entirely.
-      // Checking only the slot bone would let `idle` key the one bone that
-      // actually dirties the canvas every frame.
-      for (const mesh of meshAttachments) {
-        if (!mesh.bones) continue;
-        for (let i = 0; i < mesh.bones.length; ) {
-          const boneCount = mesh.bones[i++];
-          for (let n = 0; n < boneCount; n++, i++) {
-            const bone = data.bones[mesh.bones[i]];
-            if (bone) meshBoneNames.add(bone.name);
+      const A15 = 'A15_IDLE_NO_MESH_BONE_KEYS';
+      /**
+       * Every mesh attachment, loaded, with the bones that drive it — its slot's
+       * bone, and, once weights exist, every bone its weights name. A ring mesh
+       * is driven by its CONTROL bone, a different bone from the slot's, and
+       * checking only the slot bone would let `idle` key the one bone that
+       * actually dirties the canvas every frame.
+       */
+      const meshDrivers: Array<{ mesh: MeshAttachment; bones: Set<string> }> = [];
+      for (const skin of data.skins) {
+        for (const entry of skin.getAttachments()) {
+          const mesh = entry.attachment;
+          if (!(mesh instanceof MeshAttachment)) continue;
+          const bones = new Set<string>([data.slots[entry.slotIndex].boneData.name]);
+          if (mesh.bones) {
+            for (let i = 0; i < mesh.bones.length; ) {
+              const boneCount = mesh.bones[i++];
+              for (let n = 0; n < boneCount; n++, i++) {
+                const bone = data.bones[mesh.bones[i]];
+                if (bone) bones.add(bone.name);
+              }
+            }
           }
+          meshDrivers.push({ mesh, bones });
         }
       }
+      const meshBoneNames = new Set<string>();
+      for (const { bones } of meshDrivers) for (const name of bones) meshBoneNames.add(name);
+      const declared = input.rig?.idleDrivesMeshes ?? null;
+      /**
+       * A declaration that switches off nothing is refused rather than skipped,
+       * the standard `consumerDrivenMix` is held to: an opt-out that exempts
+       * nothing reads exactly like one that worked, and the next reader cannot
+       * tell the rig that needs it from the rig it was copied onto.
+       */
+      const stale = (why: string): void => {
+        fail(
+          A15,
+          `the rig "${input.rig?.archetype}" declares invariants.idleDrivesMeshes ("${declared}"), but ${why}, so the ` +
+            'declaration switches off nothing — remove it',
+        );
+      };
       // The same shape as A06's and A17's guards, found by auditing for it
       // (#568): a rig with no `idle` at all has nothing here to be wrong, and a
       // rule that reports "held" over a subject that does not exist is the
@@ -2342,15 +2376,45 @@ export function validate(input: ValidateInput): ValidateReport {
       // versus one that keys no bone.
       const idle = isObj(raw?.animations) ? (raw.animations as Json).idle : undefined;
       if (!isObj(idle)) {
-        return skip('A15_IDLE_NO_MESH_BONE_KEYS', 'the skeleton declares no "idle" animation, so nothing here can key a mesh-driving bone');
+        if (declared !== null) return stale('the skeleton declares no "idle" animation');
+        return skip(A15, 'the skeleton declares no "idle" animation, so nothing here can key a mesh-driving bone');
       }
       if (!isObj(idle.bones)) {
-        return skip('A15_IDLE_NO_MESH_BONE_KEYS', '"idle" carries no bone timeline at all, so there is no key to hold against the mesh-driving bones');
+        if (declared !== null) return stale('"idle" carries no bone timeline at all');
+        return skip(A15, '"idle" carries no bone timeline at all, so there is no key to hold against the mesh-driving bones');
       }
-      for (const boneName of Object.keys(idle.bones as Json)) {
-        if (meshBoneNames.has(boneName)) {
-          fail('A15_IDLE_NO_MESH_BONE_KEYS', `idle keys bone "${boneName}", which drives a mesh — meshes never idle-skip`);
-        }
+      const keyed = Object.keys(idle.bones as Json).filter((name) => meshBoneNames.has(name));
+      if (declared !== null) {
+        if (keyed.length === 0) return stale('"idle" keys no bone that drives a mesh');
+        const keyedSet = new Set(keyed);
+        const moved = meshDrivers.filter(({ bones }) => [...bones].some((name) => keyedSet.has(name)));
+        // `worldVerticesLength` is two numbers per vertex whatever the encoding,
+        // which is the count the runtime recomputes; reading `vertices.length`
+        // would count a weighted mesh's bone entries instead.
+        const vertices = moved.reduce((sum, { mesh }) => sum + mesh.worldVerticesLength / 2, 0);
+        const SHOWN = 8;
+        const names =
+          keyed.slice(0, SHOWN).map((name) => `"${name}"`).join(', ') + (keyed.length > SHOWN ? ` +${keyed.length - SHOWN}` : '');
+        return skip(
+          A15,
+          `declared by the rig ("${declared}"): idle keys ${keyed.length} bone(s) that drive ${moved.length} mesh ` +
+            `attachment(s) totalling ${vertices} vertices — ${names} — and each of those meshes is recomputed on every ` +
+            'frame it is shown',
+        );
+      }
+      for (const [i, boneName] of keyed.entries()) {
+        // The case is named once, on the first line an agent reads, rather than
+        // after every bone: the first painting rig this met printed 42 of these,
+        // and 42 identical sentences read as 42 separate mistakes. It rides the
+        // first finding rather than being a finding of its own, so the count of
+        // FAIL lines is still the count of bones.
+        const hint =
+          i > 0
+            ? ''
+            : `. ${keyed.length} bone(s) keyed by idle drive meshes; if this idle is meant to deform them (a painting ` +
+              'rig), declare invariants.idleDrivesMeshes: { "why": … } in the rig spec — or, where the motion belongs to ' +
+              'a pivot above the mesh, key that pivot one link up (FACE.md §3)';
+        fail(A15, `idle keys bone "${boneName}", which drives a mesh — meshes never idle-skip${hint}`);
       }
     });
 
@@ -2532,13 +2596,26 @@ export function validate(input: ValidateInput): ValidateReport {
       // a linked mesh has no rim of its OWN at all — the one it draws belongs to
       // its source, and is measured there. Nothing to measure is a SKIP — never
       // a pass, and never a failure on somebody else's correct geometry.
-      const measurable = meshAttachments.filter((m) => m.bones && kindOf(m) !== 'authored');
+      //
+      // 🔸 A `segments` mesh is rigc's own geometry and still has no rim to pin:
+      // its outline is traced off the art and weighted by distance like every
+      // other vertex, because a layer pulled by named bones is SUPPOSED to move
+      // at its edge. "Pinned to the slot bone" is not a claim that generator
+      // makes, so there is nothing here to hold it to — and `A20`'s coherence
+      // rules, which it does make, still apply to it in full.
+      const rimless = (m: MeshAttachment): boolean => kindOf(m) === 'authored' || kindOf(m) === 'segments';
+      const measurable = meshAttachments.filter((m) => m.bones && !rimless(m));
       if (measurable.length === 0) {
         const authored = authoredMeshNames(meshAttachments.filter((m) => m.bones));
+        const segmented = meshAttachments.filter((m) => m.bones && kindOf(m) === 'segments').map((m) => `"${m.name}"`);
         return skip(
           'A21_MESH_RIM_PINNED',
-          `every weighted mesh here is authored or linked geometry (${authored.join(', ')}), not a rigc ring or ` +
-            'ribbon — rigc did not place its rim, so it has no rim of its own to find unpinned',
+          segmented.length === 0
+            ? `every weighted mesh here is authored or linked geometry (${authored.join(', ')}), not a rigc ring or ` +
+                'ribbon — rigc did not place its rim, so it has no rim of its own to find unpinned'
+            : `every weighted mesh here is ${authored.length ? `authored or linked geometry (${authored.join(', ')}) or ` : ''}` +
+                `a "segments" lattice (${segmented.join(', ')}), not a rigc ring or ribbon — a segments mesh weights its ` +
+                'outline by distance to the bones it names, so it has no rim pinned to the slot bone to find unpinned',
         );
       }
       for (const mesh of measurable) {
@@ -5831,12 +5908,12 @@ export function validate(input: ValidateInput): ValidateReport {
       // of one whose meshes are contours — and the last two are cases where a
       // reader should know that a mesh went unmeasured on purpose.
       const unpaired = Object.entries(kinds)
-        .filter(([, kind]) => kind === 'authored' || kind === 'contour')
+        .filter(([, kind]) => kind === 'authored' || kind === 'contour' || kind === 'segments')
         .map(([slot, kind]) => `"${slot}" (${kind})`);
       return skip(
         'A28_RIBBON_ROWS_SHARE_WEIGHTS',
         unpaired.length
-          ? `the rig "${input.rig.archetype}" declares no ribbon mesh on this cut — its mesh slot(s) ${unpaired.join(', ')} have no rows to pair: authored geometry is somebody else's topology, and a contour is one silhouette loop`
+          ? `the rig "${input.rig.archetype}" declares no ribbon mesh on this cut — its mesh slot(s) ${unpaired.join(', ')} have no rows to pair: authored geometry is somebody else's topology, a contour is one silhouette loop, and a segments lattice has cells rather than cross rows`
           : `the rig "${input.rig.archetype}" declares no ribbon mesh on this cut`,
       );
     }