@rig-c/core 2.69.0 → 2.71.0

package/src/deformgen.ts

@@ -121,6 +121,16 @@ export interface DeformTurn {
   degrees: number;
   /** Where the axis crosses the driving coordinate. Default 0. */
   about?: number;
+  /**
+   * Whether the displacement includes the foreshortening of the vertex's setup
+   * position `(u − about)·(cos t − 1)`. Default `true`.
+   *
+   * When `false`, each vertex moves by `−z·sin t` alone — for a rig whose plate
+   * proportions are held at their front-view width across the turn and whose
+   * triangles therefore fold at `sin t = A₀ / A_axis` (`asin`) rather than
+   * `tan t = A₀ / A_axis` (`atan`) (issue #1584).
+   */
+  narrowing?: boolean;
   /** Scales each vertex's offset by a weight in [0, 1] — see `DeformEnvelope`. */
   envelope?: DeformEnvelope;
 }
@@ -457,6 +467,7 @@ export function evaluateDeformTransform(
       const rad = (degrees * Math.PI) / 180;
       const cosMinus1 = Math.cos(rad) - 1;
       const sin = Math.sin(rad);
+      const narrowing = t.narrowing !== false;
       // The driving coordinate is the one the axis is perpendicular to: x for a
       // yaw (a vertical axis), y for a pitch (a horizontal one). The other
       // component of every pair is 0, because a turn about an axis moves
@@ -481,11 +492,11 @@ export function evaluateDeformTransform(
         // mesh was built (`sampleContourDepth`) rather than here, where the
         // sheet is long out of reach.
         const z = fromDepth ? (depth as readonly number[])[v] : Math.sqrt(radius * radius - u * u);
-        const d = u * cosMinus1 - z * sin;
+        const d = (narrowing ? u * cosMinus1 : 0) - z * sin;
         offsets[2 * v + along] = round(widen(d));
         offsets[2 * v + (1 - along)] = 0;
       }
-      identity = round(cosMinus1) === 0 && round(sin) === 0;
+      identity = (narrowing ? round(cosMinus1) === 0 : true) && round(sin) === 0;
       identitySpelling = 'degrees 0';
       sampledTo = fromDepth
         ? `The turn is ${degrees}°, and a projection of it can only vanish where every vertex shares one ` +
@@ -494,15 +505,20 @@ export function evaluateDeformTransform(
         : `The turn is ${degrees}°, and a projection of it can only vanish where every vertex shares one ` +
           `${kind === 'yaw' ? 'x' : 'y'} — check that this attachment's setup geometry is the shape the radius says it is`;
       const c = kind === 'yaw' ? 'x' : 'y';
+      const narrowingNote = narrowing ? '' : ' narrowing=false';
       stated = fromDepth
-        ? `depth=true degrees=${degrees}${t.about === undefined ? '' : ` about=${about}`}`
-        : `radius=${radius} degrees=${degrees}${t.about === undefined ? '' : ` about=${about}`}`;
+        ? `depth=true degrees=${degrees}${t.about === undefined ? '' : ` about=${about}`}${narrowingNote}`
+        : `radius=${radius} degrees=${degrees}${t.about === undefined ? '' : ` about=${about}`}${narrowingNote}`;
       formula = fromDepth
-        ? `d${c} = (${c}−about)·(cos t − 1) − z·sin t,   z = the vertex's sampled depth`
-        : `d${c} = (${c}−about)·(cos t − 1) − z·sin t,   z = √(radius² − (${c}−about)²)`;
+        ? narrowing
+          ? `d${c} = (${c}−about)·(cos t − 1) − z·sin t,   z = the vertex's sampled depth`
+          : `d${c} = −z·sin t,   z = the vertex's sampled depth`
+        : narrowing
+          ? `d${c} = (${c}−about)·(cos t − 1) − z·sin t,   z = √(radius² − (${c}−about)²)`
+          : `d${c} = −z·sin t,   z = √(radius² − (${c}−about)²)`;
       derived = [
         `t = ${round(rad)} rad`,
-        `cos t − 1 = ${round(cosMinus1)}`,
+        ...(narrowing ? [`cos t − 1 = ${round(cosMinus1)}`] : []),
         `sin t = ${round(sin)}`,
       ];
       if (fromDepth) {

package/src/depth.ts

@@ -211,8 +211,8 @@ export function depthDigest(map: DepthMap): string {
  * be a different model. `u` is the point's offset from the axis; `z` is how far
  * in front of that axis it sits.
  */
-export function turnDisplacement(u: number, z: number, radians: number): number {
-  return u * (Math.cos(radians) - 1) - z * Math.sin(radians);
+export function turnDisplacement(u: number, z: number, radians: number, narrowing = true): number {
+  return (narrowing ? u * (Math.cos(radians) - 1) : 0) - z * Math.sin(radians);
 }
 
 /** What a field comparison measured. Pixels, in the part's own grid. */
@@ -676,10 +676,16 @@ export function turnCeiling(
   points: ReadonlyArray<readonly [number, number]>,
   z: readonly number[],
   triangles: ReadonlyArray<number>,
+  options?: { narrowing?: boolean | { yaw?: boolean; pitch?: boolean } },
 ): TurnCeiling {
   if (z.length !== points.length) {
     throw new DepthError(`the mesh has ${points.length} vertices and ${z.length} depths were supplied for it`);
   }
+  const narrowingOpt = options?.narrowing;
+  const narrowingByAxis = {
+    yaw: typeof narrowingOpt === 'object' ? narrowingOpt.yaw !== false : narrowingOpt !== false,
+    pitch: typeof narrowingOpt === 'object' ? narrowingOpt.pitch !== false : narrowingOpt !== false,
+  };
   const out: TurnCeiling = {
     yaw: { positive: null, negative: null },
     pitch: { positive: null, negative: null },
@@ -745,10 +751,17 @@ export function turnCeiling(
       ['pitch', dxb * dzc - dxc * dzb],
     ] as const) {
       // A zero here is a triangle the axis cannot fold at all: its area stays
-      // `A₀·cos t`, which only reaches zero at a right angle.
+      // `A₀·cos t` (or `A₀` when `narrowing` is false), which only reaches zero
+      // at a right angle or never.
       if (aAxis === 0) continue;
       const ratio = a0 / aAxis;
-      const degrees = (Math.atan(Math.abs(ratio)) * 180) / Math.PI;
+      const narrowing = narrowingByAxis[axis];
+      // With `narrowing: false`, `2A(t) = 2A₀ − 2A_axis·sin t`, which crosses
+      // zero at `sin t = A₀ / A_axis = ratio`. A ratio with `|ratio| >= 1` never
+      // crosses zero short of 90° (`|sin t| < 1` on `(0, 90°)`), so it is
+      // skipped for the same reason `aAxis === 0` is.
+      if (!narrowing && Math.abs(ratio) >= 1) continue;
+      const degrees = ((narrowing ? Math.atan(Math.abs(ratio)) : Math.asin(Math.abs(ratio))) * 180) / Math.PI;
       const side = ratio > 0 ? 'positive' : 'negative';
       angles[axis][side].push(degrees);
       const held = out[axis][side];

package/src/motion.ts

@@ -146,8 +146,8 @@ export const MOTION_KEYS = {
   MotionDrawOrderKey: ['t', 'offsets'],
   MotionDrawOrderOffset: ['slot', 'offset'],
   MotionEventKey: ['t', 'name', 'int', 'float', 'string', 'volume', 'balance'],
-  TrackDeriveTurn: ['kind', 'degrees', 'depth', 'carried', 'about'],
-  DeformTurn: ['kind', 'radius', 'depth', 'degrees', 'about', 'envelope'],
+  TrackDeriveTurn: ['kind', 'degrees', 'depth', 'carried', 'about', 'narrowing'],
+  DeformTurn: ['kind', 'radius', 'depth', 'degrees', 'about', 'narrowing', 'envelope'],
   DeformAffine: ['kind', 'scale', 'about', 'envelope'],
   DeformWave: ['kind', 'amplitude', 'wavelength', 'phase', 'along', 'axis', 'envelope'],
   DeformBend: ['kind', 'amount', 'from', 'to', 'power', 'along', 'axis', 'envelope'],
@@ -220,8 +220,8 @@ export const MOTION_TYPES = {
   MotionEventKey: {
     t: 'number', name: 'string', int: 'number', float: 'number', string: 'string', volume: 'number', balance: 'number',
   },
-  TrackDeriveTurn: { kind: 'enum', degrees: 'number', depth: 'mixed', carried: 'number', about: 'number' },
-  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number', envelope: 'object' },
+  TrackDeriveTurn: { kind: 'enum', degrees: 'number', depth: 'mixed', carried: 'number', about: 'number', narrowing: 'boolean' },
+  DeformTurn: { kind: 'enum', radius: 'number', depth: 'boolean', degrees: 'number', about: 'number', narrowing: 'boolean', envelope: 'object' },
   DeformAffine: { kind: 'enum', scale: 'number[]', about: 'number[]', envelope: 'object' },
   DeformWave: {
     kind: 'enum', amplitude: 'number', wavelength: 'number', phase: 'number', along: 'enum', axis: 'enum', envelope: 'object',

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/runtime/curves.ts

@@ -0,0 +1,106 @@
+/**
+ * A keyed timeline compiled once for the runtime poser (issue #1591): its key
+ * times and channel values as the oracle stores them (float32, `CoreKey.time`
+ * and `.values`), each segment's curve kind, and every Bézier segment's
+ * polyline evaluated at load by the oracle's own `bezierPolyline`, so that a
+ * pose evaluates the segment the oracle evaluates and nothing else.
+ *
+ * The two reads a pose makes are the oracle's (`keyIndexAt` and `channelAt`
+ * in `src/core/animation.ts`), operation for operation:
+ *
+ * - **The key at `t`** is the last key whose time is at or before `t`, −1
+ *   before the first. The oracle scans from key 0 every time; the runtime
+ *   walks a per-pose cursor from where the previous pose left it, backwards
+ *   while the key's time is after `t` and forwards while the next one's is
+ *   not. Over key times that never decrease (the reader refuses a key not
+ *   after the one before, and float32 can only make two equal), both find the
+ *   same key for every finite `t`. A `t` that is not finite is refused before
+ *   any search (`RuntimeInputError`): the scan reads −1 for NaN and the
+ *   cursor would read wherever it stood.
+ * - **A channel's value** on the segment from key `i`: the key's own value on
+ *   the last key and after a hold; `v0 + ((t − t0) / (t1 − t0)) · (v1 − v0)`
+ *   on a linear segment; and on a Bézier segment the linear piece of the
+ *   polyline whose end is the first point at or after `t`.
+ *
+ * Nothing here allocates once compiled.
+ */
+import { bezierPolyline, BEZIER_PIECES, type CoreKey } from '../core/animation.ts';
+
+/** A segment's curve, per key. */
+export const CURVE_LINEAR = 0;
+export const CURVE_STEPPED = 1;
+export const CURVE_BEZIER = 2;
+
+/** Numbers in one channel's polyline: the segment's two ends and the nine interior points, each a time and a value. */
+export const POLYLINE = 2 * (BEZIER_PIECES + 1);
+
+/** One compiled timeline. `values` and `polylines` are by key, then by channel. */
+export interface RuntimeCurve {
+  readonly keys: number;
+  readonly channels: number;
+  readonly times: Float64Array;
+  readonly values: Float64Array;
+  readonly kinds: Uint8Array;
+  /** `POLYLINE` numbers per key and channel; filled only where the key starts a Bézier segment. */
+  readonly polylines: Float64Array;
+}
+
+/** A timeline's keys compiled; `channels` is how many values each key carries (0 for an attachment timeline). */
+export function compileCurve(keys: readonly CoreKey[], channels: number): RuntimeCurve {
+  const n = keys.length;
+  const times = new Float64Array(n);
+  const values = new Float64Array(n * channels);
+  const kinds = new Uint8Array(n);
+  const polylines = new Float64Array(n * channels * POLYLINE);
+  for (let i = 0; i < n; i++) {
+    const a = keys[i];
+    times[i] = a.time;
+    for (let c = 0; c < channels; c++) values[i * channels + c] = a.values[c];
+    const curve = a.curve;
+    kinds[i] = curve === 'linear' ? CURVE_LINEAR : curve === 'stepped' ? CURVE_STEPPED : CURVE_BEZIER;
+    if (typeof curve === 'string' || i + 1 >= n) continue;
+    const b = keys[i + 1];
+    for (let c = 0; c < channels; c++) {
+      // The oracle's polyline (`channelAt`): the segment's float32 ends around the recurrence over the numbers as the document states them.
+      const inner = bezierPolyline(a.stated.time, a.stated.values[c], curve[c * 4], curve[c * 4 + 1], curve[c * 4 + 2], curve[c * 4 + 3], b.stated.time, b.stated.values[c]);
+      const o = (i * channels + c) * POLYLINE;
+      polylines[o] = a.time;
+      polylines[o + 1] = a.values[c];
+      for (let q = 0; q < inner.length; q++) polylines[o + 2 + q] = inner[q];
+      polylines[o + POLYLINE - 2] = b.time;
+      polylines[o + POLYLINE - 1] = b.values[c];
+    }
+  }
+  return { keys: n, channels, times, values, kinds, polylines };
+}
+
+/** The last key at or before `t` (−1 before the first), found from `cursors[slot]` and left there — the header's first read. */
+export function keyAt(curve: RuntimeCurve, cursors: Int32Array, slot: number, t: number): number {
+  const times = curve.times;
+  let i = cursors[slot];
+  while (i >= 0 && times[i] > t) i--;
+  while (i + 1 < curve.keys && times[i + 1] <= t) i++;
+  cursors[slot] = i;
+  return i;
+}
+
+/** Channel `c` of the segment starting at key `i` (at or after 0), at `t` — the header's second read. */
+export function channelValue(curve: RuntimeCurve, i: number, c: number, t: number): number {
+  const ch = curve.channels;
+  const values = curve.values;
+  const v0 = values[i * ch + c];
+  if (i + 1 >= curve.keys) return v0;
+  const kind = curve.kinds[i];
+  if (kind === CURVE_STEPPED) return v0;
+  if (kind === CURVE_LINEAR) {
+    const t0 = curve.times[i];
+    return v0 + ((t - t0) / (curve.times[i + 1] - t0)) * (values[(i + 1) * ch + c] - v0);
+  }
+  const p = curve.polylines;
+  const o = (i * ch + c) * POLYLINE;
+  let q = 2;
+  while (q < POLYLINE - 2 && p[o + q] < t) q += 2;
+  const x0 = p[o + q - 2];
+  const y0 = p[o + q - 1];
+  return y0 + ((t - x0) / (p[o + q] - x0)) * (p[o + q + 1] - y0);
+}

package/src/runtime/index.ts

@@ -0,0 +1,80 @@
+/**
+ * rigc's runtime poser (issue #1591): the model document posed in place, for
+ * a player drawing many skeletons a frame — separate from the verification
+ * oracle (`src/core/`) and held equal to it at tolerance 0.
+ *
+ * ## Why there are two posers
+ *
+ * The oracle is the reference. Each of its poses is a pure function of the
+ * document, the skin and the time, returned as a fresh, name-keyed, detached
+ * record — the shape a comparison needs, and the shape the core gate holds to
+ * spine-core 4.3.13 to the last bit. A player that consumes that record every
+ * frame pays for the record: the audit behind issue #1591 measured 175–251
+ * KiB allocated per skeleton per frame, against under half a KiB for the
+ * official runtime. The runtime poser keeps one pose per skeleton, resolves
+ * every name to an index once at load (`compileRuntime`) and overwrites typed
+ * arrays in place (`RuntimePose`), so a steady-state frame allocates nothing.
+ *
+ * It does not re-derive the oracle's rules. Every formula is the oracle's, in
+ * the oracle's order of operations (`./pose.ts`'s header), and the gate is the
+ * oracle itself: `tools/core_gate.ts`'s third dumper poses every model of the
+ * corpus through both at the oracle's samples and compares full doubles at
+ * tolerance 0 (*The runtime poser* there). The oracle is not changed for it.
+ *
+ * ## Stage 0: what it poses, and what it refuses
+ *
+ * Bones and their five inherit modes; the rotate, translate, scale and shear
+ * timelines; a slot's attachment and colour (`rgba`, `rgb`, `alpha`)
+ * timelines; region, mesh, weighted mesh and linked mesh vertices; one- and
+ * two-bone ik and world-space, absolute transform constraints with their
+ * timelines; skin-required bones and constraints under the view's skin. One
+ * animation at full weight from the setup pose, at a time or stepped as a
+ * looping track. Everything else is refused at load by name with the list of
+ * what is missing (`./model.ts`'s header and `RUNTIME_FEATURES`); a consumer
+ * falls back to the oracle for a refused model or animation, so nothing breaks
+ * while coverage grows.
+ *
+ * ```ts
+ * const model = compileRuntime(underNoSkin(readModel(text)), { ignore: ['events'] });
+ * const pose = new RuntimePose(model);
+ * pose.setAnimation('walk');
+ * pose.step(1 / 60);       // or pose.apply(t)
+ * pose.computeVertices();  // pose.world, pose.light, pose.shown, pose.vertices
+ * ```
+ *
+ * This module is the `rig-c/runtime` entry (`exports` in package.json), which
+ * is **experimental**: not promised until the poser stabilises (RELEASING.md,
+ * *The import surface*). Pure, as all of `src/`, linking nothing from the Spine
+ * runtime package (`RP10`), and safe to bundle for a browser: its value closure
+ * is this directory and `src/core/` (`CUR136`).
+ */
+export {
+  compileRuntime,
+  missingText,
+  RuntimeInputError,
+  RuntimeRefusal,
+  RUNTIME_FEATURES,
+  RUNTIME_STAGE,
+  DRAW_MESH,
+  DRAW_NONE,
+  DRAW_REGION,
+  DRAW_WEIGHTED,
+  LOCAL_FIELD_NAMES,
+  LOCALS,
+  WORLDS,
+  W_A,
+  W_B,
+  W_C,
+  W_D,
+  W_X,
+  W_Y,
+  L_X,
+  L_Y,
+  L_ROTATION,
+  L_SCALE_X,
+  L_SCALE_Y,
+  L_SHEAR_X,
+  L_SHEAR_Y,
+} from './model.ts';
+export type { RuntimeAnimation, RuntimeAttachment, RuntimeFeature, RuntimeMissing, RuntimeModel, RuntimeOptions, RuntimePlant, RuntimeSlot } from './model.ts';
+export { RuntimePose } from './pose.ts';