@flighthq/collision 0.4.0-next.1663.d9c5746 → 0.4.0-next.1695.181dea5

package/src/manifold.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from 'vitest';
 
-import { clearCollisionManifold, createCollisionManifold } from './manifold';
+import { clearCollisionManifold2D, createCollisionManifold2D } from './manifold';
 
-describe('clearCollisionManifold', () => {
+describe('clearCollisionManifold2D', () => {
   it('resets every field to the non-overlapping state', () => {
     const manifold = { overlapping: true, normalX: 0.5, normalY: -0.5, depth: 3 };
-    clearCollisionManifold(manifold);
+    clearCollisionManifold2D(manifold);
     expect(manifold.overlapping).toBe(false);
     expect(manifold.normalX).toBe(0);
     expect(manifold.normalY).toBe(0);
@@ -13,9 +13,9 @@ describe('clearCollisionManifold', () => {
   });
 });
 
-describe('createCollisionManifold', () => {
+describe('createCollisionManifold2D', () => {
   it('allocates a fresh manifold in the non-overlapping state', () => {
-    const manifold = createCollisionManifold();
+    const manifold = createCollisionManifold2D();
     expect(manifold.overlapping).toBe(false);
     expect(manifold.normalX).toBe(0);
     expect(manifold.normalY).toBe(0);
@@ -23,8 +23,8 @@ describe('createCollisionManifold', () => {
   });
 
   it('returns an independent object each call', () => {
-    const a = createCollisionManifold();
-    const b = createCollisionManifold();
+    const a = createCollisionManifold2D();
+    const b = createCollisionManifold2D();
     a.overlapping = true;
     expect(b.overlapping).toBe(false);
   });

package/src/pointContainment.test.ts

@@ -1,79 +1,83 @@
-import type { CollisionShape } from '@flighthq/types/contract';
+import type { CollisionBuiltInShape2D } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
-import { getCollisionShapeContainsPoint } from './pointContainment';
+import { getCollisionShapeContainsPoint2D } from './pointContainment';
 
-describe('getCollisionShapeContainsPoint', () => {
+describe('getCollisionShapeContainsPoint2D', () => {
   it('tests a circle inside, outside, and on the boundary (inclusive)', () => {
-    const circle: CollisionShape = { kind: 'circle', x: 0, y: 0, radius: 5 };
-    expect(getCollisionShapeContainsPoint(circle, 1, 1)).toBe(true);
-    expect(getCollisionShapeContainsPoint(circle, 5, 0)).toBe(true); // on the boundary
-    expect(getCollisionShapeContainsPoint(circle, 6, 0)).toBe(false);
+    const circle: CollisionBuiltInShape2D = { kind: 'circle', x: 0, y: 0, radius: 5 };
+    expect(getCollisionShapeContainsPoint2D(circle, 1, 1)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(circle, 5, 0)).toBe(true); // on the boundary
+    expect(getCollisionShapeContainsPoint2D(circle, 6, 0)).toBe(false);
   });
 
   it('tests an axis-aligned box, boundary-inclusive', () => {
-    const box: CollisionShape = { kind: 'aabb', minX: 0, minY: 0, maxX: 10, maxY: 10 };
-    expect(getCollisionShapeContainsPoint(box, 5, 5)).toBe(true);
-    expect(getCollisionShapeContainsPoint(box, 0, 10)).toBe(true); // corner
-    expect(getCollisionShapeContainsPoint(box, -1, 5)).toBe(false);
-    expect(getCollisionShapeContainsPoint(box, 11, 5)).toBe(false);
+    const box: CollisionBuiltInShape2D = { kind: 'aabb', minX: 0, minY: 0, maxX: 10, maxY: 10 };
+    expect(getCollisionShapeContainsPoint2D(box, 5, 5)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(box, 0, 10)).toBe(true); // corner
+    expect(getCollisionShapeContainsPoint2D(box, -1, 5)).toBe(false);
+    expect(getCollisionShapeContainsPoint2D(box, 11, 5)).toBe(false);
   });
 
   it('tests a rotated oriented box in its own frame', () => {
     // 45-degree box, half-extents 2x2. A point on the world axis at distance 2.8 is inside
     // (the box reaches ~2.83 along its diagonal) but the same distance is outside a smaller reach.
-    const obb: CollisionShape = { kind: 'obb', x: 0, y: 0, halfW: 2, halfH: 2, rotation: Math.PI / 4 };
-    expect(getCollisionShapeContainsPoint(obb, 0, 0)).toBe(true);
-    expect(getCollisionShapeContainsPoint(obb, 2.8, 0)).toBe(true); // toward a rotated corner
-    expect(getCollisionShapeContainsPoint(obb, 2.1, 2.1)).toBe(false); // just past a flat edge
+    const obb: CollisionBuiltInShape2D = { kind: 'obb', x: 0, y: 0, halfW: 2, halfH: 2, rotation: Math.PI / 4 };
+    expect(getCollisionShapeContainsPoint2D(obb, 0, 0)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(obb, 2.8, 0)).toBe(true); // toward a rotated corner
+    expect(getCollisionShapeContainsPoint2D(obb, 2.1, 2.1)).toBe(false); // just past a flat edge
   });
 
   it('tests a convex hexagon inside and outside', () => {
-    const hex: CollisionShape = { kind: 'polygon', points: [2, 0, 1, 2, -1, 2, -2, 0, -1, -2, 1, -2] };
-    expect(getCollisionShapeContainsPoint(hex, 0, 0)).toBe(true);
-    expect(getCollisionShapeContainsPoint(hex, 1.9, 0)).toBe(true);
-    expect(getCollisionShapeContainsPoint(hex, 3, 0)).toBe(false);
-    expect(getCollisionShapeContainsPoint(hex, 0, 3)).toBe(false);
+    const hex: CollisionBuiltInShape2D = { kind: 'polygon', points: [2, 0, 1, 2, -1, 2, -2, 0, -1, -2, 1, -2] };
+    expect(getCollisionShapeContainsPoint2D(hex, 0, 0)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(hex, 1.9, 0)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(hex, 3, 0)).toBe(false);
+    expect(getCollisionShapeContainsPoint2D(hex, 0, 3)).toBe(false);
   });
 
   it('rejects polygons with fewer than three vertices', () => {
-    const polygon: CollisionShape = { kind: 'polygon', points: [0, 0, 1, 1] };
-    expect(getCollisionShapeContainsPoint(polygon, 0.5, 0.5)).toBe(false);
+    const polygon: CollisionBuiltInShape2D = { kind: 'polygon', points: [0, 0, 1, 1] };
+    expect(getCollisionShapeContainsPoint2D(polygon, 0.5, 0.5)).toBe(false);
   });
 
   it('keeps containment proportional for a tiny polygon', () => {
-    const polygon: CollisionShape = {
+    const polygon: CollisionBuiltInShape2D = {
       kind: 'polygon',
       points: [0, 0, 1e-6, 0, 1e-6, 1e-6, 0, 1e-6],
     };
-    expect(getCollisionShapeContainsPoint(polygon, 0.5e-6, 0.5e-6)).toBe(true);
-    expect(getCollisionShapeContainsPoint(polygon, 2e-6, 0.5e-6)).toBe(false);
+    expect(getCollisionShapeContainsPoint2D(polygon, 0.5e-6, 0.5e-6)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(polygon, 2e-6, 0.5e-6)).toBe(false);
   });
 
   it('tests a point lying on a segment', () => {
-    const segment: CollisionShape = { kind: 'segment', x0: 0, y0: 0, x1: 10, y1: 0 };
-    expect(getCollisionShapeContainsPoint(segment, 5, 0)).toBe(true);
-    expect(getCollisionShapeContainsPoint(segment, 5, 0.1)).toBe(false);
-    expect(getCollisionShapeContainsPoint(segment, 11, 0)).toBe(false);
+    const segment: CollisionBuiltInShape2D = { kind: 'segment', x0: 0, y0: 0, x1: 10, y1: 0 };
+    expect(getCollisionShapeContainsPoint2D(segment, 5, 0)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(segment, 5, 0.1)).toBe(false);
+    expect(getCollisionShapeContainsPoint2D(segment, 11, 0)).toBe(false);
   });
 
   it('tests coincidence with a point collider', () => {
-    const point: CollisionShape = { kind: 'point', x: 3, y: 4 };
-    expect(getCollisionShapeContainsPoint(point, 3, 4)).toBe(true);
-    expect(getCollisionShapeContainsPoint(point, 3, 5)).toBe(false);
+    const point: CollisionBuiltInShape2D = { kind: 'point', x: 3, y: 4 };
+    expect(getCollisionShapeContainsPoint2D(point, 3, 4)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(point, 3, 5)).toBe(false);
   });
 
   it('treats zero-radius circles and zero-length segments as point-like', () => {
-    const circle: CollisionShape = { kind: 'circle', radius: 0, x: 3, y: 4 };
-    const segment: CollisionShape = { kind: 'segment', x0: 3, x1: 3, y0: 4, y1: 4 };
-    expect(getCollisionShapeContainsPoint(circle, 3, 4)).toBe(true);
-    expect(getCollisionShapeContainsPoint(circle, 3, 4.001)).toBe(false);
-    expect(getCollisionShapeContainsPoint(segment, 3, 4)).toBe(true);
-    expect(getCollisionShapeContainsPoint(segment, 3, 4.001)).toBe(false);
+    const circle: CollisionBuiltInShape2D = { kind: 'circle', radius: 0, x: 3, y: 4 };
+    const segment: CollisionBuiltInShape2D = { kind: 'segment', x0: 3, x1: 3, y0: 4, y1: 4 };
+    expect(getCollisionShapeContainsPoint2D(circle, 3, 4)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(circle, 3, 4.001)).toBe(false);
+    expect(getCollisionShapeContainsPoint2D(segment, 3, 4)).toBe(true);
+    expect(getCollisionShapeContainsPoint2D(segment, 3, 4.001)).toBe(false);
   });
 
   it('returns false for an unknown kind', () => {
-    const shape = { kind: 'acme.capsule', x: 0, y: 0 } as unknown as CollisionShape;
-    expect(getCollisionShapeContainsPoint(shape, 0, 0)).toBe(false);
+    // The double cast is the test: a vendor kind is a COMPILE error at this signature now, because
+    // containment has no registry to answer one with. What is asserted here is the residual runtime
+    // behaviour for callers who reach it anyway — untyped JavaScript, or a cast like this one — which
+    // must still be the `false` sentinel rather than a crash reading fields that are not there.
+    const shape = { kind: 'acme.capsule', x: 0, y: 0 } as unknown as CollisionBuiltInShape2D;
+    expect(getCollisionShapeContainsPoint2D(shape, 0, 0)).toBe(false);
   });
 });

package/src/{raycastCollisionShape.test.ts → raycastCollisionShape2D.test.ts}

@@ -1,19 +1,19 @@
-import type { CollisionRaycastHit, CollisionShape } from '@flighthq/types/contract';
+import type { CollisionRaycastHit2D, CollisionBuiltInShape2D } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
-import { createCollisionRaycastHit, raycastCollisionShape } from './raycastCollisionShape';
+import { createCollisionRaycastHit2D, raycastCollisionShape2D } from './raycastCollisionShape2D';
 
-function hit(): CollisionRaycastHit {
-  return createCollisionRaycastHit();
+function hit(): CollisionRaycastHit2D {
+  return createCollisionRaycastHit2D();
 }
 
-describe('createCollisionRaycastHit', () => {
+describe('createCollisionRaycastHit2D', () => {
   it('starts in the reusable miss state', () => {
-    expect(createCollisionRaycastHit()).toEqual({ fraction: 0, x: 0, y: 0, normalX: 0, normalY: 0 });
+    expect(createCollisionRaycastHit2D()).toEqual({ fraction: 0, x: 0, y: 0, normalX: 0, normalY: 0 });
   });
 });
 
-describe('raycastCollisionShape', () => {
+describe('raycastCollisionShape2D', () => {
   it('keeps polygon center state isolated from a nested raycast triggered by a point getter', () => {
     const points = [2, -1, 4, -1, 4, 1, 2, 1];
     let armed = false;
@@ -24,7 +24,14 @@ describe('raycastCollisionShape', () => {
         if (armed) {
           armed = false;
           nestedCalls++;
-          raycastCollisionShape({ kind: 'polygon', points: [-102, -1, -100, -1, -100, 1, -102, 1] }, 0, 0, 1, 0, hit());
+          raycastCollisionShape2D(
+            { kind: 'polygon', points: [-102, -1, -100, -1, -100, 1, -102, 1] },
+            0,
+            0,
+            1,
+            0,
+            hit(),
+          );
         }
         return 2;
       },
@@ -38,7 +45,7 @@ describe('raycastCollisionShape', () => {
     });
 
     const out = hit();
-    expect(raycastCollisionShape({ kind: 'polygon', points }, 0, 0, 1, 0, out)).toBe(true);
+    expect(raycastCollisionShape2D({ kind: 'polygon', points }, 0, 0, 1, 0, out)).toBe(true);
     expect(nestedCalls).toBeGreaterThan(0);
     expect(out.fraction).toBeCloseTo(2);
     expect(out.normalX).toBeCloseTo(-1);
@@ -54,7 +61,7 @@ describe('raycastCollisionShape', () => {
     ['point', { kind: 'point', x: 2, y: 0 }, 2, 0, 0],
   ] as const)('hits a %s at its first exact fraction', (_name, shape, fraction, normalX, normalY) => {
     const out = hit();
-    expect(raycastCollisionShape(shape as CollisionShape, 0, 0, 1, 0, out)).toBe(true);
+    expect(raycastCollisionShape2D(shape as CollisionBuiltInShape2D, 0, 0, 1, 0, out)).toBe(true);
     expect(out.fraction).toBeCloseTo(fraction);
     expect(out.x).toBeCloseTo(fraction);
     expect(out.y).toBeCloseTo(0);
@@ -64,33 +71,33 @@ describe('raycastCollisionShape', () => {
 
   it('rotates an oriented-box hit normal back to world space', () => {
     const out = hit();
-    const shape: CollisionShape = { kind: 'obb', x: 3, y: 0, halfW: 1, halfH: 0.5, rotation: Math.PI / 4 };
-    expect(raycastCollisionShape(shape, 0, 0, 1, 0, out)).toBe(true);
+    const shape: CollisionBuiltInShape2D = { kind: 'obb', x: 3, y: 0, halfW: 1, halfH: 0.5, rotation: Math.PI / 4 };
+    expect(raycastCollisionShape2D(shape, 0, 0, 1, 0, out)).toBe(true);
     expect(out.normalX).toBeCloseTo(-Math.SQRT1_2);
     expect(out.normalY).toBeCloseTo(Math.SQRT1_2);
   });
 
   it('reports an origin inside a shape at fraction zero with no entry normal', () => {
     const out = hit();
-    expect(raycastCollisionShape({ kind: 'circle', x: 0, y: 0, radius: 2 }, 0, 0, 1, 0, out)).toBe(true);
+    expect(raycastCollisionShape2D({ kind: 'circle', x: 0, y: 0, radius: 2 }, 0, 0, 1, 0, out)).toBe(true);
     expect(out).toEqual({ fraction: 0, x: 0, y: 0, normalX: 0, normalY: 0 });
   });
 
   it('honours maxFraction and clears output on a miss', () => {
     const out = { fraction: 9, x: 9, y: 9, normalX: 9, normalY: 9 };
-    expect(raycastCollisionShape({ kind: 'circle', x: 3, y: 0, radius: 1 }, 0, 0, 1, 0, out, 1)).toBe(false);
+    expect(raycastCollisionShape2D({ kind: 'circle', x: 3, y: 0, radius: 1 }, 0, 0, 1, 0, out, 1)).toBe(false);
     expect(out).toEqual({ fraction: 0, x: 0, y: 0, normalX: 0, normalY: 0 });
   });
 
   it('treats a zero direction as an exact point query', () => {
     const out = hit();
-    expect(raycastCollisionShape({ kind: 'aabb', minX: -1, minY: -1, maxX: 1, maxY: 1 }, 0, 0, 0, 0, out)).toBe(true);
-    expect(raycastCollisionShape({ kind: 'aabb', minX: 2, minY: 2, maxX: 3, maxY: 3 }, 0, 0, 0, 0, out)).toBe(false);
+    expect(raycastCollisionShape2D({ kind: 'aabb', minX: -1, minY: -1, maxX: 1, maxY: 1 }, 0, 0, 0, 0, out)).toBe(true);
+    expect(raycastCollisionShape2D({ kind: 'aabb', minX: 2, minY: 2, maxX: 3, maxY: 3 }, 0, 0, 0, 0, out)).toBe(false);
   });
 
   it('keeps point-ray tolerance invariant when direction is rescaled', () => {
-    const shape: CollisionShape = { kind: 'point', x: 2, y: 1e-6 };
-    expect(raycastCollisionShape(shape, 0, 0, 1, 0, hit())).toBe(false);
-    expect(raycastCollisionShape(shape, 0, 0, 1e6, 0, hit())).toBe(false);
+    const shape: CollisionBuiltInShape2D = { kind: 'point', x: 2, y: 1e-6 };
+    expect(raycastCollisionShape2D(shape, 0, 0, 1, 0, hit())).toBe(false);
+    expect(raycastCollisionShape2D(shape, 0, 0, 1e6, 0, hit())).toBe(false);
   });
 });

package/src/registerBuiltInCollisionPairTests2D.test.ts

@@ -0,0 +1,62 @@
+import type { CollisionShape2D } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { getCollisionPairTest2D } from './collisionSupport2D';
+import { createCollisionManifold2D } from './manifold';
+import { registerBuiltInCollisionPairTests2D } from './registerBuiltInCollisionPairTests2D';
+import { testCircleAabbCollision } from './shapeCollision';
+
+registerBuiltInCollisionPairTests2D();
+
+describe('registerBuiltInCollisionPairTests2D', () => {
+  it('registers exactly the ten canonical orders, and not their reverses', () => {
+    const kinds = ['circle', 'aabb', 'obb', 'polygon'];
+    const registered: string[] = [];
+    for (const kindA of kinds) {
+      for (const kindB of kinds) {
+        if (getCollisionPairTest2D(kindA, kindB) !== null) registered.push(`${kindA}-${kindB}`);
+      }
+    }
+
+    // Ten, not sixteen: the four self-pairs plus one order of each of the six mixed pairs. The reverse
+    // orders are absent on purpose — `testCollision2D` reaches them by trying the reverse key and
+    // negating, so registering both would double the table for no new geometry.
+    expect(registered).toEqual([
+      'circle-circle',
+      'circle-aabb',
+      'circle-obb',
+      'circle-polygon',
+      'aabb-aabb',
+      'aabb-obb',
+      'aabb-polygon',
+      'obb-obb',
+      'obb-polygon',
+      'polygon-polygon',
+    ]);
+  });
+
+  it('leaves the area-less kinds out of the table entirely', () => {
+    for (const kind of ['segment', 'point']) {
+      expect(getCollisionPairTest2D('circle', kind)).toBeNull();
+      expect(getCollisionPairTest2D(kind, 'circle')).toBeNull();
+    }
+  });
+
+  it('routes each entry to the direct typed test it specializes', () => {
+    const throughRegistry = createCollisionManifold2D();
+    const direct = createCollisionManifold2D();
+    const circle: CollisionShape2D = { kind: 'circle', x: 15, y: 5, radius: 7 };
+    const box: CollisionShape2D = { kind: 'aabb', minX: 0, minY: 0, maxX: 10, maxY: 10 };
+
+    const entry = getCollisionPairTest2D('circle', 'aabb');
+    expect(entry).not.toBeNull();
+    expect(entry?.(circle, box, throughRegistry)).toBe(true);
+    expect(testCircleAabbCollision({ x: 15, y: 5, radius: 7 }, { minX: 0, minY: 0, maxX: 10, maxY: 10 }, direct)).toBe(
+      true,
+    );
+
+    // The adapter casts rather than re-dispatching, so this is what proves the cast lands on the right
+    // function: an adapter wired to the wrong pair would still typecheck and still return a manifold.
+    expect(throughRegistry).toEqual(direct);
+  });
+});

package/src/segmentCollision.test.ts

@@ -1,9 +1,9 @@
 import type {
-  CollisionAabb,
-  CollisionCircle,
-  CollisionObb,
-  CollisionPolygon,
-  CollisionSegment,
+  CollisionAabb2D,
+  CollisionCircle2D,
+  CollisionObb2D,
+  CollisionPolygon2D,
+  CollisionSegment2D,
 } from '@flighthq/types/contract';
 import { describe, expect, it } from 'vitest';
 
@@ -15,12 +15,12 @@ import {
   testSegmentSegmentCollision,
 } from './segmentCollision';
 
-function segment(x0: number, y0: number, x1: number, y1: number): CollisionSegment {
+function segment(x0: number, y0: number, x1: number, y1: number): CollisionSegment2D {
   return { x0, y0, x1, y1 };
 }
 
 describe('testSegmentAabbCollision', () => {
-  const box: CollisionAabb = { minX: 0, minY: 0, maxX: 10, maxY: 10 };
+  const box: CollisionAabb2D = { minX: 0, minY: 0, maxX: 10, maxY: 10 };
 
   it('is true for a segment crossing the box', () => {
     expect(testSegmentAabbCollision(segment(-5, 5, 15, 5), box)).toBe(true);
@@ -45,7 +45,7 @@ describe('testSegmentAabbCollision', () => {
 });
 
 describe('testSegmentCircleCollision', () => {
-  const circle: CollisionCircle = { x: 0, y: 0, radius: 2 };
+  const circle: CollisionCircle2D = { x: 0, y: 0, radius: 2 };
 
   it('is true for a segment passing through the circle', () => {
     expect(testSegmentCircleCollision(segment(-10, 0, 10, 0), circle)).toBe(true);
@@ -65,7 +65,7 @@ describe('testSegmentCircleCollision', () => {
 });
 
 describe('testSegmentObbCollision', () => {
-  const obb: CollisionObb = { x: 0, y: 0, halfW: 3, halfH: 3, rotation: Math.PI / 4 };
+  const obb: CollisionObb2D = { x: 0, y: 0, halfW: 3, halfH: 3, rotation: Math.PI / 4 };
 
   it('is true for a segment crossing the rotated box', () => {
     expect(testSegmentObbCollision(segment(-10, 0, 10, 0), obb)).toBe(true);
@@ -77,7 +77,7 @@ describe('testSegmentObbCollision', () => {
 });
 
 describe('testSegmentPolygonCollision', () => {
-  const square: CollisionPolygon = { points: [0, 0, 10, 0, 10, 10, 0, 10] };
+  const square: CollisionPolygon2D = { points: [0, 0, 10, 0, 10, 10, 0, 10] };
 
   it('is true for a segment crossing the polygon', () => {
     expect(testSegmentPolygonCollision(segment(-5, 5, 15, 5), square)).toBe(true);