@flighthq/geometry 0.3.0 → 0.3.1-next.1041.35b950c

package/src/vector2.test.ts

@@ -96,6 +96,27 @@ describe('addVector2', () => {
 });
 
 describe('clampVector2', () => {
+  it('clamps each component to its own bounds, below, above, and not at all', () => {
+    // Every component gets a DIFFERENT min and max, so a component reading a neighbour's bound
+    // comes out as a wrong number instead of the right one by luck. Each component is then run
+    // through all three outcomes — under its floor, over its ceiling, and already in range.
+    const min = createVector2(-1, -2);
+    const max = createVector2(10, 20);
+    const out = createVector2();
+
+    clampVector2(out, createVector2(-5, -6), min, max);
+    expect(out.x).toBe(-1);
+    expect(out.y).toBe(-2);
+
+    clampVector2(out, createVector2(100, 200), min, max);
+    expect(out.x).toBe(10);
+    expect(out.y).toBe(20);
+
+    clampVector2(out, createVector2(0, 1), min, max);
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(1);
+  });
+
   it('clamps each component independently', () => {
     const out = createVector2();
     const value = createVector2(5, -2);
@@ -116,12 +137,28 @@ describe('clampVector2', () => {
     expect(out.y).toBe(2);
   });
 
+  it('clamps x low and y high', () => {
+    const out = createVector2();
+    clampVector2(out, createVector2(-2, 5), createVector2(0, 0), createVector2(3, 3));
+    expect(out).toMatchObject({ x: 0, y: 3 });
+  });
+
   it('supports out === value', () => {
     const v = createVector2(5, -1);
     clampVector2(v, v, createVector2(0, 0), createVector2(3, 3));
     expect(v.x).toBe(3);
     expect(v.y).toBe(0);
   });
+
+  it('supports out === min or max', () => {
+    const min = createVector2(0, 0);
+    clampVector2(min, createVector2(5, -2), min, createVector2(3, 3));
+    expect(min).toMatchObject({ x: 3, y: 0 });
+
+    const max = createVector2(3, 3);
+    clampVector2(max, createVector2(5, -2), createVector2(0, 0), max);
+    expect(max).toMatchObject({ x: 3, y: 0 });
+  });
 });
 
 describe('cloneVector2', () => {
@@ -195,6 +232,21 @@ describe('createVector2FromPolar', () => {
 });
 
 describe('divideVector2', () => {
+  it('gives 0 for a zero divisor on each component in turn', () => {
+    // A zero divisor is answered per component, not for the whole vector, so each component is
+    // zeroed on its own while the others still divide normally.
+    const source = createVector2(6, 8);
+    const out = createVector2();
+
+    divideVector2(out, source, createVector2(0, 4));
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(2);
+
+    divideVector2(out, source, createVector2(2, 0));
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(0);
+  });
+
   it('divides component-wise', () => {
     const out = createVector2();
     divideVector2(out, createVector2(6, 8), createVector2(2, 4));
@@ -209,15 +261,32 @@ describe('divideVector2', () => {
     expect(out.y).toBe(2);
   });
 
+  it('produces 0 for a zero y divisor', () => {
+    const out = createVector2();
+    divideVector2(out, createVector2(6, 8), createVector2(2, 0));
+    expect(out).toMatchObject({ x: 3, y: 0 });
+  });
+
   it('supports out === source', () => {
     const v = createVector2(6, 8);
     divideVector2(v, v, createVector2(2, 4));
     expect(v.x).toBe(3);
     expect(v.y).toBe(2);
   });
+
+  it('supports out === divisor', () => {
+    const divisor = createVector2(2, 4);
+    divideVector2(divisor, createVector2(6, 8), divisor);
+    expect(divisor).toMatchObject({ x: 3, y: 2 });
+  });
 });
 
 describe('equalsVector2', () => {
+  it('returns false when either vector is absent', () => {
+    expect(equalsVector2(pt, null)).toBe(false);
+    expect(equalsVector2(undefined, pt)).toBe(false);
+  });
+
   it('returns true if vectors are identical, false otherwise', () => {
     expect(equalsVector2(pt, pt2)).toBe(true);
     pt.x = 1;
@@ -234,6 +303,34 @@ describe('equalsVector2', () => {
     pt2.x = 1;
     expect(equalsVector2(pt, pt2)).toBe(true);
   });
+
+  it('compares every component, not just the first', () => {
+    // Two hand-written comparisons in a row: one left reading the wrong field still agrees with
+    // the right answer on every pair that differs in more than one place, so each differs alone.
+    const a = createVector2(1, 2);
+    expect(equalsVector2(a, createVector2(9, 2))).toBe(false);
+    expect(equalsVector2(a, createVector2(1, 9))).toBe(false);
+  });
+
+  it('returns false when either side is missing', () => {
+    // The signature accepts null and undefined, so absence is an answerable input rather than
+    // misuse: nothing is equal to a vector, including another absence.
+    const v = createVector2(1, 2);
+    expect(equalsVector2(v, null)).toBe(false);
+    expect(equalsVector2(null, v)).toBe(false);
+    expect(equalsVector2(v, undefined)).toBe(false);
+    expect(equalsVector2(undefined, v)).toBe(false);
+    expect(equalsVector2(null, null)).toBe(false);
+    expect(equalsVector2(undefined, undefined)).toBe(false);
+  });
+
+  it('holds a vector equal to itself even with a NaN component', () => {
+    // Comparing field by field would say a vector carrying NaN differs from itself, and a caller
+    // watching for changes would then see one every time it looked.
+    const notANumber = createVector2(NaN, 2);
+    expect(equalsVector2(notANumber, notANumber)).toBe(true);
+    expect(equalsVector2(notANumber, createVector2(NaN, 2))).toBe(false);
+  });
 });
 
 describe('getVector2AngleBetween', () => {
@@ -446,6 +543,23 @@ describe('interpolateVector2', () => {
 });
 
 describe('maxVector2', () => {
+  it('takes each component from whichever side wins, and gives the same answer either way round', () => {
+    // The winner alternates between the two arguments component by component, and all 4 numbers
+    // are distinct, so a line reading the wrong component or the wrong side cannot land on the
+    // right answer anyway. Running it again with the arguments swapped must not change it.
+    const a = createVector2(1, 5);
+    const b = createVector2(3, 0);
+    const out = createVector2();
+
+    maxVector2(out, a, b);
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(5);
+
+    maxVector2(out, b, a);
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(5);
+  });
+
   it('returns the component-wise maximum', () => {
     const out = createVector2();
     maxVector2(out, createVector2(1, 5), createVector2(3, 2));
@@ -460,9 +574,39 @@ describe('maxVector2', () => {
     expect(a.x).toBe(3);
     expect(a.y).toBe(5);
   });
+
+  it('supports out === b', () => {
+    const a = createVector2(1, 5);
+    const b = createVector2(3, 2);
+    maxVector2(b, a, b);
+    expect(b).toMatchObject({ x: 3, y: 5 });
+  });
+
+  it('selects a for x and b for y', () => {
+    const out = createVector2();
+    maxVector2(out, createVector2(5, 1), createVector2(2, 3));
+    expect(out).toMatchObject({ x: 5, y: 3 });
+  });
 });
 
 describe('minVector2', () => {
+  it('takes each component from whichever side wins, and gives the same answer either way round', () => {
+    // The winner alternates between the two arguments component by component, and all 4 numbers
+    // are distinct, so a line reading the wrong component or the wrong side cannot land on the
+    // right answer anyway. Running it again with the arguments swapped must not change it.
+    const a = createVector2(1, 5);
+    const b = createVector2(3, 0);
+    const out = createVector2();
+
+    minVector2(out, a, b);
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(0);
+
+    minVector2(out, b, a);
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(0);
+  });
+
   it('returns the component-wise minimum', () => {
     const out = createVector2();
     minVector2(out, createVector2(1, 5), createVector2(3, 2));
@@ -477,6 +621,19 @@ describe('minVector2', () => {
     expect(a.x).toBe(1);
     expect(a.y).toBe(2);
   });
+
+  it('supports out === b', () => {
+    const a = createVector2(1, 5);
+    const b = createVector2(3, 2);
+    minVector2(b, a, b);
+    expect(b).toMatchObject({ x: 1, y: 2 });
+  });
+
+  it('selects b for x and a for y', () => {
+    const out = createVector2();
+    minVector2(out, createVector2(5, 1), createVector2(2, 3));
+    expect(out).toMatchObject({ x: 2, y: 1 });
+  });
 });
 
 describe('multiplyVector2', () => {
@@ -493,6 +650,12 @@ describe('multiplyVector2', () => {
     expect(a.x).toBe(8);
     expect(a.y).toBe(15);
   });
+
+  it('supports out === b', () => {
+    const b = createVector2(4, 5);
+    multiplyVector2(b, createVector2(2, 3), b);
+    expect(b).toMatchObject({ x: 8, y: 15 });
+  });
 });
 
 describe('nearEqualsVector2', () => {
@@ -646,6 +809,13 @@ describe('reflectVector2', () => {
     expect(v.x).toBeCloseTo(-1, 6);
     expect(v.y).toBeCloseTo(-1, 6);
   });
+
+  it('supports out === normal', () => {
+    const normal = createVector2(1, 0);
+    reflectVector2(normal, createVector2(1, -1), normal);
+    expect(normal.x).toBeCloseTo(-1, 6);
+    expect(normal.y).toBeCloseTo(-1, 6);
+  });
 });
 
 describe('scaleVector2', () => {

package/src/vector2Pool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import type { Vector2 } from '@flighthq/types/contract';
 
 import { acquireEmptyVector2, acquireVector2, clearVector2Pool, releaseVector2 } from './vector2Pool';
@@ -59,6 +60,16 @@ describe('clearVector2Pool', () => {
 });
 
 describe('releaseVector2', () => {
+  it('detaches the previous owner binding before the vector is reused', () => {
+    const v = acquireVector2();
+    attachEntityBinding(v, { owner: 'first' });
+    releaseVector2(v);
+
+    const reused = acquireVector2();
+    expect(reused).toBe(v);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('handles null safely', () => {
     expect(() => releaseVector2(null as unknown as Vector2)).not.toThrow();
   });

package/src/vector3.test.ts

@@ -88,6 +88,30 @@ describe('addVector3', () => {
 });
 
 describe('clampVector3', () => {
+  it('clamps each component to its own bounds, below, above, and not at all', () => {
+    // Every component gets a DIFFERENT min and max, so a component reading a neighbour's bound
+    // comes out as a wrong number instead of the right one by luck. Each component is then run
+    // through all three outcomes — under its floor, over its ceiling, and already in range.
+    const min = createVector3(-1, -2, -3);
+    const max = createVector3(10, 20, 30);
+    const out = createVector3();
+
+    clampVector3(out, createVector3(-5, -6, -7), min, max);
+    expect(out.x).toBe(-1);
+    expect(out.y).toBe(-2);
+    expect(out.z).toBe(-3);
+
+    clampVector3(out, createVector3(100, 200, 300), min, max);
+    expect(out.x).toBe(10);
+    expect(out.y).toBe(20);
+    expect(out.z).toBe(30);
+
+    clampVector3(out, createVector3(0, 1, 2), min, max);
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(1);
+    expect(out.z).toBe(2);
+  });
+
   it('clamps each component independently', () => {
     const out = createVector3();
     clampVector3(out, createVector3(5, -2, 1), createVector3(0, 0, 0), createVector3(3, 3, 3));
@@ -103,6 +127,25 @@ describe('clampVector3', () => {
     expect(v.y).toBe(0);
     expect(v.z).toBe(3);
   });
+
+  it('supports out === min or max', () => {
+    const min = createVector3(0, 0, 0);
+    clampVector3(min, createVector3(5, -2, 1), min, createVector3(3, 3, 3));
+    expect(min).toMatchObject({ x: 3, y: 0, z: 1 });
+
+    const max = createVector3(3, 3, 3);
+    clampVector3(max, createVector3(5, -2, 1), createVector3(0, 0, 0), max);
+    expect(max).toMatchObject({ x: 3, y: 0, z: 1 });
+  });
+
+  it('covers every clamp outcome on every component', () => {
+    const out = createVector3();
+    clampVector3(out, createVector3(-1, 2, 5), createVector3(0, 0, 0), createVector3(3, 3, 3));
+    expect(out).toMatchObject({ x: 0, y: 2, z: 3 });
+
+    clampVector3(out, createVector3(2, 5, -1), createVector3(0, 0, 0), createVector3(3, 3, 3));
+    expect(out).toMatchObject({ x: 2, y: 3, z: 0 });
+  });
 });
 
 describe('cloneVector3', () => {
@@ -211,6 +254,28 @@ describe('crossVector3', () => {
 });
 
 describe('divideVector3', () => {
+  it('gives 0 for a zero divisor on each component in turn', () => {
+    // A zero divisor is answered per component, not for the whole vector, so each component is
+    // zeroed on its own while the others still divide normally.
+    const source = createVector3(6, 8, 9);
+    const out = createVector3();
+
+    divideVector3(out, source, createVector3(0, 4, 3));
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(2);
+    expect(out.z).toBe(3);
+
+    divideVector3(out, source, createVector3(2, 0, 3));
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(0);
+    expect(out.z).toBe(3);
+
+    divideVector3(out, source, createVector3(2, 4, 0));
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(2);
+    expect(out.z).toBe(0);
+  });
+
   it('divides component-wise', () => {
     const out = createVector3();
     divideVector3(out, createVector3(6, 8, 9), createVector3(2, 4, 3));
@@ -234,9 +299,26 @@ describe('divideVector3', () => {
     expect(v.y).toBe(2);
     expect(v.z).toBe(3);
   });
+
+  it('supports out === divisor', () => {
+    const divisor = createVector3(2, 4, 3);
+    divideVector3(divisor, createVector3(6, 8, 9), divisor);
+    expect(divisor).toMatchObject({ x: 3, y: 2, z: 3 });
+  });
+
+  it('produces 0 for a zero y divisor', () => {
+    const out = createVector3();
+    divideVector3(out, createVector3(6, 8, 9), createVector3(2, 0, 3));
+    expect(out).toMatchObject({ x: 3, y: 0, z: 3 });
+  });
 });
 
 describe('equalsVector3', () => {
+  it('returns false when either vector is absent', () => {
+    expect(equalsVector3(createVector3(), null)).toBe(false);
+    expect(equalsVector3(undefined, createVector3())).toBe(false);
+  });
+
   it('returns true if vectors are equal', () => {
     const a = createVector3(1, 2, 3);
     const b = createVector3(1, 2, 3);
@@ -248,6 +330,35 @@ describe('equalsVector3', () => {
     const b = createVector3(4, 5, 6);
     expect(equalsVector3(a, b)).toBe(false);
   });
+
+  it('compares every component, not just the first', () => {
+    // Three hand-written comparisons in a row: one left reading the wrong field agrees with the
+    // right answer on every pair that differs in more than one place, so each differs alone here.
+    const a = createVector3(1, 2, 3);
+    expect(equalsVector3(a, createVector3(9, 2, 3))).toBe(false);
+    expect(equalsVector3(a, createVector3(1, 9, 3))).toBe(false);
+    expect(equalsVector3(a, createVector3(1, 2, 9))).toBe(false);
+  });
+
+  it('returns false when either side is missing', () => {
+    // The signature accepts null and undefined, so absence is an answerable input rather than
+    // misuse: nothing is equal to a vector, including another absence.
+    const v = createVector3(1, 2, 3);
+    expect(equalsVector3(v, null)).toBe(false);
+    expect(equalsVector3(null, v)).toBe(false);
+    expect(equalsVector3(v, undefined)).toBe(false);
+    expect(equalsVector3(undefined, v)).toBe(false);
+    expect(equalsVector3(null, null)).toBe(false);
+    expect(equalsVector3(undefined, undefined)).toBe(false);
+  });
+
+  it('holds a vector equal to itself even with a NaN component', () => {
+    // Comparing field by field would say a vector carrying NaN differs from itself, and a caller
+    // watching for changes would then see one every time it looked.
+    const notANumber = createVector3(NaN, 2, 3);
+    expect(equalsVector3(notANumber, notANumber)).toBe(true);
+    expect(equalsVector3(notANumber, createVector3(NaN, 2, 3))).toBe(false);
+  });
 });
 
 describe('getVector3AngleBetween', () => {
@@ -340,6 +451,14 @@ describe('getVector3Spherical', () => {
     expect(sph.y).toBe(0);
     expect(sph.z).toBe(0);
   });
+
+  it('supports out === source', () => {
+    const vector = createVector3(1, 0, 0);
+    getVector3Spherical(vector, vector);
+    expect(vector.x).toBeCloseTo(1, 6);
+    expect(vector.y).toBeCloseTo(Math.PI / 2, 6);
+    expect(vector.z).toBeCloseTo(0, 6);
+  });
 });
 
 describe('interpolateVector3', () => {
@@ -373,9 +492,35 @@ describe('interpolateVector3', () => {
     expect(a.y).toBe(2);
     expect(a.z).toBe(3);
   });
+
+  it('supports out === b', () => {
+    const a = createVector3(0, 0, 0);
+    const b = createVector3(2, 4, 6);
+    interpolateVector3(b, a, b, 0.5);
+    expect(b).toMatchObject({ x: 1, y: 2, z: 3 });
+  });
 });
 
 describe('maxVector3', () => {
+  it('takes each component from whichever side wins, and gives the same answer either way round', () => {
+    // The winner alternates between the two arguments component by component, and all 6 numbers
+    // are distinct, so a line reading the wrong component or the wrong side cannot land on the
+    // right answer anyway. Running it again with the arguments swapped must not change it.
+    const a = createVector3(1, 5, 2);
+    const b = createVector3(3, 0, 7);
+    const out = createVector3();
+
+    maxVector3(out, a, b);
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(5);
+    expect(out.z).toBe(7);
+
+    maxVector3(out, b, a);
+    expect(out.x).toBe(3);
+    expect(out.y).toBe(5);
+    expect(out.z).toBe(7);
+  });
+
   it('returns the component-wise maximum', () => {
     const out = createVector3();
     maxVector3(out, createVector3(1, 5, 2), createVector3(3, 2, 7));
@@ -383,9 +528,44 @@ describe('maxVector3', () => {
     expect(out.y).toBe(5);
     expect(out.z).toBe(7);
   });
+
+  it('supports out === a or b', () => {
+    const a = createVector3(1, 5, 2);
+    maxVector3(a, a, createVector3(3, 2, 7));
+    expect(a).toMatchObject({ x: 3, y: 5, z: 7 });
+
+    const b = createVector3(3, 2, 7);
+    maxVector3(b, createVector3(1, 5, 2), b);
+    expect(b).toMatchObject({ x: 3, y: 5, z: 7 });
+  });
+
+  it('selects the complementary component outcomes', () => {
+    const out = createVector3();
+    maxVector3(out, createVector3(5, 1, 7), createVector3(2, 3, 4));
+    expect(out).toMatchObject({ x: 5, y: 3, z: 7 });
+  });
 });
 
 describe('minVector3', () => {
+  it('takes each component from whichever side wins, and gives the same answer either way round', () => {
+    // The winner alternates between the two arguments component by component, and all 6 numbers
+    // are distinct, so a line reading the wrong component or the wrong side cannot land on the
+    // right answer anyway. Running it again with the arguments swapped must not change it.
+    const a = createVector3(1, 5, 2);
+    const b = createVector3(3, 0, 7);
+    const out = createVector3();
+
+    minVector3(out, a, b);
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(0);
+    expect(out.z).toBe(2);
+
+    minVector3(out, b, a);
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(0);
+    expect(out.z).toBe(2);
+  });
+
   it('returns the component-wise minimum', () => {
     const out = createVector3();
     minVector3(out, createVector3(1, 5, 2), createVector3(3, 2, 7));
@@ -393,6 +573,22 @@ describe('minVector3', () => {
     expect(out.y).toBe(2);
     expect(out.z).toBe(2);
   });
+
+  it('supports out === a or b', () => {
+    const a = createVector3(1, 5, 2);
+    minVector3(a, a, createVector3(3, 2, 7));
+    expect(a).toMatchObject({ x: 1, y: 2, z: 2 });
+
+    const b = createVector3(3, 2, 7);
+    minVector3(b, createVector3(1, 5, 2), b);
+    expect(b).toMatchObject({ x: 1, y: 2, z: 2 });
+  });
+
+  it('selects the complementary component outcomes', () => {
+    const out = createVector3();
+    minVector3(out, createVector3(5, 1, 7), createVector3(2, 3, 4));
+    expect(out).toMatchObject({ x: 2, y: 1, z: 4 });
+  });
 });
 
 describe('multiplyVector3', () => {
@@ -411,6 +607,12 @@ describe('multiplyVector3', () => {
     expect(a.y).toBe(18);
     expect(a.z).toBe(28);
   });
+
+  it('supports out === b', () => {
+    const b = createVector3(5, 6, 7);
+    multiplyVector3(b, createVector3(2, 3, 4), b);
+    expect(b).toMatchObject({ x: 10, y: 18, z: 28 });
+  });
 });
 
 describe('nearEqualsVector3', () => {
@@ -567,6 +769,14 @@ describe('reflectVector3', () => {
     expect(v.x).toBeCloseTo(-1, 6);
     expect(v.y).toBeCloseTo(-1, 6);
   });
+
+  it('supports out === normal', () => {
+    const normal = createVector3(1, 0, 0);
+    reflectVector3(normal, createVector3(1, -1, 0), normal);
+    expect(normal.x).toBeCloseTo(-1, 6);
+    expect(normal.y).toBeCloseTo(-1, 6);
+    expect(normal.z).toBeCloseTo(0, 6);
+  });
 });
 
 describe('scaleVector3', () => {

package/src/vector3Pool.test.ts

@@ -1,3 +1,4 @@
+import { attachEntityBinding, getEntityBinding } from '@flighthq/entity/contract';
 import type { Vector3 } from '@flighthq/types/contract';
 
 import { acquireEmptyVector3, acquireVector3, clearVector3Pool, releaseVector3 } from './vector3Pool';
@@ -62,6 +63,16 @@ describe('clearVector3Pool', () => {
 });
 
 describe('releaseVector3', () => {
+  it('detaches the previous owner binding before the vector is reused', () => {
+    const v = acquireVector3();
+    attachEntityBinding(v, { owner: 'first' });
+    releaseVector3(v);
+
+    const reused = acquireVector3();
+    expect(reused).toBe(v);
+    expect(getEntityBinding(reused)).toBeNull();
+  });
+
   it('handles null safely', () => {
     expect(() => releaseVector3(null as unknown as Vector3)).not.toThrow();
   });