@gg-web-engine/ammo 0.0.58 → 0.0.60

package/dist/types.d.ts

@@ -12,4 +12,6 @@ export type AmmoPhysicsTypeDocRepo = {
     trigger: AmmoTriggerComponent;
     raycastVehicle: AmmoRaycastVehicleComponent;
 };
-export type AmmoGgWorld = Gg3dWorld<Gg3dWorldTypeDocPPatch<AmmoPhysicsTypeDocRepo>, Gg3dWorldSceneTypeDocPPatch<AmmoPhysicsTypeDocRepo, AmmoWorldComponent>>;
+export type AmmoTypeDoc = Gg3dWorldTypeDocPPatch<AmmoPhysicsTypeDocRepo>;
+export type AmmoSceneTypeDoc = Gg3dWorldSceneTypeDocPPatch<AmmoPhysicsTypeDocRepo, AmmoWorldComponent>;
+export type AmmoGgWorld = Gg3dWorld<AmmoTypeDoc, AmmoSceneTypeDoc>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gg-web-engine/ammo",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "description": "An attempt to create open source game engine for browser",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,20 +34,21 @@
   "dependencies": {
   },
   "devDependencies": {
-    "@gg-web-engine/core": "0.0.58",
-    "@types/jest": "^29.5.12",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "mini-signals": "2.0.0",
-    "prettier": "^3.3.3",
-    "rxjs": "7.8.1",
-    "ts-jest": "^29.2.4",
-    "typescript": "~5.5.4"
+    "@gg-web-engine/core": "0.0.60",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.4.0",
+    "jest": "^30.5.0",
+    "jest-environment-jsdom": "^30.5.0",
+    "mini-signals": "3.0.0",
+    "prettier": "^3.9.6",
+    "rxjs": "7.8.2",
+    "ts-jest": "^29.4.12",
+    "typescript": "~6.0.3"
   },
   "peerDependencies": {
-    "@gg-web-engine/core": "0.0.58",
-    "mini-signals": "2.0.0",
-    "rxjs": "7.8.1"
+    "@gg-web-engine/core": "0.0.60",
+    "mini-signals": "3.0.0",
+    "rxjs": "7.8.2"
   },
   "jest": {
     "rootDir": ".",

package/test/ammo-factory.spec.ts

@@ -0,0 +1,88 @@
+import { Shape3DDescriptor } from '@gg-web-engine/core';
+import { AmmoFactory, AmmoWorldComponent } from '../src';
+
+describe('AmmoFactory', () => {
+  let world: AmmoWorldComponent;
+  let factory: AmmoFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new AmmoWorldComponent();
+    await world.init();
+    factory = world.factory;
+    world.gravity = { x: 0, y: 0, z: 0 };
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  const shapes: { name: string; shape: Shape3DDescriptor }[] = [
+    { name: 'PLANE', shape: { shape: 'PLANE' } },
+    { name: 'BOX', shape: { shape: 'BOX', dimensions: { x: 1, y: 1, z: 1 } } },
+    { name: 'SPHERE', shape: { shape: 'SPHERE', radius: 1 } },
+    { name: 'CAPSULE', shape: { shape: 'CAPSULE', radius: 0.5, centersDistance: 1 } },
+    { name: 'CYLINDER', shape: { shape: 'CYLINDER', radius: 0.5, height: 1 } },
+    { name: 'CONE', shape: { shape: 'CONE', radius: 0.5, height: 1 } },
+    {
+      name: 'COMPOUND',
+      shape: {
+        shape: 'COMPOUND',
+        children: [
+          { shape: { shape: 'BOX', dimensions: { x: 1, y: 1, z: 1 } }, position: { x: 0, y: 0, z: 0 } },
+          { shape: { shape: 'SPHERE', radius: 0.5 }, position: { x: 0, y: 0, z: 1 } },
+        ],
+      },
+    },
+    {
+      name: 'CONVEX_HULL',
+      shape: {
+        shape: 'CONVEX_HULL',
+        vertices: [
+          { x: -1, y: -1, z: -1 },
+          { x: 1, y: -1, z: -1 },
+          { x: 1, y: 1, z: -1 },
+          { x: -1, y: 1, z: -1 },
+          { x: 0, y: 0, z: 1 },
+        ],
+      },
+    },
+    {
+      name: 'MESH',
+      shape: {
+        shape: 'MESH',
+        vertices: [
+          { x: -1, y: -1, z: 0 },
+          { x: 1, y: -1, z: 0 },
+          { x: 0, y: 1, z: 0 },
+        ],
+        faces: [[0, 1, 2]],
+      },
+    },
+  ];
+
+  describe.each(shapes)('$name shape', ({ shape }) => {
+    it('should create a static rigid body without throwing', () => {
+      const body = factory.createRigidBody({ shape, body: { dynamic: false, mass: 0 } }, { position: { x: 1, y: 2, z: 3 } });
+      body.addToWorld({ physicsWorld: world } as any);
+      expect(body.position).toEqual({ x: 1, y: 2, z: 3 });
+      world.simulate(16);
+    });
+
+    it('should create a trigger without throwing', () => {
+      const trigger = factory.createTrigger(shape, { position: { x: 0, y: 0, z: 0 } });
+      trigger.addToWorld({ physicsWorld: world } as any);
+      world.simulate(16);
+      trigger.checkOverlaps();
+    });
+  });
+
+  it('should throw a clear error for an unsupported shape', () => {
+    expect(() => factory.createRigidBody({
+      shape: { shape: 'NOT_A_SHAPE' } as any,
+      body: { dynamic: false, mass: 0 },
+    })).toThrow(/not implemented for Ammo\.js/);
+  });
+});

package/test/components/ammo-raycast-vehicle.component.spec.ts

@@ -0,0 +1,139 @@
+import { SuspensionOptions, WheelOptions } from '@gg-web-engine/core';
+import { AmmoFactory, AmmoRaycastVehicleComponent, AmmoRigidBodyComponent, AmmoWorldComponent } from '../../src';
+
+// Shared suspension/wheel setup mirroring examples/ammo-car-three-ammo, known to produce a
+// stable, quickly-settling vehicle - see that example for the full car setup.
+const suspension: SuspensionOptions = {
+  compression: 4.4,
+  damping: 2.3,
+  restLength: 0.6,
+  stiffness: 20,
+};
+
+const wheelOptions = (isFront: boolean, isLeft: boolean): WheelOptions => ({
+  isFront,
+  isLeft,
+  tyreRadius: isFront ? 0.35 : 0.4,
+  tyreWidth: isFront ? 0.2 : 0.3,
+  frictionSlip: 1000,
+  rollInfluence: 0.2,
+  maxTravel: 5,
+  position: {
+    x: isLeft ? 1 : -1,
+    y: isFront ? 1.7 : -1,
+    z: 0.3,
+  },
+});
+
+const addWheels = (vehicle: AmmoRaycastVehicleComponent) => {
+  for (const isFront of [true, false]) {
+    for (const isLeft of [true, false]) {
+      vehicle.addWheel(wheelOptions(isFront, isLeft), suspension);
+    }
+  }
+};
+
+const createFloor = (
+  factory: AmmoFactory,
+  topZ: number,
+): AmmoRigidBodyComponent =>
+  factory.createRigidBody(
+    {
+      shape: { shape: 'BOX', dimensions: { x: 75, y: 75, z: 1 } },
+      body: { dynamic: false, mass: 0 },
+    },
+    { position: { x: 0, y: 0, z: topZ - 0.5 } },
+  );
+
+const createVehicle = (
+  world: AmmoWorldComponent,
+  factory: AmmoFactory,
+  position: { x: number; y: number; z: number },
+): AmmoRaycastVehicleComponent => {
+  const chassis = factory.createRigidBody(
+    { shape: { shape: 'BOX', dimensions: { x: 1.8, y: 4, z: 0.6 } }, body: { dynamic: true, mass: 800 } },
+    { position },
+  );
+  const vehicle = factory.createRaycastVehicle(chassis);
+  addWheels(vehicle);
+  return vehicle;
+};
+
+describe('AmmoRaycastVehicleComponent', () => {
+  let world: AmmoWorldComponent;
+  let factory: AmmoFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new AmmoWorldComponent();
+    await world.init();
+    factory = world.factory;
+    // default earth-like gravity, so vehicles actually fall onto the floors below
+    world.gravity = { x: 0, y: 0, z: -9.82 };
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it('should fall under gravity and come to rest on a floor below it', () => {
+    const floor = createFloor(factory, 0);
+    floor.addToWorld({ physicsWorld: world } as any);
+
+    const vehicle = createVehicle(world, factory, { x: 0, y: 0, z: 4 });
+    vehicle.addToWorld({ physicsWorld: world } as any);
+
+    for (let i = 0; i < 100; i++) {
+      world.simulate(60);
+    }
+
+    // chassis should have settled just above the floor surface (z = 0), not still falling
+    // and not sunk through it
+    expect(vehicle.position.z).toBeGreaterThan(-1);
+    expect(vehicle.position.z).toBeLessThan(3);
+    expect(vehicle.isWheelTouchesGround(0)).toBe(true);
+  });
+
+  it('should let each vehicle fall through a floor with a different collision group and rest ' +
+    'only on the floor sharing its own collision group', () => {
+    const groupA = world.registerCollisionGroup();
+    const groupB = world.registerCollisionGroup();
+
+    const floorA = createFloor(factory, 0);
+    floorA.addToWorld({ physicsWorld: world } as any);
+    floorA.ownCollisionGroups = floorA.interactWithCollisionGroups = [groupA];
+
+    const floorB = createFloor(factory, -10);
+    floorB.addToWorld({ physicsWorld: world } as any);
+    floorB.ownCollisionGroups = floorB.interactWithCollisionGroups = [groupB];
+
+    const vehicleA = createVehicle(world, factory, { x: 0, y: 0, z: 4 });
+    vehicleA.addToWorld({ physicsWorld: world } as any);
+    vehicleA.ownCollisionGroups = vehicleA.interactWithCollisionGroups = [groupA];
+
+    const vehicleB = createVehicle(world, factory, { x: 20, y: 0, z: 4 });
+    vehicleB.addToWorld({ physicsWorld: world } as any);
+    vehicleB.ownCollisionGroups = vehicleB.interactWithCollisionGroups = [groupB];
+
+    for (let i = 0; i < 100; i++) {
+      world.simulate(60);
+    }
+
+    // vehicleA shares its collision group with floorA (z=0) - it should have landed there,
+    // both via chassis-body collision and via the raycast vehicle's suspension.
+    expect(vehicleA.position.z).toBeGreaterThan(-1);
+    expect(vehicleA.position.z).toBeLessThan(3);
+    expect(vehicleA.isWheelTouchesGround(0)).toBe(true);
+
+    // vehicleB does not share a collision group with floorA, so it must fall straight through
+    // it (this is what the custom btVehicleRaycaster collision-group patch fixes: without it,
+    // the wheel raycast ignores collision groups entirely and would detect floorA as ground,
+    // holding the vehicle up via suspension force even though its chassis passes through).
+    // It should come to rest on floorB (z=-10) instead.
+    expect(vehicleB.position.z).toBeGreaterThan(-11);
+    expect(vehicleB.position.z).toBeLessThan(-7);
+    expect(vehicleB.isWheelTouchesGround(0)).toBe(true);
+  });
+});

package/test/components/ammo-world.component.spec.ts

@@ -17,6 +17,56 @@ describe('AmmoWorldComponent', () => {
     world.dispose();
   });
 
+  describe('Gravity', () => {
+    it('should default to earth-like downward gravity on a fresh world', async () => {
+      const freshWorld = new AmmoWorldComponent();
+      await freshWorld.init();
+      expect(freshWorld.gravity).toEqual({ x: 0, y: 0, z: -9.82 });
+      freshWorld.dispose();
+    });
+
+    it('should read back a value written to it and apply it to the simulation', () => {
+      world.gravity = { x: 1, y: -2, z: 3 };
+      expect(world.gravity).toEqual({ x: 1, y: -2, z: 3 });
+
+      const ball = world.factory.createRigidBody({
+        shape: { shape: 'SPHERE', radius: 1 },
+        body: { dynamic: true, mass: 1 },
+      }, { position: { x: 0, y: 0, z: 0 } });
+      ball.addToWorld({ physicsWorld: world } as any);
+
+      for (let i = 0; i < 20; i++) {
+        world.simulate(60);
+      }
+      // ball should have drifted along every gravity axis in the sign of that axis' gravity
+      expect(ball.position.x).toBeGreaterThan(0);
+      expect(ball.position.y).toBeLessThan(0);
+      expect(ball.position.z).toBeGreaterThan(0);
+    });
+  });
+
+  describe('Collision groups', () => {
+    it('should register groups starting from 1 (0 is the reserved main collision group)', () => {
+      expect(world.mainCollisionGroup).toBe(0);
+      expect(world.registerCollisionGroup()).toBe(1);
+      expect(world.registerCollisionGroup()).toBe(2);
+    });
+
+    it('should let a deregistered group id be reused', () => {
+      const group = world.registerCollisionGroup();
+      world.deregisterCollisionGroup(group);
+      expect(world.registerCollisionGroup()).toBe(group);
+    });
+
+    it('should throw once all 16 collision groups (0-15) are exhausted', () => {
+      // group 0 is implicitly reserved as the main collision group, so 15 more can be registered
+      for (let i = 0; i < 15; i++) {
+        world.registerCollisionGroup();
+      }
+      expect(() => world.registerCollisionGroup()).toThrow();
+    });
+  });
+
   describe('Rigid bodies', () => {
 
     it('should simulate inertial motion of rigid body', () => {

package/tsconfig.json

@@ -2,7 +2,11 @@
   "extends": "./../../tsconfig.base.json",
   "compilerOptions": {
     "baseUrl": "./src/",
-    "outDir": "./dist/"
+    "outDir": "./dist/",
+    "rootDir": "./src/",
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo",
+    "types": ["jest", "node"]
   },
   "include": ["src/*.ts", "src/**/*.ts"],
+  "references": [{ "path": "../core" }]
 }