rn-gamekit 0.1.0 → 0.2.0

package/src/camera2d/transform.ts

@@ -0,0 +1,148 @@
+/**
+ * Camera2D transforms (T12.1).
+ *
+ * The frozen transform model (T12.0):
+ *
+ *     world point -> camera transform -> logical view point -> viewport -> surface
+ *     logical = L + rotate(P - C, -R) * Z
+ *     world   = C + rotate((logical - L) / Z, R)
+ *
+ * where C is the camera center, Z the zoom, R the rotation, and L the
+ * center of the authored logical view rect. Rotation follows the Skia
+ * convention (positive radians in the y-down screen plane); zoom is
+ * uniform and greater than zero. The convenience surface functions derive
+ * the logical view from the resolved viewport's visible bounds, so
+ * rendering and pointer input share one composition.
+ */
+import type { Aabb2D, Point2D } from '../geometry/types';
+import { GeometryError } from '../geometry/validation';
+import type { ResolvedViewport2D } from '../viewport2d/types';
+import { surfaceToWorld, worldToSurface } from '../viewport2d/math';
+import type { Camera2D } from './types';
+import { rotatedHalfExtents2D } from './extents';
+import { assertFinitePoint2D, assertValidCamera2D, assertValidLogicalView } from './validation';
+
+/** Rotate a point by an angle (Skia y-down convention). */
+export function rotatePoint2D(point: Point2D, radians: number): Point2D {
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+  return Object.freeze({
+    x: point.x * cos - point.y * sin,
+    y: point.x * sin + point.y * cos,
+  });
+}
+
+/** The center of the camera's authored logical view. */
+export function logicalViewCenter2D(logicalView: Aabb2D): Point2D {
+  return Object.freeze({
+    x: logicalView.x + logicalView.width / 2,
+    y: logicalView.y + logicalView.height / 2,
+  });
+}
+
+/**
+ * Create a camera from optional partial values; missing fields default to
+ * the identity camera (`center` origin, `zoom` 1, no rotation).
+ */
+export function createCamera2D(value?: Partial<Camera2D>): Camera2D {
+  if (value !== undefined && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'camera',
+      `expected a camera record, got ${value === null ? 'null' : typeof value}`,
+    );
+  }
+  const camera: Camera2D = {
+    center: value?.center ?? { x: 0, y: 0 },
+    zoom: value?.zoom ?? 1,
+    rotationRadians: value?.rotationRadians ?? 0,
+  };
+  assertValidCamera2D(camera);
+  return Object.freeze({
+    center: Object.freeze({ x: camera.center.x, y: camera.center.y }),
+    zoom: camera.zoom,
+    rotationRadians: camera.rotationRadians,
+  });
+}
+
+/** World -> logical view: `L + rotate(P - C, -R) * Z`. */
+export function worldToLogical2D(point: Point2D, camera: Camera2D, logicalView: Aabb2D): Point2D {
+  assertValidCamera2D(camera);
+  assertFinitePoint2D(point, 'point');
+  assertValidLogicalView(logicalView);
+  const { center, zoom, rotationRadians } = camera;
+  const logical = logicalViewCenter2D(logicalView);
+  const delta = {
+    x: point.x - center.x,
+    y: point.y - center.y,
+  };
+  const rotated = rotatePoint2D(delta, -rotationRadians);
+  return Object.freeze({
+    x: logical.x + rotated.x * zoom,
+    y: logical.y + rotated.y * zoom,
+  });
+}
+
+/** Logical view -> world: `C + rotate((logical - L) / Z, R)`. */
+export function logicalToWorld2D(point: Point2D, camera: Camera2D, logicalView: Aabb2D): Point2D {
+  assertValidCamera2D(camera);
+  assertFinitePoint2D(point, 'point');
+  assertValidLogicalView(logicalView);
+  const { center, zoom, rotationRadians } = camera;
+  const logical = logicalViewCenter2D(logicalView);
+  const scaled = {
+    x: (point.x - logical.x) / zoom,
+    y: (point.y - logical.y) / zoom,
+  };
+  const rotated = rotatePoint2D(scaled, rotationRadians);
+  return Object.freeze({
+    x: center.x + rotated.x,
+    y: center.y + rotated.y,
+  });
+}
+
+/** The conservative world-space AABB visible through the camera. */
+export function getCameraVisibleBounds2D(camera: Camera2D, logicalView: Aabb2D): Aabb2D {
+  assertValidCamera2D(camera);
+  assertValidLogicalView(logicalView);
+  const halfWidth = logicalView.width / 2 / camera.zoom;
+  const halfHeight = logicalView.height / 2 / camera.zoom;
+  const extent = rotatedHalfExtents2D(halfWidth, halfHeight, camera.rotationRadians);
+  const extentX = extent.x;
+  const extentY = extent.y;
+  return Object.freeze({
+    x: camera.center.x - extentX,
+    y: camera.center.y - extentY,
+    width: extentX * 2,
+    height: extentY * 2,
+  });
+}
+
+/**
+ * World -> surface through the camera and the resolved viewport.
+ *
+ * The camera's logical view is the viewport's visible logical bounds, so
+ * this composes exactly the transform the renderer draws with.
+ */
+export function worldToSurface2D(
+  point: Point2D,
+  viewport: ResolvedViewport2D,
+  camera: Camera2D,
+): Point2D {
+  assertValidCamera2D(camera);
+  assertFinitePoint2D(point, 'point');
+  const logical = worldToLogical2D(point, camera, viewport.visibleLogicalBounds);
+  return worldToSurface(viewport, logical);
+}
+
+/** Surface -> world through the viewport and the presented camera. */
+export function surfaceToWorld2D(
+  point: Point2D,
+  viewport: ResolvedViewport2D,
+  camera: Camera2D,
+): Point2D {
+  assertValidCamera2D(camera);
+  assertFinitePoint2D(point, 'point');
+  const logical = surfaceToWorld(viewport, point);
+  return logicalToWorld2D(logical, camera, viewport.visibleLogicalBounds);
+}

package/src/camera2d/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Camera2D public values (T12.1).
+ *
+ * A camera is immutable plain data: where the view is centered in world
+ * space, how much it zooms, and how it rotates. It carries no Skia
+ * matrices, no shared values, no viewport dimensions — presentation and
+ * conversion derive everything from this value plus the authored logical
+ * view.
+ */
+import type { Point2D } from '../geometry/types';
+
+/** The authored 2D camera value. */
+export interface Camera2D {
+  /** World-space point the camera looks at. */
+  readonly center: Point2D;
+  /** Finite uniform zoom, greater than zero. */
+  readonly zoom: number;
+  /** Rotation in radians, positive per the Skia coordinate convention. */
+  readonly rotationRadians: number;
+}
+
+/**
+ * A presented camera with an explicit cut signal.
+ *
+ * `cutId` increases monotonically across the lifetime of a camera binding.
+ * A changed `cutId` means the previous camera is unrelated: presentation
+ * snaps instead of interpolating (scene transitions, session replacement,
+ * binding-generation changes, explicit teleports, invalid prior data).
+ */
+export interface CameraCut2D {
+  /** The camera to present. */
+  readonly camera: Camera2D;
+  /** Monotonic cut signal; a new value disables interpolation. */
+  readonly cutId: number;
+}
+
+/** Per-axis follow enablement. Both default to true. */
+export interface CameraFollowAxisOptions2D {
+  /** Follow on the horizontal axis. */
+  readonly x?: boolean;
+  /** Follow on the vertical axis. */
+  readonly y?: boolean;
+}
+
+/** Options for `followCamera2D`. */
+export interface FollowCamera2DOptions2D {
+  /**
+   * Axis-aligned dead zone in world units, centered on the camera center.
+   * A target inside the zone leaves the camera untouched.
+   */
+  readonly deadZone?: { readonly x: number; readonly y: number; readonly width: number; readonly height: number };
+  /** Per-axis follow enablement. */
+  readonly perAxis?: CameraFollowAxisOptions2D;
+  /**
+   * Damping half-life in seconds: after this many seconds the remaining
+   * follow distance halves. Requires `deltaSeconds` on the call.
+   */
+  readonly dampingHalfLifeSeconds?: number;
+}
+
+/** Options for `sampleCameraShake2D`. */
+export interface CameraShakeOptions2D {
+  /** Deterministic seed; equal seeds produce equal offsets. */
+  readonly seed: number;
+  /** Elapsed simulation time in seconds since the shake began. */
+  readonly elapsedSeconds: number;
+  /** Shake duration in seconds; the base camera returns exactly at end. */
+  readonly durationSeconds: number;
+  /** Peak offset magnitude in world units. */
+  readonly amplitude: number;
+  /** Angular frequency in radians per second (defaults to 2π). */
+  readonly frequency?: number;
+}

package/src/camera2d/validation.ts

@@ -0,0 +1,126 @@
+/**
+ * Camera2D validation (T12.1, T12-F6).
+ *
+ * Reuses the Task 11 structured `GeometryError` codes so failures identify
+ * the operation and the invalid field. Validation happens at public
+ * operation boundaries; values are never coerced. Outer shapes are checked
+ * BEFORE field dereferencing, so null, arrays, and missing nested objects
+ * produce structured errors instead of incidental `TypeError`s.
+ */
+import type { Aabb2D, Point2D } from '../geometry/types';
+import { assertFiniteNumber, assertNonnegativeSize, GeometryError } from '../geometry/validation';
+import type { Camera2D } from './types';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Assert the outer shape of a camera before dereferencing fields. */
+export function assertCameraShape(camera: unknown, field: string): asserts camera is Camera2D {
+  if (!isRecord(camera)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a camera record, got ${camera === null ? 'null' : typeof camera}`,
+    );
+  }
+  if (!isRecord(camera.center)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      `${field}.center`,
+      `expected a point record, got ${camera.center === null ? 'null' : typeof camera.center}`,
+    );
+  }
+}
+
+/** Assert a valid camera value (shape + fields). */
+export function assertValidCamera2D(camera: Camera2D): void {
+  assertCameraShape(camera, 'camera');
+  assertFiniteNumber(camera.center.x, 'camera.center.x');
+  assertFiniteNumber(camera.center.y, 'camera.center.y');
+  assertFiniteNumber(camera.zoom, 'camera.zoom');
+  if (!(camera.zoom > 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'camera.zoom',
+      `expected a finite zoom greater than zero, got ${String(camera.zoom)}`,
+    );
+  }
+  assertFiniteNumber(camera.rotationRadians, 'camera.rotationRadians');
+}
+
+/** Assert a finite point (shape first). */
+export function assertFinitePoint2D(point: unknown, field: string): asserts point is Point2D {
+  if (!isRecord(point)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a point record, got ${point === null ? 'null' : typeof point}`,
+    );
+  }
+  const typed = point as unknown as Point2D;
+  assertFiniteNumber(typed.x, `${field}.x`);
+  assertFiniteNumber(typed.y, `${field}.y`);
+}
+
+/** Assert a valid logical view rect (shape + finite positive size). */
+export function assertValidLogicalView(view: unknown): asserts view is Aabb2D {
+  if (!isRecord(view)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'logicalView',
+      `expected a rect record, got ${view === null ? 'null' : typeof view}`,
+    );
+  }
+  const typed = view as unknown as Aabb2D;
+  assertFiniteNumber(typed.x, 'logicalView.x');
+  assertFiniteNumber(typed.y, 'logicalView.y');
+  assertNonnegativeSize(typed.width, 'logicalView.width');
+  assertNonnegativeSize(typed.height, 'logicalView.height');
+  if (!(typed.width > 0) || !(typed.height > 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_SIZE',
+      'logicalView',
+      `expected a positive logical view size, got ${view.width} x ${view.height}`,
+    );
+  }
+}
+
+/** Assert a nonnegative padding. */
+export function assertNonnegativePadding(padding: number): void {
+  assertNonnegativeSize(padding, 'padding');
+}
+
+/**
+ * Strict full-camera clone (T12-SF3): validates a COMPLETE runtime camera —
+ * every required field present and finite — and returns an owned frozen
+ * copy. Unlike `createCamera2D` (which fills partial authored options with
+ * identity defaults), a missing field is rejected. Used at publication
+ * boundaries where a partial value must never be silently completed.
+ */
+export function cloneValidCamera2D(camera: unknown, field = 'camera'): Camera2D {
+  assertCameraShape(camera, field);
+  const typed = camera as Camera2D;
+  const centerField = `${field}.center`;
+  assertFiniteNumber(typed.center.x, `${centerField}.x`);
+  assertFiniteNumber(typed.center.y, `${centerField}.y`);
+  if (typeof typed.zoom !== 'number' || !Number.isFinite(typed.zoom) || !(typed.zoom > 0)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      `${field}.zoom`,
+      `expected a finite zoom greater than zero, got ${String(typed.zoom)}`,
+    );
+  }
+  if (typeof typed.rotationRadians !== 'number' || !Number.isFinite(typed.rotationRadians)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      `${field}.rotationRadians`,
+      `expected a finite rotation, got ${String(typed.rotationRadians)}`,
+    );
+  }
+  return Object.freeze({
+    center: Object.freeze({ x: typed.center.x, y: typed.center.y }),
+    zoom: typed.zoom,
+    rotationRadians: typed.rotationRadians,
+  });
+}

package/src/camera2d/visibility.ts

@@ -0,0 +1,181 @@
+/**
+ * Camera2D visibility (T12.6).
+ *
+ * Presentation-only culling: computes what the camera can see and filters
+ * render records without changing simulation. An off-screen entity keeps
+ * simulating, colliding, and re-entering view. For rotated cameras the
+ * broad test uses the conservative visible AABB (a superset of the actual
+ * view polygon), so false positives are possible but false negatives are
+ * not — a visible object can never pop out.
+ */
+import type { Aabb2D, Circle2D, Point2D } from '../geometry/types';
+import { assertFiniteNumber, assertNonnegativeSize, GeometryError } from '../geometry/validation';
+import { intersectsAabbAabb2D, intersectsCircleAabb2D, pointInAabb2D } from '../collision2d/index';
+import { getCameraVisibleBounds2D } from './transform';
+import type { Camera2D } from './types';
+import { assertValidCamera2D, assertValidLogicalView, assertNonnegativePadding } from './validation';
+
+function assertPointPayload(value: unknown, field: string): void {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a point record, got ${value === null ? 'null' : typeof value}`,
+    );
+  }
+  const typed = value as { x?: unknown; y?: unknown };
+  assertFiniteNumber(typed.x as number, `${field}.x`);
+  assertFiniteNumber(typed.y as number, `${field}.y`);
+}
+
+function assertShapeRecord(shape: unknown): asserts shape is CameraViewShape2D {
+  if (typeof shape !== 'object' || shape === null || Array.isArray(shape)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'shape',
+      `expected a visibility shape record, got ${shape === null ? 'null' : typeof shape}`,
+    );
+  }
+  const kind = (shape as { kind?: unknown }).kind;
+  // T12-SF3: the payload is validated with Camera2D-prefixed nested paths
+  // BEFORE any Collision2D predicate dereferences it.
+  switch (kind) {
+    case 'aabb':
+      assertItemBounds((shape as { bounds?: unknown }).bounds, 'shape.bounds');
+      return;
+    case 'circle': {
+      const circle = (shape as { circle?: unknown }).circle;
+      if (typeof circle !== 'object' || circle === null || Array.isArray(circle)) {
+        throw new GeometryError(
+          'GEOMETRY_INVALID_NUMBER',
+          'shape.circle',
+          `expected a circle record, got ${circle === null ? 'null' : typeof circle}`,
+        );
+      }
+      const typed = circle as { x?: unknown; y?: unknown; radius?: unknown };
+      assertFiniteNumber(typed.x as number, 'shape.circle.x');
+      assertFiniteNumber(typed.y as number, 'shape.circle.y');
+      assertNonnegativeSize(typed.radius as number, 'shape.circle.radius');
+      return;
+    }
+    case 'point':
+      assertPointPayload((shape as { point?: unknown }).point, 'shape.point');
+      return;
+    default:
+      throw new GeometryError(
+        'GEOMETRY_INVALID_NUMBER',
+        'shape.kind',
+        `expected 'aabb' | 'circle' | 'point', got ${String(kind)}`,
+      );
+  }
+}
+
+function assertItemBounds(bounds: unknown, field = 'items.bounds'): asserts bounds is Aabb2D {
+  if (typeof bounds !== 'object' || bounds === null || Array.isArray(bounds)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a rect record, got ${bounds === null ? 'null' : typeof bounds}`,
+    );
+  }
+  const typed = bounds as Aabb2D;
+  assertFiniteNumber(typed.x, `${field}.x`);
+  assertFiniteNumber(typed.y, `${field}.y`);
+  assertNonnegativeSize(typed.width, `${field}.width`);
+  assertNonnegativeSize(typed.height, `${field}.height`);
+}
+
+function assertItemsArray(items: unknown): asserts items is readonly { readonly id: string; readonly bounds: Aabb2D }[] {
+  if (!Array.isArray(items)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'items',
+      `expected an array of indexed records, got ${items === null ? 'null' : typeof items}`,
+    );
+  }
+  for (const item of items) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+      throw new GeometryError('GEOMETRY_INVALID_NUMBER', 'items', 'expected item records');
+    }
+    const typed = item as { readonly id?: unknown; readonly bounds?: unknown };
+    if (typeof typed.id !== 'string') {
+      throw new GeometryError('GEOMETRY_INVALID_NUMBER', 'items.id', 'expected a string id');
+    }
+    assertItemBounds(typed.bounds);
+  }
+}
+
+/** A shape queryable against the camera view. */
+export type CameraViewShape2D =
+  | { readonly kind: 'aabb'; readonly bounds: Aabb2D }
+  | { readonly kind: 'circle'; readonly circle: Circle2D }
+  | { readonly kind: 'point'; readonly point: Point2D };
+
+/** The visible world bounds expanded by an optional padding. */
+export function paddedCameraBounds2D(
+  camera: Camera2D,
+  logicalView: Aabb2D,
+  padding = 0,
+): Aabb2D {
+  assertValidCamera2D(camera);
+  assertValidLogicalView(logicalView);
+  assertNonnegativePadding(padding);
+  const bounds = getCameraVisibleBounds2D(camera, logicalView);
+  return Object.freeze({
+    x: bounds.x - padding,
+    y: bounds.y - padding,
+    width: bounds.width + padding * 2,
+    height: bounds.height + padding * 2,
+  });
+}
+
+/**
+ * Whether a shape intersects the camera's visible region.
+ *
+ * The test is conservative: it uses the visible world AABB (exact for
+ * unrotated cameras, a superset for rotated ones). `padding` extends the
+ * region in world units for sprites and effects that draw outside their
+ * logical bounds.
+ */
+export function intersectsCameraView2D(
+  shape: CameraViewShape2D,
+  camera: Camera2D,
+  logicalView: Aabb2D,
+  padding = 0,
+): boolean {
+  assertShapeRecord(shape);
+  const visible = paddedCameraBounds2D(camera, logicalView, padding);
+  switch (shape.kind) {
+    case 'aabb':
+      return intersectsAabbAabb2D(shape.bounds, visible);
+    case 'circle':
+      return intersectsCircleAabb2D(shape.circle, visible);
+    case 'point':
+      return pointInAabb2D(shape.point, visible);
+  }
+}
+
+/**
+ * Filter indexed render records, preserving stable order.
+ *
+ * Returns a frozen copy containing only the records whose world bounds
+ * intersect the visible region (plus `padding`). Off-screen records keep
+ * their identity and order in the caller's array; nothing here mutates
+ * them or changes simulation.
+ */
+export function filterCameraVisible2D<T extends { readonly id: string; readonly bounds: Aabb2D }>(
+  items: readonly T[],
+  camera: Camera2D,
+  logicalView: Aabb2D,
+  padding = 0,
+): readonly T[] {
+  assertItemsArray(items as unknown);
+  const visible = paddedCameraBounds2D(camera, logicalView, padding);
+  const kept: T[] = [];
+  for (const item of items) {
+    if (intersectsAabbAabb2D(item.bounds, visible)) {
+      kept.push(item);
+    }
+  }
+  return Object.freeze(kept);
+}

package/src/camera2d.ts

@@ -0,0 +1,6 @@
+/**
+ * Subpath entry for `rn-gamekit/camera2d`.
+ *
+ * Headless camera math — no React hooks, Skia, or native peers.
+ */
+export * from './camera2d/index';