spine-rigc 2.48.0 → 2.49.0

package/docs/AUTHORING.md

@@ -4927,8 +4927,15 @@ that poses through its posers (`check`, `bonedist`, `inspect`, `--geometry`), ru
 the physics clock `2⁻³⁰` faster than the frames, so every such frame takes the steps
 exact arithmetic takes; the animation time is unchanged. A spring that has converged
 by the loop point therefore closes, which the loop-seam suite's `LS06` holds at all
-five rates. A player with a real clock is a different question and rigc does not
-answer it.
+five rates. A player that steps the core entry's live tracks at a fixed rate — a
+capture, an export, a test harness — is the render's case and takes the render's
+clock: `openTrack` and `openTracks` accept `clock`, what each step moves the physics
+clock by, and `physicsClockStep` (with `PHYSICS_CLOCK_LEAD`) is exported from
+`rig-c/core` to pass to it (issue #1396). It moves the physics alone — the track
+time, the animation time and the events stay on the steps, so the player keeps
+agreeing with `render` — and left out, a track steps the physics by the step itself,
+exactly as before. Which clock a player with a real clock uses is the player's
+question, and rigc does not answer it.
 
 `mix` is a player-side `AnimationStateData` config and is **not** emitted into
 skeleton JSON, so the parser is the only check it gets: it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.48.0",
+  "version": "2.49.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/entry.ts

@@ -17,13 +17,14 @@
  *
  * ⚠️ A symbol is listed here only because a dependant was seen using it,
  * or asked for it in writing before it could be (`openTrack`, issue #1276;
- * `openTracks`, issue #1336).
+ * `openTracks`, issue #1336; `physicsClockStep` and `PHYSICS_CLOCK_LEAD`,
+ * the clock a live track's `clock` option takes, issue #1396).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
 export { readModel, underSkin, underNoSkin, CoreInputError, CORE_DOCUMENT_SPEC, CORE_DOCUMENT_SPECS, CORE_BLEND_MODES, activeBones } from './index.ts';
 export type { CompiledDocument, CoreSlotRow, CoreBlendMode } from './index.ts';
-export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setupBounds } from './raw.ts';
+export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setupBounds, physicsClockStep, PHYSICS_CLOCK_LEAD } from './raw.ts';
 export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } from './track.ts';

package/src/core/raw.ts

@@ -257,7 +257,7 @@ export interface WalkMode {
   keep: boolean;
   /** A plant only (the core suite's `CO26`): the animation time a looping step applies at, from its track time, the duration and the track time before it — `loopedTime` unless given. */
   time?: (trackTime: number, duration: number, before: number) => number;
-  /** What the physics clock moves by, from the step and how far the animation time moved — the step itself unless given: a plant (`CO26`), or the render's offline clock passed to `poseRawAnimationEach` (issue #1380). */
+  /** What the physics clock moves by, from the step and how far the animation time moved — the step itself unless given: a plant (`CO26`), the render's offline clock passed to `poseRawAnimationEach` (issue #1380), or a live track's `clock` option (`./track.ts`, issue #1396). */
   clock?: (dt: number, moved: number) => number;
   /** A plant only (`CO26`): `false` fires no `reset` key across the wrap — the reading the walk was measured against and rejected. */
   wrapResets?: boolean;
@@ -561,6 +561,20 @@ export function physicsClockStep(step: number): number {
   return step + step * PHYSICS_CLOCK_LEAD;
 }
 
+/**
+ * A live track's `clock` option (issue #1396, `./track.ts` and `./tracks.ts`):
+ * the caller's function, called with each step, its answer checked before the
+ * skeleton's clock moves by it — a finite time at or above 0, or the step
+ * refused by name, as a step itself is. `who` names the track in the refusal.
+ */
+export function checkedClock(clock: (dt: number) => number, who: string): (dt: number) => number {
+  return (dt) => {
+    const moved = clock(dt);
+    if (typeof moved !== 'number' || !Number.isFinite(moved) || moved < 0) throw new CoreInputError(`${who} clock moved the physics by ${String(moved)} for a step of ${dt}, not a finite time at or above 0`);
+    return moved;
+  };
+}
+
 /**
  * The animation time a looping track applies its animation at (`./walk.ts`,
  * *The time*): the track time wrapped by the duration, and 0 over a duration

package/src/core/track.ts

@@ -26,7 +26,8 @@
  *
  * - **Held** (`loop: false`): the raw entry's walk — the track time the
  *   running sum of the steps, the animation time held at the duration, the
- *   physics clock moved by the step, events over `(previous animation time,
+ *   physics clock moved by the step (or by `clock`, *The physics clock*
+ *   below), events over `(previous animation time,
  *   animation time]` (`./raw.ts`, *One step*). `CO46` holds it to
  *   `poseRawAnimation` pose for pose, every field, bit for bit.
  * - **Looped** (`loop: true`): A10's looping walk's time, clock and `reset`
@@ -135,6 +136,44 @@
  *   children, the meshes they carry and the physics do not.
  * - **Pose 0 not adjusted** under `reset: 'animation'`.
  *
+ * ## The physics clock (issue #1396)
+ *
+ * `clock` is what each step moves the skeleton's physics clock by — the time
+ * a physics constraint integrates — with `poseRawAnimationEach`'s meaning.
+ * Absent, it is the step itself, and every pose is the one the track posed
+ * before the option existed (`CO46`–`CO50`, unchanged). `physicsClockStep` is
+ * the render's clock (issue #1380), for a player stepping at a fixed rate.
+ * The track time, the animation time, the wrap, the events and `trackTime`
+ * stay on the running sum of the steps: the clock moves the physics and
+ * nothing else.
+ *
+ * - **Why the track takes it.** Stepped at a fixed rate whose frame lasts a
+ *   whole number of physics steps, a spring shows the render's defect. On the
+ *   public trailer's `show`, read with play#103's detector, the frame clock
+ *   adds outlier poses 5, 11–13, 44–45 and 187–189 at a fixed 1/20 and 8,
+ *   15–17, 31–33 and 505–507 at 1/60, and `clock: physicsClockStep` removes
+ *   every one (the PR of issue #1396 carries the table). A player scaling its
+ *   own `dt` instead moves the animation time too: a key at 0.5 s fires on
+ *   the tenth step of 1/20 where the render and the runtime fire it on the
+ *   eleventh, and the player stops agreeing with `rigc render`.
+ * - **The reset.** Pose 0 under `reset: 'animation'` is a step of 0 and moves
+ *   the clock by `clock(0)`, as the render's walk does — 0 for
+ *   `physicsClockStep`; under `setup` nothing is stepped. A physics `reset`
+ *   key restarts a constraint's time from the clock as it stands, so it is
+ *   read on the same clock as every other step.
+ * - **The seek** stays the caller's — open, then step to the time — and its
+ *   steps go through the same clock, so a seek's physics is the physics of
+ *   the steps it took.
+ * - **A clock that returns no time** — not finite, or below 0 — refuses the
+ *   step by name after the track time has moved, so the track stays refused.
+ *
+ * `CO53` holds the mechanism on LS05's spring probe (every constraint update
+ * takes the steps exact arithmetic takes; the frame clock is red), `CO54` the
+ * poses (equal to the render's walk, to `poseRawAnimationEach` on the same
+ * clock, between the two live entries, and to spine-core with its
+ * `AnimationState` updated by the step and its `Skeleton` by the clock), and
+ * `CO55` that the times and the events are those of the walk without it.
+ *
  * ## The oracle chain
  *
  * Nothing here is held to spine-core directly but the events: the live track
@@ -153,15 +192,17 @@
  * 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 { checkedClock, openRawTrack, stepRawTrack, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.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 the caller's, neither with a default — and the caller's adjustment of every pose's bone locals (the header's *The adjustment*). */
+/** How a live track is opened: whether it loops, and where its physics is reset (`RawReset`) — both the caller's, neither with a default — the caller's adjustment of every pose's bone locals (the header's *The adjustment*), and what each step moves the physics clock by (the header's *The physics clock*). */
 export interface TrackOptions {
   loop: boolean;
   reset: RawReset;
   adjust?: LocalAdjust;
+  /** What each step of `dt` moves the skeleton's physics clock by — `physicsClockStep` is the render's; absent, the step itself. The track time, the animation time and the events stay on the running sum of the steps. */
+  clock?: (dt: number) => number;
 }
 
 /** A live track (`openTrack`): pose 0, then one pose per `step`. */
@@ -191,7 +232,10 @@ export function openTrack(doc: CompiledDocument, animation: string, options: Tra
   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"`);
   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);
+  if (options.clock !== undefined && typeof options.clock !== 'function') throw new CoreInputError(`the live track's options.clock is ${typeof options.clock}, not a function`);
+  const mode = options.loop ? LOOPED : HELD;
+  const clock = options.clock === undefined ? undefined : checkedClock(options.clock, 'the live track\'s');
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, clock === undefined ? mode : { ...mode, clock: (dt) => clock(dt) }, options.adjust);
   return new Track(track, first);
 }
 

package/src/core/tracks.ts

@@ -73,7 +73,12 @@
  *   out fires none** — not "until the mix passes half way": `eventThreshold`
  *   defaults to 0 and an entry's events are applied only while `mix <
  *   eventThreshold`, which no mix is. `complete` is not carried (issue #1276).
- * - **Physics** steps on top of the mixed locals, as on one track.
+ * - **Physics** steps on top of the mixed locals, as on one track — and on
+ *   the same clock: `TracksOptions.clock`, what each step moves the physics
+ *   clock by, has the single track's meaning (`./track.ts`, *The physics
+ *   clock*, issue #1396). The entries' track times, the mixes, the queue and
+ *   the events stay on the steps; `start()` under `reset: 'animation'` moves
+ *   the clock by `clock(0)`.
  *
  * `CO51` holds all of it to spine-core 4.3.13 at tolerance 0 — every bone's
  * world transform, every drawn attachment's world vertices, every slot's
@@ -159,13 +164,15 @@ import { activeBones, CoreInputError, rawNumber, readColour, shownAttachment, ty
 import { channelAt, keyIndexAt, SLOT_COLOUR_TIMELINES, slotRowsFrom, steppedLocalsWorld, type BoneTimelineKind, type CoreKey, type LocalAdjust, type SlotBase, type SlotColourKind, type TimelinePlant } from './animation.ts';
 import { deformAt, setupArray, type CoreAttachmentTimeline } from './deform.ts';
 import { eventsFired, type CoreEventKey, type CoreEventRow } from './events.ts';
-import { openRawTracksPath, type RawPose, type RawReset, type RawTracksPath } from './raw.ts';
+import { checkedClock, openRawTracksPath, type RawPose, type RawReset, type RawTracksPath } from './raw.ts';
 import { slotTimelinesApply } from './skins.ts';
 
-/** How the live tracks are opened: where the physics is reset (`RawReset`, the caller's, no default) and the caller's adjustment of every pose's bone locals. */
+/** How the live tracks are opened: where the physics is reset (`RawReset`, the caller's, no default), the caller's adjustment of every pose's bone locals, and what each step moves the physics clock by (the header's *The physics clock*). */
 export interface TracksOptions {
   reset: RawReset;
   adjust?: LocalAdjust;
+  /** What each step of `dt` moves the skeleton's physics clock by — `physicsClockStep` is the render's; absent, the step itself. Every entry's track time, the mixes, the queue and the events stay on the steps. */
+  clock?: (dt: number) => number;
 }
 
 /**
@@ -1299,7 +1306,9 @@ function delayOf(v: number, call: string): number {
 export function openTracks(doc: CompiledDocument, options: TracksOptions, plant: TracksPlant = {}): LiveTracks {
   if (typeof options !== 'object' || options === null || (options.reset !== 'animation' && options.reset !== 'setup')) throw new CoreInputError(`the live tracks' options.reset is ${JSON.stringify((options as Partial<TracksOptions> | null)?.reset)}, not "animation" or "setup"`);
   if (options.adjust !== undefined && typeof options.adjust !== 'function') throw new CoreInputError(`the live tracks' options.adjust is ${typeof options.adjust}, not a function`);
-  return new Tracks(doc, options.reset, options.adjust, plant, openRawTracksPath(doc, plant));
+  if (options.clock !== undefined && typeof options.clock !== 'function') throw new CoreInputError(`the live tracks' options.clock is ${typeof options.clock}, not a function`);
+  const clock = options.clock === undefined ? undefined : checkedClock(options.clock, 'the live tracks\'');
+  return new Tracks(doc, options.reset, options.adjust, clock, plant, openRawTracksPath(doc, plant));
 }
 
 class Tracks implements LiveTracks {
@@ -1313,6 +1322,7 @@ class Tracks implements LiveTracks {
     private readonly doc: CompiledDocument,
     private readonly reset: RawReset,
     private readonly adjust: LocalAdjust | undefined,
+    private readonly clock: ((dt: number) => number) | undefined,
     private readonly plant: TracksPlant,
     private readonly path: RawTracksPath,
   ) {
@@ -1426,7 +1436,7 @@ class Tracks implements LiveTracks {
     const { doc, path } = this;
     const ctx = path.ctx;
     const before = ctx.time;
-    ctx.time += dt;
+    ctx.time += this.clock === undefined ? dt : this.clock(dt);
     const pose = new Pose(doc, this.plant);
     const animationTime = this.mixer.apply(pose);
     const mixed = new Map(doc.slots.map((s, k) => [s.name, { deform: pose.slots[k].deform, seen: pose.slots[k].seen }]));