rn-gamekit 0.1.0 → 0.2.1

package/src/collision2d/colliders.ts

@@ -0,0 +1,292 @@
+/**
+ * Attachable collider records and placement (T11.4).
+ *
+ * A `LocalCollider2D` is immutable local-space data: its `offset` and shape
+ * dimensions are relative to an authored object position. `placeCollider2D`
+ * is the ONLY local -> world path; world colliders feed broad-phase,
+ * collider-pair, and debug operations. Placement preserves filter, sensor,
+ * identifier, and author metadata and never mutates the source.
+ *
+ * Translation only: a rectangle stays axis-aligned and a circle stays a
+ * circle. There is no general transform, and rendering never owns gameplay
+ * collision state.
+ */
+import type { Aabb2D, Circle2D, Point2D, Vector2D } from '../geometry/types';
+import {
+  assertValidAabb2D,
+  assertValidCircle2D,
+  assertValidPoint2D,
+  assertUnsigned32Bits,
+} from '../geometry/validation';
+import type { CollisionFilter2D } from './filters';
+import { ALL_FILTER2D, canCollide2D } from './filters';
+import {
+  collideAabbAabb2D,
+  collideCircleAabb2D,
+  collideCircleCircle2D,
+  type CollisionHit2D,
+} from './manifolds';
+
+/** Shared collider metadata. */
+export interface ColliderMetadata2D {
+  /** Optional collision filter; absent means eligible with everything. */
+  readonly filter?: CollisionFilter2D;
+  /** True marks detection intent; never changes geometry results. */
+  readonly sensor?: boolean;
+  /** Stable user/entity identifier, independent of array indexes. */
+  readonly id?: string;
+}
+
+/** A local-space AABB collider. */
+export interface LocalAabbCollider2D extends ColliderMetadata2D {
+  readonly space: 'local';
+  readonly shape: 'aabb';
+  /** Offset of the AABB's top-left corner from the authored object position. */
+  readonly offset: Vector2D;
+  /** Local width in logical world units. */
+  readonly width: number;
+  /** Local height in logical world units. */
+  readonly height: number;
+}
+
+/** A local-space circle collider. */
+export interface LocalCircleCollider2D extends ColliderMetadata2D {
+  readonly space: 'local';
+  readonly shape: 'circle';
+  /** Offset of the circle's center from the authored object position. */
+  readonly offset: Vector2D;
+  /** Local radius in logical world units. */
+  readonly radius: number;
+}
+
+/** A collider definition in the authored object's local space. */
+export type LocalCollider2D = LocalAabbCollider2D | LocalCircleCollider2D;
+
+/** A world-space AABB collider (already placed). */
+export interface WorldAabbCollider2D extends ColliderMetadata2D {
+  readonly space: 'world';
+  readonly shape: 'aabb';
+  /** World top-left corner. */
+  readonly x: number;
+  /** World top-left corner. */
+  readonly y: number;
+  /** World width. */
+  readonly width: number;
+  /** World height. */
+  readonly height: number;
+}
+
+/** A world-space circle collider (already placed). */
+export interface WorldCircleCollider2D extends ColliderMetadata2D {
+  readonly space: 'world';
+  readonly shape: 'circle';
+  /** World center x. */
+  readonly x: number;
+  /** World center y. */
+  readonly y: number;
+  /** World radius. */
+  readonly radius: number;
+}
+
+/** A collider placed in world space. */
+export type WorldCollider2D = WorldAabbCollider2D | WorldCircleCollider2D;
+
+/** Options for the beginner rectangle collider constructor. */
+export interface RectangleCollider2DOptions {
+  /** Offset of the top-left corner from the object position. */
+  readonly offset: Vector2D;
+  /** Local width. */
+  readonly width: number;
+  /** Local height. */
+  readonly height: number;
+  readonly filter?: CollisionFilter2D;
+  readonly sensor?: boolean;
+  readonly id?: string;
+}
+
+/** Options for the beginner circle collider constructor. */
+export interface CircleCollider2DOptions {
+  /** Offset of the center from the object position. */
+  readonly offset: Vector2D;
+  /** Local radius. */
+  readonly radius: number;
+  readonly filter?: CollisionFilter2D;
+  readonly sensor?: boolean;
+  readonly id?: string;
+}
+
+/** Clone and freeze a caller-provided filter so later mutation cannot
+ *  change already-created colliders or their placements. */
+function freezeFilter(filter: CollisionFilter2D): CollisionFilter2D {
+  return Object.freeze({ categoryBits: filter.categoryBits, maskBits: filter.maskBits });
+}
+
+function validateMetadata(metadata: ColliderMetadata2D): void {
+  if (metadata.filter !== undefined) {
+    assertUnsigned32Bits(metadata.filter.categoryBits, 'filter.categoryBits');
+    assertUnsigned32Bits(metadata.filter.maskBits, 'filter.maskBits');
+  }
+}
+
+/** Create an immutable local AABB collider. */
+export function rectangleCollider2D(options: RectangleCollider2DOptions): LocalAabbCollider2D {
+  const collider: LocalAabbCollider2D = {
+    space: 'local',
+    shape: 'aabb',
+    offset: Object.freeze({ x: options.offset.x, y: options.offset.y }),
+    width: options.width,
+    height: options.height,
+    ...(options.filter === undefined ? {} : { filter: freezeFilter(options.filter) }),
+    ...(options.sensor === undefined ? {} : { sensor: options.sensor }),
+    ...(options.id === undefined ? {} : { id: options.id }),
+  };
+  validateMetadata(collider);
+  assertValidAabb2D(
+    {
+      x: options.offset.x,
+      y: options.offset.y,
+      width: options.width,
+      height: options.height,
+    },
+    'collider',
+  );
+  return Object.freeze(collider);
+}
+
+/** Create an immutable local circle collider. */
+export function circleCollider2D(options: CircleCollider2DOptions): LocalCircleCollider2D {
+  const collider: LocalCircleCollider2D = {
+    space: 'local',
+    shape: 'circle',
+    offset: Object.freeze({ x: options.offset.x, y: options.offset.y }),
+    radius: options.radius,
+    ...(options.filter === undefined ? {} : { filter: freezeFilter(options.filter) }),
+    ...(options.sensor === undefined ? {} : { sensor: options.sensor }),
+    ...(options.id === undefined ? {} : { id: options.id }),
+  };
+  validateMetadata(collider);
+  assertValidCircle2D(
+    { x: options.offset.x, y: options.offset.y, radius: options.radius },
+    'collider',
+  );
+  return Object.freeze(collider);
+}
+
+/**
+ * Place a local collider at an authored object position, returning an
+ * immutable world-space collider. Rejects local colliders at compile time.
+ */
+export function placeCollider2D(local: LocalCollider2D, position: Point2D): WorldCollider2D {
+  assertValidPoint2D(position, 'position');
+  const worldX = position.x + local.offset.x;
+  const worldY = position.y + local.offset.y;
+  const metadata = {
+    ...(local.filter === undefined ? {} : { filter: local.filter }),
+    ...(local.sensor === undefined ? {} : { sensor: local.sensor }),
+    ...(local.id === undefined ? {} : { id: local.id }),
+  };
+  if (local.shape === 'aabb') {
+    const world: WorldAabbCollider2D = {
+      space: 'world',
+      shape: 'aabb',
+      x: worldX,
+      y: worldY,
+      width: local.width,
+      height: local.height,
+      ...metadata,
+    };
+    assertValidAabb2D(world, 'world');
+    return Object.freeze(world);
+  }
+  const world: WorldCircleCollider2D = {
+    space: 'world',
+    shape: 'circle',
+    x: worldX,
+    y: worldY,
+    radius: local.radius,
+    ...metadata,
+  };
+  assertValidCircle2D(world, 'world');
+  return Object.freeze(world);
+}
+
+/** World-space AABB view of a collider (for broad-phase bounds). */
+export function worldColliderBounds2D(world: WorldCollider2D): Aabb2D {
+  if (world.shape === 'aabb') {
+    return Object.freeze({
+      x: world.x,
+      y: world.y,
+      width: world.width,
+      height: world.height,
+    });
+  }
+  return Object.freeze({
+    x: world.x - world.radius,
+    y: world.y - world.radius,
+    width: world.radius * 2,
+    height: world.radius * 2,
+  });
+}
+
+/** World-space circle view of a collider (for narrow-phase pairs). */
+export function worldColliderCircle2D(world: WorldCollider2D): Circle2D | undefined {
+  if (world.shape === 'circle') {
+    return Object.freeze({ x: world.x, y: world.y, radius: world.radius });
+  }
+  return undefined;
+}
+
+/**
+ * Narrow-phase contact between two placed world colliders.
+ *
+ * Filters are normalized first: an absent filter behaves exactly as
+ * `ALL_FILTER2D`, so `NONE_FILTER2D` on either side truly collides with
+ * nothing. The dispatch preserves the public argument order: the returned
+ * normal always moves the FIRST argument out of the SECOND, including for
+ * mixed AABB/circle pairs (the AABB-first wrapper inverts only the
+ * circle-first manifold normal, keeping depth and the world contact point).
+ */
+export function collideWorldColliders2D(
+  first: WorldCollider2D,
+  second: WorldCollider2D,
+): CollisionHit2D | undefined {
+  const firstFilter = first.filter ?? ALL_FILTER2D;
+  const secondFilter = second.filter ?? ALL_FILTER2D;
+  if (!canCollide2D(firstFilter, secondFilter)) {
+    return undefined;
+  }
+  if (first.shape === 'aabb' && second.shape === 'aabb') {
+    return collideAabbAabb2D(
+      { x: first.x, y: first.y, width: first.width, height: first.height },
+      { x: second.x, y: second.y, width: second.width, height: second.height },
+    );
+  }
+  if (first.shape === 'circle' && second.shape === 'circle') {
+    return collideCircleCircle2D(
+      { x: first.x, y: first.y, radius: first.radius },
+      { x: second.x, y: second.y, radius: second.radius },
+    );
+  }
+  if (first.shape === 'circle' && second.shape === 'aabb') {
+    return collideCircleAabb2D(
+      { x: first.x, y: first.y, radius: first.radius },
+      { x: second.x, y: second.y, width: second.width, height: second.height },
+    );
+  }
+  // AABB first, circle second: invert the circle-first manifold normal so
+  // the normal still moves the FIRST argument (the AABB) out of the second.
+  const aabbFirst = first as WorldAabbCollider2D;
+  const circleSecond = second as WorldCircleCollider2D;
+  const circleFirst = collideCircleAabb2D(
+    { x: circleSecond.x, y: circleSecond.y, radius: circleSecond.radius },
+    { x: aabbFirst.x, y: aabbFirst.y, width: aabbFirst.width, height: aabbFirst.height },
+  );
+  if (circleFirst === undefined) {
+    return undefined;
+  }
+  return Object.freeze({
+    normal: Object.freeze({ x: 0 - circleFirst.normal.x, y: 0 - circleFirst.normal.y }),
+    depth: circleFirst.depth,
+    point: circleFirst.point,
+  });
+}

package/src/collision2d/debug.ts

@@ -0,0 +1,133 @@
+/**
+ * Headless debug projections (T11.6).
+ *
+ * Immutable debug primitives a renderer can draw without importing Skia
+ * into the collision module. Colors and labels are optional presentation
+ * metadata, never gameplay semantics. Production collision results never
+ * allocate debug data; projection is opt-in.
+ */
+import type { Point2D, Vector2D } from '../geometry/types';
+import { assertValidPoint2D, assertValidVector2D } from '../geometry/validation';
+import type { CollisionHit2D } from './manifolds';
+import type { WorldCollider2D } from './colliders';
+
+/** Optional presentation metadata. */
+export interface DebugStyle2D {
+  /** Optional presentation color (renderer-specific encoding). */
+  readonly color?: string;
+  /** Optional author label (collider names, for example). */
+  readonly label?: string;
+}
+
+/** Debug AABB. */
+export interface DebugAabb2D extends DebugStyle2D {
+  readonly kind: 'aabb';
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Debug circle. */
+export interface DebugCircle2D extends DebugStyle2D {
+  readonly kind: 'circle';
+  readonly x: number;
+  readonly y: number;
+  readonly radius: number;
+}
+
+/** Debug segment (sweep paths, rays). */
+export interface DebugSegment2D extends DebugStyle2D {
+  readonly kind: 'segment';
+  readonly start: Point2D;
+  readonly end: Point2D;
+}
+
+/** Debug point (contact points). */
+export interface DebugPoint2D extends DebugStyle2D {
+  readonly kind: 'point';
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Debug vector (normals), drawn from `(x, y)` along `(dx, dy)`. */
+export interface DebugVector2D extends DebugStyle2D {
+  readonly kind: 'vector';
+  readonly x: number;
+  readonly y: number;
+  readonly dx: number;
+  readonly dy: number;
+}
+
+/** Any headless debug primitive. */
+export type DebugPrimitive2D =
+  | DebugAabb2D
+  | DebugCircle2D
+  | DebugSegment2D
+  | DebugPoint2D
+  | DebugVector2D;
+
+/** Project a world collider into a debug primitive, preserving its id. */
+export function projectWorldCollider2D(world: WorldCollider2D): DebugAabb2D | DebugCircle2D {
+  const style = world.id === undefined ? {} : { label: world.id };
+  if (world.shape === 'aabb') {
+    return Object.freeze({
+      kind: 'aabb',
+      x: world.x,
+      y: world.y,
+      width: world.width,
+      height: world.height,
+      ...style,
+    });
+  }
+  return Object.freeze({
+    kind: 'circle',
+    x: world.x,
+    y: world.y,
+    radius: world.radius,
+    ...style,
+  });
+}
+
+/** Project a contact hit into its contact point and normal arrow. */
+export function projectHit2D(hit: CollisionHit2D): {
+  readonly point: DebugPoint2D;
+  readonly normal: DebugVector2D;
+} {
+  return Object.freeze({
+    point: Object.freeze({ kind: 'point', x: hit.point.x, y: hit.point.y }),
+    normal: Object.freeze({
+      kind: 'vector',
+      x: hit.point.x,
+      y: hit.point.y,
+      dx: hit.normal.x,
+      dy: hit.normal.y,
+    }),
+  });
+}
+
+/** Project a sweep path (start to end of the swept reference point). */
+export function projectSweepPath2D(start: Point2D, end: Point2D, label?: string): DebugSegment2D {
+  assertValidPoint2D(start, 'start');
+  assertValidPoint2D(end, 'end');
+  return Object.freeze({
+    kind: 'segment',
+    start: Object.freeze({ x: start.x, y: start.y }),
+    end: Object.freeze({ x: end.x, y: end.y }),
+    ...(label === undefined ? {} : { label }),
+  });
+}
+
+/** Project a plain vector arrow (for example a velocity). */
+export function projectVector2D(origin: Point2D, vector: Vector2D, label?: string): DebugVector2D {
+  assertValidPoint2D(origin, 'origin');
+  assertValidVector2D(vector, 'vector');
+  return Object.freeze({
+    kind: 'vector',
+    x: origin.x,
+    y: origin.y,
+    dx: vector.x,
+    dy: vector.y,
+    ...(label === undefined ? {} : { label }),
+  });
+}

package/src/collision2d/filters.ts

@@ -0,0 +1,48 @@
+/**
+ * Collision filters (T11.4).
+ *
+ * Symmetric category/mask filtering with unsigned 32-bit bit sets,
+ * following the Box2D convention: two colliders are eligible only when each
+ * category is included by the other mask. No bit positions are reserved.
+ */
+import type { Vector2D } from '../geometry/types';
+import { assertUnsigned32Bits } from '../geometry/validation';
+
+/** Two explicit unsigned 32-bit bit sets for collision eligibility. */
+export interface CollisionFilter2D {
+  /** The bits this collider belongs to. */
+  readonly categoryBits: number;
+  /** The category bits this collider can collide with. */
+  readonly maskBits: number;
+}
+
+/**
+ * True when the two filters allow a collision (symmetric check).
+ *
+ * Invalid (non-unsigned-32-bit) values throw `GeometryError` before any
+ * comparison; `false` never implies malformed input.
+ */
+export function canCollide2D(first: CollisionFilter2D, second: CollisionFilter2D): boolean {
+  assertUnsigned32Bits(first.categoryBits, 'first.categoryBits');
+  assertUnsigned32Bits(first.maskBits, 'first.maskBits');
+  assertUnsigned32Bits(second.categoryBits, 'second.categoryBits');
+  assertUnsigned32Bits(second.maskBits, 'second.maskBits');
+  return (
+    (first.categoryBits & second.maskBits) !== 0 &&
+    (second.categoryBits & first.maskBits) !== 0
+  );
+}
+
+/** A collider without a filter: eligible with everything. */
+export const ALL_FILTER2D: CollisionFilter2D = Object.freeze({
+  categoryBits: 0xffffffff,
+  maskBits: 0xffffffff,
+});
+
+/** A collider that collides with nothing. */
+export const NONE_FILTER2D: CollisionFilter2D = Object.freeze({
+  categoryBits: 0,
+  maskBits: 0,
+});
+
+export type { Vector2D };

package/src/collision2d/index.ts

@@ -0,0 +1,74 @@
+export type { CollisionHit2D } from './manifolds';
+export { RESOLUTION_TOLERANCE } from './manifolds';
+export {
+  collideAabbAabb2D,
+  collideCircleAabb2D,
+  collideCircleCircle2D,
+} from './manifolds';
+export {
+  closestPointOnAabb2D,
+  intersectsAabbAabb2D,
+  intersectsCircleAabb2D,
+  intersectsCircleCircle2D,
+  pointInAabb2D,
+  pointInCircle2D,
+} from './intersections';
+export type { SegmentHit2D } from './segments';
+export {
+  intersectSegmentAabb2D,
+  intersectSegmentCircle2D,
+} from './segments';
+export type {
+  SweepAabbAabb2DOptions,
+  SweepCircleAabb2DOptions,
+  SweepHit2D,
+} from './sweeps';
+export {
+  sweepAabbAabb2D,
+  sweepCircleAabb2D,
+} from './sweeps';
+export type { CollisionFilter2D } from './filters';
+export {
+  ALL_FILTER2D,
+  canCollide2D,
+  NONE_FILTER2D,
+} from './filters';
+export type {
+  CircleCollider2DOptions,
+  ColliderMetadata2D,
+  LocalAabbCollider2D,
+  LocalCircleCollider2D,
+  LocalCollider2D,
+  RectangleCollider2DOptions,
+  WorldAabbCollider2D,
+  WorldCircleCollider2D,
+  WorldCollider2D,
+} from './colliders';
+export {
+  circleCollider2D,
+  collideWorldColliders2D,
+  placeCollider2D,
+  rectangleCollider2D,
+  worldColliderBounds2D,
+  worldColliderCircle2D,
+} from './colliders';
+export type { BuildSpatialHash2DOptions, SpatialHashIndex2D, SpatialHashItem2D } from './spatialHash';
+export {
+  buildSpatialHash2D,
+  querySpatialHash2D,
+} from './spatialHash';
+export type {
+  DebugAabb2D,
+  DebugCircle2D,
+  DebugPoint2D,
+  DebugPrimitive2D,
+  DebugSegment2D,
+  DebugStyle2D,
+  DebugVector2D,
+} from './debug';
+export {
+  projectHit2D,
+  projectSweepPath2D,
+  projectVector2D,
+  projectWorldCollider2D,
+} from './debug';

package/src/collision2d/intersections.ts

@@ -0,0 +1,82 @@
+/**
+ * Static intersection predicates (T11.2).
+ *
+ * Boundary contact counts as intersection. Invalid geometry throws
+ * `GeometryError`; `false` means normal domain absence. All predicates
+ * allocate nothing.
+ */
+import type { Aabb2D, Circle2D, Point2D } from '../geometry/types';
+import {
+  assertValidAabb2D,
+  assertValidCircle2D,
+  assertValidPoint2D,
+} from '../geometry/validation';
+
+/** True when `point` lies in or on `aabb` (boundary inclusive). */
+export function pointInAabb2D(point: Point2D, aabb: Aabb2D): boolean {
+  assertValidPoint2D(point, 'point');
+  assertValidAabb2D(aabb);
+  return (
+    point.x >= aabb.x &&
+    point.x <= aabb.x + aabb.width &&
+    point.y >= aabb.y &&
+    point.y <= aabb.y + aabb.height
+  );
+}
+
+/** True when `point` lies in or on `circle` (boundary inclusive). */
+export function pointInCircle2D(point: Point2D, circle: Circle2D): boolean {
+  assertValidPoint2D(point, 'point');
+  assertValidCircle2D(circle);
+  const dx = point.x - circle.x;
+  const dy = point.y - circle.y;
+  return dx * dx + dy * dy <= circle.radius * circle.radius;
+}
+
+/** True when the two AABBs intersect or touch. */
+export function intersectsAabbAabb2D(first: Aabb2D, second: Aabb2D): boolean {
+  assertValidAabb2D(first, 'first');
+  assertValidAabb2D(second, 'second');
+  return (
+    first.x <= second.x + second.width &&
+    first.x + first.width >= second.x &&
+    first.y <= second.y + second.height &&
+    first.y + first.height >= second.y
+  );
+}
+
+/** True when the two circles intersect or touch. */
+export function intersectsCircleCircle2D(first: Circle2D, second: Circle2D): boolean {
+  assertValidCircle2D(first, 'first');
+  assertValidCircle2D(second, 'second');
+  const dx = second.x - first.x;
+  const dy = second.y - first.y;
+  const radiusSum = first.radius + second.radius;
+  return dx * dx + dy * dy <= radiusSum * radiusSum;
+}
+
+/** True when the circle intersects or touches the AABB. */
+export function intersectsCircleAabb2D(circle: Circle2D, aabb: Aabb2D): boolean {
+  assertValidCircle2D(circle);
+  assertValidAabb2D(aabb);
+  const closestX = clamp(circle.x, aabb.x, aabb.x + aabb.width);
+  const closestY = clamp(circle.y, aabb.y, aabb.y + aabb.height);
+  const dx = circle.x - closestX;
+  const dy = circle.y - closestY;
+  return dx * dx + dy * dy <= circle.radius * circle.radius;
+}
+
+/** Closest point on the AABB to the circle center (shared by manifold code). */
+export function closestPointOnAabb2D(
+  point: Point2D,
+  aabb: Aabb2D,
+): { readonly x: number; readonly y: number } {
+  return {
+    x: clamp(point.x, aabb.x, aabb.x + aabb.width),
+    y: clamp(point.y, aabb.y, aabb.y + aabb.height),
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}