spine-rigc 0.2.1

package/src/timelines.ts

@@ -0,0 +1,253 @@
+/**
+ * The 4.3 animation timeline catalogue, as data plus one walker.
+ *
+ * This lives on its own because two very different consumers need the same
+ * enumeration and neither may drift from the other: `validate.ts` walks it to
+ * check curve arrays (A05) and two-colour timelines (A12), and `diff.ts` walks
+ * it to count what a rig actually keys. When it was inlined in the validator,
+ * "which groups exist" was stated in one place and the comparison tool would
+ * have had to restate it — and a second copy of a catalogue is a second copy
+ * that goes stale silently.
+ *
+ * Pure JSON reading. No spine-core, no filesystem. The line numbers cited are
+ * into `SkeletonJson.ts` on branch 4.3; the field-by-field survey is in
+ * `docs/SPEC_COVERAGE.md` part 1-8.
+ */
+
+type Json = Record<string, unknown>;
+
+function isObj(v: unknown): v is Json {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * How many value channels each timeline carries. A curve array holds exactly
+ * four numbers PER channel; anything shorter
+ * multiplies `undefined` into the cubic and produces a NaN curve with no error
+ * (case 6g). `null` means "this timeline takes no curve at all".
+ */
+const BONE_CHANNELS: Record<string, number | null> = {
+  rotate: 1,
+  translate: 2,
+  translatex: 1,
+  translatey: 1,
+  scale: 2,
+  scalex: 1,
+  scaley: 1,
+  shear: 2,
+  shearx: 1,
+  sheary: 1,
+  inherit: null,
+};
+const SLOT_CHANNELS: Record<string, number | null> = {
+  attachment: null,
+  rgba: 4,
+  rgb: 3,
+  alpha: 1,
+  rgba2: 7,
+  rgb2: 6,
+};
+const ATTACHMENT_CHANNELS: Record<string, number | null> = {
+  deform: 1,
+  sequence: null,
+};
+const PHYSICS_CHANNELS: Record<string, number | null> = {
+  inertia: 1,
+  strength: 1,
+  damping: 1,
+  mass: 1,
+  wind: 1,
+  gravity: 1,
+  mix: 1,
+  reset: null,
+};
+const PATH_CHANNELS: Record<string, number | null> = {
+  position: 1,
+  spacing: 1,
+  mix: 3,
+};
+const SLIDER_CHANNELS: Record<string, number | null> = {
+  time: 1,
+  mix: 1,
+};
+/**
+ * `ik` and `transform` are ONE timeline per constraint with no sub-name — the
+ * group maps a constraint name straight to a key array. There is no name in the
+ * file to look up, so the walker passes the group's own name and these tables
+ * hold that single entry.
+ */
+const IK_CHANNELS: Record<string, number | null> = { ik: 2 };
+const TRANSFORM_CHANNELS: Record<string, number | null> = { transform: 6 };
+/** Whole-animation timelines. None of the three can carry a curve at all. */
+const DRAW_ORDER_CHANNELS: Record<string, number | null> = { drawOrder: null };
+const DRAW_ORDER_FOLDER_CHANNELS: Record<string, number | null> = { drawOrderFolder: null };
+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.
+ *
+ * ⚠️ `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
+ * wrong?", it is 16,667 times wider than this, and it hid the defect that put
+ * this here. Rung 6 rounded key times to 4 dp in its authoring tooling, so a
+ * one-frame attachment reveal landed 3.4e-5 s past a 68/12 s duration — 34 steps
+ * past this line but 1/500 of FRAME, with another track already sitting on the
+ * declared duration, so the compiler's Rule 4 and the validator's A09 both
+ * compared the animation's max key time and agreed. The reveal never fired
+ * (issue #54).
+ *
+ * It lives here, beside the timeline catalogue, for the reason the catalogue
+ * does: `compile.ts` refuses on it and `validate.ts` re-checks the emitted file
+ * against it, and a second copy of the number is a second copy that drifts.
+ */
+export const KEY_TIME_EPSILON = 1e-6;
+
+/**
+ * Every timeline group `readAnimation` reads (SPEC_COVERAGE part 1-8), keyed by
+ * the walker's `kind`. A05 selects its channel table from here, so a group that
+ * is missing from this map is a group whose curves nobody checks.
+ */
+export const CHANNELS_BY_KIND: Record<TimelineKind, Record<string, number | null>> = {
+  bone: BONE_CHANNELS,
+  slot: SLOT_CHANNELS,
+  ik: IK_CHANNELS,
+  transform: TRANSFORM_CHANNELS,
+  path: PATH_CHANNELS,
+  physics: PHYSICS_CHANNELS,
+  slider: SLIDER_CHANNELS,
+  attachment: ATTACHMENT_CHANNELS,
+  drawOrder: DRAW_ORDER_CHANNELS,
+  drawOrderFolder: DRAW_ORDER_FOLDER_CHANNELS,
+  event: EVENT_CHANNELS,
+};
+
+/** The eleven timeline groups one animation can hold in 4.3. */
+export type TimelineKind =
+  | 'bone'
+  | 'slot'
+  | 'ik'
+  | 'transform'
+  | 'path'
+  | 'physics'
+  | 'slider'
+  | 'attachment'
+  | 'drawOrder'
+  | 'drawOrderFolder'
+  | 'event';
+
+
+/**
+ * Walks every timeline group `readAnimation` reads and hands each timeline to
+ * the visitor.
+ *
+ * ⚠️ This function is the reach of A05 and A12, so a group it does not descend
+ * is a group whose curve arrays nobody checks — and a short curve array is the
+ * format's nastiest silent failure (`curve[i+3]` is
+ * `undefined`, the cubic yields NaN, nothing throws). It used to descend
+ * `bones`, `slots`, `physics` and `attachments` only, which left `ik`,
+ * `transform`, `path`, `slider`, `drawOrder`, `drawOrderFolder` and `events`
+ * completely unexamined. The comment that stood here claimed drawOrder and
+ * events were "skipped by design" because they carry no curves — but "carries
+ * no curve" is precisely a rule that has to be CHECKED, and the parser ignores
+ * a stray `curve` key on those timelines rather than rejecting it.
+ *
+ * The groups come in four shapes, and the shape is the whole reason this is not
+ * one loop (SPEC_COVERAGE part 1-8):
+ *
+ *   group.<target>.<timeline> = keys[]   bones, slots, path, physics, slider
+ *   group.<target>            = keys[]   ik, transform — one unnamed timeline
+ *   group                     = keys[]   drawOrder, events — one per animation
+ *   group                     = folders[] with .keys[]   drawOrderFolder
+ *
+ * plus `attachments.<skin>.<slot>.<attachment>.<timeline>`. For the shapes with
+ * no timeline name in the file, the walker passes the group's own name so that
+ * A05's table lookup and its "unchecked timeline" fail-closed branch both keep
+ * working unchanged.
+ */
+export function walkTimelines(
+  raw: Json | null,
+  visit: (path: string, kind: TimelineKind, name: string, keys: unknown[]) => void,
+): void {
+  if (!raw || !isObj(raw.animations)) return;
+  for (const [animName, anim] of Object.entries(raw.animations as Json)) {
+    if (!isObj(anim)) continue;
+
+    // group.<target>.<timeline> = keys[]
+    for (const [group, kind] of [
+      ['bones', 'bone'],
+      ['slots', 'slot'],
+      ['path', 'path'],
+      ['physics', 'physics'],
+      ['slider', 'slider'],
+    ] as const) {
+      if (!isObj(anim[group])) continue;
+      for (const [targetName, timelines] of Object.entries(anim[group] as Json)) {
+        if (!isObj(timelines)) continue;
+        for (const [timelineName, keys] of Object.entries(timelines)) {
+          if (!Array.isArray(keys)) continue;
+          visit(`${animName}.${group}.${targetName}.${timelineName}`, kind, timelineName, keys);
+        }
+      }
+    }
+
+    // group.<constraint> = keys[] — the constraint IS the timeline
+    for (const [group, kind] of [
+      ['ik', 'ik'],
+      ['transform', 'transform'],
+    ] as const) {
+      if (!isObj(anim[group])) continue;
+      for (const [targetName, keys] of Object.entries(anim[group] as Json)) {
+        if (!Array.isArray(keys)) continue;
+        visit(`${animName}.${group}.${targetName}`, kind, group, keys);
+      }
+    }
+
+    // group = keys[] — one timeline for the whole animation
+    for (const [group, kind] of [
+      ['drawOrder', 'drawOrder'],
+      ['events', 'event'],
+    ] as const) {
+      const keys = anim[group];
+      if (!Array.isArray(keys)) continue;
+      visit(`${animName}.${group}`, kind, group, keys);
+    }
+
+    // drawOrderFolder = [ { slots: [...], keys: [...] } ] — one timeline per folder
+    if (Array.isArray(anim.drawOrderFolder)) {
+      (anim.drawOrderFolder as unknown[]).forEach((folder, i) => {
+        if (!isObj(folder) || !Array.isArray(folder.keys)) return;
+        visit(`${animName}.drawOrderFolder[${i}]`, 'drawOrderFolder', 'drawOrderFolder', folder.keys);
+      });
+    }
+
+    // attachments.<skin>.<slot>.<attachment>.<timeline>
+    if (isObj(anim.attachments)) {
+      for (const [skinName, skinMap] of Object.entries(anim.attachments as Json)) {
+        if (!isObj(skinMap)) continue;
+        for (const [slotName, slotMap] of Object.entries(skinMap)) {
+          if (!isObj(slotMap)) continue;
+          for (const [attName, attMap] of Object.entries(slotMap)) {
+            if (!isObj(attMap)) continue;
+            for (const [timelineName, keys] of Object.entries(attMap)) {
+              if (!Array.isArray(keys)) continue;
+              visit(
+                `${animName}.attachments.${skinName}.${slotName}.${attName}.${timelineName}`,
+                'attachment',
+                timelineName,
+                keys,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+}
+

package/src/transform.ts

@@ -0,0 +1,130 @@
+/**
+ * Setup-pose world transforms, and their inverses.
+ *
+ * The mesh tier used to get away with "bind = world - bone origin", and the
+ * compiler asserted the precondition it needed: every bone translation-only. The
+ * joint archetype breaks that on purpose — `axis` carries the cut's angle and the
+ * grips carry their radial facing — so the shortcut has to become a real inverse.
+ *
+ * ⚠️ A rotated parent would NOT have failed loudly under the old shortcut. It
+ * would have sheared every weighted vertex at setup and looked like a badly
+ * measured polygon. That is why the old code refused rotation instead of ignoring
+ * it, and why this file exists rather than a relaxed assertion.
+ *
+ * The composition mirrors spine-core exactly (`Bone.updateWorldTransform`):
+ *
+ *   la = cos(rot)      lb = cos(rot + 90) = -sin(rot)
+ *   lc = sin(rot)      ld = sin(rot + 90) =  cos(rot)
+ *   a = pa*la + pb*lc  b = pa*lb + pb*ld
+ *   c = pc*la + pd*lc  d = pc*lb + pd*ld
+ *   worldX = pa*x + pb*y + parent.worldX
+ *
+ * Scale and shear are not emitted by rigc, so they are fixed at 1 and 0 here and
+ * the reader does not have to wonder which convention this file chose.
+ */
+import type { SpineBone } from './types.ts';
+
+export interface BoneTransform {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  worldX: number;
+  worldY: number;
+  /** World rotation in degrees, CCW, y up. What a region attachment cancels. */
+  worldRotation: number;
+}
+
+export class TransformError extends Error {}
+
+const DEG = Math.PI / 180;
+
+/**
+ * Crop pixels (y down, origin top-left) -> Spine world (y up, origin at the
+ * bottom-left of the crop).
+ *
+ * This is the whole coordinate contract, and it is also the viewer's: the
+ * renderer's root element sits at the BOTTOM-left of the stage because
+ * spine-html negates world Y (Spine is Y-up, CSS is Y-down).
+ *
+ * It lived in `src/archetype.ts` until the archetype tables left the code, which
+ * was the wrong home for it anyway — it is not a property of any formation.
+ */
+export function cropToSpineY(cropY: number, cropHeight: number): number {
+  return cropHeight - cropY;
+}
+
+/** Round to 6 decimals and never emit "-0" (byte-stable output). */
+function r6(n: number): number {
+  const v = Math.round(n * 1e6) / 1e6;
+  return v === 0 ? 0 : v;
+}
+
+/**
+ * World transform of every bone, in declaration order.
+ *
+ * Bones must be declared parents-first, which is also what `SkeletonJson`
+ * requires (it resolves `parent` by name against the bones already read), so a
+ * violation here is a violation there.
+ */
+export function computeWorldTransforms(bones: SpineBone[]): Map<string, BoneTransform> {
+  const out = new Map<string, BoneTransform>();
+  for (const bone of bones) {
+    const rotation = bone.rotation ?? 0;
+    const cos = Math.cos(rotation * DEG);
+    const sin = Math.sin(rotation * DEG);
+    const la = cos;
+    const lb = -sin;
+    const lc = sin;
+    const ld = cos;
+    const x = bone.x ?? 0;
+    const y = bone.y ?? 0;
+    if (!bone.parent) {
+      out.set(bone.name, { a: la, b: lb, c: lc, d: ld, worldX: x, worldY: y, worldRotation: rotation });
+      continue;
+    }
+    const p = out.get(bone.parent);
+    if (!p) throw new TransformError(`bone "${bone.name}" names parent "${bone.parent}", which is not declared before it`);
+    const a = p.a * la + p.b * lc;
+    const b = p.a * lb + p.b * ld;
+    const c = p.c * la + p.d * lc;
+    const d = p.c * lb + p.d * ld;
+    out.set(bone.name, {
+      a,
+      b,
+      c,
+      d,
+      worldX: p.a * x + p.b * y + p.worldX,
+      worldY: p.c * x + p.d * y + p.worldY,
+      worldRotation: (Math.atan2(c, a) / DEG + 360) % 360,
+    });
+  }
+  return out;
+}
+
+/** World point -> the bone's local space. Used for bind coordinates and offsets. */
+export function toBoneLocal(m: BoneTransform, worldX: number, worldY: number): [number, number] {
+  const det = m.a * m.d - m.b * m.c;
+  if (!Number.isFinite(det) || Math.abs(det) < 1e-9) {
+    throw new TransformError(`bone transform is singular (det ${det}); a zero-scale bone cannot hold bind coordinates`);
+  }
+  const px = worldX - m.worldX;
+  const py = worldY - m.worldY;
+  return [r6((px * m.d - py * m.b) / det), r6((py * m.a - px * m.c) / det)];
+}
+
+/** Normalise degrees into (-180, 180], which is how an editor shows a rotation. */
+export function normaliseDegrees(deg: number): number {
+  let v = ((deg % 360) + 360) % 360;
+  if (v > 180) v -= 360;
+  return r6(v);
+}
+
+/**
+ * Screen degrees (y down, the convention the manifest and the art share) ->
+ * Spine degrees (y up, CCW). One negation, stated once, so no other file has to
+ * remember which way the y flip goes.
+ */
+export function screenToSpineDegrees(screenDeg: number): number {
+  return normaliseDegrees(-screenDeg);
+}