@rig-c/core 2.42.0 → 2.43.0

package/README.md

@@ -416,7 +416,8 @@ and over it any of `bones` (origin to tip, a bone of length 0 marked as one),
 (each `invariants.axes` line and the bones held to it), at the setup pose, at
 `--animation <name> --at <s[,s…]>` — one picture, or a sheet — or zoomed with
 `--zoom <bone|slot>[:pad]` or `--viewport x,y,w,h`; `--bone`/`--hide-bone` pick the
-bones by glob, and `--compare <dir>` draws a second build beside the first on one
+bones by glob, `--overlay-slot`/`--hide-overlay-slot` the slots whose mesh, hull,
+weights and number are drawn over the whole painting, and `--compare <dir>` draws a second build beside the first on one
 transform, to see what a change moved. Beside the PNG it writes a legend:
 the world-to-pixel transform both ways, what each colour means, and every bone's
 origin and tip in world units and in pixels, so a position read off the picture goes

package/docs/AUTHORING.md

@@ -10094,6 +10094,7 @@ pixel (`IN09`).
 | Is this axis declared, and held? | `--show art,declared,bones` | each `invariants.axes` line (§3.7) through its two bones' origins, drawn across the whole tile, and the bones it holds drawn in their own colour; the legend states each held bone's world x axis and how far off the line it lies, as `A51` measures it, at the pose drawn |
 | Did it break during the move? | any of the above `--animation <name> --at <s,s,…>` | one tile per time, left to right on one grid, each labelled with its time and frame |
 | What does this bone move? | `--show art,mesh,weights:<bone> --dim` | the bone's weight over every region and mesh it moves, as a heat: a pixel whose centre lies in a triangle is painted the ramp's colour at the blend of its corners' weights — blue near 0, yellow at 0.5, red at 1 (the stops are in the legend) — and a weight of 0 is not painted, so the art shows where the bone does not reach. A region and an unweighted mesh are moved whole by their slot's bone. The weights are read off `skeleton.json`, the file both posers skin from; a bone that weights nothing paints nothing and the run says so on a line of its own |
+| Does this part's edge follow that bone? | `--show art,weights:<bone>,mesh --overlay-slot <part> --zoom slot:<part>` | the part's own triangles and the bone's weight over them alone, over the whole painting. Where slots stack — a neck under the face, the hair, a collar — every mesh crossing the box is drawn and the heat is the union of every slot the bone moves, so the part's edge has no pixel of its own until the others are left out. The legend's `meshes[]` gives the part's weight for the bone at every vertex, so "does the top row follow the head" is read as numbers as well as colour |
 | How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
 | Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |
 | Did this change move anything? | `--compare <dir>` beside any view | the same view of a second build beside the first, at the same times, on **one** world box and one transform, each half labelled `A`/`B` with the poser that posed it. A mark on a different pixel in the two halves is at a different place in the two rigs |
@@ -10128,7 +10129,7 @@ pixel (`IN09`).
 - `--dim` fades the art toward white (each channel keeps 0.4 of its distance from
   white) so what is drawn over it reads.
 
-### 13.3 Labels, and which bones are drawn
+### 13.3 Labels, and which bones and slots are drawn
 
 - **One label per pixel.** Bones whose origins land on one pixel — a `_ctl` bone and
   its identity child, a chain's joint — are one label: the first by declaration
@@ -10149,6 +10150,16 @@ pixel (`IN09`).
   the shell. The filter is on `bones`, `axes` and `names`; every bone stays in the
   legend, and a left-out one says which flag left it out in `undrawn`. A pattern
   that matches no bone is refused naming the bones there are.
+- **`--overlay-slot <glob[,glob…]>`** draws the per-slot views — `mesh`, `hull`,
+  `weights:<bone>` and `slots` — only for the slots a pattern matches, and
+  **`--hide-overlay-slot <glob[,glob…]>`** for none of the ones it matches, applied
+  after `--overlay-slot`; the patterns are globs, as `--bone`'s are. The **art is not
+  filtered**: the painting is what the edge is read against, and `--dim` already
+  quiets it. A slot left out is absent from `meshes[]` and `slots[]`, and a slot kept
+  keeps its number — its place in the whole draw order, not among the slots drawn. A
+  pattern that matches no slot is refused naming the slots there are. It is not
+  `--slot`: on `render` that flag draws a subset of the *art*, by exact name, which is
+  the opposite of what this keeps whole.
 
 ### 13.4 The legend
 
@@ -10186,6 +10197,8 @@ pixel (`IN09`).
 - `weights` — with `weights:<bone>`: the bone, the ramp's stops as RGBA, the floor
   below which nothing is painted, and how a pixel's weight is read.
 - `boneFilter` — `--bone` and `--hide-bone` as given.
+- `slotFilter` — `--overlay-slot` and `--hide-overlay-slot` as given; with it,
+  `meshes[]` and `slots[]` list only the slots it keeps.
 - `builds` — with `--compare`: each build (`A`, `B`), the poser that posed it, and
   its `skeleton.json`'s sha256. `poser` is build `A`'s.
 
@@ -10201,7 +10214,9 @@ or past the end, `--at` without `--animation` and the reverse, `--zoom` beside
 `--viewport`, `--show declared` on a skeleton with no `skeleton.model.json`
 beside it whose `spine.sha256` is its own — a Spine export states no rig invariants —
 `weights` with no bone or with a bone the build lacks (the bones listed), a
-`--bone`/`--hide-bone` pattern that matches no bone (the bones listed), and, with
+`--bone`/`--hide-bone` pattern that matches no bone (the bones listed), an
+`--overlay-slot`/`--hide-overlay-slot` pattern that matches no slot (the slots
+listed), and, with
 `--compare`, any of these that holds of the second build, said as `the --compare
 build: …`.
 A rig that declares no `invariants.axes` is not refused: the picture draws nothing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/core_commands.ts

@@ -680,6 +680,12 @@ export function cmdInspect(flags: Record<string, string>): void {
   const include = readBonePatterns('bone', flags.bone);
   const exclude = readBonePatterns('hide-bone', flags['hide-bone']);
   const boneFilter = include === undefined && exclude === undefined ? undefined : { ...(include === undefined ? {} : { include }), ...(exclude === undefined ? {} : { exclude }) };
+  const slotInclude = readBonePatterns('overlay-slot', flags['overlay-slot'], 'neck,hair_*');
+  const slotExclude = readBonePatterns('hide-overlay-slot', flags['hide-overlay-slot'], 'neck,hair_*');
+  const slotFilter =
+    slotInclude === undefined && slotExclude === undefined
+      ? undefined
+      : { ...(slotInclude === undefined ? {} : { include: slotInclude }), ...(slotExclude === undefined ? {} : { exclude: slotExclude }) };
   const times = readTimes(flags.at);
   const fps = readPositiveNumber(flags, 'fps', INSPECT_DEFAULT_FPS, 1);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
@@ -733,6 +739,7 @@ export function cmdInspect(flags: Record<string, string>): void {
       show,
       ...(weightsBone === undefined ? {} : { weightsBone }),
       ...(boneFilter === undefined ? {} : { boneFilter }),
+      ...(slotFilter === undefined ? {} : { slotFilter }),
       dim: flags.dim !== undefined,
       animation,
       times,

package/src/cli/shared.ts

@@ -1088,6 +1088,15 @@ const FLAG_MEANINGS: Record<string, string> = {
   'hide-bone':
     "draw none of the bones these globs match — `--bone` the other way round, applied after it, so `--bone 'bang_*' " +
     "--hide-bone '*_ctl'` is the fringe chains without their control bones",
+  'overlay-slot':
+    "draw the per-slot views — mesh, hull, weights:<bone> and slots — only for the slots these globs match (`*` any run of " +
+    "characters, `?` one, the whole name; comma-separated); the art is every slot's still, since it is what the geometry is read " +
+    "against. Not `--slot`: that flag draws a subset of the art on `render`, by exact name. The legend's meshes[] and slots[] list " +
+    'only the slots kept, a slot number stays its place in the whole draw order, and a pattern that matches no slot is refused ' +
+    'naming the slots there are',
+  'hide-overlay-slot':
+    "draw none of the per-slot views for the slots these globs match — `--overlay-slot` the other way round, applied after it, " +
+    "so `--overlay-slot 'hair_*' --hide-overlay-slot hair_back` is the hair but its back layer",
   compare:
     'a second build to draw beside --candidate, the same view at the same times on one world box and one transform — the union ' +
     'of both framings unless --zoom or --viewport pins it — each half labelled with its build and the poser that posed it. A ' +
@@ -1194,6 +1203,8 @@ const FLAG_VALUES: Record<string, string> = {
   zoom: '<name>[:<pad>]',
   bone: '<glob[,glob…]>',
   'hide-bone': '<glob[,glob…]>',
+  'overlay-slot': '<glob[,glob…]>',
+  'hide-overlay-slot': '<glob[,glob…]>',
   compare: '<dir|skeleton.json>',
   record: '<result.json>',
   ballot: '<ballot.html>',
@@ -1582,9 +1593,10 @@ export const COMMANDS: CommandDoc[] = [
       'rigc inspect … --animation <name> --at <s[,s…]> [--fps 12] [--skin <name>]   (one time, or a sheet of several on one grid)',
       'rigc inspect … --zoom <bone|slot>[:<pad>] | --viewport <x,y,w,h>   (a box, in world units)',
       "rigc inspect … --bone 'bang_*' --hide-bone '*_ctl'   (which bones bones, axes and names draw)",
+      'rigc inspect … --overlay-slot neck --hide-overlay-slot <glob>   (which slots mesh, hull, weights and slots draw; the art stays whole)',
       'rigc inspect … --compare <dir | skeleton.json>   (a second build beside the first, on one transform)',
     ],
-    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'bone', 'hide-bone', 'compare', 'max', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'bone', 'hide-bone', 'overlay-slot', 'hide-overlay-slot', 'compare', 'max', 'poser', 'out'],
     overrides: {
       animation: { meaning: 'the animation --at reads its times from (default: the setup pose, with no --at)' },
       fps: { meaning: `the frame grid --at is read on, which is the grid \`render --fps\` draws (default ${INSPECT_DEFAULT_FPS})` },

package/src/inspect.ts

@@ -170,6 +170,18 @@ export interface BoneFilter {
   exclude?: readonly string[];
 }
 
+/**
+ * `--overlay-slot` / `--hide-overlay-slot`: which slots the per-slot views
+ * (`mesh`, `hull`, `weights:<bone>`, `slots`) draw, by glob. The art is not
+ * filtered — it is what the geometry is read against.
+ */
+export interface SlotFilter {
+  /** Draw only the slots some pattern matches; absent draws every slot. */
+  include?: readonly string[];
+  /** Draw none of the slots a pattern matches — applied after `include`. */
+  exclude?: readonly string[];
+}
+
 /** One `rigc inspect` invocation, its flags read but not yet checked against the build. */
 export interface InspectRequest {
   show: readonly ShowWord[];
@@ -177,6 +189,8 @@ export interface InspectRequest {
   weightsBone?: string;
   /** Which bones `bones`, `axes` and `names` draw; absent is every one. */
   boneFilter?: BoneFilter;
+  /** Which slots `mesh`, `hull`, `weights` and `slots` draw; absent is every one. */
+  slotFilter?: SlotFilter;
   dim: boolean;
   /** `null` is the setup pose. */
   animation: string | null;
@@ -232,6 +246,8 @@ export interface InspectPlant {
   noAvoid?: boolean;
   /** Draw every bone whatever `--bone`/`--hide-bone` say. */
   ignoreFilter?: boolean;
+  /** Draw every slot's geometry whatever `--overlay-slot`/`--hide-overlay-slot` say. */
+  ignoreSlotFilter?: boolean;
   /** Draw the first build in both halves of a `--compare`. */
   compareFirstTwice?: boolean;
 }
@@ -283,7 +299,7 @@ export interface LegendLabel {
   overlaps: boolean;
 }
 
-/** One region or mesh the frame shows, when `mesh`, `hull` or `weights` is drawn. */
+/** One region or mesh the frame shows, when `mesh`, `hull` or `weights` is drawn — and, with a slot filter, that it keeps. */
 export interface LegendMesh {
   slot: string;
   attachment: string;
@@ -367,6 +383,8 @@ export interface InspectLegend {
     | { kind: 'viewport' };
   /** `--bone` / `--hide-bone` as given — each bone they leave out says so in its `undrawn`. */
   boneFilter?: { include: string[] | null; exclude: string[] | null };
+  /** `--overlay-slot` / `--hide-overlay-slot` as given — `meshes[]` and `slots[]` then list only the slots they keep. */
+  slotFilter?: { include: string[] | null; exclude: string[] | null };
   /** With `weights:<bone>`: the bone, the ramp a weight is painted with, and how a pixel's weight is read. */
   weights?: { bone: string; ramp: Array<{ weight: number; rgba: number[] }>; floor: number; reading: string };
   /** With `--compare`: each build, the poser that posed it and its `skeleton.json`'s sha256; a tile names its own in `build`. */
@@ -434,10 +452,10 @@ function showSpelled(request: InspectRequest, weightsBone: string | undefined):
  * characters and `?` one, matched against a bone's whole name. Checked against
  * the build later, where a pattern that matches no bone is refused.
  */
-export function readBonePatterns(flag: string, raw: string | undefined): string[] | undefined {
+export function readBonePatterns(flag: string, raw: string | undefined, example = 'bang_*,*_ctl'): string[] | undefined {
   if (raw === undefined) return undefined;
   const patterns = raw.split(',').map((p) => p.trim());
-  if (patterns.some((p) => p === '')) throw new InspectError(`--${flag} ${JSON.stringify(raw)}: an empty pattern; it takes globs, comma-separated, e.g. --${flag} 'bang_*,*_ctl'`);
+  if (patterns.some((p) => p === '')) throw new InspectError(`--${flag} ${JSON.stringify(raw)}: an empty pattern; it takes globs, comma-separated, e.g. --${flag} '${example}'`);
   return patterns;
 }
 
@@ -776,6 +794,31 @@ function filterOut(bones: ReadonlyArray<{ name: string }>, filter: BoneFilter |
   return out;
 }
 
+/**
+ * `--overlay-slot` / `--hide-overlay-slot` against one build's slots: the slots
+ * whose geometry is not drawn. A pattern matching no slot is refused naming the
+ * slots there are — checked even when `apply` is off, so a mutant that ignores
+ * the filter still refuses a typo.
+ */
+function slotsLeftOut(slots: ReadonlyArray<{ name: string }>, filter: SlotFilter | undefined, apply: boolean): Set<string> {
+  const out = new Set<string>();
+  if (filter === undefined) return out;
+  const names = slots.map((s) => s.name);
+  const matchers = (flag: string, patterns: readonly string[]): Array<(name: string) => boolean> =>
+    patterns.map((p) => {
+      const m = globMatcher(p);
+      if (!names.some(m)) throw new InspectError(`--${flag} ${JSON.stringify(p)} matches no slot; the slots are [${names.join(', ')}]`);
+      return m;
+    });
+  const include = filter.include === undefined ? null : matchers('overlay-slot', filter.include);
+  const exclude = filter.exclude === undefined ? null : matchers('hide-overlay-slot', filter.exclude);
+  if (!apply) return out;
+  for (const name of names) {
+    if ((include !== null && !include.some((m) => m(name))) || (exclude !== null && exclude.some((m) => m(name)))) out.add(name);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // the view
 // ---------------------------------------------------------------------------
@@ -970,6 +1013,7 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
     }
   }
   const filtered = builds.map((b) => aboutBuild(b.tag, () => filterOut(b.bones, request.boneFilter, plant.ignoreFilter !== true)));
+  const slotsOut = builds.map((b) => aboutBuild(b.tag, () => slotsLeftOut(b.slots, request.slotFilter, plant.ignoreSlotFilter !== true)));
   // The world box and its pixels: one for every tile of both builds, so a sheet's tiles and a compare's halves overlay.
   let viewport: Viewport;
   let framing: InspectLegend['framing'];
@@ -1034,19 +1078,20 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
       const row = compare ? Math.floor(k / pairs) : Math.floor(k / columns);
       const x0 = gap + column * (width + gap);
       const y0 = gap + row * (height + gap);
-      const drawnTile = drawTile(build, build.poses[k], filtered[bi], { x0, y0, viewport, sheet, compare, weightsBone, first: k === 0 && bi === 0 }, request, plant, notes);
+      const drawnTile = drawTile(build, build.poses[k], filtered[bi], slotsOut[bi], { x0, y0, viewport, sheet, compare, weightsBone, first: k === 0 && bi === 0 }, request, plant, notes);
       if (drawnTile.weighted) weighted[bi] = true;
       if (drawnTile.anyMesh) anyMesh = true;
       for (let y = 0; y < height; y++) plate.data.set(drawnTile.tile.data.subarray(y * width * 4, (y + 1) * width * 4), ((y0 + y) * plate.width + x0) * 4);
       tiles.push(drawnTile.legend);
     }
   }
+  // With a slot filter the sentence says the filter is part of why: the same build unfiltered may paint.
   if (weightsBone !== undefined) {
     for (const [bi, b] of builds.entries()) {
-      if (!weighted[bi]) notes.push(`weights: bone "${weightsBone}" weights no vertex of any region or mesh ${compare ? `build ${b.tag} ` : ''}shows here — nothing painted`);
+      if (!weighted[bi]) notes.push(`weights: bone "${weightsBone}" weights no vertex of any region or mesh${request.slotFilter === undefined ? '' : ' of the slots the filter keeps'} ${compare ? `build ${b.tag} ` : ''}shows here — nothing painted`);
     }
   }
-  if ((request.show.includes('mesh') || request.show.includes('hull')) && !anyMesh) notes.push('mesh/hull: no slot shows a mesh here — nothing drawn for it');
+  if ((request.show.includes('mesh') || request.show.includes('hull')) && !anyMesh) notes.push(`mesh/hull: no slot${request.slotFilter === undefined ? '' : ' the filter keeps'} shows a mesh here — nothing drawn for it`);
   const legend: InspectLegend = {
     spec: INSPECT_SPEC,
     poser: builds[0].poser,
@@ -1059,6 +1104,9 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
     ...(request.boneFilter === undefined
       ? {}
       : { boneFilter: { include: request.boneFilter.include === undefined ? null : [...request.boneFilter.include], exclude: request.boneFilter.exclude === undefined ? null : [...request.boneFilter.exclude] } }),
+    ...(request.slotFilter === undefined
+      ? {}
+      : { slotFilter: { include: request.slotFilter.include === undefined ? null : [...request.slotFilter.include], exclude: request.slotFilter.exclude === undefined ? null : [...request.slotFilter.exclude] } }),
     ...(weightsBone === undefined
       ? {}
       : {
@@ -1103,6 +1151,7 @@ function drawTile(
   build: Gathered,
   pose: { frame: Frame; index: number },
   filtered: Map<string, string>,
+  slotsOut: ReadonlySet<string>,
   place: TilePlace,
   request: InspectRequest,
   plant: InspectPlant,
@@ -1164,6 +1213,7 @@ function drawTile(
     legendTile.meshes = [];
     const [mx, my] = plant.meshShift ?? [0, 0];
     for (const shown of frame.attachments ?? []) {
+      if (slotsOut.has(shown.slot)) continue;
       const rest = build.rest.get(restKey(shown.slot, shown.attachment));
       const vertexCount = shown.vertices.length / 2;
       if (rest === undefined || rest.vertices.length !== shown.vertices.length) {
@@ -1314,6 +1364,8 @@ function drawTile(
     legendTile.slots = [];
     const shown = frame.attachments ?? [];
     for (const [i, att] of shown.entries()) {
+      // A left-out slot keeps its place: a number is the slot's place in the whole draw order, filtered or not.
+      if (slotsOut.has(att.slot)) continue;
       const order = plant.slotsReversed ? shown.length - 1 - i : i;
       let minX = Infinity;
       let minY = Infinity;