@ankhorage/zora-game 0.1.0 → 0.2.0

package/src/ZORA_PLUGIN_METADATA.test.ts

@@ -4,13 +4,30 @@ import { describe, expect, test } from 'bun:test';
 import { ZORA_PLUGIN_METADATA } from './ZORA_PLUGIN_METADATA';
 
 describe('ZORA game plugin metadata', () => {
-  test('makes GameField embeddable in ordinary ZORA containers', () => {
+  test('makes Game and GameField embeddable in ordinary ZORA containers', () => {
     const catalog = composeZoraPluginMetadata([ZORA_CORE_PLUGIN_METADATA, ZORA_PLUGIN_METADATA]);
+    const game = readComponentMeta(catalog.componentMeta.Game, 'Game');
+    const gameField = readComponentMeta(catalog.componentMeta.GameField, 'GameField');
+    const screen = readComponentMeta(catalog.componentMeta.Screen, 'Screen');
+    const view = readComponentMeta(catalog.componentMeta.View, 'View');
 
-    expect(catalog.componentMeta.Screen?.allowedChildren).toContain('GameField');
-    expect(catalog.componentMeta.View?.allowedChildren).toContain('GameField');
-    expect(catalog.componentMeta.GameField?.allowedChildren).toContain('GameEntity');
-    expect(catalog.componentMeta.GameField?.allowedChildren).toContain('GameOverlay');
+    expect(screen.allowedChildren).toContain('Game');
+    expect(view.allowedChildren).toContain('Game');
+    expect(screen.allowedChildren).toContain('GameField');
+    expect(view.allowedChildren).toContain('GameField');
+    expect(gameField.allowedChildren).toContain('GameEntity');
+    expect(gameField.allowedChildren).toContain('GameOverlay');
+    expect(game.allowedChildren).toContain('GameEntity');
+    expect(game.allowedChildren).toContain('GameOverlay');
+  });
+
+  test('describes bindable Game inputs and domain-neutral outputs', () => {
+    const catalog = composeZoraPluginMetadata([ZORA_CORE_PLUGIN_METADATA, ZORA_PLUGIN_METADATA]);
+    const game = readComponentMeta(catalog.componentMeta.Game, 'Game');
+
+    expect(game.bindings?.props?.definition?.value.type).toBe('object');
+    expect(game.bindings?.props?.input?.value.type).toBe('record');
+    expect(game.events?.output?.eventType).toBe('game.output');
   });
 
   test('keeps the generic presentation vocabulary free of product-specific concepts', () => {
@@ -22,3 +39,9 @@ describe('ZORA game plugin metadata', () => {
     expect(serialized).not.toContain('letterprojectile');
   });
 });
+
+/*** Require one composed component metadata entry for focused assertions. */
+function readComponentMeta<TValue>(value: TValue | undefined, name: string): TValue {
+  if (value === undefined) throw new Error(`Missing composed component metadata for ${name}.`);
+  return value;
+}

package/src/ZORA_PLUGIN_METADATA.ts

@@ -7,19 +7,23 @@ export const ZORA_PLUGIN_METADATA = {
   packageName: '@ankhorage/zora-game',
   displayName: 'ZORA Game',
   componentMeta: ZORA_GAME_COMPONENT_META,
-  extensionHosts: ['GameField', 'GameEntity', 'GameOverlay'],
+  extensionHosts: ['Game', 'GameField', 'GameEntity', 'GameOverlay'],
   placements: [
+    {
+      child: 'Game',
+      parents: ['Card', 'Grid', 'Screen', 'ScreenSection', 'View'],
+    },
     {
       child: 'GameField',
       parents: ['Card', 'Grid', 'Screen', 'ScreenSection', 'View'],
     },
     {
       child: 'GameEntity',
-      parents: ['GameField', 'GameOverlay'],
+      parents: ['Game', 'GameField', 'GameOverlay'],
     },
     {
       child: 'GameOverlay',
-      parents: ['GameField'],
+      parents: ['Game', 'GameField'],
     },
   ],
 } as const satisfies ZoraPluginMetadata;

package/src/features/game-presentation/adapters/inbound/Game.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import type { GameProps } from '../../../../types/gamePresentation';
+import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
+import { useGameRuntime } from '../../composition/useGameRuntime';
+import { GameField } from './GameField';
+
+/*** Bind one serializable game definition to a local transient session and presentation field. */
+export function Game(props: GameProps) {
+  const runtime = useGameRuntime(props);
+
+  return (
+    <GameRuntimeContext.Provider value={runtime}>
+      <GameField
+        {...(props.aspectRatio === undefined ? {} : { aspectRatio: props.aspectRatio })}
+        {...(props.minHeight === undefined ? {} : { minHeight: props.minHeight })}
+        {...(props.clip === undefined ? {} : { clip: props.clip })}
+        {...(props.accessibilityLabel === undefined
+          ? {}
+          : { accessibilityLabel: props.accessibilityLabel })}
+        {...(props.testID === undefined ? {} : { testID: props.testID })}
+      >
+        {props.children}
+      </GameField>
+    </GameRuntimeContext.Provider>
+  );
+}

package/src/features/game-presentation/composition/GameRuntimeContext.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+
+import type { GameRuntimeContextValue } from '../../../types/gameRuntime';
+
+/*** Provide the local transient game session and event dispatcher to presentation adapters. */
+export const GameRuntimeContext = React.createContext<GameRuntimeContextValue | null>(null);

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

@@ -0,0 +1,181 @@
+import {
+  advanceGameTime,
+  applyGameEvent,
+  createGameSession,
+  type GameInput,
+  type GameOutput,
+} from '@ankhorage/game';
+import React from 'react';
+
+import type { GameProps } from '../../../types/gamePresentation';
+import type { GameRuntimeContextValue, GameRuntimeState } 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): GameRuntimeContextValue {
+  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,
+  });
+  useGameOutputEmitter(runtime, outputRef);
+
+  const dispatch = React.useCallback<GameRuntimeContextValue['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]);
+}
+
+/*** Emit each runtime output exactly when one execution revision becomes current. */
+function useGameOutputEmitter(
+  runtime: GameRuntimeState,
+  outputRef: React.RefObject<GameProps['onOutput']>,
+): void {
+  React.useEffect(() => {
+    emitGameOutputs(runtime.outputs, outputRef.current);
+  }, [outputRef, runtime.outputs, runtime.revision]);
+}
+
+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 === args.current ? [] : 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-presentation/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: 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,
+  );
+}

package/src/features/game-presentation/meta/gameMeta.ts

@@ -0,0 +1,99 @@
+import type { ZoraComponentMeta } from '@ankhorage/zora/metadata';
+
+/*** Describe the embeddable config-driven Game runtime/presentation boundary for ZORA authoring. */
+export const gameMeta = {
+  name: 'Game',
+  category: 'pattern',
+  description:
+    'Embeds one config-driven game session inside ordinary ZORA layout and emits domain-neutral game outputs.',
+  directManifestNode: true,
+  allowedChildren: ['GameEntity', 'GameOverlay', 'Gradient', 'Image', 'View'],
+  blueprint: {
+    label: 'Game',
+    defaultProps: {
+      definition: {
+        id: 'game',
+        initialPhase: 'playing',
+        stages: [{ id: 'main' }],
+        rules: [],
+      },
+      seed: 0,
+      resetKey: '',
+      autoAdvanceTime: true,
+      minHeight: 320,
+      clip: true,
+    },
+  },
+  bindings: {
+    props: {
+      definition: {
+        value: { type: 'object' },
+        acceptsFallback: true,
+      },
+      input: {
+        value: { type: 'record' },
+        acceptsFallback: true,
+      },
+    },
+  },
+  events: {
+    output: {
+      label: 'Game output',
+      eventType: 'game.output',
+      description: 'Emitted when the platform-neutral game runtime produces an app/domain output.',
+      payloadFields: [
+        { path: 'type', type: 'string' },
+        { path: 'payload', type: 'record' },
+      ],
+    },
+  },
+  props: {
+    seed: {
+      type: 'number',
+      category: 'Runtime',
+      label: 'Initial seed',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    resetKey: {
+      type: 'string',
+      category: 'Runtime',
+      label: 'Reset key',
+      default: '',
+      authoring: { authority: 'instance' },
+    },
+    autoAdvanceTime: {
+      type: 'boolean',
+      category: 'Runtime',
+      label: 'Advance scheduled effects',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+    aspectRatio: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Aspect ratio',
+      authoring: { authority: 'instance' },
+    },
+    minHeight: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Minimum height',
+      default: 320,
+      authoring: { authority: 'instance' },
+    },
+    clip: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Clip overflow',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/game-presentation/public.ts

@@ -4,7 +4,9 @@ export type {
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
+  GameProps,
 } from '../../types/gamePresentation';
+export { Game } from './adapters/inbound/Game';
 export { GameEntity } from './adapters/inbound/GameEntity';
 export { GameField } from './adapters/inbound/GameField';
 export { GameOverlay } from './adapters/inbound/GameOverlay';

package/src/index.ts

@@ -4,6 +4,7 @@ export type {
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
+  GameProps,
 } from './features/game-presentation/public';
-export { GameEntity, GameField, GameOverlay } from './features/game-presentation/public';
+export { Game, GameEntity, GameField, GameOverlay } from './features/game-presentation/public';
 export { ZORA_GAME_PLUGIN } from './ZORA_GAME_PLUGIN';

package/src/types/gamePresentation.ts

@@ -1,3 +1,4 @@
+import type { GameDefinition, GameInput, GameOutput } from '@ankhorage/game';
 import type React from 'react';
 
 type GameOverlayCornerPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -39,3 +40,12 @@ export interface GameOverlayProps {
   readonly accessibilityLabel?: string;
   readonly testID?: string;
 }
+
+export interface GameProps extends GameFieldProps {
+  readonly definition: GameDefinition;
+  readonly input?: GameInput;
+  readonly seed?: number;
+  readonly resetKey?: string;
+  readonly autoAdvanceTime?: boolean;
+  readonly onOutput?: (output: GameOutput) => void;
+}

package/src/types/gameRuntime.ts

@@ -0,0 +1,13 @@
+import type { GameEvent, GameOutput, GameSession } from '@ankhorage/game';
+
+export interface GameRuntimeContextValue {
+  readonly session: GameSession;
+  readonly dispatch: (event: GameEvent) => void;
+}
+
+export interface GameRuntimeState {
+  readonly key: string;
+  readonly session: GameSession;
+  readonly outputs: readonly GameOutput[];
+  readonly revision: number;
+}