spine-rigc 0.5.0 → 0.6.0

package/src/compile.ts

@@ -21,6 +21,7 @@ import { basename, dirname, relative, resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { readPngInfo } from './png.ts';
 import { CompileError, NotImplementedError } from './errors.ts';
+import { parseJsonWithPosition } from './json-position.ts';
 import {
   parseRigSpec,
   type RigAttachment,
@@ -255,8 +256,17 @@ export function bezierForChannel(
 // ---------------------------------------------------------------------------
 
 function readJson<T>(path: string): T {
+  let text: string;
   try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
+    text = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw new CompileError(`cannot read ${path}: ${(err as Error).message}`);
+  }
+  try {
+    // A parse failure gets a line/column appended to the runtime's own
+    // message — see `parseJsonWithPosition` for why `JSON.parse` alone
+    // cannot say where.
+    return parseJsonWithPosition(text) as T;
   } catch (err) {
     throw new CompileError(`cannot read ${path}: ${(err as Error).message}`);
   }
@@ -319,6 +329,36 @@ export interface CompileOptions {
   imagesDir?: string;
 }
 
+/**
+ * One part = one page. No packer, so no PMA trap, no rotation, no strip
+ * offsets. Region covers the page exactly => u2=v2=1.
+ *
+ * Two text-shape traps are load-bearing here:
+ *   * a region name is the RAW line, not a trimmed one -> no indentation;
+ *   * a blank line closes the page block -> none between header and regions.
+ *
+ * Exported (rather than inlined into `compile`) so `--copy-images` can call it a
+ * second time with `page` rewritten to the copies' filenames, after the copy
+ * itself has happened — see [`src/emit.ts`](emit.ts). Everything else about an
+ * image (`region`, `width`, `height`) is unchanged by that rewrite; only where the
+ * bytes live moved.
+ */
+export function buildAtlasText(images: CompiledImage[]): string {
+  const atlasLines: string[] = [];
+  images.forEach((img, i) => {
+    if (i > 0) atlasLines.push(''); // exactly one blank line BETWEEN pages
+    atlasLines.push(img.page);
+    atlasLines.push(`size: ${img.width}, ${img.height}`);
+    atlasLines.push('filter: Linear, Linear');
+    atlasLines.push('pma: false');
+    atlasLines.push(img.region);
+    atlasLines.push(`bounds: 0, 0, ${img.width}, ${img.height}`);
+    atlasLines.push(`offsets: 0, 0, ${img.width}, ${img.height}`);
+    atlasLines.push('rotate: 0');
+  });
+  return `${atlasLines.join('\n')}\n`;
+}
+
 export function compile(opts: CompileOptions): CompileResult {
   const rigPath = resolve(opts.rigPath);
   const motionPath = resolve(opts.motionPath);
@@ -330,17 +370,38 @@ export function compile(opts: CompileOptions): CompileResult {
   const motion = readJson<MotionSpec>(motionPath);
   const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath);
 
-  if (motion.spec !== 'rigc-motion/1') {
-    throw new CompileError(`unknown motion spec version: ${String(motion.spec)}`);
-  }
-  // The motion spec was authored against one formation. Pairing it with another
-  // rig would aim its keys at bones whose names happen to match and whose meaning
-  // does not — the class of wrongness that loads, plays and lies.
-  if (motion.archetype !== rig.name) {
-    throw new CompileError(
-      `motion spec names archetype "${motion.archetype}" but the rig spec at ${rigPath} is called "${rig.name}"`,
-    );
-  }
+  // The rig spec names its own path in every message `parseRigSpec` throws (its
+  // `where` argument, above). The motion spec gets no such treatment below —
+  // every "animation … bone … property" refusal is built from data alone — so a
+  // reader with two input files and one error has no way to tell which one is at
+  // fault. This wraps the motion-only regions (the version/archetype check right
+  // below, the physics table and the animation loop further down) and prefixes
+  // the motion path onto any `CompileError` that escapes them, unless the
+  // message already names it.
+  const withMotionSource = <T>(fn: () => T): T => {
+    try {
+      return fn();
+    } catch (err) {
+      if (err instanceof CompileError && !err.message.includes(motionPath)) {
+        throw new CompileError(`${motionPath}: ${err.message}`);
+      }
+      throw err;
+    }
+  };
+
+  withMotionSource(() => {
+    if (motion.spec !== 'rigc-motion/1') {
+      throw new CompileError(`unknown motion spec version: ${String(motion.spec)}`);
+    }
+    // The motion spec was authored against one formation. Pairing it with another
+    // rig would aim its keys at bones whose names happen to match and whose meaning
+    // does not — the class of wrongness that loads, plays and lies.
+    if (motion.archetype !== rig.name) {
+      throw new CompileError(
+        `motion spec names archetype "${motion.archetype}" but the rig spec at ${rigPath} is called "${rig.name}"`,
+      );
+    }
+  });
 
   // The stage. The rig may state it outright (a foreign skeleton has no crop);
   // otherwise the manifest's crop is it. With neither there is nothing to
@@ -546,25 +607,7 @@ export function compile(opts: CompileOptions): CompileResult {
   }
 
   // -- 2. atlas --------------------------------------------------------------
-  // One part = one page. No packer, so no PMA trap, no rotation, no strip
-  // offsets. Region covers the page exactly => u2=v2=1.
-  //
-  // Two text-shape traps are load-bearing here:
-  //   * a region name is the RAW line, not a trimmed one -> no indentation;
-  //   * a blank line closes the page block -> none between header and regions.
-  const atlasLines: string[] = [];
-  images.forEach((img, i) => {
-    if (i > 0) atlasLines.push(''); // exactly one blank line BETWEEN pages
-    atlasLines.push(img.page);
-    atlasLines.push(`size: ${img.width}, ${img.height}`);
-    atlasLines.push('filter: Linear, Linear');
-    atlasLines.push('pma: false');
-    atlasLines.push(img.region);
-    atlasLines.push(`bounds: 0, 0, ${img.width}, ${img.height}`);
-    atlasLines.push(`offsets: 0, 0, ${img.width}, ${img.height}`);
-    atlasLines.push('rotate: 0');
-  });
-  const atlasText = `${atlasLines.join('\n')}\n`;
+  const atlasText = buildAtlasText(images);
 
   // -- 3. bones --------------------------------------------------------------
   //
@@ -728,128 +771,132 @@ export function compile(opts: CompileOptions): CompileResult {
     constraints.push(buildRigConstraint(spec as RigConstraintInput, boneNames));
     constraintNames.add(spec.name);
   }
-  for (const [name, spec] of Object.entries(motion.physics ?? {})) {
-    if (constraintNames.has(name)) {
-      throw new CompileError(`constraint "${name}" is declared in both the rig spec and the motion spec's physics table`);
-    }
-    constraintNames.add(name);
-    if (!boneNames.has(spec.bone)) {
-      throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
-    }
-    const entry: SpineConstraint = {
-      name,
-      type: 'physics',
-      bone: spec.bone,
-    };
-    const components: string[] = [];
-    for (const comp of PHYSICS_COMPONENTS) {
-      const v = spec[comp];
-      if (v === undefined || v === 0) continue;
-      entry[comp] = r6(v);
-      components.push(comp);
-    }
-    if (!components.length) {
-      // The parser is happy with this and the constraint does nothing at all.
-      // A23 catches it too; refusing here means it never reaches the gate.
-      throw new CompileError(
-        `physics constraint "${name}" drives no component — set at least one of ${PHYSICS_COMPONENTS.join('/')}`,
-      );
+  withMotionSource(() => {
+    for (const [name, spec] of Object.entries(motion.physics ?? {})) {
+      if (constraintNames.has(name)) {
+        throw new CompileError(`constraint "${name}" is declared in both the rig spec and the motion spec's physics table`);
+      }
+      constraintNames.add(name);
+      if (!boneNames.has(spec.bone)) {
+        throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
+      }
+      const entry: SpineConstraint = {
+        name,
+        type: 'physics',
+        bone: spec.bone,
+      };
+      const components: string[] = [];
+      for (const comp of PHYSICS_COMPONENTS) {
+        const v = spec[comp];
+        if (v === undefined || v === 0) continue;
+        entry[comp] = r6(v);
+        components.push(comp);
+      }
+      if (!components.length) {
+        // The parser is happy with this and the constraint does nothing at all.
+        // A23 catches it too; refusing here means it never reaches the gate.
+        throw new CompileError(
+          `physics constraint "${name}" drives no component — set at least one of ${PHYSICS_COMPONENTS.join('/')}`,
+        );
+      }
+      for (const [param, dflt] of PHYSICS_PARAMS) {
+        const v = spec[param as keyof typeof spec] as number | undefined;
+        if (v === undefined || v === dflt) continue;
+        entry[param] = r6(v);
+      }
+      constraints.push(entry);
+      physicsReport.push({
+        name,
+        bone: spec.bone,
+        components,
+        mix: spec.mix ?? 1,
+        drivesMesh: meshBones.has(spec.bone),
+      });
     }
-    for (const [param, dflt] of PHYSICS_PARAMS) {
-      const v = spec[param as keyof typeof spec] as number | undefined;
-      if (v === undefined || v === dflt) continue;
-      entry[param] = r6(v);
-    }
-    constraints.push(entry);
-    physicsReport.push({
-      name,
-      bone: spec.bone,
-      components,
-      mix: spec.mix ?? 1,
-      drivesMesh: meshBones.has(spec.bone),
-    });
-  }
+  });
 
   // -- 5. animations ---------------------------------------------------------
   const animations: SpineSkeletonJson['animations'] = {};
   const declaredDurations: Record<string, number> = {};
   const slotNames = new Set(slots.map((s) => s.name));
 
-  for (const [animName, anim] of Object.entries(motion.animations)) {
-    declaredDurations[animName] = anim.duration;
-    const slotTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const boneTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const physicsTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
-    const claimed = new Set<string>();
-    let compiledDuration = 0;
-
-    for (const track of anim.tracks) {
-      const isPhysicsTrack = track.property in PHYSICS_TRACKS;
-      const isBoneTrack = !isPhysicsTrack && track.property in BONE_TRACKS;
-      const targets = resolveTargets(track, motion, animName);
-      targets.forEach((target, index) => {
-        if (isPhysicsTrack) {
-          if (!constraintNames.has(target)) {
-            throw new CompileError(`animation "${animName}" keys unknown physics constraint "${target}"`);
+  withMotionSource(() => {
+    for (const [animName, anim] of Object.entries(motion.animations)) {
+      declaredDurations[animName] = anim.duration;
+      const slotTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const boneTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const physicsTimelines: Record<string, Record<string, SpineTimelineKey[]>> = {};
+      const claimed = new Set<string>();
+      let compiledDuration = 0;
+
+      for (const track of anim.tracks) {
+        const isPhysicsTrack = track.property in PHYSICS_TRACKS;
+        const isBoneTrack = !isPhysicsTrack && track.property in BONE_TRACKS;
+        const targets = resolveTargets(track, motion, animName);
+        targets.forEach((target, index) => {
+          if (isPhysicsTrack) {
+            if (!constraintNames.has(target)) {
+              throw new CompileError(`animation "${animName}" keys unknown physics constraint "${target}"`);
+            }
+          } else if (isBoneTrack) {
+            if (!boneNames.has(target)) {
+              throw new CompileError(`animation "${animName}" keys unknown bone "${target}"`);
+            }
+          } else if (!slotNames.has(target)) {
+            throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
           }
-        } else if (isBoneTrack) {
-          if (!boneNames.has(target)) {
-            throw new CompileError(`animation "${animName}" keys unknown bone "${target}"`);
+          const claim = `${target}.${track.property}`;
+          if (claimed.has(claim)) {
+            throw new CompileError(
+              `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
+            );
           }
-        } else if (!slotNames.has(target)) {
-          throw new CompileError(`animation "${animName}" targets unknown slot "${target}"`);
-        }
-        const claim = `${target}.${track.property}`;
-        if (claimed.has(claim)) {
-          throw new CompileError(
-            `animation "${animName}" has two tracks on ${claim}; merge them into one track`,
-          );
-        }
-        claimed.add(claim);
-
-        const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
-        const keys = isPhysicsTrack
-          ? compileValueTrack(track, motion, animName, anim.duration, target, shift, PHYSICS_TRACKS, 'physics constraint')
-          : isBoneTrack
-            ? compileValueTrack(track, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
-            : compileTrack(track, motion, animName, anim.duration, target, shift, tableFor('default'));
-        for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
-        if (isPhysicsTrack) (physicsTimelines[target] ??= {})[track.property] = keys;
-        else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
-        else (slotTimelines[target] ??= {})[track.property] = keys;
-      });
-    }
+          claimed.add(claim);
+
+          const shift = (track.lag ?? 0) + (track.stagger ?? 0) * index;
+          const keys = isPhysicsTrack
+            ? compileValueTrack(track, motion, animName, anim.duration, target, shift, PHYSICS_TRACKS, 'physics constraint')
+            : isBoneTrack
+              ? compileValueTrack(track, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
+              : compileTrack(track, motion, animName, anim.duration, target, shift, tableFor('default'));
+          for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
+          if (isPhysicsTrack) (physicsTimelines[target] ??= {})[track.property] = keys;
+          else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
+          else (slotTimelines[target] ??= {})[track.property] = keys;
+        });
+      }
 
-    const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
-    if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
-
-    const eventKeys = anim.events ? compileEvents(anim.events, animName, anim.duration, rig.events ?? {}) : null;
-    // An event timeline counts towards the animation's length the same as any
-    // other: `readAnimation` takes the duration from the longest timeline it
-    // built, and `EventTimeline.getDuration()` is its last frame like the rest.
-    if (eventKeys) for (const key of eventKeys) compiledDuration = Math.max(compiledDuration, key.time as number);
-
-    // Rule 4: the declared duration is verified, because skeleton JSON does not
-    // carry one — the loader takes the max key time.
-    //
-    // This arm is about the DECLARED DURATION being wrong, so it compares one
-    // number per animation and tolerates a frame of it. The other arm —
-    // `checkKeyTime`, above, per key — is about a key landing past the end, and
-    // a frame is 16,667 times too coarse to see one. Both are needed: this one
-    // catches an animation that stops a second early, and only that one catches
-    // a key on a track whose neighbour already sits on the declared duration.
-    if (Math.abs(compiledDuration - anim.duration) > FRAME) {
-      throw new CompileError(
-        `animation "${animName}" declares duration ${anim.duration}s but its last key is at ${compiledDuration}s`,
-      );
+      const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
+      if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
+
+      const eventKeys = anim.events ? compileEvents(anim.events, animName, anim.duration, rig.events ?? {}) : null;
+      // An event timeline counts towards the animation's length the same as any
+      // other: `readAnimation` takes the duration from the longest timeline it
+      // built, and `EventTimeline.getDuration()` is its last frame like the rest.
+      if (eventKeys) for (const key of eventKeys) compiledDuration = Math.max(compiledDuration, key.time as number);
+
+      // Rule 4: the declared duration is verified, because skeleton JSON does not
+      // carry one — the loader takes the max key time.
+      //
+      // This arm is about the DECLARED DURATION being wrong, so it compares one
+      // number per animation and tolerates a frame of it. The other arm —
+      // `checkKeyTime`, above, per key — is about a key landing past the end, and
+      // a frame is 16,667 times too coarse to see one. Both are needed: this one
+      // catches an animation that stops a second early, and only that one catches
+      // a key on a track whose neighbour already sits on the declared duration.
+      if (Math.abs(compiledDuration - anim.duration) > FRAME) {
+        throw new CompileError(
+          `animation "${animName}" declares duration ${anim.duration}s but its last key is at ${compiledDuration}s`,
+        );
+      }
+      animations[animName] = {};
+      if (Object.keys(slotTimelines).length) animations[animName].slots = slotTimelines;
+      if (Object.keys(boneTimelines).length) animations[animName].bones = boneTimelines;
+      if (Object.keys(physicsTimelines).length) animations[animName].physics = physicsTimelines;
+      if (drawOrder) animations[animName].drawOrder = drawOrder;
+      if (eventKeys) animations[animName].events = eventKeys;
     }
-    animations[animName] = {};
-    if (Object.keys(slotTimelines).length) animations[animName].slots = slotTimelines;
-    if (Object.keys(boneTimelines).length) animations[animName].bones = boneTimelines;
-    if (Object.keys(physicsTimelines).length) animations[animName].physics = physicsTimelines;
-    if (drawOrder) animations[animName].drawOrder = drawOrder;
-    if (eventKeys) animations[animName].events = eventKeys;
-  }
+  });
 
   // -- 6. assemble -----------------------------------------------------------
   const header: SpineSkeletonJson['skeleton'] = {

package/src/emit.ts

@@ -0,0 +1,88 @@
+/**
+ * Writing the compiled atlas to disk with its pages copied alongside it — the
+ * step behind `build --copy-images` (issue #217).
+ *
+ * `compile()` never touches the filesystem for output; it only reads inputs and
+ * assembles text (see its own header). A page's name in that text is
+ * `relative(outDir, absPath)` — the PNG's path *as seen from the atlas file* — so
+ * it points at wherever the source art already lives, which is very often
+ * outside `outDir` (`../parts/torso.png`). That is the right default for a build
+ * that sits beside the project that owns the art, and it is exactly what makes
+ * `--out` non-self-contained the moment the directory is zipped, committed or
+ * handed to someone who does not have that project.
+ *
+ * `copyAtlasImages` is the opt-in other half: copy every referenced page PNG
+ * into the output directory and hand back the atlas text with page names
+ * rewritten to match. Nothing here runs unless `cli.ts` calls it, so the default
+ * emit (`buildAtlasText` in [`src/compile.ts`](compile.ts)) is untouched.
+ */
+import { copyFileSync, mkdirSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { buildAtlasText } from './compile.ts';
+import type { CompiledImage } from './types.ts';
+
+/** One page's source and where `--copy-images` put it. */
+export interface CopiedPage {
+  region: string;
+  /** Absolute path the page was read from. */
+  from: string;
+  /** Filename inside the output directory — also the atlas's new page name. */
+  to: string;
+}
+
+export interface CopyImagesResult {
+  /** The atlas text, with every page name rewritten to its `to` filename. */
+  atlasText: string;
+  pages: CopiedPage[];
+}
+
+/**
+ * Copy every image `compile()` referenced into `outDir` and return the atlas
+ * text rewritten to match.
+ *
+ * ## Naming and collisions
+ *
+ * A page's filename in `outDir` is its source basename, unchanged. That is safe
+ * because rigc already enforces a stronger invariant upstream: a region name IS
+ * the PNG basename (`compile.ts`'s `addImage`), and two images sharing a region
+ * are refused at compile time — so within one compile, no two entries of
+ * `images` can legitimately carry the same basename already.
+ *
+ * The check below exists anyway. "The caller already prevents this" stops being
+ * true the moment the caller changes, and a case-insensitive filesystem (the
+ * macOS default) can still collide two basenames the region check saw as
+ * distinct (`Torso.png` vs `torso.png` are different regions, one destination
+ * file). On a genuine collision, the second and later claimants of a name get
+ * `-2`, `-3`, … inserted before the extension, assigned in the order `images`
+ * lists them — the same order the atlas itself is written in, so the mapping is
+ * identical on every run of the same compile. The rewritten atlas is the record
+ * of it: reading a page name back out says exactly which file it is, with no
+ * side table to fall out of sync.
+ */
+export function copyAtlasImages(images: CompiledImage[], outDir: string): CopyImagesResult {
+  mkdirSync(outDir, { recursive: true });
+
+  const claimedBy = new Map<string, string>(); // destination filename -> absPath holding it
+  const pages: CopiedPage[] = [];
+
+  for (const img of images) {
+    const original = basename(img.absPath);
+    let name = original;
+    if (claimedBy.has(name) && claimedBy.get(name) !== img.absPath) {
+      const ext = extname(original);
+      const stem = original.slice(0, original.length - ext.length);
+      let n = 2;
+      do {
+        name = `${stem}-${n}${ext}`;
+        n++;
+      } while (claimedBy.has(name) && claimedBy.get(name) !== img.absPath);
+    }
+    claimedBy.set(name, img.absPath);
+    pages.push({ region: img.region, from: img.absPath, to: name });
+  }
+
+  for (const page of pages) copyFileSync(page.from, join(outDir, page.to));
+
+  const rewritten: CompiledImage[] = images.map((img, i) => ({ ...img, page: pages[i].to }));
+  return { atlasText: buildAtlasText(rewritten), pages };
+}