rn-gamekit 0.1.0

package/src/sprites/sampleSpriteClip.ts

@@ -0,0 +1,51 @@
+/**
+ * Deterministic clip frame sampling (T7.3).
+ *
+ * Pure, allocation-free, worklet-compatible frame selection. The same clip
+ * metadata and elapsed time always select the same frame, so equivalent
+ * game time produces identical presentation at 30/60/90/120 Hz.
+ */
+import type { SpriteClip } from '../assets/types';
+
+/**
+ * Select the frame index for `elapsedMs` of playback.
+ *
+ * Loop clips wrap with modulo — the boundary frame is never duplicated and
+ * no zero-length boundary frame exists. One-shot clips clamp to their final
+ * frame; completion is reported separately.
+ */
+export function sampleSpriteClipFrame(
+  clip: SpriteClip,
+  elapsedMs: number,
+): number {
+  'worklet';
+  const frameCount = clip.frames.length;
+  const duration = clip.frameDurationMs;
+  if (clip.mode === 'loop') {
+    const index = Math.floor(elapsedMs / duration) % frameCount;
+    return index >= 0 ? index : index + frameCount;
+  }
+  const index = Math.floor(elapsedMs / duration);
+  return index >= frameCount ? frameCount - 1 : index;
+}
+
+/**
+ * The frame NAME selected for `elapsedMs` of playback (the ordered frame
+ * references of the clip).
+ */
+export function sampleSpriteClipFrameName(
+  clip: SpriteClip,
+  elapsedMs: number,
+): string {
+  'worklet';
+  const frames = clip.frames;
+  const index = sampleSpriteClipFrame(clip, elapsedMs);
+  const frame = frames[index];
+  return frame === undefined ? frames[0] ?? '' : frame;
+}
+
+/** Total clip duration in milliseconds (one-shot: its full timeline). */
+export function spriteClipDurationMs(clip: SpriteClip): number {
+  'worklet';
+  return clip.frames.length * clip.frameDurationMs;
+}

package/src/sprites/spriteAnimationState.ts

@@ -0,0 +1,176 @@
+/**
+ * Deterministic sprite animation playback state (T7.3).
+ *
+ * Animation state is plain serializable data advanced from fixed-step game
+ * time: `clip`, elapsed time, pause flag, speed, and completion. Changing,
+ * pausing, restarting, or completing a clip returns a NEW state object; it
+ * never mutates scene state or emits a side effect. The same input and
+ * elapsed game time always select the same presented frame (see
+ * `sampleSpriteClip`).
+ *
+ * Separation of concerns: gameplay-significant animation state lives in the
+ * scene snapshot and advances from fixed-step game time; a renderer-only
+ * loop may interpolate presentation from the latest committed state plus
+ * the interpolation alpha, but must never emit gameplay events from a
+ * presentation-only frame.
+ */
+import { GameAssetError } from '../assets/errors';
+import type { SpriteSheetDescriptor } from '../assets/types';
+import { spriteClipDurationMs } from './sampleSpriteClip';
+
+/** Immutable, serializable animation playback state. */
+export interface SpriteAnimationState<TClipName extends string = string> {
+  /** The clip currently selected on the descriptor. */
+  readonly clip: TClipName;
+  /** Elapsed milliseconds within the current playback of the clip. */
+  readonly elapsedMs: number;
+  /** Playback paused: advance is a no-op while paused. */
+  readonly paused: boolean;
+  /** Finite, positive playback speed multiplier. */
+  readonly speed: number;
+  /** One-shot clips report completion after their final frame. */
+  readonly completed: boolean;
+}
+
+function assertFinitePositiveSpeed(speed: number): void {
+  if (typeof speed !== 'number' || !Number.isFinite(speed) || speed <= 0) {
+    throw new Error('sprite animation speed must be a finite number greater than zero');
+  }
+}
+
+function assertFiniteDelta(deltaSeconds: number): void {
+  if (typeof deltaSeconds !== 'number' || !Number.isFinite(deltaSeconds)) {
+    throw new Error('sprite animation delta must be a finite number of seconds');
+  }
+}
+/** The clip names of a sprite-sheet descriptor (works through the manifest brand). */
+export type SpriteClipNames<TDescriptor extends SpriteSheetDescriptor> = Extract<
+  keyof TDescriptor['animations'],
+  string
+>;
+
+/** Runtime clip lookup; throws a structured error for unknown clips. */
+function clipOf(
+  descriptor: SpriteSheetDescriptor,
+  clip: string,
+): SpriteSheetDescriptor['animations'][string] {
+  'worklet';
+  const animation = descriptor.animations[clip];
+  if (animation === undefined) {
+    throw new GameAssetError(
+      'ASSET_UNKNOWN_CLIP',
+      ['animations', clip],
+      `unknown animation clip ${JSON.stringify(clip)}`,
+    );
+  }
+  return animation;
+}
+
+/**
+ * Start playback of `clip` from its beginning. The clip name is preserved
+ * as a string literal in the returned state; unknown clips are rejected at
+ * runtime (the manifest descriptor keeps the sheet-level frame and clip
+ * names literal via the spriteSheet contract).
+ */
+export function startSpriteAnimation<TClipName extends string>(
+  descriptor: SpriteSheetDescriptor,
+  clip: TClipName,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  clipOf(descriptor, clip);
+  return {
+    clip,
+    elapsedMs: 0,
+    paused: false,
+    speed: 1,
+    completed: false,
+  };
+}
+
+/**
+ * Advance playback by `deltaSeconds` of fixed-step game time.
+ *
+ * Finite negative deltas clamp elapsed time to zero; NaN/infinity fail
+ * clearly. Loop clips keep their elapsed time bounded within one timeline
+ * (modulo), so arbitrarily large deltas cost constant arithmetic.
+ */
+export function advanceSpriteAnimation<TClipName extends string>(
+  descriptor: SpriteSheetDescriptor,
+  state: SpriteAnimationState<TClipName>,
+  deltaSeconds: number,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  assertFiniteDelta(deltaSeconds);
+  if (state.paused || state.completed) {
+    return state;
+  }
+  const clip = clipOf(descriptor, state.clip);
+  const totalMs = spriteClipDurationMs(clip);
+  const next = state.elapsedMs + deltaSeconds * 1000 * state.speed;
+  if (clip.mode === 'once') {
+    if (next >= totalMs) {
+      return { ...state, elapsedMs: totalMs, completed: true };
+    }
+    return { ...state, elapsedMs: next < 0 ? 0 : next };
+  }
+  // Loop: bounded elapsed within one timeline; negative clamps to zero.
+  const wrapped = next < 0 ? 0 : next % totalMs;
+  return { ...state, elapsedMs: wrapped };
+}
+
+/**
+ * Switch playback to `clip`, restarting it from the beginning. The clip
+ * name is typed against the descriptor's animation table.
+ */
+export function playSpriteAnimation<TClipName extends string>(
+  descriptor: SpriteSheetDescriptor,
+  state: SpriteAnimationState<TClipName>,
+  clip: TClipName,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  if (clip === state.clip) {
+    return state;
+  }
+  clipOf(descriptor, clip);
+  return {
+    clip,
+    elapsedMs: 0,
+    paused: state.paused,
+    speed: state.speed,
+    completed: false,
+  };
+}
+
+/** Pause playback; `advance` becomes a no-op while paused. */
+export function pauseSpriteAnimation<TClipName extends string>(
+  state: SpriteAnimationState<TClipName>,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  return state.paused ? state : { ...state, paused: true };
+}
+
+/** Resume playback from the paused position. */
+export function resumeSpriteAnimation<TClipName extends string>(
+  state: SpriteAnimationState<TClipName>,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  return state.paused ? { ...state, paused: false } : state;
+}
+
+/** Restart the current clip from its beginning. */
+export function resetSpriteAnimation<TClipName extends string>(
+  state: SpriteAnimationState<TClipName>,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  return { ...state, elapsedMs: 0, completed: false };
+}
+
+/** Set a finite positive speed multiplier. */
+export function setSpriteAnimationSpeed<TClipName extends string>(
+  state: SpriteAnimationState<TClipName>,
+  speed: number,
+): SpriteAnimationState<TClipName> {
+  'worklet';
+  assertFinitePositiveSpeed(speed);
+  return state.speed === speed ? state : { ...state, speed };
+}

package/src/testing.ts

@@ -0,0 +1,61 @@
+import { createGameSessionWithDriver } from './core/session/createGameSession';
+import { createAnimationFrameDriver } from './core/frameDriver';
+import type { FrameDriver, FrameHandle } from './core/frameDriver';
+import type { SessionDiagnostics } from './core/session/diagnostics';
+
+export { createAnimationFrameDriver, createGameSessionWithDriver };
+export type { FrameDriver, FrameHandle, SessionDiagnostics };
+
+/**
+ * Deterministic animation-frame driver for headless tests.
+ *
+ * Frames are fired manually with explicit timestamps, so games can be driven
+ * with a fixed step and exact wall-clock schedules in Node without a
+ * simulator.
+ */
+export class ManualFrameDriver implements FrameDriver {
+  readonly #callbacks = new Map<number, (timestampMs: number) => void>();
+  readonly #allCallbacks = new Map<number, (timestampMs: number) => void>();
+  #nextHandle = 1;
+
+  /** Number of currently scheduled callbacks. */
+  get pendingCount(): number {
+    return this.#callbacks.size;
+  }
+
+  requestFrame(callback: (timestampMs: number) => void): FrameHandle {
+    const handle = this.#nextHandle;
+    this.#nextHandle += 1;
+    this.#callbacks.set(handle, callback);
+    this.#allCallbacks.set(handle, callback);
+    return handle;
+  }
+
+  cancelFrame(handle: FrameHandle): void {
+    this.#callbacks.delete(handle);
+  }
+
+  /** Fire the next pending callback with the given timestamp. */
+  fireNext(timestampMs: number): FrameHandle {
+    const next = this.#callbacks.entries().next();
+    if (next.done) {
+      throw new Error('No frame is pending');
+    }
+    const [handle, callback] = next.value;
+    this.#callbacks.delete(handle);
+    callback(timestampMs);
+    return handle;
+  }
+
+  /**
+   * Fire a specific handle even if it was already fired, simulating a stale
+   * callback racing with a lifecycle change.
+   */
+  fireCancelled(handle: FrameHandle, timestampMs: number): void {
+    const callback = this.#allCallbacks.get(handle);
+    if (!callback) {
+      throw new Error(`Unknown frame handle: ${handle}`);
+    }
+    callback(timestampMs);
+  }
+}

package/src/viewport2d/index.ts

@@ -0,0 +1,7 @@
+export type { LogicalSize, Rect, ResolvedViewport2D, SurfaceSize, Viewport, ViewportMode } from './types';
+export {
+  containsSurfacePoint,
+  resolveViewport2D,
+  surfaceToWorld,
+  worldToSurface,
+} from './math';

package/src/viewport2d/math.ts

@@ -0,0 +1,134 @@
+import type { Point2D } from '../geometry/types';
+import type { Rect, ResolvedViewport2D, SurfaceSize, Viewport } from './types';
+
+function freezeRect(value: Rect): Rect {
+  return Object.freeze(value);
+}
+
+function rect(x: number, y: number, width: number, height: number): Rect {
+  return freezeRect({ x, y, width, height });
+}
+
+function invalidLogicalSize(config: Viewport): string {
+  const { width, height } = config.logicalSize;
+  return `Viewport logical size must be finite and positive (got ${width} x ${height})`;
+}
+
+function isUsableSurface(size: SurfaceSize): boolean {
+  return (
+    Number.isFinite(size.width) &&
+    Number.isFinite(size.height) &&
+    size.width > 0 &&
+    size.height > 0
+  );
+}
+
+/**
+ * Resolve an authored viewport configuration against an actual surface size.
+ *
+ * Returns `undefined` until both surface dimensions are positive — a
+ * zero-sized layout is normal before the first layout pass. Invalid authored
+ * sizes throw a `RangeError` naming the invalid dimension. The result is
+ * immutable plain data with no platform dependencies.
+ */
+export function resolveViewport2D(
+  config: Viewport,
+  surfaceSize: SurfaceSize,
+): ResolvedViewport2D | undefined {
+  const { width: logicalWidth, height: logicalHeight } = config.logicalSize;
+
+  if (!Number.isFinite(logicalWidth) || !Number.isFinite(logicalHeight)) {
+    throw new RangeError(invalidLogicalSize(config));
+  }
+  if (!(logicalWidth > 0) || !(logicalHeight > 0)) {
+    throw new RangeError(invalidLogicalSize(config));
+  }
+  if (!isUsableSurface(surfaceSize)) {
+    return undefined;
+  }
+
+  if (config.mode !== 'fit' && config.mode !== 'fill' && config.mode !== 'extend-world') {
+    throw new RangeError(`Unknown viewport mode: ${String(config.mode)}`);
+  }
+
+  const { width: surfaceWidth, height: surfaceHeight } = surfaceSize;
+  const widthScale = surfaceWidth / logicalWidth;
+  const heightScale = surfaceHeight / logicalHeight;
+
+  let scale: number;
+  let offsetX: number;
+  let offsetY: number;
+  let visibleLogicalBounds: Rect;
+  let contentBounds: Rect;
+
+  if (config.mode === 'fill') {
+    scale = Math.max(widthScale, heightScale);
+    offsetX = (surfaceWidth - logicalWidth * scale) / 2;
+    offsetY = (surfaceHeight - logicalHeight * scale) / 2;
+    visibleLogicalBounds = rect(
+      -offsetX / scale,
+      -offsetY / scale,
+      surfaceWidth / scale,
+      surfaceHeight / scale,
+    );
+    contentBounds = rect(0, 0, surfaceWidth, surfaceHeight);
+  } else {
+    // `fit` and `extend-world` share the fit (minimum uniform) scale.
+    scale = Math.min(widthScale, heightScale);
+    offsetX = (surfaceWidth - logicalWidth * scale) / 2;
+    offsetY = (surfaceHeight - logicalHeight * scale) / 2;
+    if (config.mode === 'extend-world') {
+      const worldWidth = surfaceWidth / scale;
+      const worldHeight = surfaceHeight / scale;
+      visibleLogicalBounds = rect(
+        (logicalWidth - worldWidth) / 2,
+        (logicalHeight - worldHeight) / 2,
+        worldWidth,
+        worldHeight,
+      );
+      contentBounds = rect(0, 0, surfaceWidth, surfaceHeight);
+    } else {
+      visibleLogicalBounds = rect(0, 0, logicalWidth, logicalHeight);
+      contentBounds = rect(offsetX, offsetY, logicalWidth * scale, logicalHeight * scale);
+    }
+  }
+
+  return Object.freeze({
+    surfaceSize: Object.freeze({ width: surfaceWidth, height: surfaceHeight }),
+    logicalBounds: rect(0, 0, logicalWidth, logicalHeight),
+    visibleLogicalBounds,
+    contentBounds,
+    scale,
+    offsetX,
+    offsetY,
+  });
+}
+
+/** Convert a logical/world point into surface coordinates. */
+export function worldToSurface(viewport: ResolvedViewport2D, point: Point2D): Point2D {
+  return Object.freeze({
+    x: point.x * viewport.scale + viewport.offsetX,
+    y: point.y * viewport.scale + viewport.offsetY,
+  });
+}
+
+/** Convert a surface point into logical/world coordinates. */
+export function surfaceToWorld(viewport: ResolvedViewport2D, point: Point2D): Point2D {
+  return Object.freeze({
+    x: (point.x - viewport.offsetX) / viewport.scale,
+    y: (point.y - viewport.offsetY) / viewport.scale,
+  });
+}
+
+/**
+ * Decide whether a surface point lies inside the interactive content area.
+ *
+ * For `fit` this rejects letterbox space so a pointer cannot begin there. For
+ * `fill` and `extend-world` the entire surface is interactive. Conversion
+ * itself remains mathematical everywhere; this operation decides whether a
+ * gesture may begin.
+ */
+export function containsSurfacePoint(viewport: ResolvedViewport2D, point: Point2D): boolean {
+  const { x, y, width, height } = viewport.contentBounds;
+  return point.x >= x && point.y >= y && point.x <= x + width && point.y <= y + height;
+}

package/src/viewport2d/types.ts

@@ -0,0 +1,63 @@
+/** The logical size of the game viewport in design points. */
+export interface LogicalSize {
+  /** Logical width in points. */
+  readonly width: number;
+  /** Logical height in points. */
+  readonly height: number;
+}
+
+/** How the authored logical viewport maps onto the mounted surface. */
+export type ViewportMode = 'fit' | 'fill' | 'extend-world';
+
+/** The authored viewport configuration of a game. */
+export interface Viewport {
+  /** The logical coordinate space the game is authored against. */
+  readonly logicalSize: LogicalSize;
+  /** How the authored viewport scales onto the mounted game surface. */
+  readonly mode: ViewportMode;
+}
+
+/** The actual mounted size of a game surface in React Native layout points. */
+export interface SurfaceSize {
+  /** Surface width in points. */
+  readonly width: number;
+  /** Surface height in points. */
+  readonly height: number;
+}
+
+/** An axis-aligned rectangle in a coordinate space. */
+export interface Rect {
+  /** Left edge. */
+  readonly x: number;
+  /** Top edge. */
+  readonly y: number;
+  /** Width. */
+  readonly width: number;
+  /** Height. */
+  readonly height: number;
+}
+
+/**
+ * A resolved, immutable viewport mapping between logical/world coordinates
+ * and surface coordinates.
+ *
+ * The transformation is linear: `surface = world * scale + offset`. All
+ * fields are plain data and are safe to share between drawing and hit
+ * testing.
+ */
+export interface ResolvedViewport2D {
+  /** The surface size this viewport was resolved against. */
+  readonly surfaceSize: SurfaceSize;
+  /** The authored logical bounds: `{ x: 0, y: 0, width, height }`. */
+  readonly logicalBounds: Rect;
+  /** The portion of the logical/world space visible on the surface. */
+  readonly visibleLogicalBounds: Rect;
+  /** The surface region covered by visible world content. */
+  readonly contentBounds: Rect;
+  /** The one uniform scale from world units to surface points. */
+  readonly scale: number;
+  /** Horizontal translation offset in surface points. */
+  readonly offsetX: number;
+  /** Vertical translation offset in surface points. */
+  readonly offsetY: number;
+}