spine-rigc 2.51.1 → 2.52.0

package/docs/AUTHORING.md

@@ -4953,6 +4953,41 @@ 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.
 
+🌬️ **`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,
+windY` and `gravityX, gravityY`, which start at `1, 0` and `0, 1` — so a
+constraint stating `wind: 20` is pushed along whatever direction the player
+sets, times 20 (and on `x` and `y` times `referenceScale`; on a rotation, at
+a lever of the bone's `length` over `referenceScale`). A live track of the
+core entry sets that direction with `setEnvironment({ wind: [x, y], gravity:
+[x, y] })` — x to the right, **y down**, either half left out to keep the one
+that stands — and the Spine export carries only the response, so an official
+runtime whose `Skeleton` is given the same four numbers poses what the core
+poses, to the bit (`CO56`). Two consequences an author has to know:
+
+- **A constraint stating `wind: 0` feels no wind**, whatever the player sets.
+  State a `wind` on every link that should answer a gust; leave it 0 on one
+  that should not.
+- **Until the player sets one, `wind` pushes to the right.** The initial
+  direction is the runtime's `[1, 0]`, not `[0, 0]`, so a rig stating `wind`
+  leans at rest on every player that never calls `setEnvironment` — the
+  official runtimes included. A player that wants calm at rest sets `wind:
+  [0, 0]` and blows by setting it back. rigc does not change the initial
+  value: that would make the export pose differently in the runtime than in
+  the core.
+
+Moving the rig is the consumer's too: `physicsTranslate(x, y)` and
+`physicsRotate(x, y, degrees)` on a live track are the runtime's methods of
+those names — the whole rig moved or turned since the last pose, in the
+skeleton's world (y up, degrees counter-clockwise) — and every constraint's
+next update sees its bone move by that much, so a rig walked across the screen
+trails its coat. A player forwards what spine-core's `SkeletonPhysicsMovement`
+forwards: its display object's change of position since the last frame in the
+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`).
+
 `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": "spine-rigc",
-  "version": "2.51.1",
+  "version": "2.52.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/constraints_physics.ts

@@ -189,6 +189,34 @@
  * reading is rejected as a schedule no player runs; the core suite's `SC`
  * controls plant it and turn the probe red on the steps after the key.
  *
+ * ## The environment (issue #1416)
+ *
+ * A constraint's `wind` and `gravity` are not forces: they are how strongly it
+ * answers two directions the SKELETON carries — spine-core 4.3.13's
+ * `Skeleton.windX, windY` and `gravityX, gravityY`, initially `1, 0` and `0,
+ * 1` (`DEFAULT_PHYSICS_ENVIRONMENT`). The step weighs them as the runtime
+ * does: for `x` and `y`, `ax = (wind·windX + gravity·gravityX)·R` and `ay =
+ * (wind·windY + gravity·gravityY)·R`, `velocity += (ax − offset·strength)·…`
+ * on `x` and `−= (ay + offset·strength)·…` on `y`; for the rotation and the
+ * scale the same two sums without `R`, `(ax·sin + ay·cos)·length/R` and `ax·cos
+ * − ay·sin` in place of the wind and gravity terms above. The skeleton's own
+ * scale, which the runtime multiplies the `x` and `y` sums by, is 1 here. So
+ * the environment's y points DOWN — `[0, 1]` pulls toward the bottom of the
+ * screen — and with the initial values every expression is the one this file
+ * computed before the environment existed: `wind·1 + gravity·0` is `wind` for
+ * every finite `gravity` (a `wind` of −0 aside, which it reads as +0, as the
+ * runtime does), and the render and emit bases did not move.
+ *
+ * The consumer sets it (`setEnvironment` on a live track, `./track.ts`), and
+ * moves the rig from outside with `translatePhysics` and `rotatePhysics` —
+ * `Skeleton.physicsTranslate` and `physicsRotate`, which shift what each
+ * constraint last saw (`ux, uy, cx, cy`) so its next update reads the bone as
+ * having moved. A constraint with no state yet is pending, and its first
+ * update overwrites both, so it is left alone, as the runtime's translation of
+ * it is read by nothing. The core suite's `CO56` holds all of it to spine-core
+ * given the same values at tolerance 0, and `CO57` that nothing set poses what
+ * was posed before.
+ *
  * ## What is not exact, and why
  *
  * Over 3,000 random rigs of three shapes (all five inherit modes; ik and
@@ -215,6 +243,9 @@
  */
 import { channelAt, keyIndexAt, poseAnimations, sampleTime, type CoreAnimationPose, type CoreCurve, type CoreKey, type SamplePhase, type TimelinePlant } from './animation.ts';
 import { RUNTIME_PI, type CoreWorld } from './world.ts';
+
+/** Degrees to radians as the runtime converts them (`MathUtils.degRad`, `pi / 180` with the runtime's pi). */
+const RUNTIME_RAD = RUNTIME_PI / 180;
 import { previousPassSlotBones, type CoreConstraintRecord } from './constraints.ts';
 import { activeBones, type CompiledDocument } from './index.ts';
 
@@ -577,6 +608,71 @@ export interface PhysicsStepContext {
   keyedNow?: Set<string>;
   /** A plant only (issue #1049, `sliderPhysicsFromCurrent: false`): each physics record's setup values, before the step's own animation. */
   setupRecords?: Map<string, CorePhysicsRecord>;
+  /**
+   * The world every constraint answers (issue #1416, the header's *The
+   * environment*): the skeleton's wind and gravity directions, as a caller set
+   * them on the live track. Absent, spine-core's own initial values
+   * (`DEFAULT_PHYSICS_ENVIRONMENT`), which is every walk but a live one a
+   * caller set it on.
+   */
+  env?: PhysicsEnvironment;
+}
+
+/**
+ * The world a physics constraint answers (issue #1416): spine-core 4.3.13's
+ * four skeleton fields `windX`, `windY`, `gravityX` and `gravityY`, as
+ * `wind: [windX, windY]` and `gravity: [gravityX, gravityY]` — the
+ * DIRECTIONS the constraints' own `wind` and `gravity` act along, which are
+ * each constraint's response to them (the header's *The environment*). In the
+ * runtime's convention: x to the right, **y down** — a positive y component
+ * pulls a constraint toward the bottom of the screen, as `gravity: [0, 1]`
+ * does.
+ */
+export interface PhysicsEnvironment {
+  readonly wind: readonly [number, number];
+  readonly gravity: readonly [number, number];
+}
+
+/** spine-core 4.3.13's initial `Skeleton.windX, windY, gravityX, gravityY` — `1, 0, 0, 1` — the world of every walk nobody set one on. */
+export const DEFAULT_PHYSICS_ENVIRONMENT: PhysicsEnvironment = Object.freeze({ wind: Object.freeze([1, 0] as const), gravity: Object.freeze([0, 1] as const) });
+
+/**
+ * `Skeleton.physicsTranslate(x, y)` on the states in `ctx` (issue #1416): every
+ * constraint's next update sees its bone moved by `(x, y)` in the skeleton's
+ * world (y up) — the consumer moved the whole rig by that much since the last
+ * pose. A constraint with no state yet has not been updated, and its first
+ * update is pending, so the runtime's translation of it is read by nothing.
+ */
+export function translatePhysics(ctx: PhysicsStepContext, x: number, y: number): void {
+  for (const s of ctx.states.values()) {
+    s.ux -= x;
+    s.uy -= y;
+    s.cx -= x;
+    s.cy -= y;
+  }
+}
+
+/**
+ * `Skeleton.physicsRotate(x, y, degrees)` on the states in `ctx` (issue
+ * #1416): every constraint's next update sees its bone turned by `degrees`
+ * (counter-clockwise, the runtime's pi) about `(x, y)` in the skeleton's world —
+ * a translation of each constraint by how far that turn carries the origin it
+ * last saw, as `PhysicsConstraint.rotate` computes it.
+ */
+export function rotatePhysics(ctx: PhysicsStepContext, x: number, y: number, degrees: number): void {
+  const r = degrees * RUNTIME_RAD;
+  const cos = Math.cos(r);
+  const sin = Math.sin(r);
+  for (const s of ctx.states.values()) {
+    const dx = s.cx - x;
+    const dy = s.cy - y;
+    const tx = dx * cos - dy * sin - dx;
+    const ty = dx * sin + dy * cos - dy;
+    s.ux -= tx;
+    s.uy -= ty;
+    s.cx -= tx;
+    s.cy -= ty;
+  }
 }
 
 /** A constraint's state in `ctx`, created fresh on its first update. */
@@ -634,6 +730,7 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
   s.lastTime = ctx.time;
   const bx = w.worldX;
   const by = w.worldY;
+  const env = ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
   let z = 0;
   if (s.pending) {
     s.pending = false;
@@ -664,16 +761,19 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
         const e = r.strength;
         const wind = r.wind * f;
         const g = r.gravity * f;
+        // The environment's directions (issue #1416), as the runtime weighs them; the skeleton's scale is 1 here, so its factor is left out.
+        const ax = wind * env.wind[0] + g * env.gravity[0];
+        const ay = wind * env.wind[1] + g * env.gravity[1];
         const xs = s.xOffset;
         const ys = s.yOffset;
         do {
           if (x) {
-            s.xVelocity += (wind - s.xOffset * e) * m;
+            s.xVelocity += (ax - s.xOffset * e) * m;
             s.xOffset += s.xVelocity * t;
             s.xVelocity *= d;
           }
           if (y) {
-            s.yVelocity -= (g + s.yOffset * e) * m;
+            s.yVelocity -= (ay + s.yOffset * e) * m;
             s.yOffset += s.yVelocity * t;
             s.yVelocity *= d;
           }
@@ -720,20 +820,20 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
         if (d === -1) d = Math.pow(r.damping, 60 * t);
         const m = r.massInverse * t;
         const e = r.strength;
-        const wind = r.wind;
-        const g = r.gravity;
+        const ax = r.wind * env.wind[0] + r.gravity * env.gravity[0];
+        const ay = r.wind * env.wind[1] + r.gravity * env.gravity[1];
         const h = l / f;
         const rs = s.rotateOffset;
         const ss = s.scaleOffset;
         for (;;) {
           a -= t;
           if (scaleX) {
-            s.scaleVelocity += (wind * c - g * sn - s.scaleOffset * e) * m;
+            s.scaleVelocity += (ax * c - ay * sn - s.scaleOffset * e) * m;
             s.scaleOffset += s.scaleVelocity * t;
             s.scaleVelocity *= d;
           }
           if (rotateOrShearX) {
-            s.rotateVelocity -= ((wind * sn + g * c) * h + s.rotateOffset * e) * m;
+            s.rotateVelocity -= ((ax * sn + ay * c) * h + s.rotateOffset * e) * m;
             s.rotateOffset += s.rotateVelocity * t;
             s.rotateVelocity *= d;
             if (a < t) break;

package/src/core/entry.ts

@@ -18,7 +18,9 @@
  * ⚠️ 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; `physicsClockStep` and `PHYSICS_CLOCK_LEAD`,
- * the clock a live track's `clock` option takes, issue #1396).
+ * the clock a live track's `clock` option takes, issue #1396;
+ * `PhysicsEnvironment`, what a live track's `setEnvironment` takes, issue
+ * #1416).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
@@ -28,7 +30,7 @@ export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setup
 export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } from './track.ts';
-export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust } from './track.ts';
+export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust, PhysicsEnvironment } from './track.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/raw.ts

@@ -116,7 +116,7 @@
 import { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, 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, steppedPreviousPassWhy } from './constraints_physics.ts';
+import { freshStepContext, rotatePhysics, steppedPreviousPassWhy, translatePhysics, DEFAULT_PHYSICS_ENVIRONMENT, type PhysicsEnvironment, type PhysicsStepContext } from './constraints_physics.ts';
 import { attachmentStates } from './deform.ts';
 import { drawOrderAt, type CoreDrawOrderKey } from './draw_order.ts';
 import { eventsFired, type CoreEventRow } from './events.ts';
@@ -575,6 +575,53 @@ export function checkedClock(clock: (dt: number) => number, who: string): (dt: n
   };
 }
 
+/**
+ * A live track's `setEnvironment` (issue #1416, `./track.ts` and `./tracks.ts`):
+ * the world every physics constraint answers from the next pose on, set on the
+ * track's physics context — `wind` and `gravity` each a pair of finite numbers,
+ * either left out to keep the one that stands, and nothing else — or refused by
+ * name, before anything moves. The pair is copied: the caller's array changed
+ * later moves nothing.
+ */
+export function setEnvironmentOn(ctx: PhysicsStepContext, env: unknown, who: string): void {
+  if (typeof env !== 'object' || env === null || Array.isArray(env)) throw new CoreInputError(`${who} setEnvironment was given ${env === null ? 'null' : Array.isArray(env) ? 'an array' : typeof env}, not an object { wind?: [x, y], gravity?: [x, y] }`);
+  const given = env as Record<string, unknown>;
+  for (const key of Object.keys(given)) {
+    if (key !== 'wind' && key !== 'gravity') throw new CoreInputError(`${who} setEnvironment names "${key}", which is not one of [wind, gravity]`);
+  }
+  const pair = (key: 'wind' | 'gravity'): readonly [number, number] | undefined => {
+    const v = given[key];
+    if (v === undefined) return undefined;
+    if (!Array.isArray(v) || v.length !== 2 || v.some((n) => typeof n !== 'number' || !Number.isFinite(n))) throw new CoreInputError(`${who} setEnvironment's ${key} is ${JSON.stringify(v)}, not a pair of finite numbers [x, y] (x to the right, y down)`);
+    return Object.freeze([v[0] as number, v[1] as number] as const);
+  };
+  const wind = pair('wind');
+  const gravity = pair('gravity');
+  const standing = ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
+  ctx.env = Object.freeze({ wind: wind ?? standing.wind, gravity: gravity ?? standing.gravity });
+}
+
+/** The environment a live track's physics answers now (`setEnvironmentOn`): spine-core's initial one where none was set. */
+export function environmentOf(ctx: PhysicsStepContext): PhysicsEnvironment {
+  return ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
+}
+
+/** A live track's `physicsTranslate` (issue #1416): `x` and `y` finite, or refused by name before anything moves; then `translatePhysics`. */
+export function translateOn(ctx: PhysicsStepContext, x: number, y: number, who: string): void {
+  for (const [k, v] of [['x', x], ['y', y]] as const) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) throw new CoreInputError(`${who} physicsTranslate's ${k} is ${String(v)}, not a finite distance in the skeleton's world`);
+  }
+  translatePhysics(ctx, x, y);
+}
+
+/** A live track's `physicsRotate` (issue #1416): `x`, `y` and `degrees` finite, or refused by name before anything moves; then `rotatePhysics`. */
+export function rotateOn(ctx: PhysicsStepContext, x: number, y: number, degrees: number, who: string): void {
+  for (const [k, v] of [['x', x], ['y', y], ['degrees', degrees]] as const) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) throw new CoreInputError(`${who} physicsRotate's ${k} is ${String(v)}, not a finite number`);
+  }
+  rotatePhysics(ctx, x, y, degrees);
+}
+
 /**
  * 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

@@ -174,6 +174,36 @@
  * `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 environment, and the rig moved from outside (issue #1416)
+ *
+ * The rig states how each physics constraint answers the world — its `wind`
+ * and `gravity` — and the consumer states the world. `setEnvironment({ wind,
+ * gravity })` sets it from the next pose on and it stands until set again,
+ * as spine-core's four `Skeleton` fields do: `wind` is `[windX, windY]`,
+ * `gravity` is `[gravityX, gravityY]`, x to the right and **y down**, and
+ * until set it is the runtime's own `{ wind: [1, 0], gravity: [0, 1] }`
+ * (`./constraints_physics.ts`, *The environment*). Either half may be left
+ * out to keep the one that stands. So a gust is the consumer setting `wind`
+ * to `[0, 0]` at rest and `[k, 0]` while it blows, and a constraint that
+ * states `wind: 0` does not feel it — the response is the rig's, the gust the
+ * scene's.
+ *
+ * `physicsTranslate(x, y)` and `physicsRotate(x, y, degrees)` are the
+ * runtime's `Skeleton` methods of those names: the consumer moved or turned
+ * the whole rig since the last pose — in the skeleton's world, y up, degrees
+ * counter-clockwise — and every constraint's next update sees its bone move
+ * by that much, so a rig walked across the screen trails what hangs from it.
+ * A player forwards what spine-core's `SkeletonPhysicsMovement` forwards: the
+ * change of its display object's position since the last frame, converted into
+ * the skeleton's units and axes, and the change of its rotation about the
+ * skeleton's origin, `physicsRotate(0, 0, Δ)`, both before the `step` that
+ * poses the frame.
+ *
+ * `CO56` holds the poses to spine-core 4.3.13 given the same values on its
+ * `Skeleton`, and holds red the readings the mapping rejects; `CO57` holds that
+ * nothing set — or the runtime's own values set on every step and a move of 0
+ * — poses what the track posed before the methods existed, bit for bit.
+ *
  * ## The oracle chain
  *
  * Nothing here is held to spine-core directly but the events: the live track
@@ -192,9 +222,11 @@
  * history, so a seek is "open, then step to the time".
  */
 import { CoreInputError, type CompiledDocument } from './index.ts';
-import { checkedClock, openRawTrack, stepRawTrack, type RawPose, type RawReset, type TrackState, type WalkMode } from './raw.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';
+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*). */
 export interface TrackOptions {
@@ -217,6 +249,14 @@ export interface LiveTrack {
   readonly animationTime: number;
   /** The runtime's duration of the animation (`CoreAnimationTimelines.duration`). */
   readonly duration: number;
+  /** Sets the world every physics constraint answers from the next pose on (the header's *The environment*): `wind` and `gravity` as spine-core's `Skeleton.windX, windY` and `gravityX, gravityY` — x right, y down — either left out to keep the one that stands. Until set, `{ wind: [1, 0], gravity: [0, 1] }`, the runtime's own. */
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void;
+  /** The environment the next pose answers. */
+  readonly environment: PhysicsEnvironment;
+  /** 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. */
+  physicsRotate(x: number, y: number, degrees: number): void;
 }
 
 /** The two modes: a track that holds at its duration is the raw entry's walk; a looping one fires its events across the wrap and cuts its clipped rows (`live`). Neither keeps a non-finite value. */
@@ -264,6 +304,30 @@ class Track implements LiveTrack {
     return this.track.duration;
   }
 
+  get environment(): PhysicsEnvironment {
+    return environmentOf(this.track.ctx);
+  }
+
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void {
+    this.live('setEnvironment');
+    setEnvironmentOn(this.track.ctx, environment, 'the live track\'s');
+  }
+
+  physicsTranslate(x: number, y: number): void {
+    this.live('physicsTranslate');
+    translateOn(this.track.ctx, x, y, 'the live track\'s');
+  }
+
+  physicsRotate(x: number, y: number, degrees: number): void {
+    this.live('physicsRotate');
+    rotateOn(this.track.ctx, x, y, degrees, 'the live track\'s');
+  }
+
+  /** A refused track refuses every call that would move it, naming the step it was refused at. */
+  private live(call: string): void {
+    if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again (${call} not made)`);
+  }
+
   step(dt: number): RawPose {
     const n = this.steps + 1;
     if (this.refused !== null) throw new CoreInputError(`the live track was refused at step ${this.refused}, after its time and physics had moved; open the track again`);

package/src/core/tracks.ts

@@ -164,7 +164,8 @@ 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 { checkedClock, openRawTracksPath, type RawPose, type RawReset, type RawTracksPath } from './raw.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 { 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*). */
@@ -228,6 +229,14 @@ export interface LiveTracks {
   current(track: number): TrackEntryView | null;
   /** The running sum of the steps taken, 0 before the first. */
   readonly trackTime: number;
+  /** Sets the world every physics constraint answers from the next pose on, as `LiveTrack.setEnvironment` (`./track.ts`, *The environment*). */
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void;
+  /** The environment the next pose answers. */
+  readonly environment: PhysicsEnvironment;
+  /** spine-core's `Skeleton.physicsTranslate`, as `LiveTrack.physicsTranslate`. */
+  physicsTranslate(x: number, y: number): void;
+  /** spine-core's `Skeleton.physicsRotate`, as `LiveTrack.physicsRotate`. */
+  physicsRotate(x: number, y: number, degrees: number): void;
 }
 
 /**
@@ -1333,6 +1342,25 @@ class Tracks implements LiveTracks {
     return this.time;
   }
 
+  get environment(): PhysicsEnvironment {
+    return environmentOf(this.path.ctx);
+  }
+
+  setEnvironment(environment: Partial<PhysicsEnvironment>): void {
+    this.live('setEnvironment');
+    setEnvironmentOn(this.path.ctx, environment, 'the live tracks\'');
+  }
+
+  physicsTranslate(x: number, y: number): void {
+    this.live('physicsTranslate');
+    translateOn(this.path.ctx, x, y, 'the live tracks\'');
+  }
+
+  physicsRotate(x: number, y: number, degrees: number): void {
+    this.live('physicsRotate');
+    rotateOn(this.path.ctx, x, y, degrees, 'the live tracks\'');
+  }
+
   private live(call: string): void {
     if (this.refused !== null) throw new CoreInputError(`the live tracks were refused at ${this.refused}, after their entries and physics had moved; open them again (${call} not made)`);
   }