rig-c 2.35.1 → 2.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-c",
-  "version": "2.35.1",
+  "version": "2.36.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/core/animation.ts

@@ -706,6 +706,108 @@ export function posedBones(doc: CompiledDocument, timelines: CoreAnimationTimeli
   });
 }
 
+/**
+ * A player's bone-local adjustment (issue #1336): a function the live track
+ * (`openTrack`'s `adjust`, `./track.ts`) calls once per pose, after the
+ * animation's timelines have posed the bone locals at the step's time and
+ * before the world transforms, the constraints and the physics step — so a
+ * write is what the rest of the step reads: the bone's children, the
+ * attachments drawn through it, every constraint and the physics constraint
+ * stepped on top of it. It is spine-core's "application code" writing
+ * `Bone.pose` between `AnimationState.apply` and `updateWorldTransform`
+ * (`CO50` holds the two equal at tolerance 0).
+ *
+ * - **The view is the step's locals, posed from the setup pose.** Every pose
+ *   of a walk is posed from the setup pose at its time (`./raw.ts`,
+ *   `TrackState`), so a write lives for the pose it was written in and the
+ *   next step's hook reads the timelines' value again, not the write. A
+ *   channel no timeline keys reads its setup value on every step.
+ * - **A bone the hook does not write is untouched**: the timelines' bone
+ *   object as it was, the setup bone itself where nothing keys it. A written
+ *   bone is copied before the write, so the document is never written.
+ * - **A write that is not a finite number is refused by name**, the bone, the
+ *   channel and the value — where the core refuses a non-finite value, by
+ *   name, rather than posing a picture with it (`finite` in `./raw.ts`).
+ */
+export interface BoneLocals {
+  rotation: number;
+  x: number;
+  y: number;
+  scaleX: number;
+  scaleY: number;
+  shearX: number;
+  shearY: number;
+}
+
+/** The locals of a step's bones, by name (`BoneLocals`). */
+export interface AdjustableLocals {
+  /** The document's bones, in its order. */
+  readonly names: readonly string[];
+  /** One bone's locals, read and written in place; a name the document has no bone for is refused by name. */
+  bone(name: string): BoneLocals;
+}
+
+/** What `openTrack`'s `adjust` is: called once per pose with the step's locals (`BoneLocals`). */
+export type LocalAdjust = (locals: AdjustableLocals) => void;
+
+/** The seven channels a `BoneLocals` reads and writes, each with the value an unstated one reads as (`worldTransforms`' defaults). */
+const LOCAL_CHANNELS = { rotation: 0, x: 0, y: 0, scaleX: 1, scaleY: 1, shearX: 0, shearY: 0 } as const;
+type LocalChannel = keyof typeof LOCAL_CHANNELS;
+
+/** One bone of a step's `bones`, read through and written through, copied on its first write (`BoneLocals`' second rule). */
+class StepLocals implements BoneLocals {
+  constructor(
+    private readonly bones: ModelBone[],
+    private readonly index: number,
+    private readonly setup: ModelBone,
+  ) {}
+
+  private read(channel: LocalChannel): number {
+    return this.bones[this.index][channel] ?? LOCAL_CHANNELS[channel];
+  }
+
+  private write(channel: LocalChannel, value: number): void {
+    if (typeof value !== 'number' || !Number.isFinite(value)) throw new CoreInputError(`the adjustment wrote bone "${this.setup.name}" ${channel} = ${String(value)}, not a finite number`);
+    if (this.bones[this.index] === this.setup) this.bones[this.index] = { ...this.setup };
+    this.bones[this.index][channel] = value;
+  }
+
+  get rotation(): number { return this.read('rotation'); }
+  set rotation(v: number) { this.write('rotation', v); }
+  get x(): number { return this.read('x'); }
+  set x(v: number) { this.write('x', v); }
+  get y(): number { return this.read('y'); }
+  set y(v: number) { this.write('y', v); }
+  get scaleX(): number { return this.read('scaleX'); }
+  set scaleX(v: number) { this.write('scaleX', v); }
+  get scaleY(): number { return this.read('scaleY'); }
+  set scaleY(v: number) { this.write('scaleY', v); }
+  get shearX(): number { return this.read('shearX'); }
+  set shearX(v: number) { this.write('shearX', v); }
+  get shearY(): number { return this.read('shearY'); }
+  set shearY(v: number) { this.write('shearY', v); }
+}
+
+/** The adjustment run over a step's `bones` (`posedBones`' array, in the document's order), which it may replace bone by bone (`BoneLocals`). */
+function adjustLocals(doc: CompiledDocument, bones: ModelBone[], adjust: LocalAdjust): void {
+  const views = new Map<string, StepLocals>();
+  const names = doc.bones.map((b) => b.name);
+  adjust({
+    names,
+    bone(name: string): BoneLocals {
+      let view = views.get(name);
+      if (view === undefined) {
+        const index = names.indexOf(name);
+        if (index < 0) throw new CoreInputError(`the adjustment asked for bone ${JSON.stringify(name)}, which is not one of this document's bones`);
+        // A copy the timelines made is this step's own; the setup bone is the document's, copied on its first write.
+        view = new StepLocals(bones, index, doc.bones[index]);
+        views.set(name, view);
+      }
+      return view;
+    },
+  });
+}
+
 const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v);
 
 /**
@@ -778,6 +880,21 @@ export function posedSlots(
   return { rows, conflicts };
 }
 
+/**
+ * One step of the stepped phase, as a walk hands it to the bones: the physics
+ * context and the clock before the step (`./constraints_physics.ts`), and the
+ * caller's adjustment of the locals (`LocalAdjust`). The adjustment rides here
+ * rather than on the plant because it is not a rule the core measured and a
+ * control plants back — it is the caller's input to one walk — and because
+ * the step context exists exactly where a walk is stepped: the live track's
+ * every pose but a `reset: 'setup'` pose 0, which no animation is applied to.
+ */
+export interface PoseStep {
+  ctx: PhysicsStepContext;
+  before: number;
+  adjust?: LocalAdjust;
+}
+
 /**
  * The bone rows at `t`, in the oracle's shape and rounding. With `constraints`
  * — the animation's constraint timelines — the document's constraints are
@@ -792,7 +909,7 @@ export function posedBoneRows(doc: CompiledDocument, timelines: CoreAnimationTim
 }
 
 /** `posedBoneRows`, with the world transforms the rows were read off — what the sample's attachments are posed through. */
-export function posedBoneWorld(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant = {}, constraints?: CoreConstraintTimelines, sliders?: SliderApplication[], step?: { ctx: PhysicsStepContext; before: number }): { rows: CoreBoneRow[]; world: Map<string, CoreWorld> } {
+export function posedBoneWorld(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant = {}, constraints?: CoreConstraintTimelines, sliders?: SliderApplication[], step?: PoseStep): { rows: CoreBoneRow[]; world: Map<string, CoreWorld> } {
   const posed = posedBoneStep(doc, timelines, t, plant, constraints, sliders, step);
   return { rows: stepRows(posed), world: posed.world };
 }
@@ -804,7 +921,7 @@ export function posedBoneWorld(doc: CompiledDocument, timelines: CoreAnimationTi
  * no row, so the scan's walk (`scanWalkIn` in `./raw.ts`, A10's) asks for
  * this; the raw entry's walk still forms the rows it does not read, unchanged.
  */
-export function posedBoneWorldAlone(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: { ctx: PhysicsStepContext; before: number } | undefined): Map<string, CoreWorld> {
+export function posedBoneWorldAlone(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): Map<string, CoreWorld> {
   return posedBoneStep(doc, timelines, t, plant, constraints, sliders, step).world;
 }
 
@@ -835,9 +952,11 @@ function stepRows(posed: PosedStep): CoreBoneRow[] {
 }
 
 /** `posedBoneWorld` up to its rows, refusing a bone the evaluator gave no transform (`PosedStep`). */
-function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: { ctx: PhysicsStepContext; before: number } | undefined): PosedStep {
+function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines, t: number, plant: TimelinePlant, constraints: CoreConstraintTimelines | undefined, sliders: SliderApplication[] | undefined, step: PoseStep | undefined): PosedStep {
   const active = activeBones(doc);
   const bones = posedBones(doc, timelines, t, plant);
+  // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
+  if (step?.adjust !== undefined) adjustLocals(doc, bones, step.adjust);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   if (constraints !== undefined && step !== undefined) {
     // One step of the stepped phase (issue #956, `./constraints_physics.ts`): the physics records posed by their timelines and stepped under the walk's context; the deformed curve a path walks as above. No previous pass: under the step it is the previous step's, and `poseAnimations` leaves such bones out.

package/src/core/entry.ts

@@ -26,7 +26,7 @@ export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setup
 export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } from './track.ts';
-export type { LiveTrack, TrackOptions } from './track.ts';
+export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust } from './track.ts';
 export type { WalkPose } from './walk.ts';
 export { documentPageLookup, drawnRegions, regionPageUvs, meshPageUvs, readUvSequences } from './uvs.ts';
 export type { DrawnRegion, UvPage, UvRegion, UvSource } from './uvs.ts';

package/src/core/raw.ts

@@ -114,7 +114,7 @@
  * missing would draw a different picture in silence.
  */
 import { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
-import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type TimelinePlant } from './animation.ts';
+import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type LocalAdjust, type TimelinePlant } from './animation.ts';
 import { constraintsAbsentWhy, pathAnimationsWhy } from './constraints.ts';
 import { freshStepContext, steppedPreviousPassWhy } from './constraints_physics.ts';
 import { attachmentStates } from './deform.ts';
@@ -612,6 +612,8 @@ export interface TrackState<P> {
   readonly resolve: NonNullable<TimelinePlant['shown']>;
   readonly shape: PoseShape<P>;
   readonly ctx: ReturnType<typeof freshStepContext>;
+  /** The caller's adjustment of each step's locals (`LocalAdjust` in `./animation.ts`): the live track's `adjust`, absent on every batch walk. */
+  readonly adjust?: LocalAdjust;
   /** The running sum of the steps taken. */
   trackTime: number;
   /** The animation time of the step before, −1 before the first. */
@@ -631,12 +633,12 @@ function animationOf(doc: CompiledDocument, animation: string): CompiledDocument
  * `reset: 'setup'` pose 0 is the setup pose, reset; under `animation` it is the
  * animation applied at 0 and reset there, a step of 0 (`stepWalk`'s `first`).
  */
-function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations'][number], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>): { track: TrackState<P>; first: P } {
+function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations'][number], plant: TimelinePlant, reset: RawReset, mode: WalkMode, shape: PoseShape<P>, adjust?: LocalAdjust): { track: TrackState<P>; first: P } {
   const why = constraintsAbsentWhy(doc) ?? pathAnimationsWhy(doc) ?? steppedPreviousPassWhy(doc);
   if (why !== null) throw new CoreInputError(`the raw walk leaves the bones out: ${why}`);
   const ctx = freshStepContext(plant.physicsStep);
   if (mode.loop && mode.wrapResets !== false) ctx.loop = true;
-  const track: TrackState<P> = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, trackTime: 0, last: -1 };
+  const track: TrackState<P> = { doc, anim, duration: anim.timelines.duration, mode, plant, raw: { ...plant, ...roundPlant(mode) }, resolve: plant.shown ?? shownAttachment, shape, ctx, adjust, trackTime: 0, last: -1 };
   if (reset === 'setup') {
     // The reset taken at the setup pose, before the animation is applied (`src/deformmeasure.ts`'s `poseAt`): pose 0 is the setup pose.
     const setup = poseSetup(doc, { ...plant, ...roundPlant(mode) }, ctx);
@@ -657,7 +659,7 @@ function openWalk<P>(doc: CompiledDocument, anim: CompiledDocument['animations']
  * resets the physics there — and nothing else passes it.
  */
 function stepWalk<P>(track: TrackState<P>, dt: number, first = false): P {
-  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx } = track;
+  const { doc, anim, duration, mode, plant, raw, resolve, shape, ctx, adjust } = track;
   track.trackTime += dt;
   const trackTime = track.trackTime;
   const last = track.last;
@@ -665,7 +667,7 @@ function stepWalk<P>(track: TrackState<P>, dt: number, first = false): P {
   const before = ctx.time;
   ctx.time += mode.clock === undefined ? dt : mode.clock(dt, t - (first ? 0 : Math.max(last, 0)));
   const sliders: SliderApplication[] = [];
-  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before });
+  const world = shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjust });
   if (first) ctx.phase = 'update';
   const placeholders = new Map<string, string | null>();
   const slots = posedSlots(doc, anim.timelines, t, raw, sliders, placeholders);
@@ -706,8 +708,8 @@ function walkEach<P>(doc: CompiledDocument, animation: string, steps: readonly n
  * `stepRawTrack` steps. Every pose is assembled as the raw entry's
  * (`RAW_SHAPE`).
  */
-export function openRawTrack(doc: CompiledDocument, animation: string, plant: TimelinePlant, reset: RawReset, mode: WalkMode): { track: TrackState<RawPose>; first: RawPose } {
-  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE);
+export function openRawTrack(doc: CompiledDocument, animation: string, plant: TimelinePlant, reset: RawReset, mode: WalkMode, adjust?: LocalAdjust): { track: TrackState<RawPose>; first: RawPose } {
+  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust);
 }
 
 /** One step of an opened raw track (`openRawTrack`): `walkIn`'s step, the step itself checked by the caller. */

package/src/core/track.ts

@@ -95,6 +95,41 @@
  * and the events (4,009 of 4,009 on the tree row, 690 of them cutting 12,420
  * rows).
  *
+ * ## The adjustment (issue #1336)
+ *
+ * `adjust` is a player's own bone-local value — a breath's scale, a look's
+ * rotation — written onto the bones every pose, after the animation's
+ * timelines posed the locals at the step's time and before the world
+ * transforms, the constraints and the physics step (`LocalAdjust` in
+ * `./animation.ts`, which states the view's rules). It runs on every pose the
+ * animation is applied to — every `step`, and pose 0 under `reset:
+ * 'animation'` — and not on pose 0 under `reset: 'setup'`, the setup pose
+ * with nothing applied: a player applies its adjustment wherever it applies
+ * the animation state, the first frame included, and spine-core's reset at
+ * the setup pose applies none. Absent, every pose is the one the track posed
+ * before it existed, bit for bit (`CO46`, unchanged; `CO50` holds a hook that
+ * writes nothing to the same bits).
+ *
+ * `CO50` holds it to spine-core 4.3.13 on gallery/look, whose `head` carries
+ * the deformed head mesh and every face bone, and the physics-driven
+ * `ahoge_whip` two bones below it: the same `scaleY` written on `head` by the
+ * core's hook and on `Bone.pose` between `AnimationState.apply` and
+ * `updateWorldTransform(Physics.update)`, every bone's world transform and
+ * every drawn vertex equal at tolerance 0 over looping and held walks under
+ * both resets — spine-core's skeleton brought back to the setup pose
+ * (`setupPoseBones`) before each `apply`, which is the core's own reading:
+ * every pose is posed from the setup pose. Measured, and held red there:
+ *
+ * - **The write carried from frame to frame** — spine-core without that
+ *   reset, where no timeline writes an unkeyed channel back, so a `scaleY`
+ *   multiplied every frame compounds (every walk off from pose 2). The core
+ *   carries no local from one step to the next; a value a player wants
+ *   carried it keeps and writes again.
+ * - **The write at draw time** — made after `updateWorldTransform`, the
+ *   bone's own matrix alone brought up to date: the bone moves, its
+ *   children, the meshes they carry and the physics do not.
+ * - **Pose 0 not adjusted** under `reset: 'animation'`.
+ *
  * ## The oracle chain
  *
  * Nothing here is held to spine-core directly but the events: the live track
@@ -106,19 +141,22 @@
  *
  * ⛔ **A track refused part-way stays refused.** A step is checked before
  * anything moves; a refusal past that — a construct the core leaves out, a
- * non-finite vertex — comes after the track time and the physics have moved,
- * so every later `step` refuses naming the step it was refused at, and the
- * caller opens the track again. Seeking is the caller's too: a physics rig has
+ * non-finite vertex or write — comes after the track time and the physics
+ * have moved, so every later `step` refuses naming the step it was refused
+ * at, and the caller opens the track again. So does an error the caller's own
+ * `adjust` throws: it is thrown mid-step, after the same moves. Seeking is the caller's too: a physics rig has
  * history, so a seek is "open, then step to the time".
  */
 import { CoreInputError, type CompiledDocument } from './index.ts';
 import { openRawTrack, stepRawTrack, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.ts';
-import type { TimelinePlant } from './animation.ts';
+import type { LocalAdjust, TimelinePlant } from './animation.ts';
+export type { AdjustableLocals, BoneLocals, LocalAdjust } from './animation.ts';
 
-/** How a live track is opened: whether it loops, and where its physics is reset (`RawReset`). Both are the caller's and neither has a default. */
+/** How a live track is opened: whether it loops, and where its physics is reset (`RawReset`) — both the caller's, neither with a default — and the caller's adjustment of every pose's bone locals (the header's *The adjustment*). */
 export interface TrackOptions {
   loop: boolean;
   reset: RawReset;
+  adjust?: LocalAdjust;
 }
 
 /** A live track (`openTrack`): pose 0, then one pose per `step`. */
@@ -147,7 +185,8 @@ const LOOPED: WalkMode = { loop: true, keep: false, live: true };
 export function openTrack(doc: CompiledDocument, animation: string, options: TrackOptions, plant: TimelinePlant = {}): LiveTrack {
   if (typeof options !== 'object' || options === null || typeof options.loop !== 'boolean') throw new CoreInputError(`the live track's options.loop is ${JSON.stringify((options as Partial<TrackOptions> | null)?.loop)}, not true or false`);
   if (options.reset !== 'animation' && options.reset !== 'setup') throw new CoreInputError(`the live track's options.reset is ${JSON.stringify(options.reset)}, not "animation" or "setup"`);
-  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD);
+  if (options.adjust !== undefined && typeof options.adjust !== 'function') throw new CoreInputError(`the live track's options.adjust is ${typeof options.adjust}, not a function`);
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, options.loop ? LOOPED : HELD, options.adjust);
   return new Track(track, first);
 }
 
@@ -186,7 +225,7 @@ class Track implements LiveTrack {
       this.latest = pose.animationTime;
       return pose;
     } catch (err) {
-      if (err instanceof CoreInputError) this.refused = `${n} (${err.message})`;
+      this.refused = `${n} (${err instanceof Error ? err.message : String(err)})`;
       throw err;
     }
   }