@ankhorage/zora 21.0.23 → 21.1.0

package/src/features/game/adapters/inbound/GameField.tsx

@@ -0,0 +1,52 @@
+import { StyleSheet } from 'react-native';
+
+import type { GameFieldProps } from '../../../../types/gamePresentation';
+import { View } from '../../../layout/public';
+
+/*** Render a bounded relative-positioning surface for game presentation content. */
+export function GameField({
+  children,
+  aspectRatio,
+  minHeight = 320,
+  fill = false,
+  clip = true,
+  accessibilityLabel,
+  interactionPolicy,
+  testID,
+}: GameFieldProps) {
+  return (
+    <View
+      {...(accessibilityLabel === undefined ? {} : { accessibilityLabel })}
+      {...(testID === undefined ? {} : { testID })}
+      interactionPolicy={interactionPolicy}
+      pointerEvents={interactionPolicy === 'passive' ? 'none' : 'auto'}
+      style={[
+        styles.root,
+        clip ? styles.clipped : styles.overflowVisible,
+        fill ? styles.fill : undefined,
+        {
+          ...(aspectRatio === undefined ? {} : { aspectRatio }),
+          minHeight,
+        },
+      ]}
+    >
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  clipped: {
+    overflow: 'hidden',
+  },
+  fill: {
+    flex: 1,
+  },
+  overflowVisible: {
+    overflow: 'visible',
+  },
+  root: {
+    position: 'relative',
+    width: '100%',
+  },
+});

package/src/features/game/adapters/inbound/GameInputZone.tsx

@@ -0,0 +1,99 @@
+import { Platform, StyleSheet, View, type ViewStyle } from 'react-native';
+
+import type { GameInputZoneProps } from '../../../../types/gamePresentation';
+import { toGamePercentage } from '../../utils/toGamePercentage';
+import { useGameInputZoneResponder } from './useGameInputZoneResponder';
+
+/*** Capture pointer/touch geometry and optional keyboard input as normalized generic Game events. */
+export function GameInputZone({
+  x = 0,
+  y = 0,
+  width = 100,
+  height = 100,
+  zIndex = 0,
+  enabled = true,
+  continuous = true,
+  keyboardBindings,
+  accessibilityLabel,
+  interactionPolicy,
+  testID,
+  ...inputProps
+}: GameInputZoneProps) {
+  const { dispatchKeyboard, dispatchPointer, handleLayout, shouldSetResponder } =
+    useGameInputZoneResponder({
+      ...inputProps,
+      x,
+      y,
+      width,
+      height,
+      enabled: enabled && interactionPolicy !== 'passive',
+      interactionPolicy,
+      continuous,
+      ...(keyboardBindings === undefined ? {} : { keyboardBindings }),
+    });
+  const keyboardProps = createGameInputZoneKeyboardProps({
+    dispatchKeyboard,
+    enabled: enabled && interactionPolicy !== 'passive',
+    keyboardBindings,
+  });
+
+  return (
+    <View
+      {...keyboardProps}
+      {...(accessibilityLabel === undefined ? {} : { accessibilityLabel })}
+      {...(testID === undefined ? {} : { testID })}
+      {...(continuous
+        ? { onResponderGrant: dispatchPointer, onResponderMove: dispatchPointer }
+        : { onResponderRelease: dispatchPointer })}
+      collapsable={false}
+      onLayout={handleLayout}
+      onStartShouldSetResponder={shouldSetResponder}
+      pointerEvents={enabled && interactionPolicy !== 'passive' ? 'auto' : 'none'}
+      style={createInputZoneStyle({ x, y, width, height, zIndex })}
+    />
+  );
+}
+
+interface GameInputZoneKeyboardPropsInput {
+  readonly dispatchKeyboard: (event: { readonly key: string; preventDefault(): void }) => void;
+  readonly enabled: boolean;
+  readonly keyboardBindings: GameInputZoneProps['keyboardBindings'];
+}
+
+/*** Add a focusable web keyboard target only when the input zone owns key bindings. */
+function createGameInputZoneKeyboardProps({
+  dispatchKeyboard,
+  enabled,
+  keyboardBindings,
+}: GameInputZoneKeyboardPropsInput) {
+  if (Platform.OS !== 'web' || !enabled || keyboardBindings === undefined) return {};
+  if (keyboardBindings.length === 0) return {};
+
+  return { onKeyDown: dispatchKeyboard, tabIndex: 0 as const };
+}
+
+interface InputZoneStyleInput {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly zIndex: number;
+}
+
+/*** Convert field-relative input-zone props into one absolute React Native style. */
+function createInputZoneStyle({ x, y, width, height, zIndex }: InputZoneStyleInput): ViewStyle {
+  return {
+    left: toGamePercentage(x),
+    top: toGamePercentage(y),
+    width: toGamePercentage(width),
+    height: toGamePercentage(height),
+    zIndex,
+    ...styles.root,
+  };
+}
+
+const styles = StyleSheet.create({
+  root: {
+    position: 'absolute',
+  },
+});

package/src/features/game/adapters/inbound/GameMeasurementProbe.tsx

@@ -0,0 +1,83 @@
+import React from 'react';
+
+import type { GameMeasurementProbeProps } from '../../../../types/gamePresentation';
+import type { GameRuntimeContextValue } from '../../../../types/gameRuntime';
+import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
+import { createGameMeasurementEvent } from './createGameMeasurementEvent';
+
+/*** Measure two registered game entities and dispatch only their raw rendered geometry. */
+export function GameMeasurementProbe({
+  sourceId,
+  targetId,
+  eventType = 'game.measurement',
+  entityId,
+  delayMs = 0,
+  enabled = true,
+  interactionPolicy,
+}: GameMeasurementProbeProps) {
+  const runtime = React.useContext(GameRuntimeContext);
+  if (runtime === null) throw new Error('GameMeasurementProbe must be rendered inside Game.');
+
+  React.useEffect(() => {
+    if (!enabled || interactionPolicy === 'passive' || runtime.interactionPolicy === 'passive')
+      return undefined;
+
+    const timer = setTimeout(
+      () => {
+        void dispatchGameMeasurement({
+          dispatch: runtime.dispatch,
+          measure: runtime.measure,
+          sourceId,
+          targetId,
+          eventType,
+          ...(entityId === undefined ? {} : { entityId }),
+        });
+      },
+      Math.max(0, delayMs),
+    );
+
+    return () => clearTimeout(timer);
+  }, [
+    delayMs,
+    enabled,
+    interactionPolicy,
+    entityId,
+    eventType,
+    runtime.dispatch,
+    runtime.interactionPolicy,
+    runtime.measure,
+    sourceId,
+    targetId,
+  ]);
+
+  return null;
+}
+
+interface DispatchGameMeasurementInput {
+  readonly dispatch: GameRuntimeContextValue['dispatch'];
+  readonly measure: GameRuntimeContextValue['measure'];
+  readonly sourceId: string;
+  readonly targetId: string;
+  readonly eventType: string;
+  readonly entityId?: string;
+}
+
+/*** Resolve both registered entity measurements before dispatching one Game event. */
+async function dispatchGameMeasurement(input: DispatchGameMeasurementInput): Promise<void> {
+  const [source, target] = await Promise.all([
+    input.measure(input.sourceId),
+    input.measure(input.targetId),
+  ]);
+  if (source === undefined || target === undefined) return;
+
+  input.dispatch(
+    createGameMeasurementEvent({
+      eventType: input.eventType,
+      ...(input.entityId === undefined ? {} : { entityId: input.entityId }),
+      sourceId: input.sourceId,
+      targetId: input.targetId,
+      source,
+      target,
+    }),
+  );
+}

package/src/features/game/adapters/inbound/GameOverlay.tsx

@@ -0,0 +1,58 @@
+import { StyleSheet, type ViewStyle } from 'react-native';
+
+import type { GameOverlayPlacement, GameOverlayProps } from '../../../../types/gamePresentation';
+import { View } from '../../../layout/public';
+
+/*** Render an absolute game presentation layer for HUD, feedback, and phase content. */
+export function GameOverlay({
+  children,
+  placement = 'fill',
+  blocking = false,
+  padding = 0,
+  accessibilityLabel,
+  interactionPolicy,
+  testID,
+}: GameOverlayProps) {
+  return (
+    <View
+      {...(accessibilityLabel === undefined ? {} : { accessibilityLabel })}
+      {...(testID === undefined ? {} : { testID })}
+      pointerEvents={interactionPolicy === 'passive' ? 'none' : blocking ? 'auto' : 'box-none'}
+      style={[styles.root, resolvePlacementStyle(placement), { padding }]}
+    >
+      {children}
+    </View>
+  );
+}
+
+/*** Resolve overlay alignment without coupling layout to any game genre or rule. */
+function resolvePlacementStyle(placement: GameOverlayPlacement): ViewStyle {
+  switch (placement) {
+    case 'center':
+      return { alignItems: 'center', justifyContent: 'center' };
+    case 'top':
+      return { alignItems: 'center', justifyContent: 'flex-start' };
+    case 'bottom':
+      return { alignItems: 'center', justifyContent: 'flex-end' };
+    case 'top-left':
+      return { alignItems: 'flex-start', justifyContent: 'flex-start' };
+    case 'top-right':
+      return { alignItems: 'flex-end', justifyContent: 'flex-start' };
+    case 'bottom-left':
+      return { alignItems: 'flex-start', justifyContent: 'flex-end' };
+    case 'bottom-right':
+      return { alignItems: 'flex-end', justifyContent: 'flex-end' };
+    case 'fill':
+      return {};
+  }
+}
+
+const styles = StyleSheet.create({
+  root: {
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+});

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

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createGameKeyboardEvent } from './createGameKeyboardEvent';
+
+describe('createGameKeyboardEvent', () => {
+  test('maps a configured key through fallback event and entity values', () => {
+    expect(
+      createGameKeyboardEvent({
+        bindings: [{ key: 'ArrowLeft', preventDefault: true }],
+        fallbackEventType: 'player.move',
+        fallbackEntityId: 'player',
+        key: 'ArrowLeft',
+      }),
+    ).toEqual({
+      event: {
+        type: 'player.move',
+        entityId: 'player',
+        payload: { key: 'ArrowLeft' },
+      },
+      preventDefault: true,
+    });
+  });
+
+  test('allows one key binding to override the event target', () => {
+    expect(
+      createGameKeyboardEvent({
+        bindings: [{ key: ' ', eventType: 'player.action', entityId: 'actor' }],
+        fallbackEventType: 'player.move',
+        fallbackEntityId: 'player',
+        key: ' ',
+      }),
+    ).toEqual({
+      event: {
+        type: 'player.action',
+        entityId: 'actor',
+        payload: { key: ' ' },
+      },
+      preventDefault: false,
+    });
+  });
+
+  test('ignores keys without a binding', () => {
+    expect(
+      createGameKeyboardEvent({
+        bindings: [{ key: 'ArrowLeft' }],
+        fallbackEventType: 'player.move',
+        key: 'ArrowRight',
+      }),
+    ).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,33 @@
+import type { GameEvent } from '@ankhorage/game';
+
+import type { GameKeyboardBinding } from '../../../../types/gamePresentation';
+
+interface CreateGameKeyboardEventInput {
+  readonly bindings: readonly GameKeyboardBinding[];
+  readonly fallbackEventType: string;
+  readonly fallbackEntityId?: string;
+  readonly key: string;
+}
+
+interface GameKeyboardEventResult {
+  readonly event: GameEvent;
+  readonly preventDefault: boolean;
+}
+
+/*** Map one configured keyboard key into a generic Game event. */
+export function createGameKeyboardEvent(
+  input: CreateGameKeyboardEventInput,
+): GameKeyboardEventResult | undefined {
+  const binding = input.bindings.find((candidate) => candidate.key === input.key);
+  if (binding === undefined) return undefined;
+
+  const entityId = binding.entityId ?? input.fallbackEntityId;
+  return {
+    event: {
+      type: binding.eventType ?? input.fallbackEventType,
+      ...(entityId === undefined ? {} : { entityId }),
+      payload: { key: input.key },
+    },
+    preventDefault: binding.preventDefault ?? false,
+  };
+}

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);