@vgai/engine 0.2.0 → 0.3.0

package/src/animation/theatre-clock-binding.ts

@@ -0,0 +1,111 @@
+import type { ISequence } from '@theatre/core';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
+
+/**
+ * D2 — bind the canonical `AnimationClock` to a Theatre sequence's playhead
+ * (spec §10 D2, §5.3, §3.2).
+ *
+ * This is VGAI's ENTIRE glue for Theatre integration on the clock side:
+ * games import and configure `@theatre/core` with its own native vocabulary
+ * (`getProject`/`types`/`sheet`/`object`, spec §5.3) — there is no renamed
+ * Theatre API here. The only thing VGAI owns is *who drives time*: the
+ * canonical clock is the single source of truth, and this binding seeks
+ * Theatre's sequence position to match it every time the clock moves. Theatre
+ * must never be left to drive its own `requestAnimationFrame` loop — see the
+ * module doc on `animation-clock.ts` for why (deterministic export, offline
+ * scrubbing, no wall-clock dependency).
+ *
+ * ## Why setting `sequence.position` is enough (no `sequence.play()`)
+ *
+ * Theatre's `ISequence.position` setter synchronously updates every bound
+ * `SheetObject`'s pull-based `.value` (proven against the real `@theatre/core`
+ * runtime in `packages/engine/test/theatre-binding.test.ts` — setting
+ * `position` and immediately reading `.value` reflects the new keyframe
+ * interpolation with no `requestAnimationFrame`/ticker wait, which is exactly
+ * what makes this safe to drive from a synchronous, wall-clock-free
+ * `AnimationClock.seek()`/`advance()` call, including headlessly in Node for
+ * the render/export seam, I2). Theatre's *push* notification channel
+ * (`onValuesChange`/`onChange`) is batched on its own internal raf-driven
+ * ticker — it is not delivered 1:1 with each programmatic `position` write,
+ * so a subscriber can observe several coalesced position writes as a single
+ * notification, or (in a headless/no-raf context) none at all — so object
+ * bindings (`theatre-object-binding.ts`) deliberately read `sheetObject.value`
+ * (pull) after this binding has run, rather than subscribing to Theatre's
+ * push channel, to stay exactly in lockstep with the clock.
+ *
+ * ## Phase choice
+ *
+ * Note on phase semantics: `phase` here orders evaluators WITHIN a single
+ * clock `emit()` — i.e. within one `seek()`/`advance()` call — using the
+ * engine's `SystemPhaseName` vocabulary purely as a shared, familiar naming
+ * convention (`animation-clock.ts`'s module doc). It does NOT mean an
+ * evaluator registered at, say, `'preRender'` executes during the live
+ * engine's own `system-runner` `preRender` phase call within a running RAF
+ * frame — the `AnimationClock` is independent of the live game loop's phase
+ * execution, and during offline export/scrub there is no RAF frame at all.
+ * `phase` only orders same-emit evaluators relative to each other (e.g.
+ * guaranteeing this clock-to-sequence binding runs before an object binding
+ * reads the sequence on the same crossing), never relative to unrelated
+ * engine systems that happen to run in a same-named phase during a live
+ * frame.
+ *
+ * Registered by default at the `'animation'` phase — the same phase
+ * XState-bound `AnimationMixer` playback ticks in (see `ARCHITECTURE.md`'s
+ * phase table: `... gameLogic → animation → preRender → render`). Object
+ * bindings (`bindObject3DTransform`/`bindCameraLens`) default to `'preRender'`
+ * (the documented home for camera placement/material tick) specifically so
+ * `PHASE_ORDER` — not registration order — guarantees they observe the
+ * position this binding just set, regardless of which binding a caller sets
+ * up first.
+ */
+
+export interface TheatreClockBindingOptions {
+  /**
+   * Which `AnimationClock` phase to seek the sequence in. Defaults to
+   * `'animation'`. Any object binding reading this sheet's objects should use
+   * a phase that runs no earlier (see module doc above) — `'preRender'`, the
+   * default for `bindObject3DTransform`/`bindCameraLens`, always qualifies.
+   */
+  phase?: SystemPhaseName;
+}
+
+export interface TheatreClockBinding {
+  /** Removes the clock evaluator. No further `sequence.position` writes occur after this. */
+  dispose(): void;
+}
+
+/**
+ * Subscribe `sequence.position = clock.time` to every crossing of `clock` in
+ * the given phase (default `'animation'`). Returns a disposer; call it to
+ * stop driving the sequence (e.g. on `GameCleanup.dispose()` or before
+ * rebinding on hot reload — this is what keeps HMR from accumulating
+ * duplicate listeners, since re-running `setup()` disposes the old binding
+ * before creating a new one).
+ *
+ * Multiple sheets/sequences can each get their own binding with no shared
+ * mutable state on VGAI's side — collision avoidance for the underlying
+ * Theatre project/sheet identity is Theatre's own `getProject(id)`/
+ * `project.sheet(id)` namespacing (spec §5.3), which this function does not
+ * touch or wrap.
+ */
+export function bindClockToTheatreSequence(
+  clock: AnimationClock,
+  sequence: ISequence,
+  options: TheatreClockBindingOptions = {},
+): TheatreClockBinding {
+  const phase = options.phase ?? 'animation';
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    sequence.position = clock.time;
+  });
+
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+    },
+  };
+}

package/src/animation/theatre-director.ts

@@ -0,0 +1,347 @@
+import type { ISheetObject, UnknownShorthandCompoundProps } from '@theatre/core';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
+
+/**
+ * D4 — the Theatre "Director" convention (spec §10 D4, §5.3, §3.2).
+ *
+ * A `Director` is an ordinary Theatre Sheet Object, authored with Theatre's
+ * NATIVE `types.stringLiteral`/`types.boolean` vocabulary exactly as shown in
+ * spec §5.3 — this module never wraps or renames that API. It is a
+ * *convention* (a documented, stable shape) plus a thin binding, not a new
+ * animation format:
+ *
+ * ```ts
+ * import { types } from '@theatre/core';
+ * const director = sheet.object('Director', {
+ *   activeCamera: types.stringLiteral('wide', { wide: 'wide', close: 'close', gameplay: 'gameplay' }),
+ *   shot: types.stringLiteral('opening', { opening: 'opening', reveal: 'reveal', ending: 'ending' }),
+ *   letterbox: types.boolean(false),
+ *   // extensible: any additional directorial prop is carried through verbatim
+ *   // as `DirectorState.extras`, e.g.:
+ *   blendSeconds: types.number(0, { range: [0, Infinity] }),
+ * });
+ * ```
+ *
+ * `activeCamera`/`shot`/`letterbox` are required by the convention (spec §10
+ * D4 AC: "covers active camera, shot ID, letterbox, and optional directorial
+ * properties"). Anything else declared on the same Theatre object (exposure,
+ * grade, a blend-duration prop, ...) is an "optional directorial property" —
+ * it is read and surfaced verbatim through `DirectorState.extras`, never
+ * hardcoded here, which is what keeps the convention extensible without
+ * VGAI inventing a schema for it.
+ *
+ * ## Binding: pull-based, same lockstep pattern as D2/D3
+ *
+ * `bindDirectorToClock` follows exactly the `theatre-clock-binding.ts` /
+ * `theatre-object-binding.ts` pattern: it reads the Director object's
+ * pull-based `sheetObject.value` on every canonical-clock crossing (never
+ * Theatre's own batched `onValuesChange` push channel — see those modules'
+ * doc comments for why that would desync from a synchronous `clock.seek()`).
+ * Default phase is `'preRender'`, the same default `bindObject3DTransform`/
+ * `bindCameraLens` use, so — via `PHASE_ORDER`, not registration order — the
+ * Director always reads a sequence position that `bindClockToTheatreSequence`
+ * (registered at `'animation'`, which runs earlier) has already set for this
+ * crossing, regardless of which binding a caller sets up first.
+ *
+ * ## Seeking updates Director without firing gameplay cues
+ *
+ * This binding has NO concept of "seek" vs "advance" — unlike
+ * `CueRunner` (D5, `cinematic-cues.ts`), which deliberately distinguishes the
+ * two (via its own `seek()`/`advance()` wrapper methods) so a
+ * `firesDuringSeek: false` cue can be skipped on scrub. A Director value is
+ * *visual/directorial state*, not a gameplay consequence (spec §3.2: "Theatre
+ * carries visual/directorial values; ordinary TypeScript cues carry gameplay
+ * consequences") — it should always reflect the clock's current time,
+ * however the clock got there. Composing the two on the SAME
+ * `AnimationClock` (Director bound directly to the clock; cues bound through
+ * a `CueRunner` wrapping the same clock) is exactly what makes "seek updates
+ * Director but does not spuriously fire gameplay cues" fall out for free: a
+ * `CueRunner.seek(t)` call moves the one shared clock, which both this
+ * binding (always reacts) and the cue runner (gates on `firesDuringSeek`)
+ * observe on the same crossing. See `theatre-director.test.ts`'s
+ * "composes with D5" suite for the proof.
+ *
+ * ## Camera-ownership hook — the D6 seam
+ *
+ * Discrete `activeCamera` changes are exactly the moments a *camera
+ * ownership* system (D6, not built in this unit) needs to know about, to cut
+ * or blend the live gameplay camera to the Director's declared shot. This
+ * module does not own or perform any camera mutation — it only DETECTS a
+ * change in the Director's `activeCamera` value across successive
+ * evaluations and reports it through `onActiveCameraChange`
+ * (`CameraOwnershipHook`), a minimal, one-directional seam:
+ *
+ *  - fired once per detected `activeCamera` transition (never for a
+ *    no-op/unchanged evaluation, including a re-seek to the same time or a
+ *    seek that stays within the same shot's camera);
+ *  - the FIRST evaluation after bind is treated as an "assignment", not a
+ *    "cut from something" — `previousCameraKey` is `null` and `mode` is
+ *    forced to `'cut'` (there is nothing to blend FROM yet; D6 is expected
+ *    to use this event to perform its initial camera capture/placement);
+ *  - `mode`/`blendSeconds` are derived from an optional extra numeric prop on
+ *    the SAME Director object (`blendSecondsKey`, default `'blendSeconds'`)
+ *    — a positive value at the moment of the transition means `'blend'`
+ *    (with that duration), anything else means `'cut'`. This is the "expose
+ *    enough for a consumer to cut or blend" seam named in the D4 AC; the
+ *    ACTUAL blend implementation (interpolating the live camera pose over
+ *    `blendSeconds`) is D6's job, not this module's.
+ *
+ * ### `blendSeconds` MUST be authored as HOLD keyframes
+ *
+ * `blendSeconds` is read at the EXACT moment `activeCamera` is detected to
+ * change, whatever clock time that happens to land on. If `blendSeconds` is
+ * authored as an ordinary interpolating (bezier) track, a transition
+ * detected at a time that isn't exactly a keyframe position reads whatever
+ * partially-interpolated value the bezier curve has reached AT THAT MOMENT —
+ * not the value actually authored FOR that transition. Concretely: a cut
+ * authored at `t=3` with `blendSeconds=0`, followed by a blend authored at
+ * `t=6` with `blendSeconds=1.5`, makes the track interpolate from `0` to
+ * `1.5` across `[3, 6)`. If the `activeCamera` transition at `t=3` is first
+ * *observed* at some later non-keyframe time inside that span (e.g. a coarse
+ * seek from `t=2` straight to `t=4.5`, skipping past `t=3` without an
+ * intermediate evaluation), `blendSeconds` at `t=4.5` reads a nonzero,
+ * partially-interpolated value — misreporting an authored CUT as a partial
+ * BLEND.
+ *
+ * The fix is to author `blendSeconds` keyframes as Theatre HOLD keyframes
+ * (`connectedRight: false`, optionally also `type: 'hold'`) rather than the
+ * default interpolating bezier keyframes. `connectedRight: false` makes
+ * Theatre's own sequence evaluator hold the LEFT keyframe's value constant
+ * across the entire span up to (not including) the next keyframe, then snap
+ * — never partially interpolate. With `blendSeconds` authored this way, its
+ * value at ANY time within `[3, 6)` reads exactly `0` (the cut authored at
+ * `t=3`), and only reads `1.5` once the clock reaches `t=6` (the blend
+ * authored there) — correct regardless of which non-keyframe time a
+ * transition happens to first be observed at. See
+ * `fixtures/theatre-director-proof.theatre-project.json` (its `blendSeconds`
+ * track uses `connectedRight: false` on every keyframe) and
+ * `theatre-director.test.ts`'s "playback grid" suite, which proves this by
+ * evaluating a fine-grained, non-keyframe-aligned time grid across the whole
+ * span and asserting the reported `mode` never drifts from what was
+ * authored at the keyframe that produced the transition.
+ *
+ * D6 will most likely implement `CameraOwnershipHook` as (roughly) "capture
+ * gameplay camera pose once on the first `mode: 'cut'` event; on each
+ * subsequent event, cut or blend the owned camera to the shot named by
+ * `cameraKey`". Nothing above depends on that implementation existing —
+ * `onActiveCameraChange` is optional and this module works with no hook
+ * attached at all (Director values are still readable via `getState()`).
+ *
+ * ## Read API (SDK/CLI seam, B5)
+ *
+ * `readDirectorState` is a pure, synchronous read of whatever a Director
+ * Theatre object's CURRENT value is — no clock/binding required. It is what
+ * a later `cinematic.*` SDK/CLI operation (B5) would call to inspect Director
+ * state (e.g. "what shot is authored at time t") without needing to spin up
+ * a full runtime binding. `TheatreDirectorBinding.getState()` is the
+ * clock-driven equivalent — it returns the value read at bind time until the
+ * FIRST clock crossing occurs (not "the most recent crossing" — before any
+ * crossing there IS no crossing yet), and the value as of the most recent
+ * crossing thereafter.
+ *
+ * Authoring `Director` keyframes in Theatre Studio is a dev-only workflow
+ * (spec §10 D2: "Theatre Studio is available only in authoring/development
+ * contexts"); the committed project-state JSON is the source of truth this
+ * module reads in production — nothing here imports the Theatre Studio
+ * package (see `theatre-binding.test.ts`'s repo-wide grep proof of that).
+ */
+
+/** Thrown when a Theatre object does not conform to the Director convention. */
+export class TheatreDirectorError extends Error {
+  constructor(
+    message: string,
+    readonly objectKey: string,
+  ) {
+    super(message);
+    this.name = 'TheatreDirectorError';
+  }
+}
+
+/** The Director convention's three required props, plus everything else verbatim. */
+export interface DirectorState {
+  readonly activeCamera: string;
+  readonly shot: string;
+  readonly letterbox: boolean;
+  /**
+   * Any additional directorial props declared on the same Theatre object
+   * (e.g. `exposure`, `grade`, `blendSeconds`), captured verbatim from
+   * `sheetObject.value`. The Director convention is deliberately extensible
+   * here — VGAI does not enumerate or validate extras beyond the three
+   * required props.
+   */
+  readonly extras: Readonly<Record<string, unknown>>;
+}
+
+const REQUIRED_DIRECTOR_KEYS = new Set(['activeCamera', 'shot', 'letterbox']);
+
+/**
+ * Pure, synchronous read of a Director Theatre object's CURRENT value.
+ * No clock/binding involved — suitable for one-shot inspection (the later
+ * SDK/CLI read path, B5) as well as being the function
+ * `bindDirectorToClock` itself calls on every crossing.
+ *
+ * @throws {TheatreDirectorError} if the object's value does not conform to
+ *   the Director convention (missing/mistyped `activeCamera`/`shot`/`letterbox`).
+ */
+export function readDirectorState<Props extends UnknownShorthandCompoundProps>(
+  sheetObject: ISheetObject<Props>,
+): DirectorState {
+  const raw = sheetObject.value as Record<string, unknown>;
+  const objectKey = sheetObject.address.objectKey;
+
+  const activeCamera = raw['activeCamera'];
+  if (typeof activeCamera !== 'string') {
+    throw new TheatreDirectorError(
+      `[readDirectorState] Director object "${objectKey}" is missing a string "activeCamera" prop — ` +
+        `declare it with types.stringLiteral(...) (spec §5.3/§10 D4)`,
+      objectKey,
+    );
+  }
+
+  const shot = raw['shot'];
+  if (typeof shot !== 'string') {
+    throw new TheatreDirectorError(
+      `[readDirectorState] Director object "${objectKey}" is missing a string "shot" prop — ` +
+        `declare it with types.stringLiteral(...) (spec §5.3/§10 D4)`,
+      objectKey,
+    );
+  }
+
+  const letterbox = raw['letterbox'];
+  if (typeof letterbox !== 'boolean') {
+    throw new TheatreDirectorError(
+      `[readDirectorState] Director object "${objectKey}" is missing a boolean "letterbox" prop — ` +
+        `declare it with types.boolean(...) (spec §5.3/§10 D4)`,
+      objectKey,
+    );
+  }
+
+  const extras: Record<string, unknown> = {};
+  for (const key of Object.keys(raw)) {
+    if (!REQUIRED_DIRECTOR_KEYS.has(key)) extras[key] = raw[key];
+  }
+
+  return { activeCamera, shot, letterbox, extras: Object.freeze(extras) };
+}
+
+/** Whether a reported `activeCamera` transition should be a hard cut or a blend. */
+export type CameraCutMode = 'cut' | 'blend';
+
+/**
+ * One detected `activeCamera` transition. This is the entire payload the
+ * D6 camera-ownership system needs to decide what to do — it carries no
+ * camera object or mutation itself (that stays entirely on the consumer's
+ * side, matching "no arbitrary unsafe property-path evaluator" / "thin
+ * integration code" throughout D2-D5).
+ */
+export interface CameraOwnershipChangeEvent {
+  /** The Director's new `activeCamera` value. */
+  readonly cameraKey: string;
+  /** The Director's previous `activeCamera` value, or `null` on the first (assignment) event. */
+  readonly previousCameraKey: string | null;
+  /** `'cut'` unless a positive blend duration was authored for this transition. */
+  readonly mode: CameraCutMode;
+  /** Blend duration in seconds; `0` for a `'cut'`. */
+  readonly blendSeconds: number;
+  /** The Director's `shot` value at the moment of this transition, for convenience. */
+  readonly shot: string;
+}
+
+/**
+ * D6 seam: implemented fully by the camera-ownership/restoration system
+ * (spec §10 D6). This module only detects and reports discrete
+ * `activeCamera` transitions — it performs no camera capture, cut, blend, or
+ * restoration itself.
+ */
+export type CameraOwnershipHook = (event: CameraOwnershipChangeEvent) => void;
+
+export interface TheatreDirectorBindingOptions {
+  /**
+   * Which `AnimationClock` phase to evaluate the Director in. Defaults to
+   * `'preRender'` (see module doc — guaranteed by `PHASE_ORDER` to observe a
+   * sequence position `bindClockToTheatreSequence`'s `'animation'`-phase
+   * default has already set for this crossing).
+   */
+  phase?: SystemPhaseName;
+  /** Camera-ownership seam (D6) — see module doc. Optional; omit to just read state. */
+  onActiveCameraChange?: CameraOwnershipHook;
+  /**
+   * Name of an optional extra numeric Director prop that carries the blend
+   * duration (seconds) for the transition landing on the CURRENT
+   * evaluation. Defaults to `'blendSeconds'`. Absent, non-numeric, or
+   * non-positive at the moment of a transition reports `mode: 'cut'`.
+   */
+  blendSecondsKey?: string;
+}
+
+export interface TheatreDirectorBinding {
+  /**
+   * Current Director state (D4 AC: inspectable read API). Before the first
+   * clock crossing, this is the bind-time value (`readDirectorState` called
+   * once at bind); from the first crossing onward, it is the value as of the
+   * most recent crossing.
+   */
+  getState(): DirectorState;
+  /** Removes the clock evaluator. No further evaluation (or hook calls) occurs after this. */
+  dispose(): void;
+}
+
+/**
+ * Bind a Director Theatre Sheet Object to `clock`: on every crossing, read
+ * its current value (`readDirectorState`) and, if `activeCamera` changed
+ * since the last evaluation, report the transition through
+ * `onActiveCameraChange` (the D6 seam). Returns a disposer and a `getState()`
+ * read API. See the module doc comment for the full contract.
+ */
+export function bindDirectorToClock<Props extends UnknownShorthandCompoundProps>(
+  clock: AnimationClock,
+  sheetObject: ISheetObject<Props>,
+  options: TheatreDirectorBindingOptions = {},
+): TheatreDirectorBinding {
+  const phase = options.phase ?? 'preRender';
+  const blendSecondsKey = options.blendSecondsKey ?? 'blendSeconds';
+
+  let state: DirectorState = readDirectorState(sheetObject);
+  let previousCameraKey: string | null = null;
+  let hasEvaluatedOnClock = false;
+
+  function evaluate(): void {
+    state = readDirectorState(sheetObject);
+
+    const changed = !hasEvaluatedOnClock || state.activeCamera !== previousCameraKey;
+    if (changed) {
+      const blendRaw = state.extras[blendSecondsKey];
+      const blendSeconds =
+        hasEvaluatedOnClock && typeof blendRaw === 'number' && blendRaw > 0 ? blendRaw : 0;
+      const mode: CameraCutMode = blendSeconds > 0 ? 'blend' : 'cut';
+
+      options.onActiveCameraChange?.({
+        cameraKey: state.activeCamera,
+        previousCameraKey: hasEvaluatedOnClock ? previousCameraKey : null,
+        mode,
+        blendSeconds,
+        shot: state.shot,
+      });
+
+      previousCameraKey = state.activeCamera;
+      hasEvaluatedOnClock = true;
+    }
+  }
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    evaluate();
+  });
+
+  let disposed = false;
+  return {
+    getState(): DirectorState {
+      return state;
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      handle.dispose();
+    },
+  };
+}