spine-rigc 1.2.3 → 1.4.0

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`,
       );
     }