@rig-c/core 2.65.2 → 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
@@ -12045,3 +12119,79 @@ for `declared` and the run says so on a line of its own.
   `@rig-c/play` or `rigc preview`.
 - **Not a second poser.** Everything it draws is a pose `render` would have drawn at
   the same frame; where it disagrees with `render --geometry`, it is wrong (`IN04`).
+
+## 14. Read a named mesh at setup
+
+`rig-c/core` promises `readSetupMesh(view, target)` and the types
+`SetupMeshTarget` and `SetupMesh` (issue #1538). It reads any named mesh or linked
+mesh, including one the setup pose does not select, without a player, animation
+step or change to the document's setup selection.
+
+```ts
+import { readModel, underNoSkin, readSetupMesh } from 'rig-c/core';
+import type { SetupMeshTarget, SetupMesh } from 'rig-c/core';
+
+const view = underNoSkin(readModel(modelText));
+const target: SetupMeshTarget = { slot: 'flag', attachment: 'alternate' };
+const mesh: SetupMesh = readSetupMesh(view, target);
+// mesh.vertices: full-double world x,y pairs, y up; no crop/camera conversion.
+```
+
+| field | contract |
+| --- | --- |
+| `target.slot`, `target.attachment` | exact slot name and attachment **table key**; a record's display name, path or atlas region is not an alias |
+| `target.skin` omitted | retain the supplied view, including `readModel`'s `all`; use `underNoSkin` for a fresh skeleton's view |
+| `target.skin: null` | no skin set: default-table fallback, no skin-required bones or constraints activated |
+| `target.skin: name` | the named view, with default-table fallback; only the named skin's activation lists apply |
+| `target.skin: 'all'` | all activation lists; a uniquely filled key resolves, identical definitions keep the existing resolver's first supplying skin, differing definitions are refused because the model does not carry the Spine file's merge order |
+| `mesh.slot`, `mesh.attachment`, `mesh.skin` | requested slot and table key, and the table's supplying skin (which can be the default fallback); a linked mesh retains its own identity |
+| `mesh.vertices` | fresh mutable `number[]`, flat x,y in world units; stored coordinates and weights use the poser's float32 reading and influence order, without normalization |
+| `mesh.triangles`, `mesh.hull` | fresh mutable triangle indices; hull is the number of leading hull **vertices**, or `null` when absent |
+
+Definition equality ignores object property insertion order at every depth,
+including weighted binding records. Array positions, object key presence and
+leaf values remain significant; leaves use `Object.is`, so positive and negative
+zero are distinct when retained in a model. Reordering object keys alone is not
+a different definition. A genuine value, shape or array-order difference still
+produces the same named all-skin refusal; no merge order is inferred.
+
+The setup matrices come from the raw setup poser's existing constraint path,
+including setup sliders and reset physics. A selected mesh is bit-identical to
+`poseRawSetup(view)`'s geometry, including any setup-slider deform. An unselected
+mesh uses its stored vertices through those same matrices: the API never switches
+an attachment to ask what a slider or path constraint would do after a switch.
+A linked mesh borrows its source vertices, triangles and hull; unweighted
+vertices use the queried slot's bone, weighted vertices their named bindings.
+Its `timelines` flag controls source-deform inheritance only when selected, as
+in the existing setup poser. An inactive bone keeps the existing zero world
+matrix; an attachment read does not activate it.
+
+Every result is detached: changing its object or arrays changes no document,
+pose, cached topology or subsequent read. Missing slots, attachments and skins,
+and region, clipping, path or bounding-box targets, throw `CoreInputError`
+naming the requested identity and the problem. Examples include
+`setup mesh slot "s" attachment "missing" under skin null: no such attachment`
+and `…: region is not a mesh`. Ambiguous all-skin definitions name their skins
+and say `choose a named skin`; unknown skin retains `underSkin`'s existing
+`--skin "missing": no such skin` refusal. Existing setup/non-finite refusals
+propagate; the read does not manufacture a partial result when setup is absent.
+
+`S1538` controls exercise literal coordinates, detached data, linked meshes,
+skin lookup and activation, setup-slider deform, and the official runtime's
+`computeWorldVertices` using ordinary JS output arrays at tolerance 0. The
+runtime stores local mesh coordinates and weights in float32, but an output
+`Float32Array` would add a second rounding that this API does not perform.
+
+**Measured nonselected slider distinction.** In spine-core 4.3.13,
+`computeWorldVertices(skeleton, slot, …)` over an unselected mesh still reads
+the **selected slot's deform array**, even for a linked mesh with
+`timelines: false`. `S1538_09` measures a slider at time 0.5 interpolating
+local offsets `(1,2)` and `(3,4)` to `(2,3)`, with a selected source mesh,
+a linked mesh inheriting its timeline, and an independent linked mesh.
+All three selected reads are exact. Four of the six nonselected calls to the
+official method reuse the selected deform; their maximum absolute difference
+from this API is `2.9999999999999982` world units. The other two nonselected
+calls, with the independent linked mesh selected, agree exactly. The API's
+nonselected output is the stored source geometry through the unchanged setup
+matrices; it does not borrow a different selection's deform. The control
+checks both results and the source of the difference, without an epsilon.

package/package.json

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

@@ -180,9 +180,9 @@
  */
 import type { ModelSlot, ModelVertices } from '../model.ts';
 import { bezierPolyline, keyIndexAt, type CoreAnimationTimelines, type CoreCurve } from './animation.ts';
-import { activeBones, shownRow, type CompiledDocument, type CoreShown, type CoreSkin, type ShownResolution } from './index.ts';
+import { activeBones, shownAttachment, shownRow, type CompiledDocument, type CoreShown, type CoreSkin, type ShownResolution } from './index.ts';
 import { fillingSkins, slotTimelinesApply, type SlotTimelineGate } from './skins.ts';
-import type { CoreGeometry, ShownGeometry } from './vertices.ts';
+import type { ShownGeometry } from './vertices.ts';
 
 /** The far end the deform curve's recurrence runs to — the header's measurement. */
 export const DEFORM_CURVE_END = 0.99999999;
@@ -515,6 +515,111 @@ export function timelineIdentity(slot: string, shown: CoreShown): string | null
 
 const nameOf = (a: CoreAttachmentTimeline): string => `${a.skin}/${a.slot}/${a.attachment}`;
 
+/** The part of an attachment state that depends only on the document view and placeholder. */
+interface AttachmentIdentity {
+  readonly entry: ShownGeometry;
+  readonly identity: string | null;
+  readonly vertices: ModelVertices | null;
+  readonly count: number | undefined;
+  readonly fillers: readonly string[];
+}
+
+/** Like shownAttachment's cache, scoped to the view; a new skin view resolves its own records. */
+const identitiesOfView = new WeakMap<CompiledDocument, Map<string, Map<string, AttachmentIdentity | null>>>();
+
+function readIdentity(doc: CompiledDocument, resolve: (doc: CompiledDocument, slot: ModelSlot) => ShownResolution, slot: ModelSlot, placeholder: string): AttachmentIdentity | null {
+  const s = resolve(doc, { ...slot, setup: placeholder });
+  if (s === null || 'conflict' in s || s.record.geometry === undefined) return null;
+  const g = s.record.geometry;
+  const source = g.kind === 'linkedmesh' ? doc.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source] : s.record;
+  const sg = source?.geometry;
+  return Object.freeze({
+    entry: Object.freeze({ slot: slot.name, bone: slot.bone, name: shownRow(s).name, placeholder: s.placeholder, skin: s.skin, geometry: g }),
+    identity: timelineIdentity(slot.name, s),
+    vertices: sg !== undefined && sg.kind !== 'region' && sg.kind !== 'linkedmesh' ? sg.vertices : null,
+    count: source?.sequenceCount,
+    fillers: Object.freeze(fillingSkins(doc, slot.name, s.placeholder).map((k) => `"${k}"`)),
+  });
+}
+
+function identityOf(doc: CompiledDocument, resolve: (doc: CompiledDocument, slot: ModelSlot) => ShownResolution, slot: ModelSlot, placeholder: string | null): AttachmentIdentity | null {
+  if (placeholder === null) return null;
+  // A planted resolver may read changing state outside the document. Only the document's own reader is immutable.
+  if (resolve !== shownAttachment) return readIdentity(doc, resolve, slot, placeholder);
+  let slots = identitiesOfView.get(doc);
+  if (slots === undefined) identitiesOfView.set(doc, slots = new Map());
+  let placeholders = slots.get(slot.name);
+  if (placeholders === undefined) slots.set(slot.name, placeholders = new Map());
+  if (placeholders.has(placeholder)) return placeholders.get(placeholder) as AttachmentIdentity | null;
+  const identity = readIdentity(doc, resolve, slot, placeholder);
+  placeholders.set(placeholder, identity);
+  return identity;
+}
+
+/** Index only immutable timeline identity. Times, mixes and the values they compute are never cached. */
+const attachmentsByIdentity = new WeakMap<readonly CoreAttachmentTimeline[], ReadonlyMap<string, readonly CoreAttachmentTimeline[]>>();
+type AttachmentSlots = AttachmentApplication['timelines']['slots'];
+type AttachmentSwitch = NonNullable<AttachmentSlots[number]['timelines'][number]['keys']>;
+const switchesBySlot = new WeakMap<AttachmentSlots, ReadonlyMap<string, readonly AttachmentSwitch[]>>();
+
+function matchingAttachments(timelines: readonly CoreAttachmentTimeline[], identity: string): readonly CoreAttachmentTimeline[] | undefined {
+  let index = attachmentsByIdentity.get(timelines);
+  if (index === undefined) {
+    const rows = new Map<string, CoreAttachmentTimeline[]>();
+    for (const a of timelines) {
+      const name = nameOf(a);
+      const found = rows.get(name);
+      if (found === undefined) rows.set(name, [a]);
+      else found.push(a);
+    }
+    attachmentsByIdentity.set(timelines, index = rows);
+  }
+  return index.get(identity);
+}
+
+function slotSwitches(slots: AttachmentSlots, slot: string): readonly AttachmentSwitch[] | undefined {
+  let index = switchesBySlot.get(slots);
+  if (index === undefined) {
+    const rows = new Map<string, AttachmentSwitch[]>();
+    for (const target of slots) {
+      for (const tl of target.timelines) {
+        if (tl.kind !== 'attachment' || tl.keys === undefined) continue;
+        const found = rows.get(target.name);
+        if (found === undefined) rows.set(target.name, [tl.keys]);
+        else found.push(tl.keys);
+      }
+    }
+    switchesBySlot.set(slots, index = rows);
+  }
+  return index.get(slot);
+}
+
+/** Allocated only when a matching timeline or a mixed deform actually has per-pose state. */
+interface AttachmentValues {
+  deform: number[] | null;
+  frame: number | null;
+  seen: string[];
+}
+
+function applyAttachment(now: AttachmentIdentity | null, values: AttachmentValues | null, timelines: readonly CoreAttachmentTimeline[], t: number, blend: AttachmentApplication | null, evalDeform: DeformEvaluator, blendOf: DeformBlender, evalFrame: SequenceEvaluator): AttachmentValues | null {
+  if (now === null || now.identity === null) return values;
+  const matching = matchingAttachments(timelines, now.identity);
+  if (matching === undefined) return values;
+  values ??= { deform: null, frame: null, seen: [] };
+  if (!values.seen.includes(now.identity)) values.seen.push(now.identity);
+  for (const a of matching) {
+    if (a.deform !== null && now.vertices !== null) {
+      const target = evalDeform(now.vertices, a.deform, t);
+      if (target !== null) values.deform = blend === null ? target : blendOf(now.vertices, values.deform, target, blend.alpha, blend.additive);
+    }
+    if (a.sequence !== null && now.count !== undefined) {
+      const f = evalFrame(a.sequence, now.count, t);
+      if (f !== null) values.frame = f;
+    }
+  }
+  return values;
+}
+
 /**
  * Every slot's shown geometry at one pose — the setup's (`sample` null) or a
  * sample's — with the deform array and the series' frame its attachment
@@ -528,6 +633,11 @@ const nameOf = (a: CoreAttachmentTimeline): string => `${a.skin}/${a.slot}/${a.a
  * differently is left to the slots' own absence. `why` names what the core
  * does not pose: a timeline moving a record whose placeholder several skins
  * fill (the header's ⚠️).
+ *
+ * Identity is kept per document view, slot and placeholder, and timelines
+ * indexed by their record identity. A slot with no per-pose values reuses its
+ * frozen entry; deform arrays and sequence frames are evaluated afresh.
+ * Sliders select identities in application order, never a cached posed value.
  */
 export function attachmentStates(
   doc: CompiledDocument,
@@ -557,66 +667,39 @@ export function attachmentStates(
     const live = gate(doc, slot, active);
     let placeholder = placeholders.get(slot.name) ?? null;
     const base = live ? mixed?.get(slot.name) : undefined;
-    let deform: number[] | null = base?.deform ?? null;
-    let frame: number | null = null;
-    const seen: string[] = base === undefined ? [] : [...base.seen];
-    // What the slot shows now, the record its timelines are keyed as, and what a deform or a frame is computed on.
-    const state = (): { s: CoreShown; identity: string | null; vertices: ModelVertices | null; count: number | undefined } | null => {
-      if (placeholder === null) return null;
-      const s = resolve(doc, { ...slot, setup: placeholder });
-      if (s === null || 'conflict' in s || s.record.geometry === undefined) return null;
-      const g = s.record.geometry;
-      const source = g.kind === 'linkedmesh' ? doc.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source] : s.record;
-      const sg = source?.geometry;
-      const vertices = sg !== undefined && sg.kind !== 'region' && sg.kind !== 'linkedmesh' ? sg.vertices : null;
-      return { s, identity: timelineIdentity(slot.name, s), vertices, count: source?.sequenceCount };
-    };
-    const apply = (timelines: readonly CoreAttachmentTimeline[], t: number, blend: { alpha: number; additive: boolean } | null): void => {
-      const now = state();
-      if (now === null || now.identity === null) return;
-      for (const a of timelines) {
-        if (nameOf(a) !== now.identity) continue;
-        if (!seen.includes(now.identity)) seen.push(now.identity);
-        if (a.deform !== null && now.vertices !== null) {
-          const target = evalDeform(now.vertices, a.deform, t);
-          if (target !== null) deform = blend === null ? target : blendOf(now.vertices, deform, target, blend.alpha, blend.additive);
-        }
-        if (a.sequence !== null && now.count !== undefined) {
-          const f = evalFrame(a.sequence, now.count, t);
-          if (f !== null) frame = f;
-        }
-      }
-    };
-    if (sample !== null && live) apply(sample.timelines.attachments, sample.t, null);
-    for (const app of live ? sliders : []) {
-      // The slider's attachment key first, as the slot timelines are (`applySliderSlots` in `./constraints_slider.ts`); a switch to another placeholder clears what the timelines set.
-      for (const target of app.timelines.slots) {
-        if (target.name !== slot.name) continue;
-        for (const tl of target.timelines) {
-          if (tl.kind !== 'attachment' || tl.keys === undefined) continue;
-          const i = keyIndexAt(tl.keys, app.at);
-          if (i < 0) continue;
-          const next = tl.keys[i].name ?? null;
-          if (next !== placeholder) {
-            deform = null;
-            frame = null;
+    let values: AttachmentValues | null = base === undefined || (base.deform === null && base.seen.length === 0) ? null : { deform: base.deform, frame: null, seen: [...base.seen] };
+    let now = identityOf(doc, resolve, slot, placeholder);
+    if (sample !== null && live) values = applyAttachment(now, values, sample.timelines.attachments, sample.t, null, evalDeform, blendOf, evalFrame);
+    if (live) for (const app of sliders) {
+      // Each slider switches first, clearing only the per-pose values; then its attachment timelines apply to the new identity.
+      const switches = slotSwitches(app.timelines.slots, slot.name);
+      if (switches !== undefined) for (const keys of switches) {
+        const i = keyIndexAt(keys, app.at);
+        if (i < 0) continue;
+        const next = keys[i].name ?? null;
+        if (next !== placeholder) {
+          if (values !== null) {
+            values.deform = null;
+            values.frame = null;
           }
           placeholder = next;
+          now = identityOf(doc, resolve, slot, placeholder);
         }
       }
-      apply(app.timelines.attachments, app.at, { alpha: app.alpha, additive: app.additive });
+      values = applyAttachment(now, values, app.timelines.attachments, app.at, app, evalDeform, blendOf, evalFrame);
     }
-    const now = state();
     if (now === null) continue;
-    const entry: ShownGeometry = { slot: slot.name, bone: slot.bone, name: shownRow(now.s).name, placeholder: now.s.placeholder, skin: now.s.skin, geometry: now.s.record.geometry as CoreGeometry };
+    // The cached entry is frozen. A pose with a deform/frame owns its wrapper and values; later poses cannot write into it.
+    const entry = values === null || (values.deform === null && values.frame === null) ? now.entry : { ...now.entry };
     shown.push(entry);
-    const fillers = fillingSkins(doc, slot.name, now.s.placeholder).map((k) => `"${k}"`);
-    if (seen.length > 0 && fillers.length > 1) {
-      why.push(`slot "${slot.name}" shows placeholder "${now.s.placeholder}", which skins ${fillers.join(', ')} fill, and ${seen.map((x) => `"${x}"`).join(', ')} key(s) it — which record --skin all shows, and so whether the timeline moves it, is the Spine file's skin order, not the model's`);
+    if (values !== null && values.seen.length > 0 && now.fillers.length > 1) {
+      why.push(`slot "${slot.name}" shows placeholder "${now.entry.placeholder}", which skins ${now.fillers.join(', ')} fill, and ${values.seen.map((x) => `"${x}"`).join(', ')} key(s) it — which record --skin all shows, and so whether the timeline moves it, is the Spine file's skin order, not the model's`);
       continue;
     }
-    if (deform !== null) entry.deform = deform;
-    if (frame !== null) entry.frame = frame;
+    if (values !== null) {
+      if (values.deform !== null) entry.deform = values.deform;
+      if (values.frame !== null) entry.frame = values.frame;
+    }
   }
   return { shown, why };
 }

package/src/core/entry.ts

@@ -24,17 +24,21 @@
  * a Bézier segment as, so that a fitter holds its tolerance to the poser's
  * 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).
+ * `CA12` holds the identity; `readSetupMesh`, issue #1538, the named setup
+ * 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.
  */
 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, physicsClockStep, PHYSICS_CLOCK_LEAD } from './raw.ts';
-export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
+export { readSetupMesh, poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setupBounds, physicsClockStep, PHYSICS_CLOCK_LEAD } from './raw.ts';
+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/index.ts

@@ -1196,10 +1196,11 @@ const shownOfView = new WeakMap<CompiledDocument, Map<string, Map<string, ShownR
  * The answer reads the view's skins and the slot's name and placeholder only,
  * so it is resolved once per view, slot and placeholder and kept (issue
  * #1134: every sample of a walk resolved every slot again). Read-only to every
- * caller; a view built anew resolves its own.
+ * caller; a view built anew resolves its own. An explicit placeholder reads
+ * another table key without changing the slot (issue #1538).
  */
-export function shownAttachment(doc: CompiledDocument, slot: ModelSlot): ShownResolution {
-  if (slot.setup === null) return null;
+export function shownAttachment(doc: CompiledDocument, slot: ModelSlot, placeholder: string | null = slot.setup): ShownResolution {
+  if (placeholder === null) return null;
   let bySlot = shownOfView.get(doc);
   if (bySlot === undefined) {
     bySlot = new Map();
@@ -1210,9 +1211,9 @@ export function shownAttachment(doc: CompiledDocument, slot: ModelSlot): ShownRe
     byPlaceholder = new Map();
     bySlot.set(slot.name, byPlaceholder);
   }
-  if (byPlaceholder.has(slot.setup)) return byPlaceholder.get(slot.setup) as ShownResolution;
-  const resolved = resolveShown(doc, slot.name, slot.setup);
-  byPlaceholder.set(slot.setup, resolved);
+  if (byPlaceholder.has(placeholder)) return byPlaceholder.get(placeholder) as ShownResolution;
+  const resolved = resolveShown(doc, slot.name, placeholder);
+  byPlaceholder.set(placeholder, resolved);
   return resolved;
 }
 

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

@@ -113,7 +113,7 @@
  * naming why (`CoreInputError`): a renderer handed a pose with a block
  * 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 { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
 import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type CoreAnimationTimelines, type LocalAdjust, type TimelinePlant } from './animation.ts';
 import { constraintsAbsentWhy, pathAnimationsWhy } from './constraints.ts';
 import { freshStepContext, rotatePhysics, steppedPreviousPassWhy, translatePhysics, DEFAULT_PHYSICS_ENVIRONMENT, type PhysicsEnvironment, type PhysicsStepContext } from './constraints_physics.ts';
@@ -121,8 +121,9 @@ import { attachmentStates } from './deform.ts';
 import { drawOrderAt, type CoreDrawOrderKey } from './draw_order.ts';
 import { eventsFired, type CoreEventRow } from './events.ts';
 import { REGION_TRIANGLES, REGION_UVS, type CoreClippedRow, type ShapeClipper } from './clipping.ts';
-import { meshArraysOf, poseGeometry, type CoreAttachmentRow, type CoreClipRow, type ShownGeometry } from './vertices.ts';
+import { meshArraysOf, poseGeometry, worldVertices, type CoreAttachmentRow, type CoreClipRow, type ShownGeometry } from './vertices.ts';
 import { RUNTIME_DEG, type CoreWorld } from './world.ts';
+import { fillingSkins } from './skins.ts';
 import type { SliderApplication } from './constraints_slider.ts';
 
 /** One bone, posed: the world transform and the runtime getters' four readings (the header's `bones`). */
@@ -465,6 +466,81 @@ export function poseRawSetup(doc: CompiledDocument, plant: CorePlant = {}): RawP
   return setupPoseIn(doc, plant, RAW_MODE);
 }
 
+/** A table key to read, with an optional skin-view override; omitted skin keeps the supplied view. */
+export interface SetupMeshTarget {
+  readonly slot: string;
+  readonly attachment: string;
+  /** A named skin (with default fallback), `all`, or `null` for no skin set. */
+  readonly skin?: string | null;
+}
+
+/** A detached named mesh in setup world units, y up; hull counts vertices, not coordinates. */
+export interface SetupMesh {
+  slot: string;
+  /** The requested attachment table key, even when the record states another display name. */
+  attachment: string;
+  /** The skin whose table supplied the requested record, including a fallback. */
+  skin: string;
+  vertices: number[];
+  triangles: number[];
+  hull: number | null;
+}
+
+/** Model definitions by value: object key order is irrelevant, array positions and signed zero are not. */
+function sameSetupMeshDefinition(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b) && a.length !== b.length) return false;
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every((key) =>
+    Object.prototype.hasOwnProperty.call(right, key) && sameSetupMeshDefinition(left[key], right[key]));
+}
+
+/**
+ * Read a named mesh without changing the setup selection or playing anything
+ * (issue #1538). Setup constraints and reset physics use the raw poser's own
+ * path. A selected mesh includes its setup-slider deform; an unselected mesh
+ * reads its stored geometry through those same matrices, with no hypothetical
+ * attachment switch or deform. Linked meshes use their source topology and
+ * bindings, and the queried slot's bone for unweighted vertices; `timelines`
+ * affects only a selected mesh's setup-slider deform, as in `poseRawSetup`.
+ *
+ * Skin resolution is the supplied view's unless explicitly overridden. Under
+ * `all`, differing definitions of the requested mesh are refused: the model
+ * does not carry the file order that would choose one. Object property order
+ * does not distinguish definitions; array positions and Object.is leaf values
+ * do. Identical definitions keep the resolver's first supplying skin. All arrays are fresh.
+ */
+export function readSetupMesh(doc: CompiledDocument, target: SetupMeshTarget): SetupMesh {
+  const view = target.skin === undefined ? doc : target.skin === null ? underNoSkin(doc) : underSkin(doc, target.skin);
+  const where = `setup mesh slot ${JSON.stringify(target.slot)} attachment ${JSON.stringify(target.attachment)} under skin ${JSON.stringify(view.skin)}`;
+  const slot = view.slots.find((s) => s.name === target.slot);
+  if (slot === undefined) throw new CoreInputError(`${where}: no such slot`);
+  const resolved = shownAttachment(view, slot, target.attachment);
+  if (resolved === null) throw new CoreInputError(`${where}: no such attachment`);
+  const fills = fillingSkins(view, slot.name, target.attachment);
+  const definitions = fills.map((name) => view.skins.find((k) => k.name === name)?.attachments[slot.name]?.[target.attachment]);
+  if ('conflict' in resolved || definitions.some((r) => !sameSetupMeshDefinition(r, definitions[0]))) {
+    throw new CoreInputError(`${where}: skins [${fills.join(', ')}] fill this attachment differently; choose a named skin`);
+  }
+  const geometry = resolved.record.geometry;
+  const mesh = geometry?.kind === 'linkedmesh'
+    ? view.skins.find((s) => s.name === geometry.skin)?.attachments[geometry.slot]?.[geometry.source]?.geometry
+    : geometry;
+  if (mesh?.kind !== 'mesh') throw new CoreInputError(`${where}: ${resolved.record.kind} is not a mesh`);
+  const { world, shown, drawOrder } = setupPosed(view, {}, RAW_MODE);
+  const selected = shown.find((s) => s.slot === slot.name && s.placeholder === target.attachment && s.skin === resolved.skin);
+  const bone = world.get(slot.bone);
+  if (bone === undefined) throw new CoreInputError(`${where}: no setup transform for bone ${JSON.stringify(slot.bone)}`);
+  const vertices = selected === undefined
+    ? numbersOf(worldVertices(mesh.vertices, bone, world).map(rawNumber), `${where} vertex`, RAW_MODE)
+    : rawDrawn(view, [selected], world, drawOrder, {}).drawn[0].vertices;
+  return { slot: slot.name, attachment: target.attachment, skin: resolved.skin, vertices: [...vertices], triangles: [...mesh.triangles], hull: mesh.hull ?? null };
+}
+
 /** `poseRawSetup` in `mode` — under `keep`, a value that is not finite stays in the pose (`./walk.ts`). */
 export function setupPoseIn(doc: CompiledDocument, plant: CorePlant, mode: WalkMode): RawPose {
   const { world, shown, slots, drawOrder } = setupPosed(doc, plant, mode);
@@ -830,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,
@@ -948,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 };