spine-rigc 0.2.1 → 0.4.0

package/src/slots.ts

@@ -5,8 +5,9 @@
  *
  * The cheap matcher labels the reference frame's connected components and asks
  * which one each of the candidate's slots landed on. It is right whenever the
- * parts of a shot are separate blobs, and it has two failure modes that two
- * honest ladder runs hit head-on (issue #34):
+ * parts of a shot are separate blobs, and it has three failure modes that honest
+ * ladder runs hit head-on (issues #34 and #37) — all three the same mistake, which
+ * is treating a blob as a part:
  *
  * - **Parts that touch label as one component.** Rung 4 is a disc with five chain
  *   links hanging off it; they touch in every frame of every animation, so every
@@ -15,6 +16,13 @@
  *   4 px ball, on the frames where it rests against the course and has no component
  *   of its own, matched the floating girder 47 px away — and the summary line
  *   reported **48.3 px of drift for a 4 px ball**, unflagged.
+ * - **A blob one part dominates passes for that part.** Rung 2's reference merges
+ *   the course, the water, the panel and both rings into one component in which the
+ *   course is 81 % of the ink, so it is 1.24x the course's own and no wider than its
+ *   box — both merge tests see nothing, and the run reported *"course drift
+ *   11.2 px"*, the distance to a five-part centroid (issue #37). `occupantsOf`
+ *   answers that one with the label map: anything else the candidate drew inside the
+ *   blob makes the blob's centroid nobody's position.
  *
  * So: components first, and when a component cannot be attributed to one slot, the
  * slot's own rendered quad is **template-matched** against the reference in a
@@ -93,6 +101,21 @@ export interface Component {
   maxY: number;
 }
 
+/**
+ * The reference frame's components, and which one each pixel belongs to.
+ *
+ * The label map is what makes "is anything ELSE inside this blob?" a measurement
+ * rather than a guess from bounding boxes — see `occupantsOf`. It is indexed
+ * row-major on the frame's own grid, and `-1` is background or a component too
+ * small to be a part.
+ */
+export interface ComponentField {
+  components: Component[];
+  labels: Int32Array;
+  width: number;
+  height: number;
+}
+
 /**
  * Connected components of "not the background colour", 8-connected.
  *
@@ -101,6 +124,11 @@ export interface Component {
  * twenty and every match is ambiguous for a reason that is about the labeller.
  */
 export function componentsOf(plate: Plate, background: RGBA): Component[] {
+  return componentField(plate, background).components;
+}
+
+/** The same labelling, with the map kept — see `ComponentField`. */
+export function componentField(plate: Plate, background: RGBA): ComponentField {
   const { width, height } = plate;
   const label = new Int32Array(width * height).fill(-1);
   const out: Component[] = [];
@@ -145,7 +173,54 @@ export function componentsOf(plate: Plate, background: RGBA): Component[] {
       out.push({ pixels, cx: sx / pixels, cy: sy / pixels, minX, minY, maxX: maxX + 1, maxY: maxY + 1 });
     }
   }
-  return out.filter((c) => c.pixels >= MIN_COMPONENT_PIXELS).sort((a, b) => b.pixels - a.pixels);
+  // Crumbs out, biggest first — and the label map carried through the reorder, so
+  // a label is always an index into the array the caller is handed. Renumbering
+  // rather than sorting the map is what keeps the two from drifting apart.
+  const keep = out.map((c, id) => ({ c, id })).filter(({ c }) => c.pixels >= MIN_COMPONENT_PIXELS);
+  keep.sort((a, b) => b.c.pixels - a.c.pixels);
+  const renumbered = new Int32Array(out.length).fill(-1);
+  keep.forEach(({ id }, index) => {
+    renumbered[id] = index;
+  });
+  for (let at = 0; at < label.length; at++) label[at] = label[at] < 0 ? -1 : renumbered[label[at]];
+  return { components: keep.map(({ c }) => c), labels: label, width, height };
+}
+
+/**
+ * Which drawn slots' ink sits inside each component, by centroid.
+ *
+ * ## Why this exists: a blob one part dominates is still a blob
+ *
+ * The size and bounding-box tests below catch a merge when the merged neighbour is
+ * a material fraction of the blob. They cannot catch the case issue #37 filed:
+ * rung 2's reference merges the course, the water, the panel and both rings into
+ * one component, and the **course is 81 % of it**, so the blob is only 1.24x the
+ * course's own ink and barely wider than the course's own box. It passed every
+ * test, and the summary line reported *"course drift 11.2 px"* — the distance from
+ * the course's centroid to the centroid of a blob holding four other parts, which
+ * is not a measurement of the course at all.
+ *
+ * One label lookup per drawn slot answers it exactly: if anything else the
+ * candidate drew lands on this component's own pixels, the component is more than
+ * one part and its centroid is nobody's position. That is the same judgement the
+ * two-claimants rule below already makes; what was missing is that a slot which
+ * never got as far as *claiming* the blob — because it was refused for being 13x
+ * too small, or diverted to the template matcher — still proves the blob is shared.
+ */
+function occupantsOf(field: ComponentField, footprints: Map<string, Footprint>): Map<number, string[]> {
+  const out = new Map<number, string[]>();
+  for (const [slot, foot] of footprints) {
+    if (foot.pixels === 0) continue;
+    const x = Math.floor(foot.cx);
+    const y = Math.floor(foot.cy);
+    if (x < 0 || y < 0 || x >= field.width || y >= field.height) continue;
+    const label = field.labels[y * field.width + x];
+    if (label < 0) continue;
+    const seen = out.get(label) ?? [];
+    seen.push(slot);
+    out.set(label, seen);
+  }
+  return out;
 }
 
 /** How the drift beside a slot was arrived at. `none` means it could not be. */
@@ -213,11 +288,16 @@ interface Pending {
  */
 export function matchSlots(
   footprints: Map<string, Footprint>,
-  components: Component[],
+  field: ComponentField,
   source: SlotSource | null,
 ): { tracks: SlotTrack[]; matchedComponents: number } {
+  const components = field.components;
   const pending: Pending[] = [];
   const takenBy = new Map<Component, string[]>();
+  const occupants = occupantsOf(field, footprints);
+  /** Which component each one is, so an occupancy list can be looked up by it. */
+  const idOf = new Map<Component, number>();
+  components.forEach((component, id) => idOf.set(component, id));
 
   for (const [slot, foot] of [...footprints].sort((a, b) => a[0].localeCompare(b[0]))) {
     const track = blankTrack(slot);
@@ -320,6 +400,24 @@ export function matchSlots(
     }
   }
 
+  // ...and a component ONE slot claimed while other ink of the candidate's sits
+  // inside it is the same blob by the other route — the one that reported a
+  // dominant part's distance to a five-part blob as that part's drift (#37). The
+  // claim goes to the template matcher for the same reason: a centroid shared by
+  // several parts is not this part's position.
+  for (const entry of pending) {
+    if (entry.claimed === null || entry.track.ambiguity !== null) continue;
+    const id = idOf.get(entry.claimed);
+    if (id === undefined) continue;
+    const others = (occupants.get(id) ?? []).filter((slot) => slot !== entry.track.slot);
+    if (others.length === 0) continue;
+    entry.track.ambiguity =
+      `this slot's reference component also holds ${others.map((s) => JSON.stringify(s)).join(', ')} — ` +
+      `${entry.claimed.pixels} px of blob against this slot's own ${Math.round(entry.foot.pixels)} px, so its ` +
+      "centroid is the merged shape's and not this part's";
+    clearMatch(entry.track);
+  }
+
   // The fallback: anything the components could not attribute, correlated against
   // its own rendered pixels.
   if (source) {

package/src/timelines.ts

@@ -87,11 +87,15 @@ const EVENT_CHANNELS: Record<string, number | null> = { events: null };
  * How far past an animation's declared `duration` a key time may land: one step
  * of the grid every key time is rounded onto.
  *
- * The compiler emits key times through `r6`, so 1e-6 s is the finest distinction
- * a key can make and half a step is the most a *correct* key can miss its target
- * by. A key the author put exactly ON a duration of 68/12 s emits as 5.666667 —
- * 3.3e-7 s late, and legal. Anything a whole step further was authored past the
- * end, not rounded onto it.
+ * The compiler quantises key times onto that grid with `keyTime`, which rounds
+ * DOWN (issue #99), so 1e-6 s is the finest distinction a key can make and a
+ * *correct* key now misses its target only on the early side: a key the author put
+ * exactly ON a duration of 68/12 s emits as 5.666666 rather than past it. What
+ * still needs the tolerance is the other side of the same rule — `validate` re-runs
+ * it on an emitted file read back through a **Float32Array**, whose steps are
+ * coarser than this one and round both ways, and on artifacts no rigc compile ever
+ * touched. Anything a whole step past a declared duration was authored there, not
+ * rounded onto it.
  *
  * ⚠️ `FRAME` (1/60 s) is the wrong tolerance for this, which is why the constant
  * is separate rather than reused: 1/60 s answers "is the DECLARED DURATION

package/src/types.ts

@@ -303,6 +303,33 @@ export interface MotionDrawOrderKey {
   offsets?: MotionDrawOrderOffset[];
 }
 
+/**
+ * One firing of a declared event, at one time.
+ *
+ * ⚠️ Like `drawOrder` and unlike a `track`, this timeline names **no target**:
+ * 4.3 writes it as `animations.<a>.events` beside `bones` and `slots`
+ * (SPEC_COVERAGE part 1-8), and there is one per animation. The `name` picks
+ * an entry out of the rig spec's `events` table; the optional payload fields
+ * override that entry's defaults for this firing only.
+ *
+ * A key with no `int`/`float`/`string` inherits the event's setup payload
+ * (`:1250-1252`) — which is what the editor writes, and why `{ "t": 0.5,
+ * "name": "footstep" }` is the common shape.
+ */
+export interface MotionEventKey {
+  /** Time in seconds. */
+  t: number;
+  /** An event the rig spec declares. A miss throws in the parser; rigc refuses it. */
+  name: string;
+  /** Payload overrides for this firing. Omit to inherit the event's defaults. */
+  int?: number;
+  float?: number;
+  string?: string;
+  /** Read only when the declared event carries an `audio` path — see `RigEvent`. */
+  volume?: number;
+  balance?: number;
+}
+
 export interface MotionAnimation {
   /** Declared, then verified against the compiled result (rule 4). */
   duration: number;
@@ -320,6 +347,11 @@ export interface MotionAnimation {
    * time. First needed at ladder rung 5.
    */
   drawOrder?: MotionDrawOrderKey[];
+  /**
+   * The event timeline. One per animation, names no target, and for the same
+   * reason `drawOrder` is not a `track`. First needed at the spineboy rung.
+   */
+  events?: MotionEventKey[];
 }
 
 /**
@@ -442,7 +474,37 @@ export interface SpineMeshAttachment {
   color?: string;
 }
 
-export type SpineAttachment = SpineRegionAttachment | SpineMeshAttachment;
+/**
+ * The two vertex-only attachments: a polygon and nothing else.
+ *
+ * `vertexCount` is not optional the way a mesh's is absent-by-design: the parser
+ * reads `map.vertexCount << 1`, so an omission is `0` and `readVertices` decodes
+ * the coordinate array as a weight run and stores nothing.
+ */
+export interface SpineBoundingBoxAttachment {
+  type: 'boundingbox';
+  vertexCount: number;
+  /** Unweighted x/y pairs, or the weighted run — same encoding as a mesh's. */
+  vertices: number[];
+  color?: string;
+}
+
+export interface SpineClippingAttachment {
+  type: 'clipping';
+  /** The last slot the clip applies to. Absent = to the bottom of the order. */
+  end?: string;
+  convex?: boolean;
+  inverse?: boolean;
+  vertexCount: number;
+  vertices: number[];
+  color?: string;
+}
+
+export type SpineAttachment =
+  | SpineRegionAttachment
+  | SpineMeshAttachment
+  | SpineBoundingBoxAttachment
+  | SpineClippingAttachment;
 
 export type SpineTimelineKey = Record<string, unknown>;
 
@@ -469,6 +531,11 @@ export interface SpineSkeletonJson {
   slots: SpineSlot[];
   constraints?: SpineConstraint[];
   skins: Array<{ name: string; attachments: Record<string, Record<string, SpineAttachment>> }>;
+  /**
+   * Event definitions, keyed by name (`SkeletonJson.ts:451-464`). An object, not
+   * an array — the one top-level collection in the format that is.
+   */
+  events?: Record<string, SpineEvent>;
   animations: Record<
     string,
     {
@@ -477,10 +544,22 @@ export interface SpineSkeletonJson {
       physics?: Record<string, Record<string, SpineTimelineKey[]>>;
       /** Whole-animation timeline: no target name, one array per animation. */
       drawOrder?: SpineTimelineKey[];
+      /** The other whole-animation timeline; same shape, same reason. */
+      events?: SpineTimelineKey[];
     }
   >;
 }
 
+/** One entry of the emitted `events` map: the payload a firing inherits. */
+export interface SpineEvent {
+  int?: number;
+  float?: number;
+  string?: string;
+  audio?: string;
+  volume?: number;
+  balance?: number;
+}
+
 // ---------------------------------------------------------------------------
 // Compiler result
 // ---------------------------------------------------------------------------

package/src/validate.ts

@@ -19,6 +19,7 @@ import {
   AnimationState,
   AnimationStateData,
   AtlasAttachmentLoader,
+  BoundingBoxAttachment,
   ClippingAttachment,
   MeshAttachment,
   Physics,
@@ -42,8 +43,9 @@ export interface Failure {
  *
  * ⭐ The distinction this draws is the difference between "wrong" and "not how we
  * do it here", and conflating the two is how a validator stops being usable on
- * anybody else's data. Nine of the 31 assertions are policy for one renderer
- * (`spine-html`) or for one project's canvas budget, and every one of them fires
+ * anybody else's data. Fourteen of the 34 assertions are policy — seven for one
+ * renderer (`spine-html`) and one project's canvas budget, seven for rigc's own
+ * formations — and every one of them fires
  * on real, correct, editor-produced Spine data — the official example projects
  * carry clipping attachments, unweighted meshes, 116-triangle meshes and packed
  * atlases, all of which are perfectly valid and none of which spine-html likes.
@@ -113,6 +115,8 @@ const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A29_STROKE_WITHIN_CONTACT_DEPTH: 'archetype',
   A30_STROKE_WITHIN_CAP_CONTAINMENT: 'archetype',
   A31_DRAW_ORDER_OFFSETS_RESOLVE: 'validity',
+  A32_EVENT_KEYS_RESOLVE: 'validity',
+  A33_VERTEX_ATTACHMENT_GEOMETRY: 'validity',
 };
 
 export interface ValidateInput {
@@ -370,6 +374,81 @@ export function validate(input: ValidateInput): ValidateReport {
     if (!sawATimeline) return skip('A31_DRAW_ORDER_OFFSETS_RESOLVE', 'no animation carries a drawOrder timeline');
   });
 
+  // --- A32: every event key fires a declared event, in order ----------------
+  //
+  // The event timeline's three failure modes, and only the first is loud:
+  //
+  //   1. **An undeclared name.** `findEvent` returns null and `readAnimation`
+  //      throws `Event not found` (SkeletonJson.ts:1244). A00 would catch it, but
+  //      as a parser message about a name with no context; this one says which
+  //      animation, which key, and what the skeleton does declare.
+  //   2. **Times out of order.** `readAnimation` writes frame `i` from key `i` in
+  //      ARRAY order and never sorts, so a decreasing time builds an
+  //      `EventTimeline` whose frames run backwards. It loads clean, and the
+  //      firings behind the fold simply never come out. Equal times are fine —
+  //      two events on one frame is ordinary — so this is non-decreasing.
+  //   3. **`volume`/`balance` on a silent event.** `:1254-1257` reads them only
+  //      inside `if (event.data.audioPath)`, so on an event with no `audio` they
+  //      are two numbers in the file that no runtime will ever read.
+  //
+  // It runs on the raw JSON rather than on the loaded data because the loaded
+  // `Event` no longer remembers which fields the file wrote: an override that was
+  // dropped and an override that matched the default are the same object.
+  check('A32_EVENT_KEYS_RESOLVE', () => {
+    if (!raw) return skip('A32_EVENT_KEYS_RESOLVE', 'the skeleton JSON did not parse (A00 owns that failure)');
+    if (!isObj(raw.animations)) return skip('A32_EVENT_KEYS_RESOLVE', 'the skeleton declares no animations');
+    const declared = isObj(raw.events) ? (raw.events as Json) : {};
+    const known = Object.keys(declared);
+    let sawATimeline = false;
+    for (const [animName, anim] of Object.entries(raw.animations as Json)) {
+      if (!isObj(anim) || !Array.isArray(anim.events)) continue;
+      sawATimeline = true;
+      let previous = -Infinity;
+      (anim.events as unknown[]).forEach((key, k) => {
+        const at = `animation "${animName}" event key ${k}`;
+        if (!isObj(key) || typeof key.name !== 'string') {
+          fail('A32_EVENT_KEYS_RESOLVE', `${at}: an event key needs a string "name"`);
+          return;
+        }
+        const definition = declared[key.name];
+        if (definition === undefined) {
+          fail(
+            'A32_EVENT_KEYS_RESOLVE',
+            `${at}: fires "${key.name}", which the skeleton's events block does not declare` +
+              (known.length ? ` (declared: ${known.join(', ')})` : ' (that block is empty or absent)'),
+          );
+          return;
+        }
+        // `time` defaults to 0 when absent (`:1247`), which is what the editor
+        // writes for a firing on frame 0.
+        const time = key.time === undefined ? 0 : key.time;
+        if (typeof time !== 'number' || !Number.isFinite(time)) {
+          fail('A32_EVENT_KEYS_RESOLVE', `${at}: time is ${JSON.stringify(key.time)}, not a finite number`);
+          return;
+        }
+        if (time < previous) {
+          fail(
+            'A32_EVENT_KEYS_RESOLVE',
+            `${at}: "${key.name}" is at t=${time}, after a key at t=${previous} — the parser fills frames in ` +
+              'array order and never sorts them, so the earlier firing is unreachable',
+          );
+        }
+        previous = Math.max(previous, time);
+        const hasAudio = isObj(definition) && typeof definition.audio === 'string';
+        for (const field of ['volume', 'balance'] as const) {
+          if (key[field] !== undefined && !hasAudio) {
+            fail(
+              'A32_EVENT_KEYS_RESOLVE',
+              `${at}: "${key.name}" sets ${field}, but the event declares no audio path — the parser reads ` +
+                `${field} only for an event that has one, so it is dropped in silence`,
+            );
+          }
+        }
+      });
+    }
+    if (!sawATimeline) return skip('A32_EVENT_KEYS_RESOLVE', 'no animation carries an event timeline');
+  });
+
   // --- A: the round trip ----------------------------------------------------
   // The two loaded objects come back OUT of the assertion rather than being
   // assigned into it. Everything below reads them, and a `let` written inside a
@@ -563,6 +642,117 @@ export function validate(input: ValidateInput): ValidateReport {
       }
     });
 
+    // --- A33: bounding boxes and clipping polygons hold a real polygon -------
+    //
+    // These two types are the same shape — a polygon and nothing else — and they
+    // fail the same three ways, all three silent:
+    //
+    //   1. **A missing or wrong `vertexCount`.** The parser reads
+    //      `map.vertexCount << 1` and hands it to `readVertices` as the length to
+    //      expect (`:552`, `:632`). `undefined << 1` is 0, so an omission makes
+    //      the coordinate array read as a WEIGHTED run: it decodes numbers as
+    //      bone counts and weights, and the attachment ends up with no vertices
+    //      at all. Nothing throws, and neither type draws a pixel, so nothing
+    //      downstream notices either.
+    //   2. **A weighted run that does not decode to that many vertices.** Same
+    //      trap as a mesh's (A04), minus the uvs that would have caught it.
+    //   3. **A clipping `end` naming a slot that is not there.**
+    //      `skeletonData.findSlot` returns null on a miss and `:626-627` assigns
+    //      the null, so the clip does not end where it was told to — it runs to
+    //      the bottom of the draw order and takes every slot below it with it.
+    //      Checked on the raw JSON, because a null `endSlot` and an `end` that
+    //      was never written are the same loaded object.
+    check('A33_VERTEX_ATTACHMENT_GEOMETRY', () => {
+      const polygons: Array<{ what: string; att: BoundingBoxAttachment | ClippingAttachment }> = [];
+      for (const skin of data.skins) {
+        for (const entry of skin.getAttachments()) {
+          const att = entry.attachment;
+          if (att instanceof BoundingBoxAttachment) polygons.push({ what: `bounding box "${att.name}"`, att });
+          else if (att instanceof ClippingAttachment) polygons.push({ what: `clipping attachment "${att.name}"`, att });
+        }
+      }
+      const slotNames = new Set(data.slots.map((s) => s.name));
+      let endsChecked = 0;
+      if (raw && Array.isArray(raw.skins)) {
+        for (const skin of raw.skins as unknown[]) {
+          if (!isObj(skin) || !isObj(skin.attachments)) continue;
+          for (const [slotName, perSlot] of Object.entries(skin.attachments as Json)) {
+            if (!isObj(perSlot)) continue;
+            for (const [placeholder, att] of Object.entries(perSlot)) {
+              if (!isObj(att) || att.type !== 'clipping' || att.end === undefined) continue;
+              endsChecked++;
+              if (typeof att.end !== 'string' || !slotNames.has(att.end)) {
+                fail(
+                  'A33_VERTEX_ATTACHMENT_GEOMETRY',
+                  `clipping attachment "${placeholder}" on slot "${slotName}" ends at ${JSON.stringify(att.end)}, ` +
+                    'which is not a slot of this skeleton — the clip would run to the bottom of the draw order',
+                );
+              }
+            }
+          }
+        }
+      }
+      if (polygons.length === 0 && endsChecked === 0) {
+        return skip('A33_VERTEX_ATTACHMENT_GEOMETRY', 'the skeleton carries no bounding box and no clipping attachment');
+      }
+      for (const { what, att } of polygons) {
+        const length = att.worldVerticesLength;
+        if (!Number.isInteger(length) || length < 6 || length % 2 !== 0) {
+          fail(
+            'A33_VERTEX_ATTACHMENT_GEOMETRY',
+            `${what} loaded worldVerticesLength ${length}; a polygon is an even count of at least 6 (3 vertices). ` +
+              'A missing "vertexCount" reads as 0 and takes the polygon with it',
+          );
+          continue;
+        }
+        const vertexCount = length / 2;
+        if (!att.bones) {
+          if (att.vertices.length !== length) {
+            fail(
+              'A33_VERTEX_ATTACHMENT_GEOMETRY',
+              `${what} declares ${vertexCount} vertices but holds ${att.vertices.length} unweighted numbers ` +
+                `(expected ${length}); the parser reads that mismatch as a weighted run`,
+            );
+          }
+          continue;
+        }
+        // Weighted: `bones` is boneCount, (index × boneCount), repeated, and
+        // `vertices` holds x, y, weight per binding.
+        let decoded = 0;
+        let bindings = 0;
+        let ok = true;
+        for (let i = 0; i < att.bones.length; decoded++) {
+          const count = att.bones[i++];
+          if (!Number.isInteger(count) || count < 1 || i + count > att.bones.length) {
+            fail('A33_VERTEX_ATTACHMENT_GEOMETRY', `${what} vertex ${decoded} claims ${count} bone(s); the run is malformed`);
+            ok = false;
+            break;
+          }
+          for (let k = 0; k < count; k++, i++) {
+            const index = att.bones[i];
+            if (index < 0 || index >= data.bones.length) {
+              fail('A33_VERTEX_ATTACHMENT_GEOMETRY', `${what} vertex ${decoded} references bone index ${index}`);
+              ok = false;
+            }
+          }
+          bindings += count;
+        }
+        if (!ok) continue;
+        if (decoded !== vertexCount) {
+          fail(
+            'A33_VERTEX_ATTACHMENT_GEOMETRY',
+            `${what} declares ${vertexCount} vertices and its weighted run decodes to ${decoded}`,
+          );
+        }
+        if (att.vertices.length !== bindings * 3) {
+          fail(
+            'A33_VERTEX_ATTACHMENT_GEOMETRY',
+            `${what} has ${bindings} binding(s) and ${att.vertices.length} weight numbers (expected ${bindings * 3})`,
+          );
+        }
+      }
+    });
+
     // --- A11 / A13 / A14: renderer + canvas budgets ----
     check('A11_NO_CLIPPING_ATTACHMENTS', () => {
       if (clippingCount > 0) {