@vgai/engine 0.2.0 → 0.3.0

package/src/animation/camera-ownership.ts

@@ -0,0 +1,467 @@
+import * as THREE from 'three';
+import type { SystemPhaseName } from '../core/types';
+import type { AnimationClock, ClockEvaluatorHandle } from './animation-clock';
+import type { CameraOwnershipChangeEvent } from './theatre-director';
+
+/**
+ * D6 — Camera Ownership and Restoration (spec §10 D6, §3.2, §4).
+ *
+ * VGAI owns exactly one thing here: WHO is allowed to move the live,
+ * actually-rendered camera at any given moment, and what happens to it when
+ * that control is released. The actual camera math (cuts, blends, lens
+ * changes, orbit/follow/look-at/dolly behavior) is expressed entirely with
+ * native `THREE.PerspectiveCamera` objects — Object3D-as-truth, no camera
+ * wrapper (spec §4, `ARCHITECTURE.md`'s "the world node IS the entity"
+ * rule). This module reads and writes real Three.js camera properties
+ * (`position`, `quaternion`, `fov`, `near`, `far`) and nothing else.
+ *
+ * ## Two cooperating pieces
+ *
+ *  - `cameras`: a fixed registry of named SOURCE cameras (`cameraKey ->
+ *    THREE.PerspectiveCamera`), each an ordinary Object3D that ANY other
+ *    system may drive however it likes — a Theatre binding
+ *    (`bindObject3DTransform`/`bindCameraLens`, D3), a hand-written orbit/
+ *    follow/spline-dolly update, or a one-shot `camera.lookAt(target)` call.
+ *    This module never mutates a source camera; it only READS its current
+ *    pose at evaluation time.
+ *  - `liveCamera`: the ONE camera actually rendered. This module is the only
+ *    thing that writes to it while a cinematic owns it. Whatever ordinary
+ *    game code drives `liveCamera` the rest of the time (gameplay's own
+ *    orbit/follow controller, typically) is untouched and resumes writing to
+ *    it the moment ownership returns to "nobody" (the stack is empty).
+ *
+ * ## Ownership stack (LIFO) — the D6 nested/interrupted-cinematics rule
+ *
+ * `take(ownerId)` pushes a new ownership FRAME, capturing `liveCamera`'s
+ * CURRENT pose as that frame's `restorePose` — i.e. "whatever the camera
+ * looked like the instant this owner took over" (gameplay's pose for the
+ * first/outermost `take`, or the parent cinematic's current pose for a
+ * NESTED `take` while a parent is still on the stack). Only the TOP frame
+ * may drive the camera (`cut`/`blend`/`applyDirectorEvent`/`release` all
+ * throw `CameraOwnershipError` if `ownerId` is not the current top) — this
+ * is what makes nested ownership resolve deterministically: a second
+ * cinematic taking the camera while a first one owns it must explicitly
+ * `take()` (pushing on top) before it can drive anything, and must
+ * `release()` (popping) before the frame beneath it can drive anything
+ * again. There is no "steal without taking" path.
+ *
+ * `release(ownerId, { completed })` pops the top frame (throws if `ownerId`
+ * is not on top — the LIFO rule) and applies that frame's declared
+ * `CameraRestorePolicy` to `liveCamera` IMMEDIATELY:
+ *
+ *  - `'restore'` (default): `liveCamera` is set back to the frame's captured
+ *    `restorePose` — bit-exact, no interpolation.
+ *  - `'retain'`: `liveCamera` is left exactly as the cinematic last set it
+ *    (the cinematic's end pose).
+ *  - `'retain-if-completed'`: `'retain'` if `completed: true` was passed,
+ *    `'restore'` otherwise. This is the policy a cinematic controller (not
+ *    built in this unit — spec §3.2 names it as a future seam) would use to
+ *    express "keep the final shot if the cinematic played to its natural
+ *    end, but snap back to gameplay if it was skipped/cancelled".
+ *
+ * If a PARENT frame remains after the pop, it is NOT forcibly re-applied —
+ * the parent's own tracking/blending state (whatever it last was) simply
+ * resumes driving `liveCamera` on the next clock crossing, same as it always
+ * would. Concretely: "B stops → ownership returns to A's state" means
+ * `liveCamera` is snapped to A's captured pose the instant B releases, and
+ * then continues to be driven by A's own last `cut`/`blend` target (if any)
+ * on subsequent crossings — exactly as if B had never interrupted A. If A's
+ * target camera is static (not itself being animated), the snapped pose and
+ * the resumed-tracking pose are identical, which is what the test suite
+ * exercises for determinism.
+ *
+ * `dispose()` is the "render cleanup" path (D6 AC: "render cleanup restore
+ * or retain state according to the declared policy"): every still-open
+ * frame is released LIFO, per ITS OWN declared policy, with `completed:
+ * false` (a teardown is never a natural completion — `retain-if-completed`
+ * frames restore on cleanup, exactly like a cancel).
+ *
+ * ## Cut vs. blend — consuming the D4 `CameraOwnershipHook` seam
+ *
+ * `theatre-director.ts` (D4) detects discrete `activeCamera` transitions and
+ * reports them through `CameraOwnershipHook` — a `CameraOwnershipChangeEvent`
+ * carrying `cameraKey`/`mode`/`blendSeconds`, nothing else. This module's
+ * `applyDirectorEvent(ownerId, event)` is the entire consumption of that
+ * seam: it forwards `event.cameraKey`/`event.blendSeconds` into the same
+ * `cut`/`blend` logic a caller could invoke directly. The wiring is ordinary
+ * caller-side composition (same pattern D4/D5 already use to compose on one
+ * shared clock — see `theatre-director.test.ts`'s "composes with D5" suite):
+ *
+ * ```ts
+ * const ownership = createCameraOwnershipSystem({ liveCamera, cameras, clock });
+ * ownership.take('intro-cinematic');
+ * const directorBinding = bindDirectorToClock(clock, director, {
+ *   onActiveCameraChange: (event) => ownership.applyDirectorEvent('intro-cinematic', event),
+ * });
+ * // ...cinematic plays...
+ * ownership.release('intro-cinematic', { completed: true });
+ * directorBinding.dispose();
+ * ```
+ *
+ * The Director's FIRST event per bind is always `mode: 'cut'`
+ * (`previousCameraKey: null` — an "assignment", per the D4 module doc) —
+ * consumed exactly like any other cut, which is what performs the
+ * cinematic's INITIAL camera capture/placement onto its opening shot. A
+ * `take()` before binding the Director is required so the pre-cinematic
+ * gameplay pose is captured before that first cut lands.
+ *
+ * ## One unified transition model — cut is just a zero-duration blend
+ *
+ * Internally, `cut`/`blend`/`applyDirectorEvent` all record exactly one
+ * `FrameState` shape: `{ targetKey, fromPose, startTime, durationSeconds }`
+ * (`durationSeconds` is `0` for a cut). On EVERY clock crossing, the applied
+ * pose is a PURE function of `clock.time` and this fixed record — nothing is
+ * mutated as time passes:
+ *
+ * ```
+ * t = durationSeconds <= 0 ? 1 : clamp((clock.time - startTime) / durationSeconds, 0, 1)
+ * appliedPose = t >= 1 ? currentPoseOf(targetKey) : lerp(fromPose, currentPoseOf(targetKey), t)
+ * ```
+ *
+ * `currentPoseOf(targetKey)` is re-sampled LIVE every crossing (never a
+ * frozen snapshot), so blending onto — or having already cut to — a moving/
+ * Theatre-animated source camera tracks it correctly both mid-blend and
+ * after the blend window has fully elapsed. `fromPose` IS a fixed snapshot,
+ * taken once at the moment the transition begins (`capturePose(liveCamera)`
+ * — "wherever the camera currently is"); `t` clamps to `0` for any
+ * `clock.time` before `startTime` (holds `fromPose`) and to `1` at/after
+ * `startTime + durationSeconds` (holds the target's live current pose) —
+ * the same clamp-to-domain-boundary convention `AnimationClock` itself uses.
+ *
+ * Because nothing here depends on evaluation HISTORY (no state flips from
+ * "blending" to "tracking" as time passes — a cut IS just `durationSeconds:
+ * 0`, permanently, until the next `cut`/`blend` call replaces the record),
+ * a blend is fully deterministic under arbitrary re-seek: seeking forward
+ * past the blend end and then BACK into the blend window reproduces the
+ * exact same interpolated pose, not whatever the live target happened to be
+ * doing after the blend completed. See `camera-ownership.test.ts`'s
+ * "deterministic under re-seek" case.
+ *
+ * ## Phase choice: 'render', deliberately later than D3's 'preRender'
+ *
+ * `bindObject3DTransform`/`bindCameraLens` (D3) and `bindDirectorToClock`
+ * (D4) both default to the `'preRender'` phase. This module's own clock
+ * evaluator defaults to `'render'` — the LAST phase in `PHASE_ORDER` —
+ * specifically so `PHASE_ORDER` itself (not registration order) guarantees
+ * every registered source camera has already received its per-crossing
+ * pose update, and the Director has already fired any `applyDirectorEvent`
+ * for this crossing, before this module samples `cameras[key]` or resolves
+ * a pending transition. This is the same reasoning `theatre-director.ts`'s
+ * module doc gives for its own phase default relative to
+ * `bindClockToTheatreSequence`'s `'animation'` phase.
+ *
+ * ## Camera behaviors — what's tested vs. merely expressible
+ *
+ * Because a "source camera" is an ordinary `THREE.PerspectiveCamera` sampled
+ * fresh every crossing, ANY procedural code that mutates one earlier in
+ * `PHASE_ORDER` (or synchronously before a direct `cut`/`blend` call) is
+ * picked up automatically — this module does not special-case which
+ * mechanism produced the pose:
+ *
+ *  - **cuts, blends, FOV, near/far** — implemented and tested directly in
+ *    this module (`camera-ownership.test.ts`).
+ *  - **look-at** — tested: a source camera's orientation is set with
+ *    ordinary `camera.lookAt(target)` before a crossing; this module reads
+ *    the resulting `quaternion` like any other pose.
+ *  - **follow** — tested: a source camera's `position` is updated by
+ *    ordinary per-crossing application code (simulating a follow
+ *    controller); `currentPoseOf` re-samples it live every crossing, so the
+ *    live camera visibly follows.
+ *  - **orbit, spline-dolly** — EXPRESSIBLE via the identical mechanism
+ *    (ordinary code moves a registered source camera's `position`/
+ *    `quaternion` every crossing/frame — an orbit controller stepping an
+ *    angle, a spline sampler stepping arc-length) but not independently
+ *    tested in this unit; the follow test proves the general "procedurally
+ *    driven source camera, resampled live" path they would use.
+ */
+
+/** Restore-vs-retain policy applied when an ownership frame is released. */
+export type CameraRestorePolicy = 'restore' | 'retain' | 'retain-if-completed';
+
+/** A fully-captured camera pose: position, orientation, and lens. */
+export interface CameraPose {
+  readonly position: THREE.Vector3;
+  readonly quaternion: THREE.Quaternion;
+  readonly fov: number;
+  readonly near: number;
+  readonly far: number;
+}
+
+/** Thrown on an ownership-stack rule violation (not-current-owner, unknown camera key, duplicate take). */
+export class CameraOwnershipError extends Error {
+  constructor(
+    message: string,
+    readonly ownerId: string,
+  ) {
+    super(message);
+    this.name = 'CameraOwnershipError';
+  }
+}
+
+/** Snapshot a camera's full pose (position/quaternion cloned — never aliases the live object). */
+export function capturePose(camera: THREE.PerspectiveCamera): CameraPose {
+  return {
+    position: camera.position.clone(),
+    quaternion: camera.quaternion.clone(),
+    fov: camera.fov,
+    near: camera.near,
+    far: camera.far,
+  };
+}
+
+/** Write a captured pose onto a camera, updating its projection matrix. */
+export function applyPose(camera: THREE.PerspectiveCamera, pose: CameraPose): void {
+  camera.position.copy(pose.position);
+  camera.quaternion.copy(pose.quaternion);
+  camera.fov = pose.fov;
+  camera.near = pose.near;
+  camera.far = pose.far;
+  camera.updateProjectionMatrix();
+}
+
+/** Position LERP + quaternion SLERP + fov/near/far LERP, `t` in `[0, 1]`. */
+export function lerpPose(from: CameraPose, to: CameraPose, t: number): CameraPose {
+  return {
+    position: from.position.clone().lerp(to.position, t),
+    quaternion: from.quaternion.clone().slerp(to.quaternion, t),
+    fov: THREE.MathUtils.lerp(from.fov, to.fov, t),
+    near: THREE.MathUtils.lerp(from.near, to.near, t),
+    far: THREE.MathUtils.lerp(from.far, to.far, t),
+  };
+}
+
+/**
+ * A cut is represented as `durationSeconds: 0` — see the module doc's
+ * "one unified transition model" section. `fromPose` is unused (but always
+ * populated, for a uniform shape) when `durationSeconds <= 0`.
+ */
+interface FrameState {
+  readonly targetKey: string;
+  readonly fromPose: CameraPose;
+  readonly startTime: number;
+  readonly durationSeconds: number;
+}
+
+interface OwnershipFrame {
+  readonly ownerId: string;
+  readonly policy: CameraRestorePolicy;
+  readonly restorePose: CameraPose;
+  state: FrameState | undefined;
+}
+
+export interface CameraOwnershipTakeOptions {
+  /** Restore policy for this frame. Defaults to the system's `defaultPolicy` (itself default `'restore'`). */
+  policy?: CameraRestorePolicy;
+}
+
+export interface CameraOwnershipReleaseOptions {
+  /**
+   * Whether the cinematic reached its natural end (vs. stop/skip/cancel).
+   * Only meaningful for a frame taken with `policy: 'retain-if-completed'`.
+   * Default `false`.
+   */
+  completed?: boolean;
+}
+
+export interface CameraOwnershipSystemOptions {
+  /** The camera actually rendered. Mutated in place by this system; untouched by it while the ownership stack is empty. */
+  liveCamera: THREE.PerspectiveCamera;
+  /**
+   * `cameraKey -> source camera` registry. Each value is an ordinary
+   * `THREE.PerspectiveCamera` that other code (Theatre bindings, orbit/
+   * follow/dolly controllers, `lookAt`) is free to drive; this module only
+   * reads its pose.
+   */
+  cameras: Readonly<Record<string, THREE.PerspectiveCamera>>;
+  /** The canonical clock driving deterministic, time-based blends. */
+  clock: AnimationClock;
+  /** Default `CameraRestorePolicy` for `take()` calls that don't specify one. Default `'restore'`. */
+  defaultPolicy?: CameraRestorePolicy;
+  /** `AnimationClock` phase to evaluate tracking/blending in. Default `'render'` — see module doc. */
+  phase?: SystemPhaseName;
+}
+
+export interface CameraOwnershipSystem {
+  /** Push a new ownership frame for `ownerId`, capturing `liveCamera`'s current pose as its restore point. Throws if `ownerId` is already on the stack. */
+  take(ownerId: string, options?: CameraOwnershipTakeOptions): void;
+  /** Hard-cut the live camera to `cameraKey`'s current pose. `ownerId` must be the current (top-of-stack) owner. */
+  cut(ownerId: string, cameraKey: string): void;
+  /** Begin a deterministic, clock-driven blend to `cameraKey` over `blendSeconds`. `ownerId` must be the current owner. */
+  blend(ownerId: string, cameraKey: string, blendSeconds: number): void;
+  /** Consume a D4 `CameraOwnershipChangeEvent` directly — cuts or blends per `event.mode`/`event.blendSeconds`. */
+  applyDirectorEvent(ownerId: string, event: CameraOwnershipChangeEvent): void;
+  /** Pop the top frame for `ownerId` (must be the current owner) and apply its declared restore policy. */
+  release(ownerId: string, options?: CameraOwnershipReleaseOptions): void;
+  /** Whether `ownerId` currently owns the camera (is top of stack). */
+  isOwner(ownerId: string): boolean;
+  /** Current ownership-stack depth. `0` means gameplay (nobody) owns the camera. */
+  readonly depth: number;
+  /** Render-cleanup path: releases every open frame LIFO per its own policy (`completed: false`), then unsubscribes. */
+  dispose(): void;
+}
+
+/**
+ * Build a camera-ownership system bound to `clock`. See the module doc
+ * comment for the full ownership-stack, cut/blend, and restore-policy
+ * contract.
+ */
+export function createCameraOwnershipSystem(
+  options: CameraOwnershipSystemOptions,
+): CameraOwnershipSystem {
+  const { liveCamera, cameras, clock } = options;
+  const defaultPolicy = options.defaultPolicy ?? 'restore';
+  const phase = options.phase ?? 'render';
+
+  const stack: OwnershipFrame[] = [];
+  let disposed = false;
+
+  function requireNotDisposed(action: string): void {
+    if (disposed) {
+      throw new CameraOwnershipError(`[camera-ownership] ${action}: system has been disposed`, '');
+    }
+  }
+
+  function requireSourceCamera(cameraKey: string, action: string): THREE.PerspectiveCamera {
+    const camera = cameras[cameraKey];
+    if (!camera) {
+      throw new CameraOwnershipError(
+        `[camera-ownership] ${action}: no registered camera for key "${cameraKey}"`,
+        cameraKey,
+      );
+    }
+    return camera;
+  }
+
+  function requireTopOwner(ownerId: string, action: string): OwnershipFrame {
+    const top = stack[stack.length - 1];
+    if (!top) {
+      throw new CameraOwnershipError(
+        `[camera-ownership] ${action}: "${ownerId}" is not the current owner (ownership stack is empty)`,
+        ownerId,
+      );
+    }
+    if (top.ownerId !== ownerId) {
+      throw new CameraOwnershipError(
+        `[camera-ownership] ${action}: "${ownerId}" is not the current owner (current owner is "${top.ownerId}")`,
+        ownerId,
+      );
+    }
+    return top;
+  }
+
+  /**
+   * Apply a frame's CURRENT state to `liveCamera` — a pure function of
+   * `clock.time` and the fixed `FrameState` record (see the module doc's
+   * "one unified transition model"). Never mutates `frame.state`.
+   */
+  function evaluateFrame(frame: OwnershipFrame): void {
+    const state = frame.state;
+    if (!state) return;
+
+    const targetPose = capturePose(requireSourceCamera(state.targetKey, 'evaluate'));
+    const t =
+      state.durationSeconds <= 0
+        ? 1
+        : Math.min(Math.max((clock.time - state.startTime) / state.durationSeconds, 0), 1);
+
+    applyPose(liveCamera, t >= 1 ? targetPose : lerpPose(state.fromPose, targetPose, t));
+  }
+
+  function beginTransition(ownerId: string, cameraKey: string, durationSeconds: number): void {
+    const frame = requireTopOwner(ownerId, 'cut/blend');
+    requireSourceCamera(cameraKey, 'cut/blend'); // validate before mutating frame state
+
+    frame.state = {
+      targetKey: cameraKey,
+      fromPose: capturePose(liveCamera),
+      startTime: clock.time,
+      durationSeconds,
+    };
+
+    // Apply immediately so direct (non-clock-crossing-sourced) calls are
+    // visible right away; the per-crossing evaluator below re-applies the
+    // same result on every subsequent crossing (idempotent when called
+    // twice within the same crossing — e.g. once here, once from the D4
+    // hook's own 'preRender'-phase call site, once more from this module's
+    // later 'render'-phase evaluator).
+    evaluateFrame(frame);
+  }
+
+  function releaseFrame(frame: OwnershipFrame, completed: boolean): void {
+    const shouldRetain =
+      frame.policy === 'retain' || (frame.policy === 'retain-if-completed' && completed);
+    if (!shouldRetain) {
+      applyPose(liveCamera, frame.restorePose);
+    }
+  }
+
+  const handle: ClockEvaluatorHandle = clock.subscribe(phase, () => {
+    const top = stack[stack.length - 1];
+    if (top) evaluateFrame(top);
+  });
+
+  return {
+    take(ownerId, takeOptions = {}) {
+      requireNotDisposed('take');
+      if (stack.some((frame) => frame.ownerId === ownerId)) {
+        throw new CameraOwnershipError(
+          `[camera-ownership] take: "${ownerId}" is already on the ownership stack`,
+          ownerId,
+        );
+      }
+      stack.push({
+        ownerId,
+        policy: takeOptions.policy ?? defaultPolicy,
+        restorePose: capturePose(liveCamera),
+        state: undefined,
+      });
+    },
+
+    cut(ownerId, cameraKey) {
+      requireNotDisposed('cut');
+      beginTransition(ownerId, cameraKey, 0);
+    },
+
+    blend(ownerId, cameraKey, blendSeconds) {
+      requireNotDisposed('blend');
+      if (!Number.isFinite(blendSeconds) || blendSeconds < 0) {
+        throw new CameraOwnershipError(
+          `[camera-ownership] blend: blendSeconds must be a finite number >= 0, got ${blendSeconds}`,
+          ownerId,
+        );
+      }
+      beginTransition(ownerId, cameraKey, blendSeconds);
+    },
+
+    applyDirectorEvent(ownerId, event) {
+      requireNotDisposed('applyDirectorEvent');
+      beginTransition(ownerId, event.cameraKey, event.blendSeconds);
+    },
+
+    release(ownerId, releaseOptions = {}) {
+      requireNotDisposed('release');
+      const top = requireTopOwner(ownerId, 'release');
+      stack.pop();
+      releaseFrame(top, releaseOptions.completed ?? false);
+    },
+
+    isOwner(ownerId) {
+      const top = stack[stack.length - 1];
+      return !!top && top.ownerId === ownerId;
+    },
+
+    get depth() {
+      return stack.length;
+    },
+
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      while (stack.length > 0) {
+        const top = stack.pop();
+        if (top) releaseFrame(top, false);
+      }
+      handle.dispose();
+    },
+  };
+}