@rapierphysicsplugin/server 1.0.0

package/src/__tests__/integration.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect, beforeAll, afterEach } from 'vitest';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { WebSocket } from 'ws';
+import { PhysicsServer } from '../server.js';
+import {
+  MessageType,
+  encodeMessage,
+  decodeServerMessage,
+} from '@rapierphysicsplugin/shared';
+import type { ServerMessage, RoomJoinedMessage, RoomStateMessage } from '@rapierphysicsplugin/shared';
+
+const TEST_PORT = 9876;
+
+function connectClient(port: number): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://localhost:${port}`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+function waitForMessage(ws: WebSocket, type: MessageType, timeoutMs = 5000): Promise<ServerMessage> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error(`Timeout waiting for ${type}`)), timeoutMs);
+
+    const handler = (data: Buffer) => {
+      const msg = decodeServerMessage(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+      if (msg.type === type) {
+        clearTimeout(timeout);
+        ws.off('message', handler);
+        resolve(msg);
+      }
+    };
+    ws.on('message', handler);
+  });
+}
+
+describe('Integration: Server with WebSocket clients', () => {
+  let server: PhysicsServer;
+
+  beforeAll(async () => {
+    await RAPIER.init();
+  });
+
+  afterEach(() => {
+    server?.stop();
+  });
+
+  it('should allow a client to create and join a room', async () => {
+    server = new PhysicsServer(RAPIER);
+    await server.start(TEST_PORT);
+
+    const ws = await connectClient(TEST_PORT);
+
+    // Create room
+    ws.send(encodeMessage({
+      type: MessageType.CREATE_ROOM,
+      roomId: 'test-room',
+      initialBodies: [
+        {
+          id: 'box1',
+          shape: { type: 'box', params: { halfExtents: { x: 0.5, y: 0.5, z: 0.5 } } },
+          motionType: 'dynamic',
+          position: { x: 0, y: 5, z: 0 },
+          rotation: { x: 0, y: 0, z: 0, w: 1 },
+          mass: 1.0,
+        },
+      ],
+    }));
+
+    const created = await waitForMessage(ws, MessageType.ROOM_CREATED);
+    expect(created.type).toBe(MessageType.ROOM_CREATED);
+
+    // Join room
+    ws.send(encodeMessage({
+      type: MessageType.JOIN_ROOM,
+      roomId: 'test-room',
+    }));
+
+    const joined = await waitForMessage(ws, MessageType.ROOM_JOINED) as RoomJoinedMessage;
+    expect(joined.roomId).toBe('test-room');
+    expect(joined.snapshot.bodies).toHaveLength(1);
+    expect(joined.snapshot.bodies[0].id).toBe('box1');
+
+    ws.close();
+  });
+
+  it('should send state updates after starting simulation', async () => {
+    server = new PhysicsServer(RAPIER);
+    await server.start(TEST_PORT + 1);
+
+    const ws = await connectClient(TEST_PORT + 1);
+
+    ws.send(encodeMessage({
+      type: MessageType.CREATE_ROOM,
+      roomId: 'state-room',
+      initialBodies: [
+        {
+          id: 'ball',
+          shape: { type: 'sphere', params: { radius: 0.5 } },
+          motionType: 'dynamic',
+          position: { x: 0, y: 10, z: 0 },
+          rotation: { x: 0, y: 0, z: 0, w: 1 },
+          mass: 1.0,
+        },
+      ],
+    }));
+    await waitForMessage(ws, MessageType.ROOM_CREATED);
+
+    ws.send(encodeMessage({
+      type: MessageType.JOIN_ROOM,
+      roomId: 'state-room',
+    }));
+    await waitForMessage(ws, MessageType.ROOM_JOINED);
+
+    // Start simulation (no longer auto-starts on join)
+    ws.send(encodeMessage({ type: MessageType.START_SIMULATION }));
+    await waitForMessage(ws, MessageType.SIMULATION_STARTED);
+
+    // Wait for a state update — should arrive within a few seconds
+    const stateMsg = await waitForMessage(ws, MessageType.ROOM_STATE) as RoomStateMessage;
+    expect(stateMsg.tick).toBeGreaterThan(0);
+    expect(stateMsg.bodies.length).toBeGreaterThanOrEqual(1);
+
+    ws.close();
+  });
+
+  it('should allow two clients to share a room', async () => {
+    server = new PhysicsServer(RAPIER);
+    await server.start(TEST_PORT + 2);
+
+    const ws1 = await connectClient(TEST_PORT + 2);
+    const ws2 = await connectClient(TEST_PORT + 2);
+
+    // Client 1 creates room
+    ws1.send(encodeMessage({
+      type: MessageType.CREATE_ROOM,
+      roomId: 'shared-room',
+      initialBodies: [
+        {
+          id: 'shared-box',
+          shape: { type: 'box', params: { halfExtents: { x: 0.5, y: 0.5, z: 0.5 } } },
+          motionType: 'dynamic',
+          position: { x: 0, y: 5, z: 0 },
+          rotation: { x: 0, y: 0, z: 0, w: 1 },
+          mass: 1.0,
+        },
+      ],
+    }));
+    await waitForMessage(ws1, MessageType.ROOM_CREATED);
+
+    // Both clients join
+    ws1.send(encodeMessage({ type: MessageType.JOIN_ROOM, roomId: 'shared-room' }));
+    const joined1 = await waitForMessage(ws1, MessageType.ROOM_JOINED) as RoomJoinedMessage;
+    expect(joined1.snapshot.bodies).toHaveLength(1);
+
+    ws2.send(encodeMessage({ type: MessageType.JOIN_ROOM, roomId: 'shared-room' }));
+    const joined2 = await waitForMessage(ws2, MessageType.ROOM_JOINED) as RoomJoinedMessage;
+    expect(joined2.snapshot.bodies).toHaveLength(1);
+
+    // Start simulation (no longer auto-starts on join)
+    ws1.send(encodeMessage({ type: MessageType.START_SIMULATION }));
+    await waitForMessage(ws1, MessageType.SIMULATION_STARTED);
+    await waitForMessage(ws2, MessageType.SIMULATION_STARTED);
+
+    // Client 1 sends input
+    ws1.send(encodeMessage({
+      type: MessageType.CLIENT_INPUT,
+      input: {
+        tick: 0,
+        sequenceNum: 0,
+        actions: [
+          { type: 'applyImpulse', bodyId: 'shared-box', data: { impulse: { x: 20, y: 0, z: 0 } } },
+        ],
+      },
+    }));
+
+    // Both should receive state updates
+    const state1 = await waitForMessage(ws1, MessageType.ROOM_STATE) as RoomStateMessage;
+    const state2 = await waitForMessage(ws2, MessageType.ROOM_STATE) as RoomStateMessage;
+
+    expect(state1.bodies.length).toBeGreaterThanOrEqual(1);
+    expect(state2.bodies.length).toBeGreaterThanOrEqual(1);
+
+    ws1.close();
+    ws2.close();
+  });
+
+  it('should handle clock sync requests', async () => {
+    server = new PhysicsServer(RAPIER);
+    await server.start(TEST_PORT + 3);
+
+    const ws = await connectClient(TEST_PORT + 3);
+
+    const clientTimestamp = Date.now();
+    ws.send(encodeMessage({
+      type: MessageType.CLOCK_SYNC_REQUEST,
+      clientTimestamp,
+    }));
+
+    const response = await waitForMessage(ws, MessageType.CLOCK_SYNC_RESPONSE);
+    expect(response.type).toBe(MessageType.CLOCK_SYNC_RESPONSE);
+    if (response.type === MessageType.CLOCK_SYNC_RESPONSE) {
+      expect(response.clientTimestamp).toBe(clientTimestamp);
+      expect(response.serverTimestamp).toBeGreaterThan(0);
+    }
+
+    ws.close();
+  });
+
+  it('should return error for non-existent room', async () => {
+    server = new PhysicsServer(RAPIER);
+    await server.start(TEST_PORT + 4);
+
+    const ws = await connectClient(TEST_PORT + 4);
+
+    ws.send(encodeMessage({
+      type: MessageType.JOIN_ROOM,
+      roomId: 'nonexistent',
+    }));
+
+    const errorMsg = await waitForMessage(ws, MessageType.ERROR);
+    expect(errorMsg.type).toBe(MessageType.ERROR);
+
+    ws.close();
+  });
+});

package/src/__tests__/physics-world-collisions.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { PhysicsWorld } from '../physics-world.js';
+import type { BodyDescriptor } from '@rapierphysicsplugin/shared';
+
+describe('PhysicsWorld collision events', () => {
+  let world: PhysicsWorld;
+
+  beforeAll(async () => {
+    await RAPIER.init();
+  });
+
+  beforeEach(() => {
+    world = new PhysicsWorld(RAPIER);
+  });
+
+  afterEach(() => {
+    world.destroy();
+  });
+
+  function makeGround(): BodyDescriptor {
+    return {
+      id: 'ground',
+      shape: { type: 'box', params: { halfExtents: { x: 50, y: 0.5, z: 50 } } },
+      motionType: 'static',
+      position: { x: 0, y: -0.5, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+    };
+  }
+
+  function makeBox(id: string, y: number): BodyDescriptor {
+    return {
+      id,
+      shape: { type: 'box', params: { halfExtents: { x: 0.5, y: 0.5, z: 0.5 } } },
+      motionType: 'dynamic',
+      position: { x: 0, y, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+      mass: 1.0,
+    };
+  }
+
+  function makeSensor(id: string, y: number): BodyDescriptor {
+    return {
+      id,
+      shape: { type: 'box', params: { halfExtents: { x: 2, y: 2, z: 2 } } },
+      motionType: 'static',
+      position: { x: 0, y, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+      isTrigger: true,
+    };
+  }
+
+  it('should return empty events when no collisions occur', () => {
+    world.addBody(makeBox('box1', 100));
+    const events = world.step();
+    expect(events).toEqual([]);
+  });
+
+  it('should detect collision when box falls onto ground', () => {
+    world.addBody(makeGround());
+    world.addBody(makeBox('box1', 1.5));
+
+    // Step many times until box reaches ground
+    let allEvents: ReturnType<typeof world.step> = [];
+    for (let i = 0; i < 120; i++) {
+      const events = world.step();
+      allEvents.push(...events);
+    }
+
+    const collisionStarted = allEvents.filter(e => e.type === 'COLLISION_STARTED');
+    expect(collisionStarted.length).toBeGreaterThan(0);
+
+    const event = collisionStarted[0];
+    // Should involve box1 and ground (order may vary)
+    const ids = [event.bodyIdA, event.bodyIdB].sort();
+    expect(ids).toEqual(['box1', 'ground']);
+  });
+
+  it('should have contact point and normal for COLLISION_STARTED', () => {
+    world.addBody(makeGround());
+    world.addBody(makeBox('box1', 1.5));
+
+    let collisionEvent = null;
+    for (let i = 0; i < 120; i++) {
+      const events = world.step();
+      const started = events.find(e => e.type === 'COLLISION_STARTED');
+      if (started) {
+        collisionEvent = started;
+        break;
+      }
+    }
+
+    expect(collisionEvent).not.toBeNull();
+    // Contact point should exist for non-sensor collisions
+    // Note: contact point may be null if Rapier doesn't provide it on the first frame
+    // but normal should typically be available
+    if (collisionEvent!.point) {
+      expect(typeof collisionEvent!.point.x).toBe('number');
+      expect(typeof collisionEvent!.point.y).toBe('number');
+      expect(typeof collisionEvent!.point.z).toBe('number');
+    }
+  });
+
+  it('should detect TRIGGER_ENTERED when box enters sensor', () => {
+    world.addBody(makeSensor('sensor1', 2));
+    world.addBody(makeBox('box1', 10));
+
+    let allEvents: ReturnType<typeof world.step> = [];
+    for (let i = 0; i < 120; i++) {
+      const events = world.step();
+      allEvents.push(...events);
+    }
+
+    const triggerEntered = allEvents.filter(e => e.type === 'TRIGGER_ENTERED');
+    expect(triggerEntered.length).toBeGreaterThan(0);
+
+    const event = triggerEntered[0];
+    const ids = [event.bodyIdA, event.bodyIdB].sort();
+    expect(ids).toEqual(['box1', 'sensor1']);
+
+    // Sensor events should not have contact info
+    expect(event.point).toBeNull();
+    expect(event.normal).toBeNull();
+    expect(event.impulse).toBe(0);
+  });
+
+  it('should map body IDs correctly for collision events', () => {
+    world.addBody(makeGround());
+    world.addBody(makeBox('alpha', 1.5));
+    world.addBody(makeBox('beta', 5));
+
+    let allEvents: ReturnType<typeof world.step> = [];
+    for (let i = 0; i < 200; i++) {
+      const events = world.step();
+      allEvents.push(...events);
+    }
+
+    // All events should reference known body IDs
+    for (const event of allEvents) {
+      expect(['alpha', 'beta', 'ground']).toContain(event.bodyIdA);
+      expect(['alpha', 'beta', 'ground']).toContain(event.bodyIdB);
+    }
+  });
+
+  it('should return events from step() without modifying previous results', () => {
+    world.addBody(makeGround());
+    world.addBody(makeBox('box1', 1.5));
+
+    const firstEvents = world.step();
+    const secondEvents = world.step();
+
+    // Each call returns its own array
+    expect(firstEvents).not.toBe(secondEvents);
+  });
+});

package/src/__tests__/physics-world.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { PhysicsWorld } from '../physics-world.js';
+import type { BodyDescriptor } from '@rapierphysicsplugin/shared';
+
+describe('PhysicsWorld', () => {
+  let world: PhysicsWorld;
+
+  beforeAll(async () => {
+    await RAPIER.init();
+  });
+
+  beforeEach(() => {
+    world = new PhysicsWorld(RAPIER);
+  });
+
+  afterEach(() => {
+    world.destroy();
+  });
+
+  function makeBox(id: string, y: number = 5): BodyDescriptor {
+    return {
+      id,
+      shape: { type: 'box', params: { halfExtents: { x: 0.5, y: 0.5, z: 0.5 } } },
+      motionType: 'dynamic',
+      position: { x: 0, y, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+      mass: 1.0,
+    };
+  }
+
+  it('should add a body', () => {
+    const id = world.addBody(makeBox('box1'));
+    expect(id).toBe('box1');
+    expect(world.bodyCount).toBe(1);
+    expect(world.hasBody('box1')).toBe(true);
+  });
+
+  it('should throw when adding duplicate body', () => {
+    world.addBody(makeBox('box1'));
+    expect(() => world.addBody(makeBox('box1'))).toThrow('already exists');
+  });
+
+  it('should remove a body', () => {
+    world.addBody(makeBox('box1'));
+    world.removeBody('box1');
+    expect(world.bodyCount).toBe(0);
+    expect(world.hasBody('box1')).toBe(false);
+  });
+
+  it('should get body state', () => {
+    world.addBody(makeBox('box1', 10));
+    const state = world.getBodyState('box1');
+    expect(state).not.toBeNull();
+    expect(state!.id).toBe('box1');
+    expect(state!.position.y).toBeCloseTo(10);
+    expect(state!.rotation.w).toBeCloseTo(1);
+  });
+
+  it('should return null for non-existent body', () => {
+    expect(world.getBodyState('nonexistent')).toBeNull();
+  });
+
+  it('should step the physics world', () => {
+    world.addBody(makeBox('box1', 10));
+    const stateBefore = world.getBodyState('box1')!;
+
+    // Step multiple times so gravity takes effect
+    for (let i = 0; i < 60; i++) {
+      world.step();
+    }
+
+    const stateAfter = world.getBodyState('box1')!;
+    // Box should have fallen due to gravity
+    expect(stateAfter.position.y).toBeLessThan(stateBefore.position.y);
+  });
+
+  it('should get snapshot of all bodies', () => {
+    world.addBody(makeBox('box1', 5));
+    world.addBody(makeBox('box2', 10));
+
+    const snapshot = world.getSnapshot();
+    expect(snapshot).toHaveLength(2);
+    expect(snapshot.map(s => s.id).sort()).toEqual(['box1', 'box2']);
+  });
+
+  it('should apply force to a body', () => {
+    world.addBody(makeBox('box1', 5));
+    world.applyForce('box1', { x: 0, y: 100, z: 0 });
+    world.step();
+
+    const state = world.getBodyState('box1')!;
+    // Should have upward velocity from the applied force
+    expect(state.linVel.y).toBeGreaterThan(0);
+  });
+
+  it('should apply impulse to a body', () => {
+    world.addBody(makeBox('box1', 5));
+    world.applyImpulse('box1', { x: 10, y: 0, z: 0 });
+    world.step();
+
+    const state = world.getBodyState('box1')!;
+    expect(state.linVel.x).toBeGreaterThan(0);
+  });
+
+  it('should set body velocity', () => {
+    world.addBody(makeBox('box1', 5));
+    world.setBodyVelocity('box1', { x: 5, y: 0, z: 0 });
+
+    const state = world.getBodyState('box1')!;
+    expect(state.linVel.x).toBeCloseTo(5);
+  });
+
+  it('should add a sphere body', () => {
+    const descriptor: BodyDescriptor = {
+      id: 'sphere1',
+      shape: { type: 'sphere', params: { radius: 1 } },
+      motionType: 'dynamic',
+      position: { x: 0, y: 5, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+    };
+    world.addBody(descriptor);
+    expect(world.hasBody('sphere1')).toBe(true);
+  });
+
+  it('should add a static body', () => {
+    const descriptor: BodyDescriptor = {
+      id: 'ground',
+      shape: { type: 'box', params: { halfExtents: { x: 50, y: 0.5, z: 50 } } },
+      motionType: 'static',
+      position: { x: 0, y: -0.5, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+    };
+    world.addBody(descriptor);
+
+    // Static body shouldn't move
+    world.step();
+    const state = world.getBodyState('ground')!;
+    expect(state.position.y).toBeCloseTo(-0.5);
+  });
+
+  it('should apply input actions', () => {
+    world.addBody(makeBox('box1', 5));
+    world.applyInput({
+      type: 'applyForce',
+      bodyId: 'box1',
+      data: { force: { x: 0, y: 50, z: 0 } },
+    });
+    world.step();
+
+    const state = world.getBodyState('box1')!;
+    expect(state.linVel.y).toBeGreaterThan(0);
+  });
+
+  it('should load state from body descriptors', () => {
+    world.loadState([
+      makeBox('box1', 5),
+      makeBox('box2', 10),
+      makeBox('box3', 15),
+    ]);
+    expect(world.bodyCount).toBe(3);
+  });
+
+  it('should reset world with new body descriptors', () => {
+    world.loadState([makeBox('box1', 5), makeBox('box2', 10)]);
+    expect(world.bodyCount).toBe(2);
+
+    // Step to move bodies
+    for (let i = 0; i < 10; i++) {
+      world.step();
+    }
+    const stateBeforeReset = world.getBodyState('box1')!;
+    expect(stateBeforeReset.position.y).not.toBeCloseTo(5);
+
+    // Reset with same descriptors
+    world.reset([makeBox('box1', 5), makeBox('box2', 10)]);
+    expect(world.bodyCount).toBe(2);
+
+    // Bodies should be back at initial positions
+    const stateAfterReset = world.getBodyState('box1')!;
+    expect(stateAfterReset.position.y).toBeCloseTo(5);
+    const box2State = world.getBodyState('box2')!;
+    expect(box2State.position.y).toBeCloseTo(10);
+  });
+
+  it('should reset with different body descriptors', () => {
+    world.loadState([makeBox('box1', 5)]);
+    expect(world.bodyCount).toBe(1);
+
+    world.reset([makeBox('boxA', 3), makeBox('boxB', 7), makeBox('boxC', 12)]);
+    expect(world.bodyCount).toBe(3);
+    expect(world.hasBody('box1')).toBe(false);
+    expect(world.hasBody('boxA')).toBe(true);
+    expect(world.hasBody('boxB')).toBe(true);
+    expect(world.hasBody('boxC')).toBe(true);
+  });
+});