spine-rigc 0.36.0 → 1.0.0

package/src/compile.ts

@@ -95,6 +95,7 @@ import {
   pageFootprint,
   pageGridSaid,
   pageGridSentence,
+  canonicalAtlasShape,
   parseAtlasText,
   rewritePageNames,
   writeAtlasText,
@@ -2463,6 +2464,14 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // for — `scale:` most expensively — so the text passes through by line and only
   // the name lines are replaced (`rewritePageNames`).
   //
+  // 🔸 Its BLANK lines are the one thing put into rigc's shape
+  // (`canonicalAtlasShape`, issue #803): none before the first entry, one between
+  // blocks, one trailing newline. The runtime reads any run of blank lines as
+  // one, and a 3.8-era packer opens every file with one, which `A07` read at
+  // `line 1` and refused — the gate refusing a whitespace choice of a packer
+  // rigc re-anchored, on a pack every 4.x runtime loads. Non-blank lines are
+  // untouched, so a pack already in that shape is emitted byte for byte as before.
+  //
   // ⚠️ Regions the rig does not use stay in the emitted atlas. They are not a
   // defect: a real pack is shared between cuts, an unused region costs a consumer
   // nothing, and dropping them would make `--out` disagree with the pack it was
@@ -2470,8 +2479,8 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const atlasText =
     atlasIn === null
       ? buildAtlasText(images)
-      : rewritePageNames(atlasIn.parsed, (name) =>
-          relative(outDir, resolve(atlasIn.dir, name)).split('\\').join('/'),
+      : canonicalAtlasShape(
+          rewritePageNames(atlasIn.parsed, (name) => relative(outDir, resolve(atlasIn.dir, name)).split('\\').join('/')),
         );
 
   // -- 3. bones --------------------------------------------------------------
@@ -2523,10 +2532,32 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   };
   /** Linked meshes to resolve once every skin exists — see `resolveLinkedMeshes`. */
   const pendingLinks: PendingLink[] = [];
-  tableFor('default'); // rigc always emits a default skin, even when it is empty
-  // ...and every skin the rig declares, for the same reason: a skin can now carry
-  // `bones`/constraint lists with no attachments at all, and a skin that only
-  // switches bones on would otherwise never reach the emitted array.
+  // 🔑 **A `default` skin is emitted exactly when the spec has one** (issue #801):
+  // the rig spec's `skins` carries the key — empty or not — or a manifest part
+  // files its states under it (the loop below). Otherwise there is none, which is
+  // the shape the editor's own export has: a rig whose art all lives in named
+  // skins came back from 4.3.26 with `skins` 3 → 2, the empty `default` gone,
+  // and `SkeletonBinary.readSkin` returns null for a default skin with no slots,
+  // so the binary half cannot even hold one. The runtime treats the two
+  // spellings alike — `SkeletonData.defaultSkin` is null or an empty skin, and
+  // `Skeleton.getAttachment` finds nothing in either (`Skeleton.js:335-346`).
+  // This line used to create it unconditionally, "even when it is empty", which
+  // made every rebuild of such an export differ from it by one skin — a value
+  // the spec never stated.
+  //
+  // Created HERE, before the slot loop, rather than lazily by the first part
+  // that fills it, so `skinTables` keeps `default` first whichever of the two
+  // put it there, and every refusal that lists the emitted skins lists them in
+  // the order it did before.
+  const partsFillDefault = rig.slots.some(
+    (rigSlot) =>
+      partBySlot.has(rigSlot.name) &&
+      (slotAttachments.get(rigSlot.name) ?? rigAttachmentNames.get(rigSlot.name) ?? []).length > 0,
+  );
+  if (skinNames.includes(DEFAULT_SKIN) || partsFillDefault) tableFor(DEFAULT_SKIN);
+  // ...and every skin the rig declares: a skin can carry `bones`/constraint lists
+  // with no attachments at all, and a skin that only switches bones on would
+  // otherwise never reach the emitted array.
   for (const skinName of skinNames) tableFor(skinName);
   const meshBones = new Set<string>();
   const meshes: CompileResult['meshes'] = [];
@@ -4028,6 +4059,17 @@ function setupWorldVertices(
  * two are the outer control handles of the end knots, which no curve uses. A
  * closed path instead rotates by one and repeats the first knot at the end.
  * Either way what comes out is a `3K + 1` chain: knot, handle, handle, knot, …
+ *
+ * ⭐ **`lengths` is measured over the CLOSED chain whether the path is closed or
+ * not** (issue #804), because that is the array the format holds: the parser
+ * sizes it `vertexCount / 3` on both (`SkeletonJson.js:601`), which on an open
+ * path is one more than its curves, and the editor fills that last entry with
+ * the wrap-around curve's cumulative — measured on a 4.3 production export, all
+ * four of whose entries the closed chain over the runtime's own posed vertices
+ * reproduces to the digit it prints. The open chain is the closed chain's
+ * prefix, so the entries the runtime reads are the same numbers either way; the
+ * trailing one is read by nothing, and is written so a rebuild is the file the
+ * editor writes rather than one entry short of it.
  */
 function pathChain(points: Array<[number, number]>, closed: boolean): Array<[number, number]> {
   if (!closed) return points.slice(1, points.length - 1);
@@ -4050,11 +4092,33 @@ function pathChain(points: Array<[number, number]>, closed: boolean): Array<[num
  * — `0.1875 = 3t²`, `0.09375 = 6t³`, `0.75 = 3t`, `0.16666667` standing in for
  * 1/6 — accumulating four `Math.sqrt` terms per curve into a running
  * `pathLength`, and writing the running value into `curves[i]` at each curve's
- * end. The Spine editor's exported `lengths` are that same computation: measured
- * against two editor exports, one open path from 4.3.23 and one closed path from
- * 4.3.26, this reproduces every digit the editor printed. So the loop below is a
- * transcription, not a sampler that happens to agree — and the two are not the
- * same thing, which is the reason the transcription is here.
+ * end. The Spine editor's exported `lengths` are that same computation, and the
+ * loop below is a transcription of it, not a sampler that happens to agree.
+ *
+ * 🚨 **What that computation is fed decides the number, and this comment once
+ * claimed more than was measured** (issue #804). It said the loop matched the
+ * editor to every digit it printed — true on the two exports it was measured on,
+ * one open and one closed path on unweighted, unscaled, unconstrained rigs, and
+ * false in production on two counts:
+ *
+ *   - **Geometry.** The editor measures the world positions of the posed
+ *     vertices. rigc blends weighted vertices through its own setup transforms,
+ *     which until #804 ignored bone scale, shear and `inherit` — 2.35× the
+ *     runtime's own `curves` on a production rig's weighted path, 0.752× on a
+ *     50/50 probe over a bone at scale 2. `computeWorldTransforms` is now the
+ *     runtime's, and the gap is gone on both.
+ *   - **Constraints.** The runtime measures the pose its update order hands the
+ *     path constraint at the first `updateWorldTransform`: a transform
+ *     constraint on the path's slot bone ordered BEFORE the path constraint
+ *     moves the curves (416.14 → 551.59 on a probe), one ordered after does
+ *     not. A production 4.2 export's four numbers are the constrained pose's to
+ *     the digit, and its unconstrained setup measures 76.08 against 76.65 on the
+ *     first curve. Reproducing that means solving every constraint type in
+ *     update order, which is posing — and `src/compile.ts` does not link the
+ *     runtime. ⇒ **An omitted `lengths` is measured on the unconstrained setup
+ *     pose**, and a path whose bones a constraint moves at rest gets that
+ *     figure. What closes the gap for an editor export is not measuring at all:
+ *     a stated `lengths` is carried (`buildRigPath`).
  *
  * ⚠️ rigc measured this with a 64-chord sum until issue #560, and the comment
  * that stood here argued the difference was inside anything's tolerance. It was
@@ -4065,7 +4129,7 @@ function pathChain(points: Array<[number, number]>, closed: boolean): Array<[num
  * two apart and since issue #716 rigc's own file can only where the two land on
  * either side of a float's boundary. Under the six-decimal rounding that stood
  * until then it could: on both measured rigs the two spellings differed on the
- * LAST curve, where the accumulated difference is largest. `PS67`–`PS69` in `selftest.ts` compare
+ * LAST curve, where the accumulated difference is largest. `PS67`, `PS68` and `PS186` in `selftest.ts` compare
  * this against `PathConstraint`'s own `curves` array read off a posed skeleton,
  * which is the only oracle that can see that gap.
  *
@@ -4118,20 +4182,17 @@ function pathCurveLengths(chain: Array<[number, number]>): number[] {
  *      groups of six then straddle the knots, and bones slide along a curve
  *      nobody drew. Too few points is the same failure with fewer symptoms — an
  *      open path needs 6 for one curve, a closed one 3.
- *   2. **`lengths` is measured, not copied.** See `RigPathAttachment`: it is the
- *      setup arc length of the geometry two fields above it, and a restated
- *      number that disagrees is only visible under `constantSpeed: false`, where
- *      it silently rescales the whole traversal.
- *   3. **An authored `lengths` is refused**, for that reason.
+ *   2. **A stated `lengths` is carried as stated** (issue #804), and checked for
+ *      the one shape the parser cannot hold: `vertexCount / 3` entries, each
+ *      finite and none below the one before it. The file is the record of what
+ *      was measured, and the number an editor export states is the editor's
+ *      measurement of a pose rigc cannot reproduce without posing (see
+ *      `pathCurveLengths`) — so re-deriving it moved a production rig's bones by
+ *      up to 0.0054 in issue #804's pose comparison, where carrying it moved none.
+ *   3. **An omitted one is measured**, `vertexCount / 3` entries over the closed
+ *      chain (`pathChain`), on the unconstrained setup pose.
  */
 function buildRigPath(att: RigPathAttachment, where: string, ctx: AttachmentContext): SpinePathAttachment {
-  if (att.lengths !== undefined) {
-    throw new CompileError(
-      `${where}: "lengths" is not authored — rigc measures the setup arc length of each curve off the geometry, the ` +
-        'same way it measures a region\'s size off its PNG. A restated length that disagrees with the vertices is ' +
-        'invisible until `constantSpeed` is false, and then it rescales the whole traversal in silence.',
-    );
-  }
   const vertices = buildVertexGeometry(att, where, ctx);
   const count = att.vertexCount;
   const closed = att.closed === true;
@@ -4149,15 +4210,25 @@ function buildRigPath(att: RigPathAttachment, where: string, ctx: AttachmentCont
         `${closed ? 'a closed path of K curves carries 3K points' : 'an open one carries 3(K + 1), the first and last being the end knots\' outer handles'}`,
     );
   }
-  const anchor = ctx.transforms.get(ctx.anchorBone);
-  if (!anchor) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" has no setup transform`);
-  const points = setupWorldVertices(vertices, count, anchor, ctx.bones, ctx.transforms, where);
-  const lengths = pathCurveLengths(pathChain(points, closed));
-  if (!lengths.length || !lengths.every((n) => Number.isFinite(n)) || lengths[lengths.length - 1] <= 0) {
-    throw new CompileError(
-      `${where}: the geometry measures ${lengths.length} curve(s) of total length ${String(lengths[lengths.length - 1])}; ` +
-        'a path of zero length divides by zero the first time a bone is placed on it',
-    );
+  const entries = count / 3;
+  let lengths: number[];
+  if (att.lengths !== undefined) {
+    lengths = statedPathLengths(att.lengths, entries, closed, where);
+  } else {
+    const anchor = ctx.transforms.get(ctx.anchorBone);
+    if (!anchor) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" has no setup transform`);
+    const points = setupWorldVertices(vertices, count, anchor, ctx.bones, ctx.transforms, where);
+    lengths = pathCurveLengths(pathChain(points, true));
+    // The total the runtime reads is the last CURVE's entry, `lengths[vertexCount
+    // / 3 - (closed ? 1 : 2)]` (`PathConstraint.js:204-206`) — on an open path
+    // the one before the trailing wrap-around entry, which nothing reads.
+    const total = lengths[closed ? entries - 1 : entries - 2];
+    if (lengths.length !== entries || !lengths.every((n) => Number.isFinite(n)) || !(total > 0)) {
+      throw new CompileError(
+        `${where}: the geometry measures ${lengths.length} entry(ies) where the parser sizes ${entries}, of total ` +
+          `length ${String(total)}; a path of zero length divides by zero the first time a bone is placed on it`,
+      );
+    }
   }
   // Field order is the parser's reading order (`:606-623`), and each optional key
   // is present exactly when the spec declared it — the rule the whole rig spec
@@ -4173,6 +4244,50 @@ function buildRigPath(att: RigPathAttachment, where: string, ctx: AttachmentCont
   };
 }
 
+/**
+ * A stated `lengths`, checked for the shape the parser needs and returned as
+ * stated (issue #804).
+ *
+ * 🔒 **The count is the parser's, not the constraint's.** `SkeletonJson.js:601`
+ * allocates `vertexCount / 3` entries on an open path and a closed one alike and
+ * copies what the file gives: a SHORT array leaves zeros the constraint then
+ * reads as a curve's end (a position divided by 0, in silence), and a LONG one
+ * grows the array past what the attachment's own geometry has. Both are refused
+ * with the two counts rather than trimmed or padded, because either repair is a
+ * value the spec did not state.
+ *
+ * ⚠️ Equal neighbours are accepted here and refused by `A33` where the runtime
+ * reads them — a zero-length curve is a fact about the pose, which the gate
+ * measures; a DECREASING entry is not a cumulative length at all, on any pose.
+ */
+function statedPathLengths(stated: unknown, entries: number, closed: boolean, where: string): number[] {
+  if (!Array.isArray(stated)) {
+    throw new CompileError(`${where}: "lengths" is ${JSON.stringify(stated)}; it is an array of ${entries} number(s)`);
+  }
+  if (stated.length !== entries) {
+    throw new CompileError(
+      `${where}: "lengths" has ${stated.length} entry(ies) where the parser sizes ${entries} — vertexCount / 3 on ` +
+        `${closed ? 'a closed' : 'an open'} path${closed ? '' : ', one more than its curves: the editor writes the wrap-around curve\'s cumulative last and nothing reads it'}. ` +
+        'Give the array the source states, or leave the field out and rigc measures it',
+    );
+  }
+  let previous = 0;
+  for (let i = 0; i < stated.length; i++) {
+    const value: unknown = stated[i];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new CompileError(`${where}: "lengths"[${i}] is ${JSON.stringify(value)}; every entry is a finite cumulative length`);
+    }
+    if (value < previous) {
+      throw new CompileError(
+        `${where}: "lengths"[${i}] is ${value}, below ${i === 0 ? '0' : `the ${previous} before it`}. The array is CUMULATIVE — the length at ` +
+          'the end of each curve — so no entry is below its predecessor',
+      );
+    }
+    previous = value;
+  }
+  return stated as number[];
+}
+
 /**
  * The compiled image an attachment's `image` names — or a refusal that names the
  * file and says what is actually wrong with it.
@@ -4857,13 +4972,21 @@ function resolveLinkedMeshes(
 ): void {
   const skinNames = [...tables.keys()];
   for (const link of links) {
-    // ⚠️ Only a STATED `skin` can miss here, and it is worth saying why rather
-    // than leaving the other half to look like a branch nothing reaches: rigc
-    // always emits a `default` skin, empty if it has to (`tableFor('default')`),
-    // so the parser's own default always resolves to a table. An omitted `skin`
-    // therefore fails one line down, at the source, and the sentence there is
-    // what names the trap.
+    // ⚠️ An omitted `skin` can miss here too since issue #801: rigc emits a
+    // `default` skin only when the spec has one, and the parser's default for a
+    // link is `skeletonData.defaultSkin`, which is then null — the runtime reads
+    // `getAttachment` off it and throws a `TypeError` naming neither. So the
+    // omitted case is said separately, because "the skin is default" would be a
+    // sentence about a value nobody wrote.
     const table = tables.get(link.skin);
+    if (table === undefined && !link.skinStated) {
+      throw new CompileError(
+        `${link.where}: no "skin" is stated, so the parser looks for the source "${link.source}" in the default ` +
+          `skin — and this rig declares no default skin. The rig's skins are ${skinNames.map((s) => JSON.stringify(s)).join(', ')}. ` +
+          'State the skin the source is filed under. Left to the round trip this is a `TypeError` off the null ' +
+          '`SkeletonData.defaultSkin`, which names neither this attachment nor where it was looking.',
+      );
+    }
     if (table === undefined) {
       throw new CompileError(
         `${link.where}: "skin" is ${JSON.stringify(link.skin)}, and the rig declares no such skin. The rig's skins ` +
@@ -7189,8 +7312,8 @@ function deformGeometryOf(
     //
     //   - `lengths` is a field of the ATTACHMENT. The format has nowhere to put
     //     a per-key length, so no export of any tool carries a re-measured one;
-    //     the editor's own is the setup measurement, which is what
-    //     `pathCurveLengths` reproduces digit for digit.
+    //     the editor's own is the setup measurement, which a stated array
+    //     carries and `pathCurveLengths` measures when none is stated.
     //   - `PathConstraint.computeWorldPositions` reads that field only under
     //     `constantSpeed: false` (`PathConstraint.js:205`). Under the parser's
     //     default, `true`, it re-measures the curve from the posed world

package/src/ingest.ts

@@ -124,8 +124,8 @@ export class IngestSpecRefused extends Error {
  * - `judgement` — the skeleton does not carry it and somebody decided. There
  *   are exactly two: a stage the caller supplied, and an animation's duration.
  * - `lossy` — the skeleton's spelling and rigc's differ, on purpose, and the
- *   difference is named: a value rigc re-derives rather than takes (`lengths`,
- *   the `spine` version), a field the spec has no home for (`hash`), or
+ *   difference is named: a value rigc re-derives rather than takes (the
+ *   `spine` version), a field the spec has no home for (`hash`), or
  *   a default the source left to the format and the rebuild writes out
  *   (`HEADER_ORIGIN`, issue #622). The rebuilt file is a different file in that
  *   field; it is not a different rig.
@@ -1407,17 +1407,12 @@ function ingestAttachment(
     out.vertexCount = att.vertexCount;
     geometry(vertexCount);
     for (const field of ['closed', 'constantSpeed', 'color']) if (att[field] !== undefined) out[field] = att[field];
-    if (att.lengths !== undefined) {
-      note(
-        'lossy',
-        'PATH_LENGTHS',
-        at.where,
-        'the source states `lengths`; the rig spec refuses an authored one and rigc RE-MEASURES it as ' +
-          '`PathConstraint` does (issue #560, `pathCurveLengths`). Dropping it is correct: the field is the ' +
-          "runtime's own four-sample forward difference, not an arc length, and a transcribed one would freeze " +
-          'whatever produced the source',
-      );
-    }
+    // Carried verbatim (issue #804), where until then it was dropped as `LOSS
+    // PATH_LENGTHS` and re-measured. The editor measures it on the pose the
+    // first update gives the path constraint — constraints applied — and rigc
+    // does not pose, so the re-measure was a different number on every path a
+    // constraint moves at rest, and on every weighted path over a scaled bone.
+    if (att.lengths !== undefined) out.lengths = att.lengths;
   } else {
     note(
       'blocker',

package/src/rig.ts

@@ -827,7 +827,7 @@ export interface RigLinkedMeshAttachment {
   sequence?: RigSequence;
   /**
    * 🚫 Every geometry field a mesh may state, refused by name on a link. They
-   * are declared for the reason `RigPathAttachment.lengths` is: a key the shape
+   * are declared so the refusal can name them: a key the shape
    * does not hold at all comes back as *keys this compiler does not read … fix
    * the spelling or remove it*, and the remedy sentence is wrong here — the
    * fault is not a typo, it is that the parser reads none of them on a link.
@@ -938,12 +938,22 @@ export interface RigClippingAttachment extends RigVertexGeometry {
  * six then straddle the knots, and the constraint slides bones along a curve
  * nobody drew.
  *
- * ⚠️ `lengths` is NOT authored here. It is the cumulative length at the end of
- * each curve in the SETUP pose, in world units — a measurement of the geometry
- * above, and the same relationship `image` has to `width`/`height`: a restated
- * number can disagree with the vertices, and when it does, a
- * `constantSpeed: false` path traverses a length that is not the length of the
- * curve, silently. So rigc measures it and refuses an authored one by name.
+ * ⭐ `lengths` is **stated or measured** (issue #804). It is the cumulative
+ * length at the end of each curve, in world units, and `vertexCount / 3` entries
+ * on an open path and a closed one alike — the parser's allocation, one more
+ * than an open path's curves, the last being the wrap-around curve's cumulative,
+ * which nothing reads. Stated, it is emitted as stated: that is what `ingest`
+ * writes from an export, because the editor measured it on a pose rigc does not
+ * reproduce (below). Left out, rigc measures it off the geometry on the
+ * unconstrained setup pose. Only `constantSpeed: false` reads it.
+ *
+ * ⚠️ Why a stated one is not re-measured: the editor's numbers are
+ * `PathConstraint`'s own measurement of the pose the first update gives it —
+ * with every constraint ordered before the path constraint applied. rigc does
+ * not pose, so an authored path whose bones a constraint moves at rest gets the
+ * unconstrained figure, and an export's own array is the only way to carry the
+ * constrained one. Re-deriving it moved 232 of a production rig's 259 bones in
+ * issue #804's pose comparison.
  *
  * 🔸 *Which* length, exactly, is `SpinePathAttachment`'s subject in
  * [`types.ts`](types.ts) and it is not the arc: it is `PathConstraint`'s own
@@ -966,8 +976,8 @@ export interface RigPathAttachment extends RigVertexGeometry {
    */
   constantSpeed?: boolean;
   /**
-   * 🚫 Refused by name. rigc measures the arc lengths off `vertices`/`weights` —
-   * see the note above. The field is declared so the refusal can name it.
+   * Stated: exactly `vertexCount / 3` finite entries, none below the one before
+   * it, emitted as stated. Absent: measured — see the note above.
    */
   lengths?: number[];
 }
@@ -1631,7 +1641,11 @@ export interface RigSpec {
   bones: RigBone[];
   slots: RigSlot[];
   /**
-   * At least `default`, which becomes `skeletonData.defaultSkin` (`:441`).
+   * `default`, if the rig has one, becomes `skeletonData.defaultSkin` (`:441`).
+   * It is emitted exactly when this map carries the key — an empty `{}` included
+   * — or a manifest part files its states under it; a rig whose art is all in
+   * named skins states no `default` and gets none, which is what the editor's
+   * export of such a rig declares (issue #801).
    *
    * Each entry is either the short form — `slotName -> placeholderName ->
    * attachment` — or the long one, `{ "attachments": {…}, "bones": [...],