@rig-c/core 2.74.1 → 2.75.0

package/docs/AUTHORING.md

@@ -5578,6 +5578,43 @@ 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`).
 
+Both `LiveTrack` and `LiveTracks` also accept an optional last `scope` argument
+for movement, a readonly array of **exact physics constraint names** (play #197):
+
+```ts
+track.physicsTranslate(dx, dy, ['hair_left', 'hair_right']);
+track.physicsRotate(pivotX, pivotY, deltaDegrees, ['hair_left', 'hair_right']);
+```
+
+Omitted or `undefined` means every existing state, exactly as before. `[]`
+selects none; repeated names select once, in the existing state order. Every
+name is checked against the document before any state changes: an unknown name
+is refused as `physics movement scope: no constraint "name"`; a non-physics
+constraint is refused naming its kind. A non-array scope or non-string name
+also refuses. Finite movement/pivot checks still apply, including an empty
+scope. A declared inactive constraint is a valid selection; movement creates
+no state for it. No document, parameter override, clock or held pose is changed.
+
+These are synchronous **before-evaluation** inputs: only the selected remembered
+origins (`ux`, `uy`, `cx`, `cy`) change, so the next `step` sees extra apparent
+motion. Distances and the explicit pivot are skeleton world units, x right,
+y up; the angle is degrees CCW **in the XY plane**, not yaw or pitch. The turn
+is the displacement of each remembered origin around the pivot, not a direct
+angular impulse; an origin at the pivot has no displacement. The caller derives
+any projected yaw/pitch displacement from its own geometry and depth. Do not
+supply it again for movement the bone itself already makes.
+
+The ordinary step still owns reset, inertia, limits and integration. A reset
+or first active update can overwrite this input; an intervening `step(0)` may
+consume it without the intended positive-time response. There is no queue or
+motion-history replay. Input writes leave all unselected states unchanged;
+after stepping, exact isolation holds for independent chains. Descendants or
+constraints that read a selected bone may react through their normal solver
+dependencies. Scope does not suppress that coupling or expand itself to cover it.
+`CO64` checks single/composed tracks, both resets, exact independent-state
+isolation, native per-constraint operations, empty/all/repeated selections and
+atomic named refusals; the existing `CO56`/`CO57` cover unscoped movement.
+
 For a live preview of one named constraint (issue #1541), both `LiveTrack` and
 `LiveTracks` on `rig-c/core` expose:
 

package/package.json

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

@@ -645,8 +645,9 @@ export const DEFAULT_PHYSICS_ENVIRONMENT: PhysicsEnvironment = Object.freeze({ w
  * 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()) {
+export function translatePhysics(ctx: PhysicsStepContext, x: number, y: number, scope?: ReadonlySet<string>): void {
+  for (const [name, s] of ctx.states) {
+    if (scope !== undefined && !scope.has(name)) continue;
     s.ux -= x;
     s.uy -= y;
     s.cx -= x;
@@ -661,11 +662,12 @@ export function translatePhysics(ctx: PhysicsStepContext, x: number, y: number):
  * 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 {
+export function rotatePhysics(ctx: PhysicsStepContext, x: number, y: number, degrees: number, scope?: ReadonlySet<string>): void {
   const r = degrees * RUNTIME_RAD;
   const cos = Math.cos(r);
   const sin = Math.sin(r);
-  for (const s of ctx.states.values()) {
+  for (const [name, s] of ctx.states) {
+    if (scope !== undefined && !scope.has(name)) continue;
     const dx = s.cx - x;
     const dy = s.cy - y;
     const tx = dx * cos - dy * sin - dx;

package/src/core/raw.ts

@@ -728,20 +728,36 @@ export function environmentOf(ctx: PhysicsStepContext): PhysicsEnvironment {
   return ctx.env ?? DEFAULT_PHYSICS_ENVIRONMENT;
 }
 
+/** Validate the complete explicit selection before any remembered state changes. */
+export function checkedPhysicsScope(doc: CompiledDocument, scope: readonly string[] | undefined, who: string): ReadonlySet<string> | undefined {
+  if (scope === undefined) return undefined;
+  if (!Array.isArray(scope)) throw new CoreInputError(`${who} physics movement scope is ${String(scope)}, not an array of physics constraint names`);
+  const selected = new Set<string>();
+  for (const name of scope) {
+    if (typeof name !== 'string') throw new CoreInputError(`${who} physics movement scope name ${String(name)} is not a string`);
+    const constraint = doc.constraints.find((c) => c.kind === 'physics' && c.name === name)
+      ?? doc.constraints.find((c) => c.name === name);
+    if (constraint === undefined) throw new CoreInputError(`${who} physics movement scope: no constraint "${name}"; this document declares [${doc.constraints.map((c) => c.name).join(', ')}]`);
+    if (constraint.kind !== 'physics') throw new CoreInputError(`${who} physics movement scope: constraint "${name}" is ${constraint.kind}, not physics`);
+    selected.add(name);
+  }
+  return selected;
+}
+
 /** 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 {
+export function translateOn(ctx: PhysicsStepContext, x: number, y: number, who: string, scope?: ReadonlySet<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);
+  translatePhysics(ctx, x, y, scope);
 }
 
 /** 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 {
+export function rotateOn(ctx: PhysicsStepContext, x: number, y: number, degrees: number, who: string, scope?: ReadonlySet<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);
+  rotatePhysics(ctx, x, y, degrees, scope);
 }
 
 /**

package/src/core/track.ts

@@ -222,7 +222,7 @@
  * history, so a seek is "open, then step to the time".
  */
 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 { checkedClock, checkedPhysicsScope, 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';
 import { LivePhysicsParameters, type PhysicsParameterPatch, type PhysicsParameterRead } from './physics_parameters.ts';
@@ -261,10 +261,12 @@ export interface LiveTrack {
   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. */
-  physicsRotate(x: number, y: number, degrees: number): void;
+  /** Scope omitted: all physics; otherwise exact physics names, validated atomically. Empty selects none, duplicates select once.
+   * Movement changes remembered world origins synchronously, before the next evaluation.
+   * 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, scope?: readonly string[]): void;
+  /** Same scope contract as physicsTranslate. The consumer turned by `degrees` (counter-clockwise) about explicit `(x, y)` in the skeleton's world; changes remembered origins, not tip direction or angular velocity. */
+  physicsRotate(x: number, y: number, degrees: number, scope?: readonly string[]): 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. */
@@ -336,14 +338,14 @@ class Track implements LiveTrack {
     this.parameters.clear(name);
   }
 
-  physicsTranslate(x: number, y: number): void {
+  physicsTranslate(x: number, y: number, scope?: readonly string[]): void {
     this.live('physicsTranslate');
-    translateOn(this.track.ctx, x, y, 'the live track\'s');
+    translateOn(this.track.ctx, x, y, 'the live track\'s', checkedPhysicsScope(this.track.doc, scope, 'the live track\'s'));
   }
 
-  physicsRotate(x: number, y: number, degrees: number): void {
+  physicsRotate(x: number, y: number, degrees: number, scope?: readonly string[]): void {
     this.live('physicsRotate');
-    rotateOn(this.track.ctx, x, y, degrees, 'the live track\'s');
+    rotateOn(this.track.ctx, x, y, degrees, 'the live track\'s', checkedPhysicsScope(this.track.doc, scope, 'the live track\'s'));
   }
 
   /** A refused track refuses every call that would move it, naming the step it was refused at. */

package/src/core/tracks.ts

@@ -164,7 +164,7 @@ import { activeBones, CoreInputError, rawNumber, shownAttachment, viewColours, W
 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, environmentOf, openRawTracksPath, rotateOn, setEnvironmentOn, translateOn, type RawPose, type RawReset, type RawTracksPath } from './raw.ts';
+import { checkedClock, checkedPhysicsScope, 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';
@@ -240,10 +240,12 @@ export interface LiveTracks {
   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`. */
-  physicsRotate(x: number, y: number, degrees: number): void;
+  /** Scope omitted: all physics; otherwise exact physics names, validated atomically. Empty selects none, duplicates select once.
+   * Movement changes remembered world origins synchronously, before the next evaluation.
+   * spine-core's `Skeleton.physicsTranslate`, as `LiveTrack.physicsTranslate`. */
+  physicsTranslate(x: number, y: number, scope?: readonly string[]): void;
+  /** Same exact-name scope and explicit world pivot as `LiveTrack.physicsRotate`. */
+  physicsRotate(x: number, y: number, degrees: number, scope?: readonly string[]): void;
 }
 
 /**
@@ -1384,14 +1386,14 @@ class Tracks implements LiveTracks {
     this.parameters.clear(name);
   }
 
-  physicsTranslate(x: number, y: number): void {
+  physicsTranslate(x: number, y: number, scope?: readonly string[]): void {
     this.live('physicsTranslate');
-    translateOn(this.path.ctx, x, y, 'the live tracks\'');
+    translateOn(this.path.ctx, x, y, 'the live tracks\'', checkedPhysicsScope(this.doc, scope, 'the live tracks\''));
   }
 
-  physicsRotate(x: number, y: number, degrees: number): void {
+  physicsRotate(x: number, y: number, degrees: number, scope?: readonly string[]): void {
     this.live('physicsRotate');
-    rotateOn(this.path.ctx, x, y, degrees, 'the live tracks\'');
+    rotateOn(this.path.ctx, x, y, degrees, 'the live tracks\'', checkedPhysicsScope(this.doc, scope, 'the live tracks\''));
   }
 
   private live(call: string): void {