@ankhorage/zora 21.0.22 → 21.1.0

package/src/features/game/composition/useGameRuntime.ts

@@ -0,0 +1,200 @@
+import {
+  advanceGameTime,
+  applyGameEvent,
+  createGameSession,
+  type GameInput,
+  type GameOutput,
+} from '@ankhorage/game';
+import React from 'react';
+
+import type { GameProps } from '../../../types/gamePresentation';
+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): GameRuntimeValue {
+  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,
+  });
+  useGameAutoAdvanceClock(autoAdvanceTime, clockRef);
+  useGameOutputEmitter(runtime, outputRef, setRuntime);
+
+  const dispatch = React.useCallback<GameRuntimeValue['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]);
+}
+
+/*** Rebase elapsed-time tracking when automatic game-time advancement resumes. */
+function useGameAutoAdvanceClock(enabled: boolean, clockRef: React.RefObject<number>): void {
+  const previousEnabledRef = React.useRef(enabled);
+
+  React.useEffect(() => {
+    if (enabled && !previousEnabledRef.current) {
+      clockRef.current = Date.now();
+    }
+    previousEnabledRef.current = enabled;
+  }, [clockRef, enabled]);
+}
+
+/*** Emit each committed runtime output once and clear the delivered queue. */
+function useGameOutputEmitter(
+  runtime: GameRuntimeState,
+  outputRef: React.RefObject<GameProps['onOutput']>,
+  setRuntime: React.Dispatch<React.SetStateAction<GameRuntimeState>>,
+): void {
+  React.useEffect(() => {
+    if (runtime.outputs.length === 0) return;
+
+    setRuntime((current) =>
+      current.revision === runtime.revision ? { ...current, outputs: [] } : current,
+    );
+    emitGameOutputs(runtime.outputs, outputRef.current);
+  }, [outputRef, runtime.outputs, runtime.revision, setRuntime]);
+}
+
+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.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/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: [...current.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/meta/gameEntityMeta.ts

@@ -0,0 +1,226 @@
+import type { ZoraComponentMeta } from '../../../types/authoring';
+
+/*** Describe one positioned generic game entity for ZORA authoring tools. */
+export const gameEntityMeta = {
+  name: 'GameEntity',
+  category: 'component',
+  description: 'Positions arbitrary visual content inside a GameField without owning game rules.',
+  directManifestNode: true,
+  allowedChildren: ['Badge', 'Icon', 'Image', 'Text', 'View'],
+  blueprint: {
+    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 },
+      measurementId: { value: { type: 'string' }, acceptsFallback: true },
+      transitionDurationMs: { value: { type: 'number' }, acceptsFallback: true },
+      transitionEasing: { value: { type: 'string' }, acceptsFallback: true },
+      motionOffsetX: { value: { type: 'number' }, acceptsFallback: true },
+      motionOffsetY: { value: { type: 'number' }, acceptsFallback: true },
+      motionOpacityDelta: { value: { type: 'number' }, acceptsFallback: true },
+      motionScaleDelta: { value: { type: 'number' }, acceptsFallback: true },
+      motionRotationDelta: { value: { type: 'number' }, acceptsFallback: true },
+      motionDurationMs: { value: { type: 'number' }, acceptsFallback: true },
+      motionDelayMs: { value: { type: 'number' }, acceptsFallback: true },
+      motionEasing: { value: { type: 'string' }, acceptsFallback: true },
+      motionRepeat: { value: { type: 'boolean' }, acceptsFallback: true },
+      motionAlternate: { value: { type: 'boolean' }, acceptsFallback: true },
+      motionPaused: { value: { type: 'boolean' }, acceptsFallback: true },
+      motionEssential: { value: { type: 'boolean' }, acceptsFallback: true },
+    },
+  },
+  props: {
+    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',
+      authoring: { authority: 'instance' },
+    },
+    height: {
+      type: 'number',
+      category: 'Size',
+      label: 'Height',
+      authoring: { authority: 'instance' },
+    },
+    opacity: {
+      type: 'number',
+      category: 'Appearance',
+      label: 'Opacity',
+      default: 1,
+      authoring: { authority: 'instance' },
+    },
+    scale: {
+      type: 'number',
+      category: 'Transform',
+      label: 'Scale',
+      default: 1,
+      authoring: { authority: 'instance' },
+    },
+    rotation: {
+      type: 'number',
+      category: 'Transform',
+      label: 'Rotation',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    zIndex: {
+      type: 'number',
+      category: 'Position',
+      label: 'Z index',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    hidden: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Hidden',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    pointerEvents: {
+      type: 'enum',
+      category: 'Interaction',
+      label: 'Pointer events',
+      enum: ['auto', 'box-none', 'box-only', 'none'],
+      default: 'auto',
+      authoring: { authority: 'instance' },
+    },
+    measurementId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Measurement id',
+      authoring: { authority: 'instance' },
+    },
+
+    transitionDurationMs: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Transition duration (ms)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    transitionEasing: {
+      type: 'enum',
+      category: 'Motion',
+      label: 'Transition easing',
+      enum: ['linear', 'ease-in', 'ease-out', 'ease-in-out'],
+      default: 'linear',
+      authoring: { authority: 'instance' },
+    },
+    motionOffsetX: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion X offset (%)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionOffsetY: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion Y offset (%)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionOpacityDelta: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion opacity delta',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionScaleDelta: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion scale delta',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionRotationDelta: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion rotation delta',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionDurationMs: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion duration (ms)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionDelayMs: {
+      type: 'number',
+      category: 'Motion',
+      label: 'Motion delay (ms)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    motionEasing: {
+      type: 'enum',
+      category: 'Motion',
+      label: 'Motion easing',
+      enum: ['linear', 'ease-in', 'ease-out', 'ease-in-out'],
+      default: 'linear',
+      authoring: { authority: 'instance' },
+    },
+    motionRepeat: {
+      type: 'boolean',
+      category: 'Motion',
+      label: 'Repeat motion',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    motionAlternate: {
+      type: 'boolean',
+      category: 'Motion',
+      label: 'Alternate motion',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    motionPaused: {
+      type: 'boolean',
+      category: 'Motion',
+      label: 'Pause motion',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    motionEssential: {
+      type: 'boolean',
+      category: 'Motion',
+      label: 'Essential motion',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/game/meta/gameFieldMeta.ts

@@ -0,0 +1,49 @@
+import type { ZoraComponentMeta } from '../../../types/authoring';
+
+/*** Describe the embeddable game field for ZORA authoring tools. */
+export const gameFieldMeta = {
+  name: 'GameField',
+  category: 'layout',
+  description: 'Relative positioning surface for embeddable game presentation content.',
+  directManifestNode: true,
+  allowedChildren: ['GameEntity', 'GameOverlay', 'Gradient', 'Image', 'View'],
+  blueprint: {
+    label: 'Game field',
+    defaultProps: { minHeight: 320, clip: true },
+  },
+  props: {
+    aspectRatio: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Aspect ratio',
+      authoring: { authority: 'instance' },
+    },
+    minHeight: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Minimum height',
+      default: 320,
+      authoring: { authority: 'instance' },
+    },
+    fill: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Fill available space',
+      default: false,
+      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/meta/gameInputZoneMeta.ts

@@ -0,0 +1,140 @@
+import type { ZoraComponentMeta } from '../../../types/authoring';
+
+/*** Describe a field-relative pointer/touch input adapter for one embeddable Game session. */
+export const gameInputZoneMeta = {
+  name: 'GameInputZone',
+  category: 'component',
+  description:
+    'Normalizes pointer/touch positions and optional keyboard bindings into generic game events.',
+  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' },
+    },
+    keyboardBindings: {
+      type: 'array',
+      category: 'Input',
+      label: 'Keyboard bindings',
+      default: [],
+      itemSchema: [
+        {
+          key: 'key',
+          schema: {
+            type: 'string',
+            category: 'Input',
+            label: 'Key',
+            authoring: { authority: 'instance' },
+          },
+        },
+        {
+          key: 'eventType',
+          schema: {
+            type: 'string',
+            category: 'Input',
+            label: 'Event type',
+            authoring: { authority: 'instance' },
+          },
+        },
+        {
+          key: 'entityId',
+          schema: {
+            type: 'string',
+            category: 'Input',
+            label: 'Entity id',
+            authoring: { authority: 'instance' },
+          },
+        },
+        {
+          key: 'preventDefault',
+          schema: {
+            type: 'boolean',
+            category: 'Input',
+            label: 'Prevent browser default',
+            default: false,
+            authoring: { authority: 'instance' },
+          },
+        },
+      ],
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;