@ankhorage/zora 21.0.22 → 21.1.0

package/src/features/game/adapters/inbound/createGameMeasurementEvent.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { GameMeasurementBounds } from '../../../../types/gameRuntime';
+import { createGameMeasurementEvent } from './createGameMeasurementEvent';
+
+const source: GameMeasurementBounds = {
+  left: 20,
+  right: 30,
+  top: 40,
+  bottom: 50,
+  width: 10,
+  height: 10,
+};
+
+const target: GameMeasurementBounds = {
+  left: 25,
+  right: 45,
+  top: 45,
+  bottom: 65,
+  width: 20,
+  height: 20,
+};
+
+describe('createGameMeasurementEvent', () => {
+  test('reports raw source and target bounds without deciding collision semantics', () => {
+    const event = createGameMeasurementEvent({
+      eventType: 'geometry.sample',
+      sourceId: 'projectile:1',
+      targetId: 'player',
+      source,
+      target,
+    });
+
+    expect(event.type).toBe('geometry.sample');
+    expect(event.entityId).toBe('projectile:1');
+    expect(event.payload).toEqual({
+      sourceId: 'projectile:1',
+      targetId: 'player',
+      source: { left: 20, right: 30, top: 40, bottom: 50, width: 10, height: 10 },
+      target: { left: 25, right: 45, top: 45, bottom: 65, width: 20, height: 20 },
+    });
+  });
+
+  test('allows the dispatched Game entity context to differ from the measured source id', () => {
+    expect(
+      createGameMeasurementEvent({
+        eventType: 'geometry.sample',
+        entityId: 'actor:1',
+        sourceId: 'visual:1',
+        targetId: 'player',
+        source,
+        target,
+      }).entityId,
+    ).toBe('actor:1');
+  });
+});

package/src/features/game/adapters/inbound/createGameMeasurementEvent.ts

@@ -0,0 +1,38 @@
+import type { GameEvent, GameRecord } from '@ankhorage/game';
+
+import type { GameMeasurementBounds } from '../../../../types/gameRuntime';
+
+/*** Create one raw geometry event without deciding collision semantics. */
+export function createGameMeasurementEvent(input: CreateGameMeasurementEventInput): GameEvent {
+  return {
+    type: input.eventType,
+    entityId: input.entityId ?? input.sourceId,
+    payload: {
+      sourceId: input.sourceId,
+      targetId: input.targetId,
+      source: toGameMeasurementRecord(input.source),
+      target: toGameMeasurementRecord(input.target),
+    },
+  };
+}
+
+interface CreateGameMeasurementEventInput {
+  readonly eventType: string;
+  readonly entityId?: string;
+  readonly sourceId: string;
+  readonly targetId: string;
+  readonly source: GameMeasurementBounds;
+  readonly target: GameMeasurementBounds;
+}
+
+/*** Convert measured geometry into a serializable Game record. */
+function toGameMeasurementRecord(bounds: GameMeasurementBounds): GameRecord {
+  return {
+    left: bounds.left,
+    right: bounds.right,
+    top: bounds.top,
+    bottom: bounds.bottom,
+    width: bounds.width,
+    height: bounds.height,
+  };
+}

package/src/features/game/adapters/inbound/createGamePointerEvent.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createGamePointerEvent } from './createGamePointerEvent';
+
+describe('createGamePointerEvent', () => {
+  test('maps zone-local pointer coordinates into field percentages', () => {
+    expect(
+      createGamePointerEvent({
+        eventType: 'player.move',
+        entityId: 'player',
+        localX: 100,
+        localY: 25,
+        measuredWidth: 200,
+        measuredHeight: 100,
+        zoneX: 10,
+        zoneY: 60,
+        zoneWidth: 80,
+        zoneHeight: 30,
+      }),
+    ).toEqual({
+      type: 'player.move',
+      entityId: 'player',
+      payload: { x: 50, y: 67.5 },
+    });
+  });
+
+  test('clamps out-of-bounds native coordinates and rejects unmeasured zones', () => {
+    expect(
+      createGamePointerEvent({
+        eventType: 'pointer.move',
+        localX: 500,
+        localY: -20,
+        measuredWidth: 100,
+        measuredHeight: 100,
+        zoneX: 20,
+        zoneY: 20,
+        zoneWidth: 50,
+        zoneHeight: 50,
+      }),
+    ).toEqual({ type: 'pointer.move', payload: { x: 70, y: 20 } });
+
+    expect(
+      createGamePointerEvent({
+        eventType: 'pointer.move',
+        localX: 0,
+        localY: 0,
+        measuredWidth: 0,
+        measuredHeight: 100,
+        zoneX: 0,
+        zoneY: 0,
+        zoneWidth: 100,
+        zoneHeight: 100,
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/features/game/adapters/inbound/createGamePointerEvent.ts

@@ -0,0 +1,39 @@
+import type { GameEvent } from '@ankhorage/game';
+
+import { clampGamePercentage } from '../../utils/clampGamePercentage';
+
+interface GamePointerEventInput {
+  readonly eventType: string;
+  readonly entityId?: string;
+  readonly localX: number;
+  readonly localY: number;
+  readonly measuredWidth: number;
+  readonly measuredHeight: number;
+  readonly zoneX: number;
+  readonly zoneY: number;
+  readonly zoneWidth: number;
+  readonly zoneHeight: number;
+}
+
+/*** Normalize one measured pointer/touch position into a field-relative generic Game event. */
+export function createGamePointerEvent(input: GamePointerEventInput): GameEvent | undefined {
+  if (
+    !Number.isFinite(input.measuredWidth) ||
+    !Number.isFinite(input.measuredHeight) ||
+    input.measuredWidth <= 0 ||
+    input.measuredHeight <= 0
+  ) {
+    return undefined;
+  }
+
+  const localX = clampGamePercentage((input.localX / input.measuredWidth) * 100);
+  const localY = clampGamePercentage((input.localY / input.measuredHeight) * 100);
+  const x = clampGamePercentage(input.zoneX + (localX * input.zoneWidth) / 100);
+  const y = clampGamePercentage(input.zoneY + (localY * input.zoneHeight) / 100);
+
+  return {
+    type: input.eventType,
+    ...(input.entityId === undefined ? {} : { entityId: input.entityId }),
+    payload: { x, y },
+  };
+}

package/src/features/game/adapters/inbound/measureGameEntity.ts

@@ -0,0 +1,28 @@
+import type { View } from 'react-native';
+
+import type { GameMeasurementBounds } from '../../../../types/gameRuntime';
+
+/*** Measure one rendered React Native or React Native Web game entity in window coordinates. */
+export function measureGameEntity(
+  element: View | null,
+): Promise<GameMeasurementBounds | undefined> {
+  if (element === null) return Promise.resolve(undefined);
+
+  return new Promise((resolve) => {
+    element.measureInWindow((left, top, width, height) => {
+      if (![left, top, width, height].every(Number.isFinite) || width < 0 || height < 0) {
+        resolve(undefined);
+        return;
+      }
+
+      resolve({
+        left,
+        right: left + width,
+        top,
+        bottom: top + height,
+        width,
+        height,
+      });
+    });
+  });
+}

package/src/features/game/adapters/inbound/useGameInputZoneResponder.ts

@@ -0,0 +1,85 @@
+import React from 'react';
+import type { GestureResponderEvent, LayoutChangeEvent } from 'react-native';
+
+import type { GameInputZoneProps } from '../../../../types/gamePresentation';
+import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
+import { createGameKeyboardEvent } from './createGameKeyboardEvent';
+import { createGamePointerEvent } from './createGamePointerEvent';
+
+interface GameKeyboardInputEvent {
+  readonly key: string;
+  preventDefault(): void;
+}
+
+interface MeasuredSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/*** Own React Native responder measurement and event dispatch for one Game input zone. */
+export function useGameInputZoneResponder(props: GameInputZoneProps) {
+  const runtime = React.useContext(GameRuntimeContext);
+  if (runtime === null) throw new Error('GameInputZone must be rendered inside Game.');
+
+  const measuredSizeRef = React.useRef<MeasuredSize>({ width: 0, height: 0 });
+  const handleLayout = React.useCallback((event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    measuredSizeRef.current = { width, height };
+  }, []);
+
+  const dispatchPointer = React.useCallback(
+    (event: GestureResponderEvent) => {
+      if (runtime.interactionPolicy === 'passive' || props.interactionPolicy === 'passive') return;
+      const measured = measuredSizeRef.current;
+      const gameEvent = createGamePointerEvent({
+        eventType: props.eventType,
+        ...(props.entityId === undefined ? {} : { entityId: props.entityId }),
+        localX: event.nativeEvent.locationX,
+        localY: event.nativeEvent.locationY,
+        measuredWidth: measured.width,
+        measuredHeight: measured.height,
+        zoneX: props.x ?? 0,
+        zoneY: props.y ?? 0,
+        zoneWidth: props.width ?? 100,
+        zoneHeight: props.height ?? 100,
+      });
+      if (gameEvent !== undefined) runtime.dispatch(gameEvent);
+    },
+    [
+      props.entityId,
+      props.eventType,
+      props.height,
+      props.interactionPolicy,
+      props.width,
+      props.x,
+      props.y,
+      runtime,
+    ],
+  );
+
+  const dispatchKeyboard = React.useCallback(
+    (event: GameKeyboardInputEvent) => {
+      if (runtime.interactionPolicy === 'passive' || props.interactionPolicy === 'passive') return;
+      const result = createGameKeyboardEvent({
+        bindings: props.keyboardBindings ?? [],
+        fallbackEventType: props.eventType,
+        ...(props.entityId === undefined ? {} : { fallbackEntityId: props.entityId }),
+        key: event.key,
+      });
+      if (result === undefined) return;
+      if (result.preventDefault) event.preventDefault();
+      runtime.dispatch(result.event);
+    },
+    [props.entityId, props.eventType, props.interactionPolicy, props.keyboardBindings, runtime],
+  );
+
+  return {
+    dispatchKeyboard,
+    dispatchPointer,
+    handleLayout,
+    shouldSetResponder: () =>
+      (props.enabled ?? true) &&
+      props.interactionPolicy !== 'passive' &&
+      runtime.interactionPolicy !== 'passive',
+  };
+}

package/src/features/game/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/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);
+    }
+  };
+}