spine-rigc 1.2.2 → 1.3.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/banner.svg" alt="rigc - Rig compiler for Spine" width="100%" />
+  <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/banner.svg" alt="rigc — AI-authored Spine 2D rigging and animation, verified before it is written" width="100%" />
 </p>
 
 <p align="center">
@@ -8,9 +8,11 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-38BDF8.svg?style=flat-square" alt="license" /></a>
 </p>
 
-**Rig compiler for Spine.** Declarative rig specs in, Spine 4.3 skeleton data out,
-verified by a `spine-core` round-trip. Built so AI agents can author rigs and check
-their own work.
+**AI-authored Spine 2D rigging and animation, verified before it is written.** rigc is
+a rig compiler for Spine: a rig spec and a motion spec in, Spine 4.3 skeleton data out,
+round-tripped through `spine-core` and a list of named assertions before a byte is
+written. Built so AI agents can author rigs and check their own work; it ships as an
+agent skill.
 
 ## What you get
 
@@ -528,7 +530,7 @@ commands take it and what its default is.
 | Command | Does |
 | --- | --- |
 | `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained, with `skeleton.images` pointing at it so the editor's import finds the parts |
-| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
+| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size`, `--padding` and `--page-edges` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |

package/cli.ts

@@ -101,8 +101,12 @@ import { NotAPngError } from './src/png.ts';
 import { copyAtlasPages } from './src/emit.ts';
 import {
   DEFAULT_PADDING,
+  DEFAULT_PAGE_EDGES,
   DEFAULT_PAGE_SIZE,
+  FREE_EDGE_STEP,
+  PAGE_EDGES,
   packAtlas,
+  type PageEdges,
   pageFootprint,
   parseAtlasText,
   type AtlasRegion,
@@ -612,9 +616,37 @@ const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> =
   ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
   contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
   grid: 'grid      a lattice over the part window at stated column and row positions, every vertex pinned to the slot bone',
+  segments: 'segments  a lattice over the part\'s alpha, every vertex weighted by distance to the bone segments it names',
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
+/**
+ * The line under a `segments` mesh: how its bones share the vertices.
+ *
+ * ⭐ The weights are this generator's whole output, and the per-vertex numbers
+ * are nowhere a reader can see them — so the three figures that say whether the
+ * falloff did what was meant are printed where the mesh is: the most bones any
+ * vertex binds (against `maxBones`), the mean, and how many vertices a single
+ * bone owns outright. A named bone no vertex binds is said by name, because it
+ * is in no weight and so in no other figure either.
+ */
+function meshInfluenceNote(m: CompileResult['meshes'][number]): string {
+  const inf = m.influence;
+  if (inf === undefined) return '';
+  const unbound = m.bones.filter((b) => !inf.bound.includes(b));
+  const single = m.vertices === 0 ? 0 : (inf.singleBone / m.vertices) * 100;
+  const joined = inf.keptCells - inf.artCells;
+  return (
+    `\n        influence  max ${inf.maxBones} bone(s) per vertex, mean ${inf.meanBones.toFixed(2)}, ` +
+    `${inf.singleBone} of ${m.vertices} vertices (${single.toFixed(2)}%) on a single bone` +
+    (unbound.length ? `; named and bound by no vertex: ${unbound.join(', ')}` : '') +
+    `\n        lattice    cell ${inf.cell}px, ${inf.cols}x${inf.rows} cells, ${inf.artCells} with art, ${inf.keptCells} kept` +
+    (inf.islands > 1 || joined > 0
+      ? ` (${inf.islands} island(s) joined into one outline, ${joined} cell(s) added that hold no art)`
+      : '')
+  );
+}
+
 /**
  * Why a figure taken off a part's texels is withheld on a page whose file is
  * not the size its atlas declares — the tail of every line that withholds one
@@ -1260,6 +1292,21 @@ function readIntFlag(flags: Record<string, string>, name: string, fallback: numb
   return Number(raw);
 }
 
+/**
+ * Read `--page-edges`, or its default — `pot`.
+ *
+ * An unknown value is a usage error for `readProfile`'s reason: a typo that fell
+ * back to `pot` would hand the caller who asked for the smaller page the bigger
+ * one, green, and say nothing.
+ */
+function readPageEdges(flags: Record<string, string>): PageEdges {
+  const raw = flags['page-edges'];
+  if (raw === undefined) return DEFAULT_PAGE_EDGES;
+  const found = PAGE_EDGES.find((e) => e === raw);
+  if (!found) throw new UsageError(`--page-edges ${JSON.stringify(raw)}; known values: ${PAGE_EDGES.join(', ')}`);
+  return found;
+}
+
 /**
  * One `DROP` line, written once because two outcomes print it.
  *
@@ -1343,7 +1390,7 @@ function cmdBuild(flags: Record<string, string>): void {
   // now a build like any other — and it is the only one that puts the renderer's
   // own rulebook over shared-page sampling.
   if (!packing) {
-    for (const name of ['page-size', 'padding'] as const) {
+    for (const name of ['page-size', 'padding', 'page-edges'] as const) {
       if (flags[name] !== undefined) throw new UsageError(`--${name} only means something with --pack`);
     }
   }
@@ -1394,7 +1441,8 @@ function cmdBuild(flags: Record<string, string>): void {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
         `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}` +
-        meshDepthNote(m),
+        meshDepthNote(m) +
+        meshInfluenceNote(m),
     );
   }
   for (const ph of result.physics) {
@@ -1445,6 +1493,7 @@ function cmdBuild(flags: Record<string, string>): void {
     const packOpts = {
       pageSize: readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE),
       padding: readIntFlag(flags, 'padding', DEFAULT_PADDING),
+      pageEdges: readPageEdges(flags),
       pageStem: 'skeleton',
     };
     const inputs = result.images.map((img) => ({
@@ -1460,7 +1509,8 @@ function cmdBuild(flags: Record<string, string>): void {
       console.log(
         `  ..    pack: ${page.name} ${page.width}x${page.height}, ` +
           `${packed.placements.filter((p) => packed.pages[p.page].name === page.name).length} region(s), ` +
-          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}`,
+          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}` +
+          (packOpts.pageEdges === 'free' ? ', page edges free' : ''),
       );
     }
     for (const place of packed.placements) {
@@ -3327,7 +3377,8 @@ function cmdExplain(flags: Record<string, string>): void {
       console.log(
         `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
           `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}` +
-          meshDepthNote(m),
+          meshDepthNote(m) +
+          meshInfluenceNote(m),
       );
     }
   }
@@ -3737,6 +3788,10 @@ const FLAG_MEANINGS: Record<string, string> = {
     'one written is the smallest that holds the pack, spilling to more pages only when the set will not fit',
   padding: `gutter each region reserves on every side, --pack only (default ${DEFAULT_PADDING}); it is filled by ` +
     "extending the region's own edge pixels outwards, which is what stops a neighbour bleeding in",
+  'page-edges': `what a page's edges may be, --pack only (default ${DEFAULT_PAGE_EDGES}): pot is a power of two on ` +
+    `both; free tries every width on a ${FREE_EDGE_STEP}px step, takes the height the placement needs and keeps ` +
+    'the least area — a smaller page, at the cost of region attachments sampling within 1 LSB of the loose ' +
+    'build rather than exactly',
   'atlas-in':
     'resolve every part against the regions of this pre-packed .atlas instead of against loose PNGs — region ' +
     'geometry (bounds/offsets/rotate) is read from the file and the atlas is re-emitted into --out, re-anchored',
@@ -3855,6 +3910,7 @@ const FLAG_VALUES: Record<string, string> = {
   'atlas-in': '<file.atlas>',
   'page-size': '<px>',
   padding: '<px>',
+  'page-edges': 'pot|free',
   'texture-from': '<path>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
@@ -3941,7 +3997,7 @@ const COMMANDS: CommandDoc[] = [
     name: 'build',
     usage: [
       'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
-      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}]   (parts onto shared pages, written into --out)`,
+      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free]   (parts onto shared pages, written into --out)`,
       'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
       'rigc build --cut <name> --cuts <cuts.json>',
     ],
@@ -3955,6 +4011,7 @@ const COMMANDS: CommandDoc[] = [
       'pack',
       'page-size',
       'padding',
+      'page-edges',
       'atlas-in',
       'cut',
       'cuts',
@@ -3973,7 +4030,7 @@ const COMMANDS: CommandDoc[] = [
       'this line said "the same arguments as build, minus --profile" and was false in both',
       'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
       'command read what `ingest --art none` writes was reachable and undocumented, while',
-      '--pack, --page-size, --padding and --copy-images are build\'s and do nothing here —',
+      '--pack, --page-size, --padding, --page-edges and --copy-images are build\'s and do nothing here —',
       'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
       'above, and that is now the whole of it.',
     ],