@ankhorage/zora-game 0.1.0 → 0.3.0

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/gameInputZoneMeta.ts

@@ -0,0 +1,94 @@
+import type { ZoraComponentMeta } from '@ankhorage/zora/metadata';
+
+/*** Describe a field-relative pointer/touch input adapter for one embeddable Game session. */
+export const gameInputZoneMeta = {
+  name: 'GameInputZone',
+  category: 'component',
+  description:
+    'Normalizes pointer and touch positions into field-relative percentages and dispatches a generic game event.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Game input zone',
+    defaultProps: {
+      eventType: 'game.pointer',
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      zIndex: 1,
+      enabled: true,
+      continuous: true,
+    },
+  },
+  props: {
+    eventType: {
+      type: 'string',
+      category: 'Input',
+      label: 'Game event type',
+      default: 'game.pointer',
+      authoring: { authority: 'instance' },
+    },
+    entityId: {
+      type: 'string',
+      category: 'Input',
+      label: 'Entity id',
+      authoring: { authority: 'instance' },
+    },
+    x: {
+      type: 'number',
+      category: 'Position',
+      label: 'X (%)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    y: {
+      type: 'number',
+      category: 'Position',
+      label: 'Y (%)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    width: {
+      type: 'number',
+      category: 'Size',
+      label: 'Width (%)',
+      default: 100,
+      authoring: { authority: 'instance' },
+    },
+    height: {
+      type: 'number',
+      category: 'Size',
+      label: 'Height (%)',
+      default: 100,
+      authoring: { authority: 'instance' },
+    },
+    zIndex: {
+      type: 'number',
+      category: 'Position',
+      label: 'Z index',
+      default: 1,
+      authoring: { authority: 'instance' },
+    },
+    enabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Enabled',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+    continuous: {
+      type: 'boolean',
+      category: 'Input',
+      label: 'Dispatch while moving',
+      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/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', 'GameInputZone', '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

@@ -1,10 +1,14 @@
 export type {
   GameEntityProps,
   GameFieldProps,
+  GameInputZoneProps,
   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 { GameInputZone } from './adapters/inbound/GameInputZone';
 export { GameOverlay } from './adapters/inbound/GameOverlay';

package/src/features/game-presentation/utils/clampGamePercentage.ts

@@ -0,0 +1,4 @@
+/*** Clamp one game presentation coordinate to the inclusive field-percentage range. */
+export function clampGamePercentage(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}

package/src/features/game-presentation/utils/toGamePercentage.ts

@@ -0,0 +1,6 @@
+import { clampGamePercentage } from './clampGamePercentage';
+
+/*** Convert one game percentage coordinate to React Native percentage style syntax. */
+export function toGamePercentage(value: number): `${number}%` {
+  return `${clampGamePercentage(value)}%`;
+}

package/src/index.ts

@@ -1,9 +1,17 @@
 export type {
   GameEntityProps,
   GameFieldProps,
+  GameInputZoneProps,
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
+  GameProps,
+} from './features/game-presentation/public';
+export {
+  Game,
+  GameEntity,
+  GameField,
+  GameInputZone,
+  GameOverlay,
 } from './features/game-presentation/public';
-export { 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';
@@ -31,6 +32,20 @@ export interface GameEntityProps {
   readonly testID?: string;
 }
 
+export interface GameInputZoneProps {
+  readonly eventType: string;
+  readonly entityId?: string;
+  readonly x?: number;
+  readonly y?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly zIndex?: number;
+  readonly enabled?: boolean;
+  readonly continuous?: boolean;
+  readonly accessibilityLabel?: string;
+  readonly testID?: string;
+}
+
 export interface GameOverlayProps {
   readonly children?: React.ReactNode;
   readonly placement?: GameOverlayPlacement;
@@ -39,3 +54,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;
+}