@ankhorage/zora 21.0.23 → 21.1.1

package/src/features/game/composition/createGameBindingContext.test.ts

@@ -0,0 +1,66 @@
+import type { GameSession } from '@ankhorage/game';
+import { resolveRuntimeBindingValueSync } from '@ankhorage/runtime/bindings';
+import { describe, expect, test } from 'bun:test';
+
+import { createGameBindingContext } from './createGameBindingContext';
+
+const session: GameSession = {
+  definitionId: 'binding-demo',
+  stageId: 'main',
+  phase: 'playing',
+  state: { health: 80, progress: 0.5 },
+  entities: {
+    player: {
+      id: 'player',
+      templateId: 'actor',
+      state: { x: 42, y: 73, label: 'Player' },
+    },
+    shot: {
+      id: 'shot',
+      templateId: 'projectile',
+      state: { x: 50, y: 60, label: 'A' },
+    },
+  },
+  scheduled: [],
+  elapsedMs: 120,
+  sequence: 4,
+};
+
+describe('createGameBindingContext', () => {
+  test('resolves ordinary Runtime context bindings from the local Game session', () => {
+    const context = createGameBindingContext(session);
+
+    expect(
+      resolveRuntimeBindingValueSync(
+        { source: { kind: 'context', path: 'game.session.entities.player.state.x' } },
+        { context },
+      ),
+    ).toBe(42);
+    expect(
+      resolveRuntimeBindingValueSync(
+        { source: { kind: 'context', path: 'game.session.state.health' } },
+        { context },
+      ),
+    ).toBe(80);
+  });
+
+  test('exposes current entities as a repeatable array with stable ids', () => {
+    const context = createGameBindingContext(session);
+    const entities = resolveRuntimeBindingValueSync(
+      { source: { kind: 'context', path: 'game.entities' } },
+      { context },
+    );
+
+    expect(Array.isArray(entities)).toBe(true);
+    expect(entities).toEqual(Object.values(session.entities));
+  });
+
+  test('owns only the local game namespace', () => {
+    expect(createGameBindingContext(session)).toEqual({
+      game: {
+        entities: Object.values(session.entities),
+        session,
+      },
+    });
+  });
+});

package/src/features/game/composition/createGameBindingContext.ts

@@ -0,0 +1,11 @@
+import type { GameSession } from '@ankhorage/game';
+
+/*** Create the canonical Runtime context namespace for one local game session. */
+export function createGameBindingContext(session: GameSession): Record<string, unknown> {
+  return {
+    game: {
+      entities: Object.values(session.entities),
+      session,
+    },
+  };
+}

package/src/features/game/composition/createGameMeasurementRegistry.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { GameMeasurementBounds } from '../../../types/gameRuntime';
+import { createGameMeasurementRegistry } from './createGameMeasurementRegistry';
+
+const bounds: GameMeasurementBounds = {
+  left: 10,
+  right: 30,
+  top: 20,
+  bottom: 50,
+  width: 20,
+  height: 30,
+};
+
+describe('createGameMeasurementRegistry', () => {
+  test('registers, reads, and unregisters one local measurement source', async () => {
+    const registry = createGameMeasurementRegistry();
+    const unregister = registry.registerMeasurement('player', () => Promise.resolve(bounds));
+
+    expect(await registry.measure('player')).toEqual(bounds);
+    unregister();
+    expect(await registry.measure('player')).toBeUndefined();
+  });
+
+  test('does not let an older cleanup delete a newer registration with the same id', async () => {
+    const registry = createGameMeasurementRegistry();
+    const firstCleanup = registry.registerMeasurement('actor', () => Promise.resolve(bounds));
+    const newerBounds = { ...bounds, left: 40, right: 60 };
+    registry.registerMeasurement('actor', () => Promise.resolve(newerBounds));
+
+    firstCleanup();
+
+    expect(await registry.measure('actor')).toEqual(newerBounds);
+  });
+});

package/src/features/game/composition/createGameMeasurementRegistry.ts

@@ -0,0 +1,16 @@
+import type { GameMeasurementReader, GameMeasurementRegistry } from '../../../types/gameRuntime';
+
+/*** Create one isolated measurement registry for an embeddable Game instance. */
+export function createGameMeasurementRegistry(): GameMeasurementRegistry {
+  const readers = new Map<string, GameMeasurementReader>();
+
+  return {
+    registerMeasurement: (id, reader) => {
+      readers.set(id, reader);
+      return () => {
+        if (readers.get(id) === reader) readers.delete(id);
+      };
+    },
+    measure: (id) => readers.get(id)?.() ?? Promise.resolve(undefined),
+  };
+}

package/src/features/game/composition/useGameRuntime.test.tsx

@@ -0,0 +1,173 @@
+import type { GameDefinition, GameEvent, GameOutput } from '@ankhorage/game';
+import { describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { GameRuntimeValue } from '../../../types/gameRuntime';
+import { useGameRuntime } from './useGameRuntime';
+
+interface RuntimeHarnessProps {
+  readonly autoAdvanceTime: boolean;
+  readonly definition: GameDefinition;
+  readonly dispatchRef: { current: GameRuntimeValue['dispatch'] | undefined };
+  readonly onOutput: (output: GameOutput) => void;
+}
+
+function RuntimeHarness({
+  autoAdvanceTime,
+  definition,
+  dispatchRef,
+  onOutput,
+}: RuntimeHarnessProps) {
+  const runtime = useGameRuntime({ autoAdvanceTime, definition, onOutput });
+
+  React.useEffect(() => {
+    dispatchRef.current = runtime.dispatch;
+    return () => {
+      dispatchRef.current = undefined;
+    };
+  }, [dispatchRef, runtime.dispatch]);
+
+  return null;
+}
+
+const batchedOutputDefinition: GameDefinition = {
+  id: 'batched-output-test',
+  stages: [{ id: 'main' }],
+  rules: [
+    {
+      id: 'emit-first',
+      event: 'emit.first',
+      effects: [{ kind: 'emit', type: 'first' }],
+    },
+    {
+      id: 'emit-second',
+      event: 'emit.second',
+      effects: [{ kind: 'emit', type: 'second' }],
+    },
+  ],
+};
+
+const pausedScheduleDefinition: GameDefinition = {
+  id: 'paused-schedule-test',
+  stages: [{ id: 'main' }],
+  rules: [
+    {
+      id: 'schedule-output',
+      event: 'schedule.output',
+      effects: [
+        {
+          kind: 'schedule',
+          delayMs: { kind: 'literal', value: 500 },
+          effects: [{ kind: 'emit', type: 'scheduled' }],
+        },
+      ],
+    },
+    {
+      id: 'noop',
+      event: 'noop',
+      effects: [],
+    },
+  ],
+};
+
+describe('useGameRuntime', () => {
+  test('delivers outputs from every state update in one React batch', () => {
+    const browser = new Window();
+    const restoreGlobals = installBrowserGlobals(browser);
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    const outputs: GameOutput[] = [];
+    const dispatchRef: { current: ((event: GameEvent) => void) | undefined } = {
+      current: undefined,
+    };
+
+    try {
+      act(() =>
+        root.render(
+          <RuntimeHarness
+            autoAdvanceTime
+            definition={batchedOutputDefinition}
+            dispatchRef={dispatchRef}
+            onOutput={(output) => outputs.push(output)}
+          />,
+        ),
+      );
+
+      act(() => {
+        dispatchRef.current?.({ type: 'emit.first' });
+        dispatchRef.current?.({ type: 'emit.second' });
+      });
+
+      expect(outputs.map((output) => output.type)).toEqual(['first', 'second']);
+    } finally {
+      act(() => root.unmount());
+      browser.close();
+      restoreGlobals();
+    }
+  });
+
+  test('does not advance scheduled effects across time spent paused', () => {
+    const browser = new Window();
+    const restoreGlobals = installBrowserGlobals(browser);
+    const originalNow = Date.now;
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    const outputs: GameOutput[] = [];
+    const dispatchRef: { current: ((event: GameEvent) => void) | undefined } = {
+      current: undefined,
+    };
+    let now = 100;
+    Date.now = () => now;
+
+    const render = (autoAdvanceTime: boolean) => (
+      <RuntimeHarness
+        autoAdvanceTime={autoAdvanceTime}
+        definition={pausedScheduleDefinition}
+        dispatchRef={dispatchRef}
+        onOutput={(output) => outputs.push(output)}
+      />
+    );
+
+    try {
+      act(() => root.render(render(false)));
+      act(() => dispatchRef.current?.({ type: 'schedule.output' }));
+
+      now = 10_000;
+      act(() => root.render(render(true)));
+      act(() => dispatchRef.current?.({ type: 'noop' }));
+
+      expect(outputs).toEqual([]);
+    } finally {
+      Date.now = originalNow;
+      act(() => root.unmount());
+      browser.close();
+      restoreGlobals();
+    }
+  });
+});
+
+function installBrowserGlobals(browser: Window): () => void {
+  const keys = ['window', 'document', 'Node', 'navigator', 'IS_REACT_ACT_ENVIRONMENT'] as const;
+  const previous = keys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+
+  Object.assign(globalThis, {
+    window: browser,
+    document: browser.document,
+    Node: browser.Node,
+    navigator: browser.navigator,
+    IS_REACT_ACT_ENVIRONMENT: true,
+  });
+
+  return () => {
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  };
+}

package/src/features/game/composition/useGameRuntime.ts

@@ -0,0 +1,200 @@
+import {
+  advanceGameTime,
+  applyGameEvent,
+  createGameSession,
+  type GameInput,
+  type GameOutput,
+} from '@ankhorage/game';
+import React from 'react';
+
+import type { GameProps } from '../../../types/gamePresentation';
+import type { GameRuntimeState, GameRuntimeValue } from '../../../types/gameRuntime';
+import { useGameScheduledEffects } from './useGameScheduledEffects';
+
+const EMPTY_GAME_INPUT: GameInput = {};
+
+/*** Own one local transient Game session while delegating all domain transitions to @ankhorage/game. */
+export function useGameRuntime(props: GameProps): GameRuntimeValue {
+  const { definition, input = EMPTY_GAME_INPUT, seed = 0, resetKey = '' } = props;
+  const definitionRef = useLatestValue(definition);
+  const inputRef = useLatestValue(input);
+  const outputRef = useLatestValue(props.onOutput);
+  const autoAdvanceTime = props.autoAdvanceTime ?? true;
+  const clockRef = React.useRef(0);
+  const runtimeKey = createRuntimeKey(definition.id, resetKey, seed);
+  const [runtime, setRuntime] = React.useState<GameRuntimeState>(() =>
+    createRuntimeState(definition, input, seed, runtimeKey, 0),
+  );
+
+  useGameRuntimeReset({
+    clockRef,
+    definitionRef,
+    inputRef,
+    runtimeKey,
+    seed,
+    setRuntime,
+  });
+  useGameAutoAdvanceClock(autoAdvanceTime, clockRef);
+  useGameOutputEmitter(runtime, outputRef, setRuntime);
+
+  const dispatch = React.useCallback<GameRuntimeValue['dispatch']>(
+    (event) => {
+      const now = Date.now();
+      setRuntime((current) =>
+        applyRuntimeEvent({
+          autoAdvanceTime,
+          current,
+          definition: definitionRef.current,
+          elapsedMs: Math.max(0, now - clockRef.current),
+          event,
+          input: inputRef.current,
+          runtimeKey,
+          seed,
+        }),
+      );
+      clockRef.current = now;
+    },
+    [autoAdvanceTime, definitionRef, inputRef, runtimeKey, seed],
+  );
+
+  useGameScheduledEffects({
+    clockRef,
+    definitionRef,
+    enabled: autoAdvanceTime,
+    inputRef,
+    runtimeKey,
+    scheduled: runtime.session.scheduled,
+    setRuntime,
+  });
+
+  return React.useMemo(() => ({ session: runtime.session, dispatch }), [dispatch, runtime.session]);
+}
+
+interface GameRuntimeResetArgs {
+  readonly clockRef: React.RefObject<number>;
+  readonly definitionRef: React.RefObject<GameProps['definition']>;
+  readonly inputRef: React.RefObject<GameInput>;
+  readonly runtimeKey: string;
+  readonly seed: number;
+  readonly setRuntime: React.Dispatch<React.SetStateAction<GameRuntimeState>>;
+}
+
+/*** Reset the transient session only when its explicit serializable runtime identity changes. */
+function useGameRuntimeReset({
+  clockRef,
+  definitionRef,
+  inputRef,
+  runtimeKey,
+  seed,
+  setRuntime,
+}: GameRuntimeResetArgs): void {
+  React.useEffect(() => {
+    clockRef.current = Date.now();
+    setRuntime((current) =>
+      current.key === runtimeKey
+        ? current
+        : createRuntimeState(
+            definitionRef.current,
+            inputRef.current,
+            seed,
+            runtimeKey,
+            current.revision + 1,
+          ),
+    );
+  }, [clockRef, definitionRef, inputRef, runtimeKey, seed, setRuntime]);
+}
+
+/*** Rebase elapsed-time tracking when automatic game-time advancement resumes. */
+function useGameAutoAdvanceClock(enabled: boolean, clockRef: React.RefObject<number>): void {
+  const previousEnabledRef = React.useRef(enabled);
+
+  React.useEffect(() => {
+    if (enabled && !previousEnabledRef.current) {
+      clockRef.current = Date.now();
+    }
+    previousEnabledRef.current = enabled;
+  }, [clockRef, enabled]);
+}
+
+/*** Emit each committed runtime output once and clear the delivered queue. */
+function useGameOutputEmitter(
+  runtime: GameRuntimeState,
+  outputRef: React.RefObject<GameProps['onOutput']>,
+  setRuntime: React.Dispatch<React.SetStateAction<GameRuntimeState>>,
+): void {
+  React.useEffect(() => {
+    if (runtime.outputs.length === 0) return;
+
+    setRuntime((current) =>
+      current.revision === runtime.revision ? { ...current, outputs: [] } : current,
+    );
+    emitGameOutputs(runtime.outputs, outputRef.current);
+  }, [outputRef, runtime.outputs, runtime.revision, setRuntime]);
+}
+
+interface ApplyRuntimeEventArgs {
+  readonly autoAdvanceTime: boolean;
+  readonly current: GameRuntimeState;
+  readonly definition: GameProps['definition'];
+  readonly elapsedMs: number;
+  readonly event: Parameters<typeof applyGameEvent>[2];
+  readonly input: GameInput;
+  readonly runtimeKey: string;
+  readonly seed: number;
+}
+
+/*** Apply elapsed time and one explicit game event against the matching local session. */
+function applyRuntimeEvent(args: ApplyRuntimeEventArgs): GameRuntimeState {
+  const base =
+    args.current.key === args.runtimeKey
+      ? args.current
+      : createRuntimeState(
+          args.definition,
+          args.input,
+          args.seed,
+          args.runtimeKey,
+          args.current.revision,
+        );
+  const timed = args.autoAdvanceTime
+    ? advanceGameTime(args.definition, base.session, args.elapsedMs, args.input)
+    : { session: base.session, outputs: [] };
+  const result = applyGameEvent(args.definition, timed.session, args.event, args.input);
+  return {
+    key: args.runtimeKey,
+    session: result.session,
+    outputs: [...base.outputs, ...timed.outputs, ...result.outputs],
+    revision: args.current.revision + 1,
+  };
+}
+
+/*** Create one transient runtime state through the published Game owner API. */
+function createRuntimeState(
+  definition: GameProps['definition'],
+  input: GameInput,
+  seed: number,
+  key: string,
+  revision: number,
+): GameRuntimeState {
+  const result = createGameSession(definition, { input, seed });
+  return { key, session: result.session, outputs: result.outputs, revision };
+}
+
+/*** Create one runtime identity from serializable definition/session initialization inputs. */
+function createRuntimeKey(definitionId: string, resetKey: string, seed: number): string {
+  return `${definitionId}:${resetKey}:${seed}`;
+}
+
+/*** Emit runtime outputs through the ZORA event callback boundary. */
+function emitGameOutputs(outputs: readonly GameOutput[], onOutput: GameProps['onOutput']): void {
+  if (onOutput === undefined) return;
+  outputs.forEach((output) => onOutput(output));
+}
+
+/*** Keep a stable ref object updated with the latest adapter input. */
+function useLatestValue<TValue>(value: TValue): React.RefObject<TValue> {
+  const ref = React.useRef(value);
+  React.useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+}

package/src/features/game/composition/useGameScheduledEffects.ts

@@ -0,0 +1,85 @@
+import { advanceGameTime, type GameDefinition, type GameInput } from '@ankhorage/game';
+import React from 'react';
+
+import type { GameRuntimeState } from '../../../types/gameRuntime';
+
+type SetGameRuntime = React.Dispatch<React.SetStateAction<GameRuntimeState>>;
+
+/*** Advance the nearest scheduled game effects through one platform timer. */
+export function useGameScheduledEffects({
+  clockRef,
+  definitionRef,
+  enabled,
+  inputRef,
+  runtimeKey,
+  scheduled,
+  setRuntime,
+}: UseGameScheduledEffectsArgs): void {
+  React.useEffect(() => {
+    if (!enabled || scheduled.length === 0) return undefined;
+    const delayMs = resolveNextScheduledDelay(scheduled);
+
+    const timer = setTimeout(() => {
+      const now = Date.now();
+      const elapsedMs = Math.max(0, now - clockRef.current);
+      clockRef.current = now;
+      setRuntime((current) =>
+        advanceScheduledRuntime({
+          current,
+          definition: definitionRef.current,
+          elapsedMs,
+          input: inputRef.current,
+          runtimeKey,
+        }),
+      );
+    }, delayMs);
+
+    return () => clearTimeout(timer);
+  }, [clockRef, definitionRef, enabled, inputRef, runtimeKey, scheduled, setRuntime]);
+}
+
+interface UseGameScheduledEffectsArgs {
+  readonly clockRef: React.RefObject<number>;
+  readonly definitionRef: React.RefObject<GameDefinition>;
+  readonly enabled: boolean;
+  readonly inputRef: React.RefObject<GameInput>;
+  readonly runtimeKey: string;
+  readonly scheduled: GameRuntimeState['session']['scheduled'];
+  readonly setRuntime: SetGameRuntime;
+}
+
+interface AdvanceScheduledRuntimeArgs {
+  readonly current: GameRuntimeState;
+  readonly definition: GameDefinition;
+  readonly elapsedMs: number;
+  readonly input: GameInput;
+  readonly runtimeKey: string;
+}
+
+/*** Advance one matching runtime state while preserving sessions that have already reset. */
+function advanceScheduledRuntime({
+  current,
+  definition,
+  elapsedMs,
+  input,
+  runtimeKey,
+}: AdvanceScheduledRuntimeArgs): GameRuntimeState {
+  if (current.key !== runtimeKey) return current;
+  const result = advanceGameTime(definition, current.session, elapsedMs, input);
+  return {
+    key: runtimeKey,
+    session: result.session,
+    outputs: [...current.outputs, ...result.outputs],
+    revision: current.revision + 1,
+  };
+}
+
+/*** Resolve the nearest scheduled game consequence without owning domain timing rules. */
+function resolveNextScheduledDelay(
+  scheduledEffects: GameRuntimeState['session']['scheduled'],
+): number {
+  return scheduledEffects.reduce(
+    (nearest, scheduled) => Math.min(nearest, scheduled.remainingMs),
+    Number.POSITIVE_INFINITY,
+  );
+}