spine-rigc 0.22.2 → 0.24.0

package/src/atlas.ts

@@ -115,9 +115,10 @@ export interface AtlasRegion {
    *
    * ⚠️ Not the page footprint. At `rotate: 90` / `270` the rectangle on the page
    * is `height x width`; `TextureAtlas` transposes for `u2/v2` at 90 and not at
-   * 270, which is a bug in the runtime and the reason `windowOf` in
-   * [`src/render.ts`](render.ts) derives the rectangle rather than reading those
-   * two numbers. This field is the atlas's own meaning of `bounds`, untouched.
+   * 270, which is a bug in the runtime and the reason every reader here derives
+   * the rectangle rather than reading those two numbers. `pageFootprint` below
+   * is that derivation, spelled once. This field is the atlas's own meaning of
+   * `bounds`, untouched.
    */
   width: number;
   height: number;
@@ -174,6 +175,61 @@ export interface ParsedAtlas {
   lines: string[];
 }
 
+/**
+ * The rectangle a region occupies **on its page** — which is not the rectangle
+ * its `bounds:` line states.
+ *
+ * `bounds:` is the kept rectangle in the DRAWING's orientation, so a packer that
+ * turned the drawing a quarter turn to fit it wrote `width x height` for a
+ * region that covers `height x width` of the page. 180 turns nothing: the
+ * footprint is the drawing's own way round at 0 and at 180, and transposed at 90
+ * and at 270.
+ *
+ * ## Why this is one function and was four (issue #579)
+ *
+ * Four readers in this tree want exactly this rectangle — `windowOf` in
+ * [`src/render.ts`](render.ts) fences a substituted piece with it,
+ * `resolveFromAtlas` in [`src/compile.ts`](compile.ts) refuses a region that
+ * runs off its page by it, and `A06` and `A19` in [`src/validate.ts`](validate.ts)
+ * measure a shared page's tiling and open one region's own texels with it — and
+ * two of the four transposed at 90 **only**, under a comment that read *"spine-core
+ * transposes a region's extent at 90 and not at 270 when it derives the UVs, so
+ * the rectangle ON THE PAGE follows the same rule"*.
+ *
+ * The premise is true and the conclusion does not follow, because the two are
+ * different quantities:
+ *
+ *   * what `TextureAtlas` transposes at 90 and not at 270 is `u2`/`v2`
+ *     (spine-core 4.3.13, `dist/TextureAtlas.js:162-171`) — so at 270 those two
+ *     numbers do describe a rectangle the page does not have;
+ *   * but `MeshAttachment.computeUVs` (`dist/attachments/MeshAttachment.js:118-162`)
+ *     never reads `u2`/`v2` for an atlas region. It branches on `degrees` and
+ *     derives the span from `originalWidth`/`originalHeight`, transposed at 90
+ *     **and** at 270 alike. That is the routine that says where a region's texels
+ *     are, and `extractRegion` below is its inverse.
+ *
+ * ⚠️ The consequence was not confined to a printed number, which is what the
+ * card assumed. A19 opens a shared page and scans one region's own rectangle for
+ * a transparent texel: at 270 it scanned `width x height` where the drawing
+ * occupies `height x width`, ran off the part into the transparent gutter, found
+ * its texel there and **named nothing**. Two fully opaque parts on one turned
+ * page — the exact defect A19 exists for — were measured green at `rotate: 270`
+ * and red at 0, 90 and 180.
+ *
+ * Structurally typed rather than taking `AtlasRegion`, because two of the four
+ * callers hold spine-core's `TextureAtlasRegion` instead and this file
+ * deliberately does not link the runtime.
+ */
+export function pageFootprint(region: { width: number; height: number; degrees: number }): {
+  width: number;
+  height: number;
+} {
+  const turned = region.degrees === 90 || region.degrees === 270;
+  return turned
+    ? { width: region.height, height: region.width }
+    : { width: region.width, height: region.height };
+}
+
 /**
  * `TextureAtlasReader.readEntry`, to the value.
  *
@@ -413,8 +469,27 @@ export const PACK_NO_ROTATE = 0;
  * The unpacked default goes through here too (`buildAtlasText` builds one page
  * per image and calls this), which is what makes "the defaults change nothing" a
  * property of one function instead of a promise made by two.
+ *
+ * ⭐ **No pages is the empty FILE, not a blank line** (issue #608). A compile that
+ * measured no art — a rig whose skins fill no slot with anything that needs a
+ * page — used to come out of here as `"\n"`, because `[].join('\n')` is `''` and
+ * the trailing newline was appended unconditionally. That one byte contradicts
+ * the paragraph above it: a blank line is the separator that sits BETWEEN page
+ * blocks, so a file consisting of one is a separator with nothing on either side.
+ * `A07_ATLAS_TEXT_SHAPE` then read it as a malformed page block and refused the
+ * compiler's own output, which is how a rig with nothing to draw became a red
+ * gate on a file nobody had written wrong.
+ *
+ * The runtime cannot tell the two apart — `new TextureAtlas('')`,
+ * `new TextureAtlas('\n')` and `new TextureAtlas('\n\n')` all come back with
+ * `pages.length === 0` and `regions.length === 0`, and the constructor
+ * (`TextureAtlas.js:97-174`) has no `throw` in it at all — so the runtime is no
+ * help in choosing, and the choice is made on what the text SAYS. Zero bytes has
+ * exactly one reading; a blank line has two, and the wrong one is the one A07 was
+ * built to catch.
  */
 export function writeAtlasText(pages: EmitPage[]): string {
+  if (pages.length === 0) return '';
   const lines: string[] = [];
   pages.forEach((page, i) => {
     if (i > 0) lines.push(''); // exactly one blank line BETWEEN pages
@@ -919,25 +994,69 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  * a plate's rows run downwards, so the kept rectangle's top row is
  * `originalHeight - offsetY - height`.
  *
- * ⛔ A rotated region is refused rather than guessed. `TextureAtlas` transposes
- * `u2/v2` at 90 and not at 270, and `RegionAttachment.computeUVs` assigns a
- * different corner order at 90 — there are already three opinions in the runtime
- * about that mapping and this file is not going to be a fourth. rigc's own packer
- * never rotates (`PACK_NO_ROTATE`), so only a foreign atlas can reach this.
+ * ## A rotated region is TRANSCRIBED, not guessed at (issue #570)
+ *
+ * This refused a rotated region until 2026-09-17, on the argument that the
+ * runtime holds "three opinions" about the mapping. Measurement refutes the
+ * argument: the three are not three readings of one mapping, they are one
+ * mapping and two places that do not implement it.
+ *
+ *   * `MeshAttachment.computeUVs` (spine-core 4.3.13,
+ *     `dist/attachments/MeshAttachment.js:126-162`) is the one routine that
+ *     states where a region's texels are for **all four** `degrees`, and it is
+ *     the routine `substituteTexture` in [`src/render.ts`](render.ts) already
+ *     goes through. The loop below is its inverse, term for term;
+ *   * `TextureAtlas`'s `u2`/`v2` (`dist/TextureAtlas.js:164-171`) transpose the
+ *     rectangle at 90 and not at 270, so at 270 they describe a rectangle the
+ *     page does not have — but `MeshAttachment.computeUVs` never reads them for
+ *     an atlas region, and neither does this;
+ *   * `RegionAttachment.computeUVs` (`dist/attachments/RegionAttachment.js:156-167`)
+ *     assigns the turned corner order at 90 and at nothing else, which is a
+ *     region-attachment rendering defect (issue #199) and not a statement about
+ *     where the drawing sits.
+ *
+ * Inverting the runtime's own expression on texel centres puts kept-rectangle
+ * pixel `(x, y)` — `x` from the drawing's left, `y` down from `top` — at page
+ * pixel `(X + x, Y + y)` unturned, `(X + y, Y + width - 1 - x)` at 90,
+ * `(X + width - 1 - x, Y + height - 1 - y)` at 180 and
+ * `(X + height - 1 - y, Y + x)` at 270, writing `X`/`Y` for the region's own
+ * `x`/`y`; the packed footprint is `height x width` for the two quarter turns
+ * and `width x height` for the other two. `repackRotatedTrimmed` in
+ * `selftest.ts` derived the same 270 mapping for issue #199's fixture, and had
+ * been shipping it green, while this comment claimed the mapping was unknowable.
+ *
+ * ⚠️ Any other `degrees` takes the unturned branch, because that is what the
+ * runtime does with it: `regionFields.rotate` (`dist/TextureAtlas.js:87-93`)
+ * `parseInt`s the value without checking it, and `computeUVs` falls to
+ * `default:` for everything that is not 90, 180 or 270. Reading such a region
+ * unturned is not a guess, it is agreement with the thing that will draw it.
+ *
+ * rigc's own packer still never rotates (`PACK_NO_ROTATE`), so only a foreign
+ * atlas reaches any branch but the first.
  */
 export function extractRegion(page: Plate, region: AtlasRegion): Plate {
-  if (region.degrees !== 0) {
-    throw new CompileError(
-      `region "${region.name.trim()}" is packed rotate: ${region.degrees}; reading a drawing back off a rotated ` +
-        'region is not implemented — rigc\'s own packer never rotates, so this is a foreign pack. Supply the loose ' +
-        'PNG instead of --atlas-in for the part that needs measuring.',
-    );
-  }
   const out = new Plate(region.originalWidth, region.originalHeight);
   const top = region.originalHeight - region.offsetY - region.height;
+  const { degrees } = region;
   for (let y = 0; y < region.height; y++) {
     for (let x = 0; x < region.width; x++) {
-      out.set(region.offsetX + x, top + y, page.get(region.x + x, region.y + y));
+      const px =
+        degrees === 90
+          ? region.x + y
+          : degrees === 180
+            ? region.x + region.width - 1 - x
+            : degrees === 270
+              ? region.x + region.height - 1 - y
+              : region.x + x;
+      const py =
+        degrees === 90
+          ? region.y + region.width - 1 - x
+          : degrees === 180
+            ? region.y + region.height - 1 - y
+            : degrees === 270
+              ? region.y + x
+              : region.y + y;
+      out.set(region.offsetX + x, top + y, page.get(px, py));
     }
   }
   return out;

package/src/check.ts

@@ -863,6 +863,24 @@ export interface CheckReport {
   candidate: { skeleton: string; atlas: string };
   framesDir: string;
   framesRoot: string;
+  /**
+   * The skin the CANDIDATE was posed under, or `null` for no skin at all.
+   *
+   * ⭐ In the report rather than only in the run's arguments because a figure is
+   * only readable beside what produced it: on a multi-skin rig the same
+   * candidate and the same frames give a different number per skin, and a
+   * `check.json` that did not say which one it was is a number with no subject
+   * (issue #571).
+   */
+  skin: string | null;
+  /**
+   * The skin `frames.json` records for the reference frames, or `null`.
+   *
+   * `null` covers two facts that are the same on disk — the frames set no skin,
+   * and the frames were rendered before the field existed — which is why a
+   * mismatch against it is refused and an absence is only noted. See `notes`.
+   */
+  referenceSkin: string | null;
   /** One framing per set, or one across every set — see `FramingScope`. */
   framingScope: FramingScope;
   /**
@@ -947,6 +965,17 @@ export interface CheckOptions {
   viewport?: { x: number; y: number; width: number; height: number };
   /** Play this candidate animation against the frames, when the names differ. */
   as?: string;
+  /**
+   * Pose the candidate under this skin — see `PoseOptions.skin` (issue #571).
+   *
+   * Absent sets no skin, which resolves every slot through the default skin
+   * alone: on a multi-skin rig that draws none of the art the named skins carry,
+   * and a `check` of it compares blank against blank and reads 0.0000. A name
+   * the candidate does not declare is refused with the ones it does, and the
+   * reference frames' own recorded skin is checked against this — see the
+   * `referenceSkin` field of `CheckReport` for what an absent record means.
+   */
+  skin?: string;
   /**
    * Fit one framing per frame set, or one across every set compared.
    *
@@ -1026,7 +1055,20 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   const substitution = options.textureFrom
     ? textureSubstitutionFromText(options.textureFrom.atlasText, options.textureFrom.atlasDir)
     : null;
-  const poseOptions: PoseOptions | undefined = substitution ? { texture: true } : undefined;
+  // The skin is refused here rather than deeper in the sampler, for the reason
+  // every miss in this project is refused where the names are: the skeleton is
+  // open on this line and the alternatives can be listed.
+  if (options.skin !== undefined && !posable.data.skins.some((s) => s.name === options.skin)) {
+    throw new CheckError(
+      `the candidate declares no skin ${JSON.stringify(options.skin)}; it declares [${
+        posable.data.skins.map((s) => s.name).join(', ') || 'none'
+      }]`,
+    );
+  }
+  const poseOptions: PoseOptions | undefined =
+    substitution || options.skin !== undefined
+      ? { ...(substitution ? { texture: true } : {}), ...(options.skin === undefined ? {} : { skin: options.skin }) }
+      : undefined;
   let background: RGBA;
   let sets: FrameSet[];
   let pixelWidth: number;
@@ -1086,6 +1128,35 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
 
   if (sets.length === 0) throw new CheckError(`no frame set to compare in ${options.framesDir}`);
 
+  // --- the skin the frames were rendered under, against the one asked for ----
+  //
+  // ⭐ The asymmetry is the honest part (issue #571). A sidecar that RECORDS a
+  // skin is a claim, and a claim that disagrees is refused by name; a sidecar
+  // that records none is making no claim at all — it either set no skin or was
+  // written before the field existed, and those are the same bytes — so the run
+  // proceeds and says out loud that nothing checked it. Inventing a refusal out
+  // of an absent field would refuse every frame set in this repository.
+  const referenceSkin = located.sidecar?.skin ?? null;
+  if (referenceSkin !== null && referenceSkin !== options.skin) {
+    throw new CheckError(
+      `${FRAMES_SIDECAR} records that these frames were rendered under skin ${JSON.stringify(referenceSkin)}, and ` +
+        `this run poses the candidate ${
+          options.skin === undefined
+            ? 'under no skin at all (the default skin alone)'
+            : `under skin ${JSON.stringify(options.skin)}`
+        }. Two skins are two different pictures of one rig, so the comparison would be a number about the ` +
+        `difference between them. Pass --skin ${JSON.stringify(referenceSkin)}, or render the reference frames ` +
+        `${options.skin === undefined ? 'with no --skin' : `with --skin ${JSON.stringify(options.skin)}`}.`,
+    );
+  }
+  if (referenceSkin === null && options.skin !== undefined) {
+    notes.push(
+      `the candidate is posed under skin ${JSON.stringify(options.skin)} and the reference frames record no skin ` +
+        `at all, so nothing here could check that they are the same picture. A frame set rendered by \`rigc ` +
+        `render --skin\` since #571 carries the name in ${FRAMES_SIDECAR} and this run would have compared it.`,
+    );
+  }
+
   // Pose every set once. Its frames are wanted twice — to frame the candidate and
   // to compare it — and posing twice is both slower and a chance for the framing
   // and the comparison to disagree about what they measured.
@@ -1347,6 +1418,8 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
     },
     framesDir: resolve(options.framesDir),
     framesRoot: located.root,
+    skin: options.skin ?? null,
+    referenceSkin,
     framingScope: scope,
     framing: topHow,
     viewport: topViewport === null ? null : framingOfViewport(topViewport),
@@ -3117,6 +3190,15 @@ export function checkLines(report: CheckReport, opts?: { allFrames?: boolean }):
   lines.push(`  candidate  ${report.candidate.skeleton}`);
   lines.push(`  atlas      ${report.candidate.atlas}`);
   lines.push(`  frames     ${report.framesDir}`);
+  // Always printed, on both sides, because the reading a reader has to be able
+  // to make is "which picture of this rig is this" — and a line that appears
+  // only when a skin was named cannot say that the run used none (issue #571).
+  lines.push(
+    `  skin       candidate ${report.skin === null ? 'no skin set (the default skin alone)' : report.skin}   ` +
+      `frames ${
+        report.referenceSkin === null ? `no skin recorded in ${FRAMES_SIDECAR}` : report.referenceSkin
+      }`,
+  );
   lines.push(
     `  scope      ${
       report.framingScope === 'per-shot'