@rig-c/core 2.66.0 → 2.67.0

package/docs/AUTHORING.md

@@ -5381,6 +5381,39 @@ agreeing with `render` — and left out, a track steps the physics by the step i
 exactly as before. Which clock a player with a real clock uses is the player's
 question, and rigc does not answer it.
 
+A player's `adjust` option on `openTrack` or `openTracks` receives
+`(locals, ctx)` (issue #1540). `LocalAdjustContext`, `LocalAdjust`,
+`AdjustableLocals` and `BoneLocals` are types promised through `rig-c/core`.
+The callback runs once per evaluated pose **after all track composition**,
+before world transforms, constraints and physics. A crossfade does not call it
+for the outgoing entry as well. Existing unary callbacks keep the same writes,
+pose bytes and call schedule.
+
+- `ctx.trackTime: number | null` is the **current track-0 entry's** unwrapped
+  seconds from its own start. Loops do not wrap it; a held animation clamps its
+  sampling time while this entry clock continues. Replacing the entry starts its
+  clock at 0 even at a nonzero global time. A queued switch preserves the
+  remainder the mixer has already advanced into its new entry.
+- `ctx.animation: string | null` names that **same entry**. With no current
+  track-0 entry, both fields are null, even if an upper track plays. An explicit
+  empty entry has a null animation name and its own numeric entry time until
+  removed, matching `current(0)`.
+- `ctx.globalTime: number` is the running sum of this walk's steps, in seconds.
+  On a single track it equals the entry time. It is separate from entry time in
+  a composition, and is never substituted for an absent track-0 time. Neither
+  time includes the optional physics clock's lead.
+
+With `reset: 'animation'` the initial pose calls the hook at 0;
+`reset: 'setup'` leaves its initial setup pose unadjusted. Every explicit
+`step(0)` still evaluates a pose. This API adds no seek or cache: a caller may
+reuse a cached pose without asking the core to evaluate it again. Time-dependent
+adjustments replay exactly with the **same reset, environment and step
+partition**; arbitrary physics histories are not interchangeable. A callback
+closing over mutable external state still needs its caller's cache invalidated.
+For example, `adjust: (locals, ctx) => { locals.bone('dial').rotation =
+30 * (ctx.trackTime ?? 0); }` explicitly chooses a value when there is no base
+entry; the core supplies null rather than inventing that choice.
+
 🌬️ **`wind` and `gravity` are the constraint's response; the world is the
 consumer's** (issue #1416). In 4.3 the two are not forces but how strongly the
 constraint answers two directions the *skeleton* carries — `Skeleton.windX,
@@ -5420,6 +5453,47 @@ skeleton's units and axes, and its change of rotation as `physicsRotate(0, 0,
 Δ)`, before the `step` that poses the frame. Nothing set, every pose is the
 one the track posed before these existed (`CO57`).
 
+For a live preview of one named constraint (issue #1541), both `LiveTrack` and
+`LiveTracks` on `rig-c/core` expose:
+
+```ts
+track.setPhysicsParameters('spring', { damping: 0.3, wind: 2 });
+const { override, effective } = track.readPhysicsParameters('spring');
+track.clearPhysicsParameters('spring');
+```
+
+`PhysicsParameters` has exactly six numeric fields: `strength`, `damping`,
+`inertia`, `wind`, `gravity`, `mix`. `PhysicsParameterPatch` is a partial set of
+them; setting merges with the instance's existing patch, omitted fields keep
+their overrides, and an empty patch does nothing. Finite numbers are accepted
+without clamping or unit conversion. The patch applies after the authored,
+keyed and slider values, immediately before that active constraint's integrator.
+It persists across poses, loops and composed-entry replacement or mixing out to
+nothing, until `clearPhysicsParameters(name)` removes the whole named patch.
+No document, another instance, or another named constraint is changed.
+
+`PhysicsParameterRead` contains detached snapshots: `override` is the patch
+currently in force, or `null`; `effective` is the exact six values last passed
+to that constraint's step, or `null` when it has never been evaluated. In
+particular composed tracks before `start()` and inactive constraints have no
+evaluated values. Returning resolved setup defaults there would invent a pose:
+the parser has read them, but the integrator has not used them. A single track
+evaluates pose 0 when opened, including under `reset: 'setup'`. Setting or
+clearing changes `override` immediately, while `effective` keeps describing the
+previous evaluation until the next pose. No reset or fake evaluation is done to
+fill a readout. Values omitted by the author come from the existing resolved
+records; this API defines no second default table.
+
+Clear resumes whatever authored, keyed and slider values the next pose supplies,
+and retains the clock, offsets, velocities and remaining integration time. It
+does not undo motion or promise transforms equal to an untouched trajectory.
+An unknown constraint name, a name of another kind, an unknown field (including
+`mass`), or a non-finite/non-number field throws a named `CoreInputError` before
+any part of the patch changes. Set/read/clear name errors list the relevant
+name; field errors also name the field and required finite value or allowed
+field set. The composed tracks' existing refusal of animation constraint
+timelines is unchanged; this API adds no timeline mixing or solver behavior.
+
 `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
 `{ "default": <seconds>, "pairs"?: [["<from>", "<to>", <seconds>], …] }`, and a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.66.0",
+  "version": "2.67.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

@@ -747,8 +747,18 @@ export interface AdjustableLocals {
   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 pose being adjusted (issue #1540), independent of the physics clock. */
+export interface LocalAdjustContext {
+  /** Current track-0 entry's unwrapped seconds, starting at 0; null without that entry. */
+  readonly trackTime: number | null;
+  /** That same entry's animation name; null without it or for an explicit empty entry. */
+  readonly animation: string | null;
+  /** Running sum of this walk's steps, in seconds; never the physics clock. */
+  readonly globalTime: number;
+}
+
+/** Called once per evaluated pose, after track composition and before world transforms and physics. Unary callbacks remain assignable. */
+export type LocalAdjust = (locals: AdjustableLocals, ctx: LocalAdjustContext) => 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;
@@ -789,7 +799,7 @@ class StepLocals implements BoneLocals {
 }
 
 /** 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 {
+function adjustLocals(doc: CompiledDocument, bones: ModelBone[], adjust: LocalAdjust, context: LocalAdjustContext): void {
   const views = new Map<string, StepLocals>();
   const names = doc.bones.map((b) => b.name);
   adjust({
@@ -805,7 +815,7 @@ function adjustLocals(doc: CompiledDocument, bones: ModelBone[], adjust: LocalAd
       }
       return view;
     },
-  });
+  }, context);
 }
 
 const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v);
@@ -925,7 +935,8 @@ export function slotRowsFrom(
 export interface PoseStep {
   ctx: PhysicsStepContext;
   before: number;
-  adjust?: LocalAdjust;
+  /** Callback and its authoritative evaluation identity travel together; no inferred clock fallback. */
+  adjustment?: { callback: LocalAdjust; context: LocalAdjustContext };
 }
 
 /**
@@ -991,7 +1002,7 @@ function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines,
   if (constraints !== undefined && step !== undefined) return steppedLocals(doc, bones, plant, () => pathDeformed(doc, posedRecords(constraintRecords(doc), constraints, t), timelines, t, plant), constraints.physicsKeyed ?? [], t, sliders, step);
   const active = activeBones(doc);
   // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
-  if (step?.adjust !== undefined) adjustLocals(doc, bones, step.adjust);
+  if (step?.adjustment !== undefined) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   if (constraints !== undefined) {
     const setupRecords = constraintRecords(doc);
@@ -1018,7 +1029,7 @@ function posedBoneStep(doc: CompiledDocument, timelines: CoreAnimationTimelines,
 function steppedLocals(doc: CompiledDocument, bones: ModelBone[], plant: TimelinePlant, records: () => CoreConstraintRecord[], physicsKeyed: NonNullable<CoreConstraintTimelines['physicsKeyed']>, t: number, sliders: SliderApplication[] | undefined, step: PoseStep): PosedStep {
   const active = activeBones(doc);
   // The caller's adjustment, after the timelines and before anything reads the locals (`LocalAdjust`).
-  if (step.adjust !== undefined) adjustLocals(doc, bones, step.adjust);
+  if (step.adjustment !== undefined) adjustLocals(doc, bones, step.adjustment.callback, step.adjustment.context);
   let world = (plant.evaluate ?? worldTransforms)(bones, active);
   const stepped = stepPhysicsRecords(records(), physicsKeyed, t, active, step.ctx, step.before);
   world = applyConstraints(bones, world, active, plant.constraints ? plant.constraints(stepped) : stepped, null, sliders, step.ctx, undefined, solverRules(plant.solver));

package/src/core/constraints.ts

@@ -1548,7 +1548,8 @@ export function applyConstraints(bones: readonly ModelBone[], world: ReadonlyMap
       // Under Physics.none a physics constraint applies nothing; stepped, it moves its bone in world space (`./constraints_physics.ts`).
       if (physics !== undefined) {
         const w = { ...(state.world.get(c.bone) as CoreWorld) };
-        const posed = physicsPose?.records.get(c.name) ?? c;
+        const authored = physicsPose?.records.get(c.name) ?? c;
+        const posed = physics.parameters?.apply(authored) ?? authored;
         if ((physics.step ?? stepPhysics)(posed, w, bone(state, c.bone).length ?? 0, physics)) {
           state.world.set(c.bone, w);
           changed = [c.bone];

package/src/core/constraints_physics.ts

@@ -583,6 +583,8 @@ export type PhysicsStepper = (r: CorePhysicsRecord, w: CoreWorld, length: number
 /** What a stepped pose carries into every physics constraint it applies. */
 export interface PhysicsStepContext {
   phase: PhysicsPhase;
+  /** Live track's final parameter layer, after authored/keyed/slider values (issue #1541). */
+  parameters?: { apply(record: CorePhysicsRecord): CorePhysicsRecord };
   /** The skeleton's clock: the sum of every step's delta so far. */
   time: number;
   /** Each constraint's state, by name, carried from update to update. */

package/src/core/entry.ts

@@ -25,7 +25,9 @@
  * own evaluation rather than to a mirror of it, issue #1417 — re-exported,
  * never copied, because a copy is the drift the request exists to remove;
  * `CA12` holds the identity; `readSetupMesh`, issue #1538, the named setup
- * geometry read requested by the player, with `SetupMesh` and `SetupMeshTarget`).
+ * geometry read requested by the player, with `SetupMesh` and `SetupMeshTarget`;
+ * `PhysicsParameters`, `PhysicsParameterPatch`, `PhysicsParameterRead`, the live
+ * named constraint overrides requested on issue #1541).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
@@ -35,7 +37,8 @@ export { readSetupMesh, poseRawSetup, poseRawAnimation, poseRawAnimationEach, lo
 export type { SetupMesh, SetupMeshTarget, 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, AdjustableLocals, BoneLocals, LocalAdjust, PhysicsEnvironment } from './track.ts';
+export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust, LocalAdjustContext, PhysicsEnvironment } from './track.ts';
+export type { PhysicsParameters, PhysicsParameterPatch, PhysicsParameterRead } from './physics_parameters.ts';
 export { openTracks } from './tracks.ts';
 export type { LiveTracks, TracksOptions, MixOptions, QueueOptions, TrackEntryView } from './tracks.ts';
 export type { WalkPose } from './walk.ts';

package/src/core/physics_parameters.ts

@@ -0,0 +1,72 @@
+/** Live, per-instance parameter patches (issue #1541). No model writes or history resets. */
+import { CoreInputError, type CompiledDocument } from './index.ts';
+import type { CorePhysicsRecord } from './constraints_physics.ts';
+
+/** The six scalar responses a consumer can override; no units or range conversion. */
+export interface PhysicsParameters {
+  readonly strength: number;
+  readonly damping: number;
+  readonly inertia: number;
+  readonly wind: number;
+  readonly gravity: number;
+  readonly mix: number;
+}
+/** Omitted fields keep their existing override, if any. */
+export type PhysicsParameterPatch = Partial<PhysicsParameters>;
+/** Detached snapshots. `effective` is null until this constraint has been evaluated. */
+export interface PhysicsParameterRead {
+  readonly override: PhysicsParameterPatch | null;
+  readonly effective: PhysicsParameters | null;
+}
+
+const FIELDS = ['strength', 'damping', 'inertia', 'wind', 'gravity', 'mix'] as const;
+const values = (r: CorePhysicsRecord): PhysicsParameters => ({ strength: r.strength, damping: r.damping, inertia: r.inertia, wind: r.wind, gravity: r.gravity, mix: r.mix });
+
+/** Owned by one live track, including all entries of a composed track. */
+export class LivePhysicsParameters {
+  private readonly overrides = new Map<string, PhysicsParameterPatch>();
+  private readonly evaluated = new Map<string, PhysicsParameters>();
+
+  constructor(private readonly doc: CompiledDocument) {}
+
+  private named(name: string): void {
+    const constraint = this.doc.constraints.find((c) => c.name === name);
+    if (constraint === undefined) throw new CoreInputError(`physics parameters: no constraint "${String(name)}"; this document declares [${this.doc.constraints.map((c) => c.name).join(', ')}]`);
+    if (constraint.kind !== 'physics') throw new CoreInputError(`physics parameters: constraint "${name}" is ${constraint.kind}, not physics`);
+  }
+
+  set(name: string, patch: PhysicsParameterPatch): void {
+    this.named(name);
+    if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) throw new CoreInputError(`physics parameters: constraint "${name}" patch is ${String(patch)}, not an object of finite fields [${FIELDS.join(', ')}]`);
+    const checked: Partial<Record<(typeof FIELDS)[number], number>> = {};
+    // Validate the complete patch before publishing it, including unknown symbol keys.
+    for (const key of Reflect.ownKeys(patch)) {
+      if (typeof key !== 'string' || !(FIELDS as readonly string[]).includes(key)) throw new CoreInputError(`physics parameters: constraint "${name}" field "${String(key)}" is unknown; expected [${FIELDS.join(', ')}]`);
+      const field = key as (typeof FIELDS)[number];
+      const value = patch[field];
+      if (typeof value !== 'number' || !Number.isFinite(value)) throw new CoreInputError(`physics parameters: constraint "${name}" field "${field}" is ${String(value)}, not a finite number`);
+      checked[field] = value;
+    }
+    if (Reflect.ownKeys(checked).length > 0) this.overrides.set(name, { ...this.overrides.get(name), ...checked });
+  }
+
+  read(name: string): PhysicsParameterRead {
+    this.named(name);
+    const patch = this.overrides.get(name);
+    const effective = this.evaluated.get(name);
+    return { override: patch === undefined ? null : { ...patch }, effective: effective === undefined ? null : { ...effective } };
+  }
+
+  clear(name: string): void {
+    this.named(name);
+    this.overrides.delete(name);
+  }
+
+  /** Called only for an active constraint, after the sliders and immediately before its step. */
+  apply(record: CorePhysicsRecord): CorePhysicsRecord {
+    const patch = this.overrides.get(record.name);
+    const posed = patch === undefined ? record : { ...record, ...patch };
+    this.evaluated.set(record.name, values(posed));
+    return posed;
+  }
+}

package/src/core/raw.ts

@@ -906,8 +906,9 @@ function stepWalk<P>(track: TrackState<P>, dt: number, first = false): P {
   // `clipped` rows are empty. The live track's looping mode (`live`) fires its events across the wrap by the rule `./track.ts` states as measured.
   const fire = plant.events ?? eventsFired;
   const keys = anim.timelines.events;
+  const adjustment = adjust === undefined ? undefined : { callback: adjust, context: { trackTime, animation: anim.name, globalTime: trackTime } };
   const pose = poseStepFrom(doc, plant, resolve, shape, mode, ctx, first, trackTime, t, {
-    world: (sliders) => (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 })),
+    world: (sliders) => (shape.rows ? posedBoneWorld(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjustment }).world : posedBoneWorldAlone(doc, anim.timelines, t, raw, anim.constraints, sliders, { ctx, before, adjustment })),
     slots: (sliders, placeholders) => posedSlots(doc, anim.timelines, t, raw, sliders, placeholders),
     drawOrder: anim.timelines.drawOrder,
     at: t,
@@ -1024,8 +1025,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, adjust?: LocalAdjust): { track: TrackState<RawPose>; first: RawPose } {
-  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust);
+export function openRawTrack(doc: CompiledDocument, animation: string, plant: TimelinePlant, reset: RawReset, mode: WalkMode, adjust?: LocalAdjust, before?: (ctx: PhysicsStepContext) => void): { track: TrackState<RawPose>; first: RawPose } {
+  return openWalk(doc, animationOf(doc, animation), plant, reset, mode, RAW_SHAPE, adjust, before);
 }
 
 /** One step of an opened raw track (`openRawTrack`): `walkIn`'s step, the step itself checked by the caller. */

package/src/core/track.ts

@@ -225,7 +225,9 @@ import { CoreInputError, type CompiledDocument } from './index.ts';
 import { checkedClock, environmentOf, openRawTrack, rotateOn, setEnvironmentOn, stepRawTrack, translateOn, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.ts';
 import type { LocalAdjust, TimelinePlant } from './animation.ts';
 import type { PhysicsEnvironment } from './constraints_physics.ts';
-export type { AdjustableLocals, BoneLocals, LocalAdjust } from './animation.ts';
+import { LivePhysicsParameters, type PhysicsParameterPatch, type PhysicsParameterRead } from './physics_parameters.ts';
+export type { PhysicsParameters, PhysicsParameterPatch, PhysicsParameterRead } from './physics_parameters.ts';
+export type { AdjustableLocals, BoneLocals, LocalAdjust, LocalAdjustContext } from './animation.ts';
 export type { PhysicsEnvironment } from './constraints_physics.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 — 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*). */
@@ -253,6 +255,12 @@ export interface LiveTrack {
   setEnvironment(environment: Partial<PhysicsEnvironment>): void;
   /** The environment the next pose answers. */
   readonly environment: PhysicsEnvironment;
+  /** Merges a finite six-field patch for one physics constraint, applied from the next pose until clear. */
+  setPhysicsParameters(name: string, patch: PhysicsParameterPatch): void;
+  /** Pending patch and the last evaluated six values; null effective means not yet evaluated (e.g. inactive). */
+  readPhysicsParameters(name: string): PhysicsParameterRead;
+  /** Removes the patch for the next pose without resetting velocities, offsets or the clock. */
+  clearPhysicsParameters(name: string): void;
   /** spine-core's `Skeleton.physicsTranslate`: the consumer moved the whole rig by `(x, y)` in the skeleton's world (y up) since the last pose, and every physics constraint's next update sees it. */
   physicsTranslate(x: number, y: number): void;
   /** spine-core's `Skeleton.physicsRotate`: the consumer turned the whole rig by `degrees` (counter-clockwise) about `(x, y)` in the skeleton's world since the last pose. */
@@ -275,8 +283,9 @@ export function openTrack(doc: CompiledDocument, animation: string, options: Tra
   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);
+  const parameters = new LivePhysicsParameters(doc);
+  const { track, first } = openRawTrack(doc, animation, plant, options.reset, clock === undefined ? mode : { ...mode, clock: (dt) => clock(dt) }, options.adjust, (ctx) => { ctx.parameters = parameters; });
+  return new Track(track, first, parameters);
 }
 
 class Track implements LiveTrack {
@@ -286,7 +295,7 @@ class Track implements LiveTrack {
   private latest: number;
   private refused: string | null = null;
 
-  constructor(track: TrackState<RawPose>, first: RawPose) {
+  constructor(track: TrackState<RawPose>, first: RawPose, private readonly parameters: LivePhysicsParameters) {
     this.track = track;
     this.first = first;
     this.latest = first.animationTime;
@@ -313,6 +322,20 @@ class Track implements LiveTrack {
     setEnvironmentOn(this.track.ctx, environment, 'the live track\'s');
   }
 
+  setPhysicsParameters(name: string, patch: PhysicsParameterPatch): void {
+    this.live('setPhysicsParameters');
+    this.parameters.set(name, patch);
+  }
+
+  readPhysicsParameters(name: string): PhysicsParameterRead {
+    return this.parameters.read(name);
+  }
+
+  clearPhysicsParameters(name: string): void {
+    this.live('clearPhysicsParameters');
+    this.parameters.clear(name);
+  }
+
   physicsTranslate(x: number, y: number): void {
     this.live('physicsTranslate');
     translateOn(this.track.ctx, x, y, 'the live track\'s');

package/src/core/tracks.ts

@@ -166,6 +166,7 @@ import { deformAt, setupArray, type CoreAttachmentTimeline } from './deform.ts';
 import { eventsFired, type CoreEventKey, type CoreEventRow } from './events.ts';
 import { checkedClock, environmentOf, openRawTracksPath, rotateOn, setEnvironmentOn, translateOn, type RawPose, type RawReset, type RawTracksPath } from './raw.ts';
 import type { PhysicsEnvironment } from './constraints_physics.ts';
+import { LivePhysicsParameters, type PhysicsParameterPatch, type PhysicsParameterRead } from './physics_parameters.ts';
 import { slotTimelinesApply } from './skins.ts';
 
 /** 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*). */
@@ -233,6 +234,12 @@ export interface LiveTracks {
   setEnvironment(environment: Partial<PhysicsEnvironment>): void;
   /** The environment the next pose answers. */
   readonly environment: PhysicsEnvironment;
+  /** Per-instance final parameter layer, as LiveTrack.setPhysicsParameters. Persists across entry changes. */
+  setPhysicsParameters(name: string, patch: PhysicsParameterPatch): void;
+  /** Detached pending patch and last evaluated six values, or null effective before start / when never active. */
+  readPhysicsParameters(name: string): PhysicsParameterRead;
+  /** Removes the patch without resetting the physics history, as LiveTrack.clearPhysicsParameters. */
+  clearPhysicsParameters(name: string): void;
   /** spine-core's `Skeleton.physicsTranslate`, as `LiveTrack.physicsTranslate`. */
   physicsTranslate(x: number, y: number): void;
   /** spine-core's `Skeleton.physicsRotate`, as `LiveTrack.physicsRotate`. */
@@ -1322,6 +1329,7 @@ export function openTracks(doc: CompiledDocument, options: TracksOptions, plant:
 
 class Tracks implements LiveTracks {
   private readonly mixer: Mixer;
+  private readonly parameters: LivePhysicsParameters;
   private started = false;
   private steps = 0;
   private time = 0;
@@ -1336,6 +1344,8 @@ class Tracks implements LiveTracks {
     private readonly path: RawTracksPath,
   ) {
     this.mixer = new Mixer(doc, plant);
+    this.parameters = new LivePhysicsParameters(doc);
+    this.path.ctx.parameters = this.parameters;
   }
 
   get trackTime(): number {
@@ -1351,6 +1361,20 @@ class Tracks implements LiveTracks {
     setEnvironmentOn(this.path.ctx, environment, 'the live tracks\'');
   }
 
+  setPhysicsParameters(name: string, patch: PhysicsParameterPatch): void {
+    this.live('setPhysicsParameters');
+    this.parameters.set(name, patch);
+  }
+
+  readPhysicsParameters(name: string): PhysicsParameterRead {
+    return this.parameters.read(name);
+  }
+
+  clearPhysicsParameters(name: string): void {
+    this.live('clearPhysicsParameters');
+    this.parameters.clear(name);
+  }
+
   physicsTranslate(x: number, y: number): void {
     this.live('physicsTranslate');
     translateOn(this.path.ctx, x, y, 'the live tracks\'');
@@ -1467,9 +1491,14 @@ class Tracks implements LiveTracks {
     ctx.time += this.clock === undefined ? dt : this.clock(dt);
     const pose = new Pose(doc, this.plant);
     const animationTime = this.mixer.apply(pose);
+    const entry = this.mixer.tracks[0] ?? null;
+    const adjustment = this.adjust === undefined ? undefined : {
+      callback: this.adjust,
+      context: { trackTime: entry?.trackTime ?? null, animation: entry?.anim.name ?? null, globalTime: this.time },
+    };
     const mixed = new Map(doc.slots.map((s, k) => [s.name, { deform: pose.slots[k].deform, seen: pose.slots[k].seen }]));
     return path.step(first, this.time, animationTime, {
-      world: (sliders) => steppedLocalsWorld(doc, pose.bones, path.raw, sliders, { ctx, before, adjust: this.adjust }, true),
+      world: (sliders) => steppedLocalsWorld(doc, pose.bones, path.raw, sliders, { ctx, before, adjustment }, true),
       slots: (sliders, placeholders) => slotRowsFrom(doc, path.raw, sliders, placeholders, (_slot, _live): SlotBase => {
         const s = pose.slots[doc.slots.indexOf(_slot)];
         return { placeholder: s.placeholder, light: s.light, dark: s.dark };