spine-rigc 0.22.2 → 0.23.0

package/src/render.ts

@@ -184,6 +184,19 @@ export interface FramesSidecar {
   example?: string;
   rung?: string;
   skeleton?: string;
+  /**
+   * The skin these frames were posed under, when one was asked for (issue #571).
+   *
+   * ⭐ **Absent is not `"default"`.** A render with no skin sets none — every
+   * slot resolves through `SkeletonData.defaultSkin` alone — and a frame set
+   * written before this field existed says nothing either, so the two are the
+   * same fact on disk and the field is omitted for both. That is what keeps
+   * every frame set in this repository byte-identical across this change, and it
+   * is why `check` can refuse a mismatch it can SEE (`skin` present and
+   * different, or present where the run asked for none) and can only NOTE the
+   * one it cannot (`skin` absent while the run asked for one).
+   */
+  skin?: string;
   /** The colour the frames were cleared to, straight RGBA 0..255. */
   background: RGBA;
   viewport: {
@@ -281,6 +294,71 @@ export interface PoseOptions {
    * one instrument that does (`bonedist.ts`) needs it on every frame.
    */
   bones?: boolean;
+  /**
+   * Pose under this skin, by the name the skeleton declares for it.
+   *
+   * ⭐ Absent means **no skin is set at all**, which is spine-core's own initial
+   * state (`Skeleton.skin` is null) and resolves every slot through
+   * `SkeletonData.defaultSkin` alone. That is not the same claim as "the default
+   * skin was chosen": it is the absence of a choice, and the two are spelled
+   * differently everywhere this travels — the frames sidecar omits the field
+   * rather than writing `"default"` into it (issue #571).
+   *
+   * ⚠️ Read by the SAMPLERS, never by `piecesOf`, which is handed a skeleton
+   * somebody else already posed; handing it one is refused by name rather than
+   * ignored, because a skin quietly dropped here is exactly the silence this
+   * whole flag exists to remove.
+   */
+  skin?: string;
+}
+
+/**
+ * A fresh skeleton with `skin` applied, or refused by name.
+ *
+ * ## Why the skin goes on before `setupPose`, and why nothing else is needed
+ *
+ * `Skeleton.setSkin` (spine-core 4.3.13 `Skeleton.js:279-311`) attaches the new
+ * skin's art into each slot's pose and calls `updateCache`, which is what turns
+ * on a `skinRequired` bone or constraint the skin names. Every sampler below
+ * then calls `skeleton.setupPose()`, and `setupPose` → `setupPoseSlots`
+ * (`Skeleton.js:231-249`) re-resolves each slot's setup attachment through
+ * `Slot.setupPose` → `Skeleton.getAttachment`, which checks `this.skin` first
+ * and `SkeletonData.defaultSkin` second (`Skeleton.js:335-346`). So the setup
+ * pose of a skinned skeleton is already the skin's, and the extra
+ * `setSlotsToSetupPose()` a 4.1-era recipe prescribes has no 4.3 spelling to
+ * call: the method is named `setupPoseSlots` here, and `setupPose()` runs it.
+ *
+ * `setSkin(string)` exists too, but its by-name half throws
+ * `Skin not found: <name>` (`Skeleton.js:286-291`) — a message that names the
+ * miss and not the alternatives. Everything in a rig resolves by name and a miss
+ * is refused **by name, with the names that would have worked**, so the lookup
+ * happens here and the runtime is handed a `Skin` it cannot fail on.
+ */
+function skeletonUnderSkin(data: SkeletonData, skin: string | undefined): Skeleton {
+  const skeleton = new Skeleton(data);
+  if (skin === undefined) return skeleton;
+  const found = data.findSkin(skin);
+  if (!found) {
+    throw new Error(
+      `no skin ${JSON.stringify(skin)} in this skeleton; it declares [${
+        data.skins.map((s) => s.name).join(', ') || 'none'
+      }]`,
+    );
+  }
+  skeleton.setSkin(found);
+  return skeleton;
+}
+
+/**
+ * The same options with the skin taken off — what the samplers hand `piecesOf`.
+ *
+ * Spelled once, so the one function that must not see a `skin` cannot come to
+ * see one because a second call site forgot.
+ */
+function piecesOptions(opts: PoseOptions | undefined): PoseOptions | undefined {
+  if (opts === undefined || opts.skin === undefined) return opts;
+  const { skin: _applied, ...rest } = opts;
+  return rest;
 }
 
 /**
@@ -460,7 +538,8 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
       `no animation "${name}" in this skeleton; it has [${data.animations.map((a) => a.name).join(', ') || 'none'}]`,
     );
   }
-  const skeleton = new Skeleton(data);
+  const skeleton = skeletonUnderSkin(data, opts?.skin);
+  const pieceOpts = piecesOptions(opts);
   const state = new AnimationState(new AnimationStateData(data));
   // Not looping: the last frame sits at the animation's duration, and a looping
   // entry would wrap it back onto the first pose.
@@ -484,7 +563,7 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
     frames.push({
       index: i,
       time: i * step,
-      pieces: piecesOf(skeleton, opts),
+      pieces: piecesOf(skeleton, pieceOpts),
       ...(opts?.bones ? { bones: boneSnapshots(skeleton) } : {}),
     });
   }
@@ -500,7 +579,7 @@ export function sampleAnimation(data: SkeletonData, name: string, fps: number, o
  * whole content is the setup pose.
  */
 export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[] {
-  const skeleton = new Skeleton(data);
+  const skeleton = skeletonUnderSkin(data, opts?.skin);
   skeleton.setupPose();
   skeleton.update(0);
   skeleton.updateWorldTransform(Physics.reset);
@@ -508,7 +587,7 @@ export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[]
     {
       index: 0,
       time: 0,
-      pieces: piecesOf(skeleton, opts),
+      pieces: piecesOf(skeleton, piecesOptions(opts)),
       ...(opts?.bones ? { bones: boneSnapshots(skeleton) } : {}),
     },
   ];
@@ -519,10 +598,10 @@ export function sampleSetupPose(data: SkeletonData, opts?: PoseOptions): Frame[]
  * filed under. A skeleton with no animation at all contributes its setup pose
  * under `SETUP_POSE_DIR`.
  */
-export function sampleAll(data: SkeletonData, fps: number): Map<string, Frame[]> {
+export function sampleAll(data: SkeletonData, fps: number, opts?: PoseOptions): Map<string, Frame[]> {
   const out = new Map<string, Frame[]>();
-  if (data.animations.length === 0) out.set(SETUP_POSE_DIR, sampleSetupPose(data));
-  else for (const animation of data.animations) out.set(animation.name, sampleAnimation(data, animation.name, fps));
+  if (data.animations.length === 0) out.set(SETUP_POSE_DIR, sampleSetupPose(data, opts));
+  else for (const animation of data.animations) out.set(animation.name, sampleAnimation(data, animation.name, fps, opts));
   return out;
 }
 
@@ -537,6 +616,17 @@ export function sampleAll(data: SkeletonData, fps: number): Map<string, Frame[]>
  * of them draws a pixel.
  */
 export function piecesOf(skeleton: Skeleton, opts?: PoseOptions): Piece[] {
+  // A skin is chosen before a skeleton is posed, and this one is already posed —
+  // so there is nothing honest to do with the name except say so. Silently
+  // ignoring it is the shape of defect #571 itself: a skin asked for, no skin
+  // applied, and a picture that looks like an answer.
+  if (opts?.skin !== undefined) {
+    throw new Error(
+      `piecesOf was asked for skin ${JSON.stringify(opts.skin)}, and it reads a skeleton that is already posed. ` +
+        'Ask a sampler for it — sampleSetupPose/sampleAnimation/sampleAll take { skin } — or call ' +
+        'skeleton.setSkin(...) and skeleton.setupPose() before this.',
+    );
+  }
   const pieces: Piece[] = [];
   for (const slot of skeleton.drawOrder.appliedPose) {
     const pose = slot.appliedPose;
@@ -970,11 +1060,15 @@ export function trimmedUnionBounds(
  * Measuring the box densely and once makes the framing a property of the SHOT,
  * so every rate of one skeleton lands on the same pixels.
  */
-export function framingViewport(data: SkeletonData, maxSide: number): Viewport | null {
+export function framingViewport(data: SkeletonData, maxSide: number, opts?: PoseOptions): Viewport | null {
+  // The skin belongs here as much as in the frames: the union box is over the
+  // attachments that POSE, and two skins fill a slot with art of different sizes
+  // in different places. Framing one skin's shot with another skin's box would
+  // put the difference between two skins into every measurement taken in it.
   const sets =
     data.animations.length === 0
-      ? [sampleSetupPose(data)]
-      : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS));
+      ? [sampleSetupPose(data, opts)]
+      : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS, opts));
   const box = unionBounds(sets);
   if (!Number.isFinite(box.minX)) return null;
   const pad = Math.max(box.maxX - box.minX, box.maxY - box.minY) * PAD;

package/src/rig.ts

@@ -80,6 +80,25 @@ export const RIG_SPEC_VERSION = 'rigc-rig/1';
  * `A19_OVERLAY_PNGS_HAVE_ALPHA` measure against, and a guessed stage is a gate
  * that measures against a number nobody wrote down.
  *
+ * ⭐ **`width: null, height: null` is the third state: this skeleton declares no
+ * stage** (issue #578). Omitting them is silence and stays a refusal by name;
+ * stating them `null` is a claim, and the emitted header then carries none of
+ * `x`/`y`/`width`/`height` — which is what an editor export of a skeleton whose
+ * stage was never set looks like, and what a transcriber of one has to be able
+ * to write down. `null` is this spec's spelling for a stated absence everywhere
+ * else it has one (`RigSlot.attachment` = "show nothing", the cut manifest's
+ * `image` = "this cut does not carry the part"), so it is the spelling here too
+ * and no new key is introduced: the pair already exists, and only a third value
+ * of it is new.
+ *
+ * Two shapes are refused rather than interpreted, both in `parseRigSpec`:
+ * stating one of the pair `null` and the other a number (a stage with one
+ * extent is not a stage, and guessing which half was meant is inventing), and
+ * stating `x` or `y` alongside the absence (an origin for a box that is not
+ * there). ⚠️ A stated absence also beats a cut manifest's `crop`, for the reason
+ * a stated `width` already does: the rig spec is where a claim about the
+ * skeleton is made, and the manifest is a record of what the art measured.
+ *
  * `spine` is not here: rigc emits its own version label and `A16` re-checks it.
  * `hash` is not here either — it is the editor's change-detection token and
  * inventing one would be claiming an export this file did not come from.
@@ -87,8 +106,10 @@ export const RIG_SPEC_VERSION = 'rigc-rig/1';
 export interface RigSkeletonHeader {
   x?: number;
   y?: number;
-  width?: number;
-  height?: number;
+  /** A number, or `null` with `height` for "this skeleton declares no stage". */
+  width?: number | null;
+  /** A number, or `null` with `width` for "this skeleton declares no stage". */
+  height?: number | null;
   /** Nonessential; `SkeletonData.fps` stays 30 when absent. */
   fps?: number;
   /** 4.2+; the runtime's physics/scale reference. Parser default 100. */
@@ -107,6 +128,18 @@ export interface RigSkeletonHeader {
   images?: string;
 }
 
+/**
+ * Does this header state that the skeleton has no stage?
+ *
+ * One reading of the spelling, exported so that the compiler, the emitter and
+ * anything that grows a third opinion later read it the same way. `parseRigSpec`
+ * has already refused the half-stated shapes by the time this is asked, so the
+ * two `null`s travel together.
+ */
+export function declaresNoStage(header: RigSkeletonHeader | undefined): boolean {
+  return header !== undefined && header.width === null && header.height === null;
+}
+
 // ---------------------------------------------------------------------------
 // bones — `root.bones[]` (SkeletonJson.ts:90-118)
 // ---------------------------------------------------------------------------
@@ -223,12 +256,22 @@ export const RIG_SLOT_BLEND: readonly RigSlotBlend[] = ['normal', 'additive', 'm
  * One slot. **The array order IS the draw order** — there is no separate setup
  * draw-order field anywhere in the format.
  *
- * The rig's slot list is the CANONICAL table, which is a slightly stronger claim
- * than "the slots this cut emits". A cut whose manifest carries no part for a
- * slot does not emit it, and the emitted array is then a *subsequence* of this
- * one; that is what `A26_SLOT_DRAW_ORDER` checks. Declaring a slot no cut fills
- * is therefore legitimate — it fixes where that slot will sit when a cut does
- * fill it.
+ * The rig's slot list is the CANONICAL table and **every slot in it is emitted**,
+ * in this order, whether or not anything fills it. A slot no skin and no manifest
+ * part fills is emitted with no setup attachment — the shape an editor export
+ * carries for a slot that shows nothing (the slot reader above takes `attachment`
+ * with a `null` default) — so the emitted array and this one are the same array.
+ * `A26_SLOT_DRAW_ORDER` checks both halves of that: nothing out of order, and
+ * nothing missing. Declaring a slot no cut fills is therefore legitimate, and it
+ * fixes where that slot sits whether or not this cut has art for it.
+ *
+ * ⚠️ Until issue #575 such a slot was **dropped**, and the gate licensed it: the
+ * emitted array was allowed to be any *subsequence* of this one. What that
+ * bought was the format's own silence. Nothing said which slot had gone, and
+ * every slot below it moved up one index — the index a `drawOrder` key's offsets
+ * are counted against, and the one an index-keyed consumer splits on. Two
+ * production exports declaring 53 and 61 slots built green at 51 and 57 and read
+ * 0.962 and 0.934 under `diff` against the file they were transcribed from.
  */
 export interface RigSlot {
   name: string;
@@ -241,6 +284,12 @@ export interface RigSlot {
    * comes from: `motion.setup` owns it, because which of the two overlay
    * mechanisms a slot uses (attachment + alpha 0, or attachment swapping) is a
    * decision about time. Declaring it in both is a compile error.
+   *
+   * Required for a slot something fills — the compiler will not guess which of
+   * the slot's attachments the setup pose shows — and **optional for a slot
+   * nothing fills**, where it can only be `null` and saying so changes no
+   * emitted byte. Naming an attachment on a slot nothing fills is refused: the
+   * name resolves to nothing, which is the shape of a half-finished wiring-up.
    */
   attachment?: string | null;
   /** `rrggbbaa`. Default opaque white. */
@@ -1520,6 +1569,15 @@ function checkRigSpecKeys(raw: Record<string, unknown>, where: string): void {
         const type = att.type === undefined ? 'region' : String(att.type);
         const shape = ATTACHMENT_SHAPE[type];
         if (shape === undefined) continue;
+        // A mesh carrying `source` is a LINKED mesh — `type: "mesh"` and
+        // `type: "linkedmesh"` share one parser branch and the `source` key is
+        // what decides (`:568-569`, `:582`; SPEC_COVERAGE part 1-6). It has no
+        // key set here because `RigUnimplementedAttachment` deliberately has
+        // none, and checking it against a MESH's keys named the wrong fault:
+        // *2 keys this compiler does not read: "source", "skin" … fix the
+        // spelling or remove it*, where removing `source` is what unmakes the
+        // linked mesh. `buildRigAttachment` refuses it as the construct it is.
+        if (type === 'mesh' && att.source !== undefined) continue;
         at(att, shape, `${who} (${type})`);
         for (const [i, vertex] of (Array.isArray(att.weights) ? att.weights : []).entries()) {
           for (const [j, binding] of (Array.isArray(vertex) ? vertex : []).entries()) {
@@ -1573,6 +1631,32 @@ export function parseRigSpec(raw: unknown, where: string): RigSpec {
 
   const spec = raw as unknown as RigSpec;
 
+  // The stage, stated or stated absent. Half a statement is refused here rather
+  // than resolved in `compile`, because which half was meant is not derivable
+  // and a compiler that picks one is inventing a number (issue #578).
+  const header = spec.skeleton;
+  if (header !== undefined) {
+    const noWidth = header.width === null;
+    const noHeight = header.height === null;
+    if (noWidth !== noHeight) {
+      const stated = noWidth ? 'height' : 'width';
+      const absent = noWidth ? 'width' : 'height';
+      throw new CompileError(
+        `${where}: "skeleton" states ${absent}: null and a ${stated} of ` +
+          `${JSON.stringify(noWidth ? header.height : header.width)}. A stage has both extents or neither: ` +
+          'write both as null for "this skeleton declares no stage", or give both a number',
+      );
+    }
+    if (noWidth && noHeight && (header.x !== undefined || header.y !== undefined)) {
+      const origin = [header.x !== undefined ? 'x' : null, header.y !== undefined ? 'y' : null].filter((k) => k !== null);
+      throw new CompileError(
+        `${where}: "skeleton" declares no stage (width: null, height: null) and still states ${origin.join(' and ')}. ` +
+          `${origin.length === 1 ? 'That is an origin' : 'Those are an origin'} for a box that is not there: ` +
+          'drop them, or state a width and a height',
+      );
+    }
+  }
+
   const seen = new Set<string>();
   for (const bone of spec.bones) {
     if (!isObj(bone) || typeof bone.name !== 'string' || bone.name.length === 0) {

package/src/types.ts

@@ -515,13 +515,30 @@ export interface MotionTransformTrack {
 export interface MotionDeformKey {
   /** Time in seconds. */
   t: number;
-  /** Where the run starts in the attachment's own deform array. Default 0. */
+  /**
+   * Where the run starts in the attachment's own deform array. Default 0.
+   *
+   * Any index the array holds, **odd ones included** (issue #576): the parser
+   * copies at this index and does no pair arithmetic, so an odd start is what an
+   * editor writes when it trims the leading numbers off a delta run.
+   */
   offset?: number;
   /** The same start, given as a vertex index. Never together with `offset`. */
   fromVertex?: number;
   /**
-   * The run: `x, y` offsets, two numbers per array slot. Absent or `null` is the
-   * parser's own encoding for "back to the setup pose" — the key with no edit.
+   * The run: consecutive numbers written into the deform array from `offset` on,
+   * `x, y` per array slot. Absent or `null` is the parser's own encoding for
+   * "back to the setup pose" — the key with no edit.
+   *
+   * ⚠️ **An ODD count is legal and means something** (issue #576). Both readers
+   * copy the run verbatim — `Utils.arrayCopy(vertices, 0, deform, offset,
+   * vertices.length)` in `SkeletonJson`, a `for (let v = start; v < end; v++)`
+   * fill in `SkeletonBinary` — so a run of three numbers moves one vertex in x
+   * and y and the next in x alone, leaving that y at its setup value. Padding a
+   * `0` to even it out is a different animation whenever that setup y is
+   * non-zero, which is why the even-length rule that stood here could not be kept
+   * as a convenience: it left one production export with no spelling in this
+   * spec at all.
    */
   vertices?: number[] | null;
   /**
@@ -926,10 +943,25 @@ export type SpineConstraint = { name: string; type: string } & Record<string, un
 export interface SpineSkeletonJson {
   skeleton: {
     spine: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
+    /**
+     * The setup-pose bounding box. All four together or none of them: a rig spec
+     * that declares no stage (`skeleton.width`/`height` stated `null` — see
+     * `RigSkeletonHeader`) emits a header without any of them, which is what an
+     * export of a skeleton whose stage was never set carries (issue #578).
+     *
+     * ⚠️ Optional here because the *runtime* leaves them `undefined` when they
+     * are absent, not 0. `SkeletonData` declares `x = 0 … height = 0`
+     * (`SkeletonData.js:55-61`), and `SkeletonJson` then overwrites all four
+     * unconditionally — `skeletonData.x = skeletonMap.x` (`SkeletonJson.js:70-73`,
+     * no `getValue` default) — so an absent field lands as `undefined` on a
+     * `SkeletonData` whose own `.d.ts` types it `number`. Anything reading these
+     * back off a parsed skeleton guards for it; `validate.ts`'s `data.width || 0`
+     * is why A14 and A19 were already right about a stage-less file.
+     */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
     fps?: number;
     referenceScale?: number;
     images?: string;