@ankhorage/zora-game 0.2.0 → 0.4.0

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

@@ -2,6 +2,7 @@ import { View } from '@ankhorage/zora';
 import { StyleSheet, type ViewStyle } from 'react-native';
 
 import type { GameEntityProps } from '../../../../types/gamePresentation';
+import { toGamePercentage } from '../../utils/toGamePercentage';
 
 /*** Render one generic positioned game entity without owning gameplay semantics. */
 export function GameEntity({
@@ -60,10 +61,10 @@ function createEntityStyle({
 }: GameEntityStyleInput): ViewStyle {
   return {
     display: hidden ? 'none' : 'flex',
-    left: toPercent(x),
-    opacity: clamp(opacity, 0, 1),
+    left: toGamePercentage(x),
+    opacity: Math.min(1, Math.max(0, opacity)),
     position: 'absolute',
-    top: toPercent(y),
+    top: toGamePercentage(y),
     transform: [{ scale }, { rotate: `${rotation}deg` }],
     zIndex,
     ...(height === undefined ? {} : { height }),
@@ -71,16 +72,6 @@ function createEntityStyle({
   };
 }
 
-/*** Convert a bounded percentage number to React Native percentage syntax. */
-function toPercent(value: number): `${number}%` {
-  return `${clamp(value, 0, 100)}%`;
-}
-
-/*** Clamp one numeric presentation value to an inclusive range. */
-function clamp(value: number, minimum: number, maximum: number): number {
-  return Math.min(maximum, Math.max(minimum, value));
-}
-
 const styles = StyleSheet.create({
   root: {
     position: 'absolute',

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

@@ -0,0 +1,70 @@
+import { 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 dispatch only normalized generic Game events. */
+export function GameInputZone({
+  x = 0,
+  y = 0,
+  width = 100,
+  height = 100,
+  zIndex = 0,
+  enabled = true,
+  continuous = true,
+  accessibilityLabel,
+  testID,
+  ...inputProps
+}: GameInputZoneProps) {
+  const { dispatchPointer, handleLayout, shouldSetResponder } = useGameInputZoneResponder({
+    ...inputProps,
+    x,
+    y,
+    width,
+    height,
+    enabled,
+    continuous,
+  });
+
+  return (
+    <View
+      {...(accessibilityLabel === undefined ? {} : { accessibilityLabel })}
+      {...(testID === undefined ? {} : { testID })}
+      {...(continuous
+        ? { onResponderGrant: dispatchPointer, onResponderMove: dispatchPointer }
+        : { onResponderRelease: dispatchPointer })}
+      collapsable={false}
+      onLayout={handleLayout}
+      onStartShouldSetResponder={shouldSetResponder}
+      pointerEvents={enabled ? 'auto' : 'none'}
+      style={createInputZoneStyle({ x, y, width, height, zIndex })}
+    />
+  );
+}
+
+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-presentation/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-presentation/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-presentation/adapters/inbound/useGameInputZoneResponder.ts

@@ -0,0 +1,49 @@
+import React from 'react';
+import type { GestureResponderEvent, LayoutChangeEvent } from 'react-native';
+
+import type { GameInputZoneProps } from '../../../../types/gamePresentation';
+import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
+import { createGamePointerEvent } from './createGamePointerEvent';
+
+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) => {
+      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.width, props.x, props.y, runtime],
+  );
+
+  return {
+    dispatchPointer,
+    handleLayout,
+    shouldSetResponder: () => props.enabled ?? true,
+  };
+}

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

@@ -0,0 +1,47 @@
+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' },
+    },
+  },
+  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('owns only the local game namespace', () => {
+    expect(createGameBindingContext(session)).toEqual({
+      game: { session },
+    });
+  });
+});

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

@@ -0,0 +1,10 @@
+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: {
+      session,
+    },
+  };
+}

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

@@ -11,6 +11,19 @@ export const gameEntityMeta = {
     label: 'Game entity',
     defaultProps: { x: 0, y: 0, opacity: 1, scale: 1, rotation: 0, zIndex: 0 },
   },
+  bindings: {
+    props: {
+      x: { value: { type: 'number' }, acceptsFallback: true },
+      y: { value: { type: 'number' }, acceptsFallback: true },
+      width: { value: { type: 'number' }, acceptsFallback: true },
+      height: { value: { type: 'number' }, acceptsFallback: true },
+      opacity: { value: { type: 'number' }, acceptsFallback: true },
+      scale: { value: { type: 'number' }, acceptsFallback: true },
+      rotation: { value: { type: 'number' }, acceptsFallback: true },
+      zIndex: { value: { type: 'number' }, acceptsFallback: true },
+      hidden: { value: { type: 'boolean' }, acceptsFallback: true },
+    },
+  },
   props: {
     x: {
       type: 'number',

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

@@ -7,7 +7,7 @@ export const gameMeta = {
   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'],
+  allowedChildren: ['GameEntity', 'GameInputZone', 'GameOverlay', 'Gradient', 'Image', 'View'],
   blueprint: {
     label: 'Game',
     defaultProps: {

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

@@ -1,6 +1,7 @@
 export type {
   GameEntityProps,
   GameFieldProps,
+  GameInputZoneProps,
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
@@ -9,4 +10,5 @@ export type {
 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,10 +1,17 @@
 export type {
   GameEntityProps,
   GameFieldProps,
+  GameInputZoneProps,
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
   GameProps,
 } from './features/game-presentation/public';
-export { Game, GameEntity, GameField, GameOverlay } from './features/game-presentation/public';
+export {
+  Game,
+  GameEntity,
+  GameField,
+  GameInputZone,
+  GameOverlay,
+} from './features/game-presentation/public';
 export { ZORA_GAME_PLUGIN } from './ZORA_GAME_PLUGIN';

package/src/types/gamePresentation.ts

@@ -32,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;