rn-gamekit 0.1.0 → 0.2.0

package/lib/module/collision2d/manifolds.js

@@ -0,0 +1,218 @@
+"use strict";
+
+/**
+ * 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 { assertValidAabb2D, assertValidCircle2D } from "../geometry/validation.js";
+import { closestPointOnAabb2D } from "./intersections.js";
+
+/** One contact between two shapes, in the first shape's local resolution. */
+
+/** 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, second) {
+  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;
+  let depth;
+  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, second) {
+  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 = 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, aabb) {
+  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;
+    let point;
+    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 = 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
+    })
+  });
+}
+//# sourceMappingURL=manifolds.js.map

package/lib/module/collision2d/manifolds.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["assertValidAabb2D","assertValidCircle2D","closestPointOnAabb2D","RESOLUTION_TOLERANCE","collideAabbAabb2D","first","second","firstMaxX","x","width","firstMaxY","y","height","secondMaxX","secondMaxY","undefined","exitLeft","exitRight","exitUp","exitDown","depthX","Math","min","depthY","normal","depth","Object","freeze","point","max","collideCircleCircle2D","dx","dy","radiusSum","radius","distanceSquared","distance","sqrt","collideCircleAabb2D","circle","aabb","closest","left","right","top","bottom","minimum"],"sourceRoot":"../../../src","sources":["collision2d/manifolds.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/collision2d/segments.js

@@ -0,0 +1,187 @@
+"use strict";
+
+/**
+ * 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 { assertValidAabb2D, assertValidCircle2D, assertValidSegment2D } from "../geometry/validation.js";
+import { pointInAabb2D, pointInCircle2D } from "./intersections.js";
+
+/** Earliest segment crossing of a shape. */
+
+/** Earliest crossing of a segment with an AABB (slab method). */
+export function intersectSegmentAabb2D(segment, aabb) {
+  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;
+  let entrySign = 0;
+  for (const axis of ['x', 'y']) {
+    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 = 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, aabb) {
+  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;
+  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, circle) {
+  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 = 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 = 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
+    })
+  });
+}
+//# sourceMappingURL=segments.js.map

package/lib/module/collision2d/segments.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["assertValidAabb2D","assertValidCircle2D","assertValidSegment2D","pointInAabb2D","pointInCircle2D","intersectSegmentAabb2D","segment","aabb","start","insideStart","dx","end","x","dy","y","minX","maxX","width","minY","maxY","height","tMin","tMax","entryAxis","entrySign","axis","origin","delta","min","max","undefined","tMinFace","tMaxFace","t1","Math","t2","atX","atY","normal","Object","freeze","time","point","left","right","top","bottom","minimum","intersectSegmentCircle2D","circle","fx","fy","distanceSquared","distance","sqrt","a","b","c","radius","discriminant","root","t","outX","outY","outDistance","hypot"],"sourceRoot":"../../../src","sources":["collision2d/segments.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/collision2d/spatialHash.js

@@ -0,0 +1,167 @@
+"use strict";
+
+/**
+ * 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 { assertValidAabb2D, GeometryError } from "../geometry/validation.js";
+
+/** One indexed item with a stable identifier and AABB bounds. */
+
+/** A frozen, immutable spatial-hash index. */
+
+/** Options for building an index. */
+
+/** 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();
+
+/** Build a spatial-hash index over the given items. */
+export function buildSpatialHash2D(options) {
+  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();
+  const cells = new Map();
+  const order = new Map();
+  const frozenItems = [];
+  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 = 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, bounds) {
+  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();
+  const collected = [];
+  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);
+}
+/** Every cell an AABB occupies, in deterministic order. */
+function* cellsOf(bounds, cellSize) {
+  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, cellSize) {
+  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, axis) {
+  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, spanY) {
+  // 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, y) {
+  return `${x},${y}`;
+}
+//# sourceMappingURL=spatialHash.js.map

package/lib/module/collision2d/spatialHash.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["assertValidAabb2D","GeometryError","MAX_SPATIAL_HASH_SPAN_CELLS","MAX_SPATIAL_HASH_TOTAL_CELLS","internalState","WeakMap","buildSpatialHash2D","options","items","cellSize","Number","isFinite","String","seen","Set","cells","Map","order","frozenItems","item","has","id","add","bounds","cloned","Object","freeze","push","set","length","cell","cellsOf","key","cellKey","x","y","bucket","get","undefined","index","entries","map","ids","querySpatialHash2D","state","collected","sort","a","b","minX","cellIndex","maxX","width","minY","maxY","height","assertSpan","assertTotalCells","coord","Math","floor","isSafeInteger","span","axis","spanX","spanY","total"],"sourceRoot":"../../../src","sources":["collision2d/spatialHash.ts"],"mappings":"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","ignoreList":[]}