@ankhorage/zora-game 0.5.0 → 0.6.0

package/src/features/game-presentation/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-presentation/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-presentation/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-presentation/composition/useGameRuntime.ts

@@ -8,13 +8,13 @@ import {
 import React from 'react';
 
 import type { GameProps } from '../../../types/gamePresentation';
-import type { GameRuntimeContextValue, GameRuntimeState } from '../../../types/gameRuntime';
+import type { GameRuntimeState, GameRuntimeValue } 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 {
+export function useGameRuntime(props: GameProps): GameRuntimeValue {
   const { definition, input = EMPTY_GAME_INPUT, seed = 0, resetKey = '' } = props;
   const definitionRef = useLatestValue(definition);
   const inputRef = useLatestValue(input);
@@ -36,7 +36,7 @@ export function useGameRuntime(props: GameProps): GameRuntimeContextValue {
   });
   useGameOutputEmitter(runtime, outputRef);
 
-  const dispatch = React.useCallback<GameRuntimeContextValue['dispatch']>(
+  const dispatch = React.useCallback<GameRuntimeValue['dispatch']>(
     (event) => {
       const now = Date.now();
       setRuntime((current) =>

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

@@ -22,6 +22,7 @@ export const gameEntityMeta = {
       rotation: { value: { type: 'number' }, acceptsFallback: true },
       zIndex: { value: { type: 'number' }, acceptsFallback: true },
       hidden: { value: { type: 'boolean' }, acceptsFallback: true },
+      measurementId: { value: { type: 'string' }, acceptsFallback: true },
     },
   },
   props: {
@@ -94,6 +95,12 @@ export const gameEntityMeta = {
       default: 'auto',
       authoring: { authority: 'instance' },
     },
+    measurementId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Measurement id',
+      authoring: { authority: 'instance' },
+    },
     accessibilityLabel: {
       type: 'string',
       category: 'Accessibility',

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

@@ -0,0 +1,72 @@
+import type { ZoraComponentMeta } from '@ankhorage/zora/metadata';
+
+/*** Describe a non-visual source/target geometry sampling adapter for one Game instance. */
+export const gameMeasurementProbeMeta = {
+  name: 'GameMeasurementProbe',
+  category: 'component',
+  description:
+    'Measures two registered game entities and reports their raw rendered bounds through a generic Game event.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Game measurement probe',
+    defaultProps: {
+      sourceId: 'source',
+      targetId: 'target',
+      eventType: 'game.measurement',
+      delayMs: 0,
+      enabled: true,
+    },
+  },
+  bindings: {
+    props: {
+      sourceId: { value: { type: 'string' }, acceptsFallback: true },
+      targetId: { value: { type: 'string' }, acceptsFallback: true },
+      eventType: { value: { type: 'string' }, acceptsFallback: true },
+      entityId: { value: { type: 'string' }, acceptsFallback: true },
+      delayMs: { value: { type: 'number' }, acceptsFallback: true },
+      enabled: { value: { type: 'boolean' }, acceptsFallback: true },
+    },
+  },
+  props: {
+    sourceId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Source id',
+      authoring: { authority: 'instance' },
+    },
+    targetId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Target id',
+      authoring: { authority: 'instance' },
+    },
+    eventType: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Event type',
+      default: 'game.measurement',
+      authoring: { authority: 'instance' },
+    },
+    entityId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Game entity id',
+      authoring: { authority: 'instance' },
+    },
+    delayMs: {
+      type: 'number',
+      category: 'Measurement',
+      label: 'Delay (ms)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    enabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Enabled',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

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

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

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

@@ -3,6 +3,7 @@ export type {
   GameFieldProps,
   GameInputZoneProps,
   GameKeyboardBinding,
+  GameMeasurementProbeProps,
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
@@ -12,4 +13,5 @@ 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 { GameMeasurementProbe } from './adapters/inbound/GameMeasurementProbe';
 export { GameOverlay } from './adapters/inbound/GameOverlay';

package/src/index.ts

@@ -3,6 +3,7 @@ export type {
   GameFieldProps,
   GameInputZoneProps,
   GameKeyboardBinding,
+  GameMeasurementProbeProps,
   GameOverlayPlacement,
   GameOverlayProps,
   GamePointerEvents,
@@ -13,6 +14,7 @@ export {
   GameEntity,
   GameField,
   GameInputZone,
+  GameMeasurementProbe,
   GameOverlay,
 } from './features/game-presentation/public';
 export { ZORA_GAME_PLUGIN } from './ZORA_GAME_PLUGIN';

package/src/types/gamePresentation.ts

@@ -28,6 +28,7 @@ export interface GameEntityProps {
   readonly zIndex?: number;
   readonly hidden?: boolean;
   readonly pointerEvents?: GamePointerEvents;
+  readonly measurementId?: string;
   readonly accessibilityLabel?: string;
   readonly testID?: string;
 }
@@ -54,6 +55,15 @@ export interface GameInputZoneProps {
   readonly testID?: string;
 }
 
+export interface GameMeasurementProbeProps {
+  readonly sourceId: string;
+  readonly targetId: string;
+  readonly eventType?: string;
+  readonly entityId?: string;
+  readonly delayMs?: number;
+  readonly enabled?: boolean;
+}
+
 export interface GameOverlayProps {
   readonly children?: React.ReactNode;
   readonly placement?: GameOverlayPlacement;

package/src/types/gameRuntime.ts

@@ -1,10 +1,28 @@
 import type { GameEvent, GameOutput, GameSession } from '@ankhorage/game';
 
-export interface GameRuntimeContextValue {
+export interface GameMeasurementBounds {
+  readonly left: number;
+  readonly right: number;
+  readonly top: number;
+  readonly bottom: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export type GameMeasurementReader = () => Promise<GameMeasurementBounds | undefined>;
+
+export interface GameMeasurementRegistry {
+  readonly registerMeasurement: (id: string, reader: GameMeasurementReader) => () => void;
+  readonly measure: (id: string) => Promise<GameMeasurementBounds | undefined>;
+}
+
+export interface GameRuntimeValue {
   readonly session: GameSession;
   readonly dispatch: (event: GameEvent) => void;
 }
 
+export interface GameRuntimeContextValue extends GameRuntimeValue, GameMeasurementRegistry {}
+
 export interface GameRuntimeState {
   readonly key: string;
   readonly session: GameSession;