@flighthq/physics3d 0.4.0-edge.1908.751021c

package/src/ownership.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  assertPhysics3DBodyNotStepping,
+  assertPhysics3DWorldNotStepping,
+  physics3DBodyOwners,
+  physics3DJointOwners,
+  steppingPhysics3DWorlds,
+} from './ownership';
+import { addPhysics3DBody, createPhysics3DWorld, createRigidBody3D } from './world';
+
+describe('assertPhysics3DBodyNotStepping', () => {
+  it('resolves the owning world and refuses mutation during its step', () => {
+    const world = createPhysics3DWorld();
+    const body = createRigidBody3D();
+    addPhysics3DBody(world, body);
+    steppingPhysics3DWorlds.add(world);
+
+    expect(() => assertPhysics3DBodyNotStepping(body)).toThrow();
+
+    steppingPhysics3DWorlds.delete(world);
+    expect(() => assertPhysics3DBodyNotStepping(body)).not.toThrow();
+  });
+});
+
+describe('assertPhysics3DWorldNotStepping', () => {
+  it('permits a mutation outside the step', () => {
+    expect(() => assertPhysics3DWorldNotStepping(createPhysics3DWorld())).not.toThrow();
+  });
+
+  it('refuses a mutation while the world is stepping', () => {
+    const world = createPhysics3DWorld();
+    steppingPhysics3DWorlds.add(world);
+
+    expect(() => assertPhysics3DWorldNotStepping(world)).toThrow();
+
+    steppingPhysics3DWorlds.delete(world);
+  });
+
+  it('tracks each world separately', () => {
+    const stepping = createPhysics3DWorld();
+    const idle = createPhysics3DWorld();
+    steppingPhysics3DWorlds.add(stepping);
+
+    expect(() => assertPhysics3DWorldNotStepping(idle)).not.toThrow();
+
+    steppingPhysics3DWorlds.delete(stepping);
+  });
+
+  it('keeps joint ownership out of the serializable world record', () => {
+    // Ownership is runtime state: a world reconstructed by a format layer carries no owner map, and rebuilding
+    // one is the add path's job rather than something the record has to round-trip.
+    expect(physics3DJointOwners).toBeInstanceOf(WeakMap);
+    expect(Object.keys(createPhysics3DWorld())).not.toContain('jointOwners');
+  });
+
+  it('keeps body ownership out of the serializable world record', () => {
+    expect(physics3DBodyOwners).toBeInstanceOf(WeakMap);
+    expect(Object.keys(createPhysics3DWorld())).not.toContain('bodyOwners');
+  });
+});

package/src/physics3DBroadphasePublication.test.ts

@@ -0,0 +1,63 @@
+import { createBvhSpatialBackend3D, setSpatialIndexingGuard } from '@flighthq/spatial/contract';
+import type { SpatialAabb3D, SpatialIndexingNotice } from '@flighthq/types/contract';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  getPhysics3DBroadphaseBodyIndices,
+  publishPhysics3DBroadphaseBody,
+  withdrawPhysics3DBroadphaseBody,
+} from './physics3DBroadphasePublication';
+import { createPhysics3DWorld } from './world';
+
+afterEach(() => {
+  setSpatialIndexingGuard(null);
+});
+
+describe('getPhysics3DBroadphaseBodyIndices', () => {
+  it('retains publication state for one backend and rebuilds it when the backend changes', () => {
+    const world = createPhysics3DWorld();
+    const first = getPhysics3DBroadphaseBodyIndices(world);
+    first.add(7);
+    expect(getPhysics3DBroadphaseBodyIndices(world)).toBe(first);
+
+    world.index = createBvhSpatialBackend3D();
+
+    const replaced = getPhysics3DBroadphaseBodyIndices(world);
+    expect(replaced).not.toBe(first);
+    expect(replaced.size).toBe(0);
+  });
+});
+
+describe('publishPhysics3DBroadphaseBody', () => {
+  it('inserts once and then updates without reporting a missing-id lifecycle fault', () => {
+    const notices: SpatialIndexingNotice[] = [];
+    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
+    const world = createPhysics3DWorld();
+
+    publishPhysics3DBroadphaseBody(world, 7, box(0));
+    publishPhysics3DBroadphaseBody(world, 7, box(1));
+
+    expect(world.index.explainSpatialIndexing(7).mode).toBe('cells');
+    expect(notices.filter((notice) => notice.reason === 'missing-id')).toEqual([]);
+  });
+});
+
+describe('withdrawPhysics3DBroadphaseBody', () => {
+  it('removes a publication once and leaves a never-published id alone', () => {
+    const notices: SpatialIndexingNotice[] = [];
+    setSpatialIndexingGuard((notice) => notices.push({ ...notice }));
+    const world = createPhysics3DWorld();
+
+    withdrawPhysics3DBroadphaseBody(world, 8);
+    publishPhysics3DBroadphaseBody(world, 7, box(0));
+    withdrawPhysics3DBroadphaseBody(world, 7);
+    withdrawPhysics3DBroadphaseBody(world, 7);
+
+    expect(world.index.explainSpatialIndexing(7).mode).toBe('absent');
+    expect(notices.filter((notice) => notice.reason === 'missing-id')).toEqual([]);
+  });
+});
+
+function box(offset: number): SpatialAabb3D {
+  return { minX: offset, minY: 0, minZ: 0, maxX: offset + 1, maxY: 1, maxZ: 1 };
+}

package/src/physics3DSpatialIndexingGuards.test.ts

@@ -0,0 +1,43 @@
+import type { Physics3DWorld } from '@flighthq/types/contract';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { reportPhysics3DSpatialIndexing, setPhysics3DSpatialIndexingGuard } from './physics3DSpatialIndexingGuards';
+import { createPhysics3DWorld } from './world';
+
+afterEach(() => {
+  setPhysics3DSpatialIndexingGuard(null);
+});
+
+describe('reportPhysics3DSpatialIndexing', () => {
+  it('reports the world only while the optional seam is installed', () => {
+    const world = createPhysics3DWorld();
+    const received: Readonly<Physics3DWorld>[] = [];
+
+    reportPhysics3DSpatialIndexing(world);
+    setPhysics3DSpatialIndexingGuard((reported) => received.push(reported));
+    reportPhysics3DSpatialIndexing(world);
+    setPhysics3DSpatialIndexingGuard(null);
+    reportPhysics3DSpatialIndexing(world);
+
+    expect(received).toEqual([world]);
+  });
+});
+
+describe('setPhysics3DSpatialIndexingGuard', () => {
+  it('replaces the previous guard instead of accumulating callbacks', () => {
+    const world = createPhysics3DWorld();
+    let firstCalls = 0;
+    let secondCalls = 0;
+    setPhysics3DSpatialIndexingGuard(() => {
+      firstCalls += 1;
+    });
+    setPhysics3DSpatialIndexingGuard(() => {
+      secondCalls += 1;
+    });
+
+    reportPhysics3DSpatialIndexing(world);
+
+    expect(firstCalls).toBe(0);
+    expect(secondCalls).toBe(1);
+  });
+});

package/src/registerBuiltInPhysics3DJointSolvers.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { getPhysics3DJointSolver } from './jointRegistry';
+import {
+  physics3DBallAndSocketJointSolver,
+  physics3DConeTwistJointSolver,
+  physics3DDistanceJointSolver,
+  physics3DFixedJointSolver,
+  physics3DGeneric6DofJointSolver,
+  physics3DHingeJointSolver,
+  physics3DSliderJointSolver,
+  Physics3DBallAndSocketJointKind,
+  Physics3DConeTwistJointKind,
+  Physics3DDistanceJointKind,
+  Physics3DFixedJointKind,
+  Physics3DGeneric6DofJointKind,
+  Physics3DHingeJointKind,
+  Physics3DSliderJointKind,
+} from './joints';
+import { registerBuiltInPhysics3DJointSolvers } from './registerBuiltInPhysics3DJointSolvers';
+import { createPhysics3DWorld } from './world';
+
+describe('registerBuiltInPhysics3DJointSolvers', () => {
+  it('binds every built-in kind to its own solver', () => {
+    const world = createPhysics3DWorld();
+
+    registerBuiltInPhysics3DJointSolvers(world);
+
+    expect(getPhysics3DJointSolver(world, Physics3DBallAndSocketJointKind)).toBe(physics3DBallAndSocketJointSolver);
+    expect(getPhysics3DJointSolver(world, Physics3DConeTwistJointKind)).toBe(physics3DConeTwistJointSolver);
+    expect(getPhysics3DJointSolver(world, Physics3DDistanceJointKind)).toBe(physics3DDistanceJointSolver);
+    expect(getPhysics3DJointSolver(world, Physics3DFixedJointKind)).toBe(physics3DFixedJointSolver);
+    expect(getPhysics3DJointSolver(world, Physics3DGeneric6DofJointKind)).toBe(physics3DGeneric6DofJointSolver);
+    expect(getPhysics3DJointSolver(world, Physics3DHingeJointKind)).toBe(physics3DHingeJointSolver);
+    expect(getPhysics3DJointSolver(world, Physics3DSliderJointKind)).toBe(physics3DSliderJointSolver);
+  });
+
+  it('registers the whole bank and nothing else', () => {
+    const world = createPhysics3DWorld();
+
+    registerBuiltInPhysics3DJointSolvers(world);
+
+    expect(world.jointSolvers.size).toBe(7);
+  });
+
+  it('leaves a world that never calls it with no solvers at all', () => {
+    // Registration is explicit rather than part of world construction, so constructing a world links no
+    // constraint math and a caller may register only the kinds it uses.
+    expect(createPhysics3DWorld().jointSolvers.size).toBe(0);
+  });
+});