@rapierphysicsplugin/server 1.0.0

package/src/__tests__/room.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeAll, afterEach } from 'vitest';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { Room, RoomManager } from '../room.js';
+import { decodeMessage } from '@rapierphysicsplugin/shared';
+import type { BodyDescriptor, ServerMessage } from '@rapierphysicsplugin/shared';
+
+describe('Room', () => {
+  let rapier: typeof RAPIER;
+
+  beforeAll(async () => {
+    await RAPIER.init();
+    rapier = RAPIER;
+  });
+
+  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 create a room with initial bodies', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1', 5), makeBox('box2', 10)]);
+
+    const snapshot = room.getSnapshot();
+    expect(snapshot.bodies).toHaveLength(2);
+    room.destroy();
+  });
+
+  it('should add and remove bodies', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1')]);
+
+    const snapshot1 = room.getSnapshot();
+    expect(snapshot1.bodies).toHaveLength(1);
+
+    room.destroy();
+  });
+
+  it('should step physics and advance tick', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1', 10)]);
+
+    expect(room.tickNumber).toBe(0);
+    room.tick();
+    expect(room.tickNumber).toBe(1);
+    room.tick();
+    expect(room.tickNumber).toBe(2);
+
+    room.destroy();
+  });
+
+  it('should process buffered inputs during tick', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1', 5)]);
+
+    // Simulate a client connection by directly buffering input
+    // We need to add a mock client first
+    const mockConn = {
+      id: 'client1',
+      roomId: null as string | null,
+      ws: { readyState: 1, OPEN: 1, send: () => {} } as any,
+      send: () => {},
+      rtt: 0,
+      clockOffset: 0,
+      lastAcknowledgedTick: 0,
+      inputSequence: 0,
+      updateClockSync: () => {},
+      mapClientTickToServerTick: () => 0,
+    };
+
+    room.addClient(mockConn as any);
+    room.bufferInput('client1', {
+      tick: 0,
+      sequenceNum: 0,
+      actions: [
+        { type: 'applyImpulse', bodyId: 'box1', data: { impulse: { x: 10, y: 0, z: 0 } } },
+      ],
+    });
+
+    room.tick();
+
+    const state = room.getSnapshot();
+    const box1 = state.bodies.find(b => b.id === 'box1')!;
+    expect(box1.linVel.x).toBeGreaterThan(0);
+
+    room.destroy();
+  });
+
+  it('should not auto-start simulation when a client joins', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1', 5)]);
+
+    const mockConn = {
+      id: 'client1',
+      roomId: null as string | null,
+      ws: { readyState: 1, OPEN: 1, send: () => {} } as any,
+      send: () => {},
+      rtt: 0,
+      clockOffset: 0,
+      lastAcknowledgedTick: 0,
+      inputSequence: 0,
+      updateClockSync: () => {},
+      mapClientTickToServerTick: () => 0,
+    };
+
+    room.addClient(mockConn as any);
+    expect(room.isSimulationRunning).toBe(false);
+
+    room.destroy();
+  });
+
+  it('should start simulation on startSimulation call', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1', 5)]);
+
+    const sentMessages: ServerMessage[] = [];
+    const mockConn = {
+      id: 'client1',
+      roomId: null as string | null,
+      ws: { readyState: 1, OPEN: 1, send: () => {} } as any,
+      send: (msg: Uint8Array) => { sentMessages.push(decodeMessage(msg) as ServerMessage); },
+      rtt: 0,
+      clockOffset: 0,
+      lastAcknowledgedTick: 0,
+      inputSequence: 0,
+      updateClockSync: () => {},
+      mapClientTickToServerTick: () => 0,
+    };
+
+    room.addClient(mockConn as any);
+    expect(room.isSimulationRunning).toBe(false);
+
+    room.startSimulation();
+    expect(room.isSimulationRunning).toBe(true);
+
+    // Should have broadcast SIMULATION_STARTED
+    const startedMsg = sentMessages.find(m => m.type === 'simulation_started');
+    expect(startedMsg).toBeDefined();
+
+    room.destroy();
+  });
+
+  it('should reset physics on startSimulation when already running', () => {
+    const room = new Room('test', rapier);
+    room.loadInitialState([makeBox('box1', 10)]);
+
+    const mockConn = {
+      id: 'client1',
+      roomId: null as string | null,
+      ws: { readyState: 1, OPEN: 1, send: () => {} } as any,
+      send: () => {},
+      rtt: 0,
+      clockOffset: 0,
+      lastAcknowledgedTick: 0,
+      inputSequence: 0,
+      updateClockSync: () => {},
+      mapClientTickToServerTick: () => 0,
+    };
+
+    room.addClient(mockConn as any);
+    room.startSimulation();
+
+    // Run some ticks so physics changes
+    for (let i = 0; i < 60; i++) {
+      room.tick();
+    }
+    expect(room.tickNumber).toBeGreaterThan(0);
+    const stateBefore = room.getSnapshot();
+    const box = stateBefore.bodies.find(b => b.id === 'box1')!;
+    expect(box.position.y).not.toBeCloseTo(10);
+
+    // Reset
+    room.startSimulation();
+    expect(room.tickNumber).toBe(0);
+    const stateAfter = room.getSnapshot();
+    const boxAfter = stateAfter.bodies.find(b => b.id === 'box1')!;
+    expect(boxAfter.position.y).toBeCloseTo(10);
+
+    room.destroy();
+  });
+});
+
+describe('RoomManager', () => {
+  let rapier: typeof RAPIER;
+
+  beforeAll(async () => {
+    await RAPIER.init();
+    rapier = RAPIER;
+  });
+
+  it('should create and retrieve rooms', () => {
+    const manager = new RoomManager(rapier);
+    manager.createRoom('room1');
+
+    expect(manager.getRoom('room1')).toBeDefined();
+    expect(manager.roomCount).toBe(1);
+
+    manager.destroyRoom('room1');
+  });
+
+  it('should throw on duplicate room creation', () => {
+    const manager = new RoomManager(rapier);
+    manager.createRoom('room1');
+    expect(() => manager.createRoom('room1')).toThrow('already exists');
+    manager.destroyRoom('room1');
+  });
+
+  it('should destroy rooms', () => {
+    const manager = new RoomManager(rapier);
+    manager.createRoom('room1');
+    manager.destroyRoom('room1');
+    expect(manager.getRoom('room1')).toBeUndefined();
+    expect(manager.roomCount).toBe(0);
+  });
+
+  it('should list all room ids', () => {
+    const manager = new RoomManager(rapier);
+    manager.createRoom('room1');
+    manager.createRoom('room2');
+
+    expect(manager.getAllRoomIds().sort()).toEqual(['room1', 'room2']);
+
+    manager.destroyRoom('room1');
+    manager.destroyRoom('room2');
+  });
+});

package/src/__tests__/state-manager.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import RAPIER from '@dimforge/rapier3d-compat';
+import { PhysicsWorld } from '../physics-world.js';
+import { StateManager } from '../state-manager.js';
+import type { BodyDescriptor } from '@rapierphysicsplugin/shared';
+import { FIELD_POSITION, FIELD_ROTATION, FIELD_LIN_VEL, FIELD_ANG_VEL, FIELD_ALL } from '@rapierphysicsplugin/shared';
+
+describe('StateManager', () => {
+  let world: PhysicsWorld;
+  let stateManager: StateManager;
+
+  beforeAll(async () => {
+    await RAPIER.init();
+  });
+
+  beforeEach(() => {
+    world = new PhysicsWorld(RAPIER);
+    stateManager = new StateManager();
+  });
+
+  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,
+    };
+  }
+
+  function makeStaticBox(id: string, y: number = 0): BodyDescriptor {
+    return {
+      id,
+      shape: { type: 'box', params: { halfExtents: { x: 5, y: 0.5, z: 5 } } },
+      motionType: 'static',
+      position: { x: 0, y, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 },
+    };
+  }
+
+  it('should create a full snapshot', () => {
+    world.addBody(makeBox('box1', 5));
+    world.addBody(makeBox('box2', 10));
+
+    const snapshot = stateManager.createSnapshot(world, 42);
+    expect(snapshot.tick).toBe(42);
+    expect(snapshot.bodies).toHaveLength(2);
+    expect(snapshot.timestamp).toBeGreaterThan(0);
+  });
+
+  it('should create delta with all bodies on first call (fieldMask = FIELD_ALL)', () => {
+    world.addBody(makeBox('box1', 5));
+    const delta = stateManager.createDelta(world, 1);
+    expect(delta.bodies).toHaveLength(1);
+    expect(delta.bodies[0].fieldMask).toBe(FIELD_ALL);
+    expect(delta.isDelta).toBe(true);
+  });
+
+  it('should create empty delta when nothing changed', () => {
+    world.addBody(makeBox('box1', 5));
+
+    // First delta includes everything
+    stateManager.createDelta(world, 1);
+
+    // No stepping, nothing changed — delta should be empty
+    const delta2 = stateManager.createDelta(world, 2);
+    expect(delta2.bodies).toHaveLength(0);
+  });
+
+  it('should detect changes after physics step', () => {
+    world.addBody(makeBox('box1', 5));
+
+    // First delta
+    stateManager.createDelta(world, 1);
+
+    // Step physics — body should fall
+    for (let i = 0; i < 10; i++) {
+      world.step();
+    }
+
+    const delta2 = stateManager.createDelta(world, 2);
+    expect(delta2.bodies).toHaveLength(1);
+    expect(delta2.bodies[0].id).toBe('box1');
+  });
+
+  it('should set per-field mask for position+linVel change (falling body)', () => {
+    world.addBody(makeBox('box1', 5));
+
+    // First delta
+    stateManager.createDelta(world, 1);
+
+    // Step physics — body falls (position and linVel change, rotation stays identity)
+    for (let i = 0; i < 10; i++) {
+      world.step();
+    }
+
+    const delta2 = stateManager.createDelta(world, 2);
+    expect(delta2.bodies).toHaveLength(1);
+    const mask = delta2.bodies[0].fieldMask!;
+    // A falling body should have position and linVel changed
+    expect(mask & FIELD_POSITION).toBeTruthy();
+    expect(mask & FIELD_LIN_VEL).toBeTruthy();
+  });
+
+  it('should assign body indices', () => {
+    world.addBody(makeBox('box1', 5));
+    world.addBody(makeBox('box2', 10));
+
+    stateManager.createSnapshot(world, 0);
+
+    expect(stateManager.getBodyIndex('box1')).toBe(0);
+    expect(stateManager.getBodyIndex('box2')).toBe(1);
+  });
+
+  it('should produce ID mapping record', () => {
+    world.addBody(makeBox('box1', 5));
+    world.addBody(makeBox('box2', 10));
+    stateManager.createSnapshot(world, 0);
+
+    const record = stateManager.getIdToIndexRecord();
+    expect(record).toEqual({ box1: 0, box2: 1 });
+  });
+
+  it('should keep index after body removal (indices are never reused)', () => {
+    world.addBody(makeBox('box1', 5));
+    world.addBody(makeBox('box2', 10));
+    stateManager.createSnapshot(world, 0);
+
+    stateManager.removeBody('box1');
+    // box1 index is still in the map (not reused)
+    expect(stateManager.getBodyIndex('box1')).toBe(0);
+
+    // Adding a new body gets the next index
+    world.addBody(makeBox('box3', 15));
+    stateManager.ensureBodyIndex('box3');
+    expect(stateManager.getBodyIndex('box3')).toBe(2);
+  });
+
+  it('should clear all state on clear()', () => {
+    world.addBody(makeBox('box1', 5));
+    stateManager.createSnapshot(world, 0);
+
+    stateManager.clear();
+    expect(stateManager.getBodyIndex('box1')).toBeUndefined();
+    expect(stateManager.getIdToIndexRecord()).toEqual({});
+  });
+});

package/src/client-connection.ts

@@ -0,0 +1,52 @@
+import type { WebSocket } from 'ws';
+
+export class ClientConnection {
+  readonly id: string;
+  readonly ws: WebSocket;
+  roomId: string | null = null;
+  rtt = 0;
+  clockOffset = 0;
+  lastAcknowledgedTick = 0;
+  inputSequence = 0;
+
+  private rttSamples: number[] = [];
+  private offsetSamples: number[] = [];
+  private static readonly MAX_SAMPLES = 10;
+
+  constructor(id: string, ws: WebSocket) {
+    this.id = id;
+    this.ws = ws;
+  }
+
+  send(data: Uint8Array): void {
+    if (this.ws.readyState === this.ws.OPEN) {
+      this.ws.send(data);
+    }
+  }
+
+  updateClockSync(clientTimestamp: number, serverTimestamp: number): void {
+    const now = Date.now();
+    const rtt = now - clientTimestamp;
+
+    this.rttSamples.push(rtt);
+    if (this.rttSamples.length > ClientConnection.MAX_SAMPLES) {
+      this.rttSamples.shift();
+    }
+
+    const offset = serverTimestamp - clientTimestamp - rtt / 2;
+    this.offsetSamples.push(offset);
+    if (this.offsetSamples.length > ClientConnection.MAX_SAMPLES) {
+      this.offsetSamples.shift();
+    }
+
+    // Rolling average
+    this.rtt = this.rttSamples.reduce((a, b) => a + b, 0) / this.rttSamples.length;
+    this.clockOffset = this.offsetSamples.reduce((a, b) => a + b, 0) / this.offsetSamples.length;
+  }
+
+  mapClientTickToServerTick(clientTick: number, serverTickRate: number): number {
+    // Use clock offset to map client tick to server tick
+    const offsetInTicks = Math.round((this.clockOffset / 1000) * serverTickRate);
+    return clientTick + offsetInTicks;
+  }
+}

package/src/clock-sync.ts

@@ -0,0 +1,16 @@
+import type { ClockSyncRequestMessage, ClockSyncResponseMessage } from '@rapierphysicsplugin/shared';
+import { MessageType, encodeMessage } from '@rapierphysicsplugin/shared';
+import type { ClientConnection } from './client-connection.js';
+
+export function handleClockSyncRequest(
+  conn: ClientConnection,
+  message: ClockSyncRequestMessage
+): void {
+  const response: ClockSyncResponseMessage = {
+    type: MessageType.CLOCK_SYNC_RESPONSE,
+    clientTimestamp: message.clientTimestamp,
+    serverTimestamp: Date.now(),
+  };
+
+  conn.send(encodeMessage(response));
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+import { DEFAULT_PORT, ComputeBackend, loadRapier } from '@rapierphysicsplugin/shared';
+import { PhysicsServer } from './server.js';
+
+export { PhysicsServer } from './server.js';
+export { PhysicsWorld } from './physics-world.js';
+export { Room, RoomManager } from './room.js';
+export { ClientConnection } from './client-connection.js';
+export { SimulationLoop } from './simulation-loop.js';
+export { StateManager } from './state-manager.js';
+export { InputBuffer } from './input-buffer.js';
+
+async function main(): Promise<void> {
+  const backend = (process.env.PHYSICS_BACKEND as ComputeBackend) ?? ComputeBackend.WASM_SIMD;
+  console.log(`Initializing Rapier WASM (${backend})...`);
+  const RAPIER = await loadRapier({ backend });
+  console.log('Rapier initialized.');
+
+  const port = parseInt(process.env.PORT || String(DEFAULT_PORT), 10);
+  const server = new PhysicsServer(RAPIER);
+  await server.start(port);
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\nShutting down...');
+    server.stop();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    console.log('\nShutting down...');
+    server.stop();
+    process.exit(0);
+  });
+}
+
+// Only run main when executed directly
+const isMainModule = process.argv[1]?.endsWith('index.ts') || process.argv[1]?.endsWith('index.js');
+if (isMainModule) {
+  main().catch(console.error);
+}

package/src/input-buffer.ts

@@ -0,0 +1,46 @@
+import type { ClientInput } from '@rapierphysicsplugin/shared';
+import { MAX_INPUT_BUFFER } from '@rapierphysicsplugin/shared';
+
+export class InputBuffer {
+  private buffer: Map<number, ClientInput[]> = new Map();
+  private oldestTick = 0;
+
+  addInput(input: ClientInput, serverTick: number): void {
+    // Map client tick to server tick using provided mapping
+    const targetTick = serverTick;
+
+    if (!this.buffer.has(targetTick)) {
+      this.buffer.set(targetTick, []);
+    }
+    this.buffer.get(targetTick)!.push(input);
+
+    // Clean up old entries
+    this.pruneOldEntries(targetTick);
+  }
+
+  getInputsForTick(tick: number): ClientInput[] {
+    const inputs = this.buffer.get(tick);
+    if (inputs) {
+      this.buffer.delete(tick);
+      return inputs;
+    }
+    return [];
+  }
+
+  private pruneOldEntries(currentTick: number): void {
+    const cutoff = currentTick - MAX_INPUT_BUFFER;
+    for (const tick of this.buffer.keys()) {
+      if (tick < cutoff) {
+        this.buffer.delete(tick);
+      }
+    }
+  }
+
+  clear(): void {
+    this.buffer.clear();
+  }
+
+  get size(): number {
+    return this.buffer.size;
+  }
+}