@rig-c/core 2.68.0 → 2.70.0

package/src/cli/shared.ts

@@ -41,6 +41,7 @@ import { FOLDS_FILE } from '../folds.ts';
 import { DRAWN_ALPHA, PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
 import { SEAM_FILE } from '../seam.ts';
 import { OVERLAPS_FILE } from '../overlaps.ts';
+import { DEFAULT_SHEET_FORMAT, SHEET_FORMATS, SHEET_MANIFEST_FILE, SHEET_MANIFEST_SPEC, SHEET_PADDING, SHEET_PAGE_SIZE, type SheetFormat } from '../sheet.ts';
 import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
@@ -151,7 +152,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all', 'all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'overlaps', 'sheet', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1078,6 +1079,15 @@ const FLAG_MEANINGS: Record<string, string> = {
     'pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. Read on the frames\' own ' +
     'grid, so a peak between two frames is not read. A reading, not a gate: nothing is written. An unknown bone, a bone against itself, ' +
     'a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame (a world matrix of zero)',
+  sheet:
+    `also pack each rendered set's frames over a transparent [0, 0, 0, 0] canvas into deterministic RGBA8 sprite sheet page(s) ` +
+    `(\`sheet.png\`, \`sheet2.png\`, …; max edge ${SHEET_PAGE_SIZE}, padding ${SHEET_PADDING} with clamped edge extrusion, trimmed to alpha > 0 ` +
+    'with a 1x1 transparent sentinel for empty frames), a shared TexturePacker-style JSON-Hash table per page (`sheet.json`, `sheet2.json`, …; ' +
+    `\`anchor\` at world (0, 0)), and \`${SHEET_MANIFEST_FILE}\` (\`${SHEET_MANIFEST_SPEC}\`) ` +
+    'in each set directory; diagnostic `f####.png` and `contact.png` stay over opaque `BACKGROUND` unchanged',
+  'sheet-format':
+    `the table format \`render --sheet\` writes beside each sheet page (default \`${DEFAULT_SHEET_FORMAT}\`, verified against pixi.js@8.22.0 and phaser@3.90.0 by tools/sheet_readers.ts; known formats: ${SHEET_FORMATS.join(', ')}). ` +
+    'Takes --sheet',
   'viewport-from':
     "draw on an earlier render's grid exactly — the box, the scale and the pixel size its frames.json records (the file, or the " +
     'directory `render --out` wrote it into) — so a world point lands on the same pixel in both renders. A slot that reaches past ' +
@@ -1285,6 +1295,7 @@ const FLAG_VALUES: Record<string, string> = {
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
   seam: '<slot>:<slot>[,<slot>:<slot>…]',
   'angle-range': '<bone>:<relative-to>[,…]',
+  'sheet-format': 'json-hash',
   'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
@@ -1753,9 +1764,15 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --overlaps   (which slot each frame drew over which, by name, with an outline plate)',
       'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
+      'rigc render … --sheet [--sheet-format json-hash] [--page-edges pot|free]   (deterministic sprite sheets + JSON hash table + sheet-manifest.json per set)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'overlaps', 'angle-range', 'sheet', 'sheet-format', 'page-edges', 'environment', 'poser', 'out'],
     overrides: {
+      'page-edges': {
+        meaning:
+          `what each sprite sheet page's edges may be, --sheet only (default ${DEFAULT_PAGE_EDGES}, max edge ${SHEET_PAGE_SIZE}, padding ${SHEET_PADDING}): ` +
+          'pot is a power of two on both; free chooses the smallest-area rectangle up to the max edge that holds the trimmed frames',
+      },
       out: {
         value: '<dir>',
         meaning:
@@ -2252,6 +2269,17 @@ export function readPageEdges(flags: Record<string, string>): PageEdges {
   return found;
 }
 
+/**
+ * Read `--sheet-format`, or its default — `json-hash` (issue #1560).
+ */
+export function readSheetFormat(flags: Record<string, string>): SheetFormat {
+  const raw = flags['sheet-format'];
+  if (raw === undefined) return DEFAULT_SHEET_FORMAT;
+  const found = SHEET_FORMATS.find((f) => f === raw);
+  if (!found) throw new UsageError(`--sheet-format ${JSON.stringify(raw)}; known formats: ${SHEET_FORMATS.join(', ')}`);
+  return found;
+}
+
 /**
  * Read `--pack-shape`, or its default — `rect` (issue #1099).
  *

package/src/cli/write_whole.ts

@@ -3,7 +3,7 @@
  * refusal — the writer a command uses for a document too large to trust to
  * `console.log` (issue #1487).
  *
- * ⚖️ Why not `console.log`: on Bun 1.2.0, the declared minimum, one ~322 KB
+ * ⚖️ Why not `console.log`: on Bun 1.2.0 (then the declared minimum), one ~322 KB
  * line with non-ASCII in it came out 330,634 bytes for 330,632, a stray
  * `\xe2\x00` at a 64 KiB chunk boundary — to a file, a pipe and a slow pipe
  * alike. And on a stdout whose pipe is non-blocking (a parent set `O_NONBLOCK`

package/src/render_read.ts

@@ -0,0 +1,55 @@
+/**
+ * The promised renderer reads for checked consumers (issue #1561).
+ *
+ * This entry registers no Spine side. Rigc builds use the official candidate
+ * chooser and core poser; inputs needing Spine are refused by SpineRuntimeError
+ * unless the consumer has explicitly loaded rig-c/render. That entry keeps its
+ * eager runtime import and registers the same implementation this seam uses.
+ * Only the agreed reads, their types and their existing failure classes belong
+ * here. The broader implementation module is not the public contract.
+ */
+export {
+  loadCandidate,
+  throughPoser,
+  sampleAnimation,
+  sampleSetupPose,
+  pageFor,
+  projector,
+  rasterisePiece,
+  renderFrame,
+  CandidateAtlasError,
+  CandidatePairError,
+  PoserChoiceError,
+  SlotSubsetError,
+} from './render_shared.ts';
+export { SpineRuntimeError } from './spine_side.ts';
+export { CoreInputError } from './core/index.ts';
+export type {
+  Candidate,
+  SkeletonFacts,
+  PoserChoice,
+  PoserName,
+  MakeCorePoser,
+  Poser,
+  Posed,
+  PoseSource,
+  PoseOptions,
+  DrawOptions,
+  SkinRoster,
+  SlotSubset,
+  Frame,
+  BoneSnapshot,
+  AttachmentPose,
+  AttachmentRest,
+  Piece,
+  PieceCommon,
+  PieceTexture,
+  UvWindow,
+  Quad,
+  Mesh,
+  ClipSource,
+  Viewport,
+  EmitPixel,
+} from './render_shared.ts';
+export type { Plate, RGBA } from '../tools/plate.ts';
+export type { EnvironmentStep, EnvironmentChange } from './environment.ts';

package/src/render_shared.ts

@@ -97,6 +97,8 @@ export { choosePosers, pairRefusal, regionKey };
 
 /** Opaque, and light: both of rung 3's parts are dark slate, so is every ground. */
 export const BACKGROUND: RGBA = [232, 232, 232, 255];
+/** Transparent canvas for `render --sheet`, leaving diagnostic `f####.png` and `contact.png` on `BACKGROUND`. */
+export const TRANSPARENT_BACKGROUND: RGBA = [0, 0, 0, 0];
 /** Padding around the union bounding box, as a fraction of its long side. */
 export const PAD = 0.04;
 /**
@@ -221,6 +223,23 @@ export interface FrameSet {
     plates: number;
     moving: Array<{ under: string; over: string; frames: number; most: { index: number; px: number } }>;
   };
+  /**
+   * The spritesheet export, when `render --sheet` asked for it (issue #1560):
+   * the set's manifest file, the table format, the page-edge policy, how many
+   * pages were written, how many frames were packed, and how many of them were
+   * empty (`1x1` transparent sentinel).
+   *
+   * ⭐ Absent unless asked for, for `skin`'s reason in `FramesSidecar`: a render
+   * without the flag stays the bytes it always was.
+   */
+  sheet?: {
+    manifest: string;
+    format: 'json-hash';
+    pageEdges: 'pot' | 'free';
+    pages: number;
+    frames: number;
+    emptyFrames: number;
+  };
 }
 
 export interface FramesSidecar {

package/src/seam.ts

@@ -290,7 +290,7 @@ function weightsIn(triangles: readonly number[], xy: ArrayLike<number>, t: numbe
  * the triangle the point is least outside of (the largest smallest weight, the
  * lowest index on a tie). `null` when every triangle has collapsed in `from`.
  */
-function carry(triangles: readonly number[], from: ArrayLike<number>, to: ArrayLike<number>, id: number, qx: number, qy: number): [number, number] | null {
+export function carry(triangles: readonly number[], from: ArrayLike<number>, to: ArrayLike<number>, id: number, qx: number, qy: number): [number, number] | null {
   let best = id;
   let w = id >= 0 ? weightsIn(triangles, from, id, qx, qy) : null;
   if (w === null) {
@@ -309,7 +309,11 @@ function carry(triangles: readonly number[], from: ArrayLike<number>, to: ArrayL
   }
   if (w === null || best < 0) return null;
   const [a, b, c] = [triangles[3 * best], triangles[3 * best + 1], triangles[3 * best + 2]];
-  return [w[0] * to[2 * a] + w[1] * to[2 * b] + w[2] * to[2 * c], w[0] * to[2 * a + 1] + w[1] * to[2 * b + 1] + w[2] * to[2 * c + 1]];
+  // #1568: stationary and translated pieces must carry without barycentric round-trip drift.
+  const dxa = to[2 * a] - from[2 * a], dya = to[2 * a + 1] - from[2 * a + 1];
+  const dxb = to[2 * b] - from[2 * b], dyb = to[2 * b + 1] - from[2 * b + 1];
+  const dxc = to[2 * c] - from[2 * c], dyc = to[2 * c + 1] - from[2 * c + 1];
+  return [qx + dxc + w[0] * (dxa - dxc) + w[1] * (dxb - dxc), qy + dyc + w[0] * (dya - dyc) + w[1] * (dyb - dyc)];
 }
 
 /** The convex hull of `points`, counter-clockwise, collinear points dropped (Andrew's monotone chain). */