rn-gamekit 0.1.0 → 0.2.0

package/src/collision2d/manifolds.ts

@@ -0,0 +1,191 @@
+/**
+ * Contact manifolds (T11.2).
+ *
+ * A `CollisionHit2D` reports geometry only: the normal that moves the FIRST
+ * argument out of the SECOND, the nonnegative penetration depth, and a
+ * stable contact point. Applying `first += normal * depth` resolves an
+ * ordinary overlap within documented floating-point tolerance. Misses
+ * return `undefined` and allocate nothing.
+ *
+ * Conventions (locked in T11.0):
+ * - Boundary contact counts as intersection and may return a zero-depth hit.
+ * - Circle-AABB: the contact point is the closest point on the AABB to the
+ *   circle center; when the center is inside the AABB, the minimum
+ *   penetration face wins with ties in the order left, top, right, bottom.
+ * - Circle-circle: the contact point is on the first circle's boundary
+ *   toward the second; coincident centers use the fallback normal `(0, 1)`
+ *   (straight up the positive-y axis) with full overlap depth `r1 + r2`.
+ * - AABB-AABB: the contact point is the center of the overlap rectangle;
+ *   exact corner ties use the normal `(0, 1)`.
+ */
+import type { Aabb2D, Circle2D, Point2D, Vector2D } from '../geometry/types';
+import {
+  assertValidAabb2D,
+  assertValidCircle2D,
+} from '../geometry/validation';
+import { closestPointOnAabb2D } from './intersections';
+
+/** One contact between two shapes, in the first shape's local resolution. */
+export interface CollisionHit2D {
+  /** Unit normal moving the first argument out of the second. */
+  readonly normal: Vector2D;
+  /** Nonnegative penetration depth in logical world units. */
+  readonly depth: number;
+  /** Stable contact point in world coordinates. */
+  readonly point: Point2D;
+}
+
+/** Resolution tolerance used by tests: relative to the shape size. */
+export const RESOLUTION_TOLERANCE = 1e-9;
+
+/** AABB-AABB contact manifold. `undefined` when the shapes do not touch. */
+export function collideAabbAabb2D(first: Aabb2D, second: Aabb2D): CollisionHit2D | undefined {
+  assertValidAabb2D(first, 'first');
+  assertValidAabb2D(second, 'second');
+
+  const firstMaxX = first.x + first.width;
+  const firstMaxY = first.y + first.height;
+  const secondMaxX = second.x + second.width;
+  const secondMaxY = second.y + second.height;
+
+  if (firstMaxX < second.x || first.x > secondMaxX || firstMaxY < second.y || first.y > secondMaxY) {
+    return undefined;
+  }
+
+  // Directional minimum translation (T11-F1): for each axis, the distance
+  // that fully separates the intervals in each direction. This resolves
+  // containment completely, not merely to a smaller intersection rectangle.
+  const exitLeft = firstMaxX - second.x;
+  const exitRight = secondMaxX - first.x;
+  const exitUp = firstMaxY - second.y;
+  const exitDown = secondMaxY - first.y;
+  const depthX = Math.min(exitLeft, exitRight);
+  const depthY = Math.min(exitUp, exitDown);
+
+  let normal: Vector2D;
+  let depth: number;
+  if (depthX === 0 && depthY === 0) {
+    // Exact corner touch: locked deterministic tie rule.
+    normal = Object.freeze({ x: 0, y: 1 });
+    depth = 0;
+  } else if (depthX < depthY) {
+    normal = Object.freeze({ x: exitLeft <= exitRight ? -1 : 1, y: 0 });
+    depth = depthX;
+  } else {
+    // Equal axes resolve on Y (locked tie rule); equal directions on the
+    // chosen axis resolve toward the negative direction.
+    normal = Object.freeze({ x: 0, y: exitUp <= exitDown ? -1 : 1 });
+    depth = depthY;
+  }
+
+  return Object.freeze({
+    normal,
+    depth,
+    point: Object.freeze({
+      x: (Math.max(first.x, second.x) + Math.min(firstMaxX, secondMaxX)) / 2,
+      y: (Math.max(first.y, second.y) + Math.min(firstMaxY, secondMaxY)) / 2,
+    }),
+  });
+}
+
+/** Circle-circle contact manifold. `undefined` when the circles do not touch. */
+export function collideCircleCircle2D(
+  first: Circle2D,
+  second: Circle2D,
+): CollisionHit2D | undefined {
+  assertValidCircle2D(first, 'first');
+  assertValidCircle2D(second, 'second');
+
+  const dx = first.x - second.x;
+  const dy = first.y - second.y;
+  const radiusSum = first.radius + second.radius;
+  const distanceSquared = dx * dx + dy * dy;
+  if (distanceSquared > radiusSum * radiusSum) {
+    return undefined;
+  }
+
+  const distance = Math.sqrt(distanceSquared);
+  if (distance === 0) {
+    // Coincident centers: locked fallback normal (straight up), full
+    // overlap depth, contact point on the first circle's boundary along
+    // the normal.
+    return Object.freeze({
+      normal: Object.freeze({ x: 0, y: 1 }),
+      depth: radiusSum,
+      point: Object.freeze({ x: first.x, y: first.y + first.radius }),
+    });
+  }
+
+  // From the second center toward the first: moves the first argument out
+  // of the second.
+  const normal: Vector2D = Object.freeze({ x: dx / distance, y: dy / distance });
+  // Contact point: on the first circle's boundary, on the side facing the
+  // second circle (opposite the push-out normal).
+  return Object.freeze({
+    normal,
+    depth: radiusSum - distance,
+    point: Object.freeze({
+      x: first.x - normal.x * first.radius,
+      y: first.y - normal.y * first.radius,
+    }),
+  });
+}
+
+/** Circle-AABB contact manifold. `undefined` when they do not touch. */
+export function collideCircleAabb2D(circle: Circle2D, aabb: Aabb2D): CollisionHit2D | undefined {
+  assertValidCircle2D(circle);
+  assertValidAabb2D(aabb);
+
+  const closest = closestPointOnAabb2D(circle, aabb);
+  const dx = circle.x - closest.x;
+  const dy = circle.y - closest.y;
+  const distanceSquared = dx * dx + dy * dy;
+  if (distanceSquared > circle.radius * circle.radius) {
+    return undefined;
+  }
+
+  if (distanceSquared === 0) {
+    // The circle center is inside the AABB: push out along the nearest
+    // face; ties resolve left, top, right, bottom (locked).
+    const left = circle.x - aabb.x;
+    const right = aabb.x + aabb.width - circle.x;
+    const top = circle.y - aabb.y;
+    const bottom = aabb.y + aabb.height - circle.y;
+    const minimum = Math.min(left, right, top, bottom);
+
+    let normal: Vector2D;
+    let point: Point2D;
+    if (minimum === left) {
+      normal = Object.freeze({ x: -1, y: 0 });
+      point = Object.freeze({ x: aabb.x, y: circle.y });
+    } else if (minimum === top) {
+      normal = Object.freeze({ x: 0, y: -1 });
+      point = Object.freeze({ x: circle.x, y: aabb.y });
+    } else if (minimum === right) {
+      normal = Object.freeze({ x: 1, y: 0 });
+      point = Object.freeze({ x: aabb.x + aabb.width, y: circle.y });
+    } else {
+      normal = Object.freeze({ x: 0, y: 1 });
+      point = Object.freeze({ x: circle.x, y: aabb.y + aabb.height });
+    }
+    return Object.freeze({
+      normal,
+      depth: minimum + circle.radius,
+      point,
+    });
+  }
+
+  const distance = Math.sqrt(distanceSquared);
+  // From the closest AABB point toward the circle center: moves the circle
+  // (the first argument) out of the AABB.
+  const normal: Vector2D = Object.freeze({ x: dx / distance, y: dy / distance });
+  return Object.freeze({
+    normal,
+    depth: circle.radius - distance,
+    // GS-COLLISION-01: copy-freeze the contact point at the public result
+    // boundary. `closest` is rebuilt per call, but copying keeps the hit
+    // independent of any future helper caching; sweeps reuse this object
+    // through hitFromManifold, so one fix covers every wrapper.
+    point: Object.freeze({ x: closest.x, y: closest.y }),
+  });
+}

package/src/collision2d/segments.ts

@@ -0,0 +1,176 @@
+/**
+ * Segment queries (T11.3).
+ *
+ * Return the earliest crossing of a directed segment with a shape, with
+ * `time` in `[0, 1]`. A segment starting inside a shape returns `time: 0`
+ * with the deterministic nearest-face normal (same tie rule as the
+ * manifolds: left, top, right, bottom for AABBs; the outward radial
+ * direction for circles with the `(0, 1)` fallback at the center).
+ */
+import type { Aabb2D, Circle2D, Point2D, Segment2D, Vector2D } from '../geometry/types';
+import {
+  assertValidAabb2D,
+  assertValidCircle2D,
+  assertValidSegment2D,
+} from '../geometry/validation';
+import { pointInAabb2D, pointInCircle2D } from './intersections';
+
+/** Earliest segment crossing of a shape. */
+export interface SegmentHit2D {
+  /** Normalized crossing time in `[0, 1]`. */
+  readonly time: number;
+  /** Unit normal at the crossed boundary (nearest-face rule inside). */
+  readonly normal: Vector2D;
+  /** Crossing point in world coordinates. */
+  readonly point: Point2D;
+}
+
+/** Earliest crossing of a segment with an AABB (slab method). */
+export function intersectSegmentAabb2D(segment: Segment2D, aabb: Aabb2D): SegmentHit2D | undefined {
+  assertValidSegment2D(segment);
+  assertValidAabb2D(aabb);
+
+  if (pointInAabb2D(segment.start, aabb)) {
+    return insideStart(segment.start, aabb);
+  }
+
+  const dx = segment.end.x - segment.start.x;
+  const dy = segment.end.y - segment.start.y;
+  const minX = aabb.x;
+  const maxX = aabb.x + aabb.width;
+  const minY = aabb.y;
+  const maxY = aabb.y + aabb.height;
+
+  let tMin = 0;
+  let tMax = 1;
+  let entryAxis: 'x' | 'y' | undefined;
+  let entrySign = 0;
+
+  for (const axis of ['x', 'y'] as const) {
+    const origin = axis === 'x' ? segment.start.x : segment.start.y;
+    const delta = axis === 'x' ? dx : dy;
+    const min = axis === 'x' ? minX : minY;
+    const max = axis === 'x' ? maxX : maxY;
+    if (delta === 0) {
+      if (origin <= min || origin >= max) {
+        // Parallel and outside the slab, or grazing exactly along a
+        // boundary: neither is a crossing.
+        return undefined;
+      }
+      continue;
+    }
+    const tMinFace = (min - origin) / delta;
+    const tMaxFace = (max - origin) / delta;
+    const t1 = Math.min(tMinFace, tMaxFace);
+    const t2 = Math.max(tMinFace, tMaxFace);
+    if (t1 > tMin) {
+      tMin = t1;
+      entryAxis = axis;
+      // The outward normal of the face crossed first: the min face points
+      // -axis, the max face points +axis.
+      entrySign = t1 === tMinFace ? -1 : 1;
+    }
+    tMax = Math.min(tMax, t2);
+    if (tMax < tMin) {
+      return undefined;
+    }
+  }
+
+  if (entryAxis === undefined) {
+    return undefined; // The segment travels along the boundary without crossing.
+  }
+  const atX = segment.start.x + dx * tMin;
+  const atY = segment.start.y + dy * tMin;
+  const normal: Vector2D =
+    entryAxis === 'x'
+      ? Object.freeze({ x: entrySign, y: 0 })
+      : Object.freeze({ x: 0, y: entrySign });
+  return Object.freeze({
+    time: tMin,
+    normal,
+    point: Object.freeze({ x: atX, y: atY }),
+  });
+}
+
+/** A segment starting inside an AABB: time 0 with the nearest-face normal. */
+function insideStart(point: Point2D, aabb: Aabb2D): SegmentHit2D {
+  const left = point.x - aabb.x;
+  const right = aabb.x + aabb.width - point.x;
+  const top = point.y - aabb.y;
+  const bottom = aabb.y + aabb.height - point.y;
+  const minimum = Math.min(left, right, top, bottom);
+  let normal: Vector2D;
+  if (minimum === left) {
+    normal = Object.freeze({ x: -1, y: 0 });
+  } else if (minimum === top) {
+    normal = Object.freeze({ x: 0, y: -1 });
+  } else if (minimum === right) {
+    normal = Object.freeze({ x: 1, y: 0 });
+  } else {
+    normal = Object.freeze({ x: 0, y: 1 });
+  }
+  return Object.freeze({
+    time: 0,
+    normal,
+    point: Object.freeze({ x: point.x, y: point.y }),
+  });
+}
+
+/** Earliest crossing of a segment with a circle. */
+export function intersectSegmentCircle2D(
+  segment: Segment2D,
+  circle: Circle2D,
+): SegmentHit2D | undefined {
+  assertValidSegment2D(segment);
+  assertValidCircle2D(circle);
+
+  const dx = segment.end.x - segment.start.x;
+  const dy = segment.end.y - segment.start.y;
+  const fx = segment.start.x - circle.x;
+  const fy = segment.start.y - circle.y;
+
+  if (pointInCircle2D(segment.start, circle)) {
+    const distanceSquared = fx * fx + fy * fy;
+    const distance = Math.sqrt(distanceSquared);
+    // Outward radial: the normalized center-to-start vector. The (0, 1)
+    // fallback applies only at the exact center.
+    const normal: Vector2D =
+      distance === 0
+        ? Object.freeze({ x: 0, y: 1 })
+        : Object.freeze({ x: fx / distance, y: fy / distance });
+    return Object.freeze({
+      time: 0,
+      normal,
+      point: Object.freeze({ x: segment.start.x, y: segment.start.y }),
+    });
+  }
+
+  const a = dx * dx + dy * dy;
+  const b = 2 * (fx * dx + fy * dy);
+  const c = fx * fx + fy * fy - circle.radius * circle.radius;
+  const discriminant = b * b - 4 * a * c;
+  if (discriminant < 0) {
+    return undefined;
+  }
+
+  const root = Math.sqrt(discriminant);
+  const t = (-b - root) / (2 * a);
+  if (t < 0 || t > 1) {
+    return undefined;
+  }
+
+  const atX = segment.start.x + dx * t;
+  const atY = segment.start.y + dy * t;
+  const outX = atX - circle.x;
+  const outY = atY - circle.y;
+  const outDistance = Math.hypot(outX, outY);
+  const normal: Vector2D =
+    outDistance === 0
+      ? Object.freeze({ x: 0, y: 1 })
+      : Object.freeze({ x: outX / outDistance, y: outY / outDistance });
+  return Object.freeze({
+    time: t,
+    normal,
+    point: Object.freeze({ x: atX, y: atY }),
+  });
+}

package/src/collision2d/spatialHash.ts

@@ -0,0 +1,211 @@
+/**
+ * Deterministic spatial hash broad phase (T11.5).
+ *
+ * `buildSpatialHash2D` validates and freezes a plain immutable index value;
+ * the per-cell buckets live in an internal WeakMap so callers can never
+ * mutate or depend on them. `querySpatialHash2D` visits only the query's
+ * cells and returns candidate ids deduplicated and in original insertion
+ * order. The broad phase is conservative: it returns candidates, never a
+ * narrow-phase collision claim.
+ */
+import type { Aabb2D } from '../geometry/types';
+import {
+  assertValidAabb2D,
+  GeometryError,
+} from '../geometry/validation';
+
+/** One indexed item with a stable identifier and AABB bounds. */
+export interface SpatialHashItem2D {
+  /** Stable identifier; must be unique within one index. */
+  readonly id: string;
+  /** AABB bounds in world coordinates. */
+  readonly bounds: Aabb2D;
+}
+
+/** A frozen, immutable spatial-hash index. */
+export interface SpatialHashIndex2D {
+  /** Positive finite cell size in world units. */
+  readonly cellSize: number;
+  /** The ordered items, deduplicated by identifier. */
+  readonly items: readonly SpatialHashItem2D[];
+}
+
+/** Options for building an index. */
+export interface BuildSpatialHash2DOptions {
+  /** Items to index, in the order candidates must be returned. */
+  readonly items: readonly SpatialHashItem2D[];
+  /** Positive finite cell size in world units. */
+  readonly cellSize: number;
+}
+
+/** Maximum cells an item or query may OCCUPY per axis (bounded execution). */
+export const MAX_SPATIAL_HASH_SPAN_CELLS = 1024;
+
+/**
+ * Maximum cells visited by ONE item insert or ONE query (GS-COLLISION-02).
+ *
+ * The per-axis bound alone permits ~1M cell visits per operation (~38ms
+ * on desktop V8, multiples of that on mobile). The total budget fails
+ * clearly before such spans do any work. Ordinary game spans (a few
+ * hundred cells per axis at most) pass with wide headroom; aggregate build
+ * cost still scales with item count, so prefer an appropriate cell size
+ * and reuse static indexes instead of rebuilding per dynamic body per tick.
+ */
+export const MAX_SPATIAL_HASH_TOTAL_CELLS = 65_536;
+
+/** Opaque per-index internal buckets and order, never exposed publicly. */
+const internalState = new WeakMap<
+  SpatialHashIndex2D,
+  { readonly cells: ReadonlyMap<string, readonly string[]>; readonly order: ReadonlyMap<string, number> }
+>();
+
+/** Build a spatial-hash index over the given items. */
+export function buildSpatialHash2D(options: BuildSpatialHash2DOptions): SpatialHashIndex2D {
+  const { items, cellSize } = options;
+  if (!Number.isFinite(cellSize) || cellSize <= 0) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'cellSize',
+      `expected a positive finite number, got ${String(cellSize)}`,
+    );
+  }
+  const seen = new Set<string>();
+  const cells = new Map<string, string[]>();
+  const order = new Map<string, number>();
+  const frozenItems: SpatialHashItem2D[] = [];
+  for (const item of items) {
+    if (seen.has(item.id)) {
+      throw new GeometryError(
+        'GEOMETRY_DUPLICATE_ID',
+        'items.id',
+        `expected unique item ids, got duplicate "${item.id}"`,
+      );
+    }
+    seen.add(item.id);
+    assertValidAabb2D(item.bounds, `items.${item.id}.bounds`);
+    // Clone the caller's item and its bounds: the index must never freeze
+    // or retain caller-owned objects, and the private buckets must agree
+    // with the public `items` view.
+    const cloned: SpatialHashItem2D = Object.freeze({
+      id: item.id,
+      bounds: Object.freeze({ ...item.bounds }),
+    });
+    frozenItems.push(cloned);
+    order.set(item.id, frozenItems.length - 1);
+    for (const cell of cellsOf(cloned.bounds, cellSize)) {
+      const key = cellKey(cell.x, cell.y);
+      const bucket = cells.get(key);
+      if (bucket === undefined) {
+        cells.set(key, [item.id]);
+      } else {
+        bucket.push(item.id);
+      }
+    }
+  }
+  const index = Object.freeze({
+    cellSize,
+    items: Object.freeze(frozenItems),
+  });
+  internalState.set(index, {
+    cells: new Map([...cells.entries()].map(([key, ids]) => [key, Object.freeze(ids)])),
+    // The local `order` map never escapes this function, so it is stored
+    // directly (GS-COLLISION-02): the extra copy served no ownership purpose.
+    order,
+  });
+  return index;
+}
+
+/** Query candidates whose bounds share a cell with the query bounds. */
+export function querySpatialHash2D(index: SpatialHashIndex2D, bounds: Aabb2D): readonly string[] {
+  assertValidAabb2D(bounds, 'bounds');
+  const state = internalState.get(index);
+  if (state === undefined) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'index',
+      'expected an index built by buildSpatialHash2D',
+    );
+  }
+  const seen = new Set<string>();
+  const collected: string[] = [];
+  for (const cell of cellsOf(bounds, index.cellSize)) {
+    const bucket = state.cells.get(cellKey(cell.x, cell.y));
+    if (bucket === undefined) {
+      continue;
+    }
+    for (const id of bucket) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        collected.push(id);
+      }
+    }
+  }
+  // Preserve original insertion order regardless of bucket order.
+  collected.sort((a, b) => state.order.get(a)! - state.order.get(b)!);
+  // The public result is frozen (T11-FF5): the immutable contract is
+  // runtime-enforced, not only a type-level promise.
+  return Object.freeze(collected);
+}
+
+interface Cell {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Every cell an AABB occupies, in deterministic order. */
+function* cellsOf(bounds: Aabb2D, cellSize: number): Generator<Cell> {
+  const minX = cellIndex(bounds.x, cellSize);
+  const maxX = cellIndex(bounds.x + bounds.width, cellSize);
+  const minY = cellIndex(bounds.y, cellSize);
+  const maxY = cellIndex(bounds.y + bounds.height, cellSize);
+  assertSpan(maxX - minX, 'x');
+  assertSpan(maxY - minY, 'y');
+  assertTotalCells(maxX - minX, maxY - minY);
+  for (let y = minY; y <= maxY; y += 1) {
+    for (let x = minX; x <= maxX; x += 1) {
+      yield { x, y };
+    }
+  }
+}
+
+/** Validate a derived cell index as a finite safe integer. */
+function cellIndex(coord: number, cellSize: number): number {
+  const index = Math.floor(coord / cellSize);
+  if (!Number.isSafeInteger(index)) {
+    throw new GeometryError(
+      'GEOMETRY_SPATIAL_INDEX_RANGE',
+      'bounds',
+      `coordinate ${coord} produces an unsafe cell index`,
+    );
+  }
+  return index;
+}
+
+/** Reject spans that would block the JS thread (bounded execution). */
+function assertSpan(span: number, axis: 'x' | 'y'): void {
+  const cells = span + 1; // The inclusive loop visits span + 1 cells.
+  if (cells > MAX_SPATIAL_HASH_SPAN_CELLS) {
+    throw new GeometryError(
+      'GEOMETRY_SPATIAL_INDEX_RANGE',
+      `bounds.${axis}`,
+      `bounds occupy ${cells} cells, exceeding the maximum of ${MAX_SPATIAL_HASH_SPAN_CELLS}`,
+    );
+  }
+}
+
+/** Reject total occupied cells beyond the work budget (GS-COLLISION-02). */
+function assertTotalCells(spanX: number, spanY: number): void {
+  // Both axes already passed assertSpan, so the product cannot overflow.
+  const total = (spanX + 1) * (spanY + 1);
+  if (total > MAX_SPATIAL_HASH_TOTAL_CELLS) {
+    throw new GeometryError(
+      'GEOMETRY_SPATIAL_INDEX_RANGE',
+      'bounds',
+      `bounds occupy ${total} cells, exceeding the total maximum of ${MAX_SPATIAL_HASH_TOTAL_CELLS}`,
+    );
+  }
+}
+
+function cellKey(x: number, y: number): string {
+  return `${x},${y}`;
+}