@rapierphysicsplugin/client 1.0.0

package/src/__tests__/interpolator.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Interpolator } from '../interpolator.js';
+import type { BodyState } from '@rapierphysicsplugin/shared';
+
+function makeState(id: string, x: number, y: number, z: number, vx = 0, vy = 0, vz = 0): BodyState {
+  return {
+    id,
+    position: { x, y, z },
+    rotation: { x: 0, y: 0, z: 0, w: 1 },
+    linVel: { x: vx, y: vy, z: vz },
+    angVel: { x: 0, y: 0, z: 0 },
+  };
+}
+
+describe('Interpolator', () => {
+  let interpolator: Interpolator;
+
+  beforeEach(() => {
+    // Use 0ms render delay for deterministic testing
+    interpolator = new Interpolator(0);
+  });
+
+  it('should return null for unknown bodies', () => {
+    expect(interpolator.getInterpolatedState('unknown', Date.now())).toBeNull();
+  });
+
+  it('should return earliest state when render time is before all snapshots', () => {
+    interpolator.addSnapshot('body1', makeState('body1', 0, 0, 0), 1000);
+    interpolator.addSnapshot('body1', makeState('body1', 10, 0, 0), 2000);
+
+    const state = interpolator.getInterpolatedState('body1', 500);
+    expect(state).not.toBeNull();
+    expect(state!.position.x).toBeCloseTo(0);
+  });
+
+  it('should interpolate between two snapshots', () => {
+    interpolator.addSnapshot('body1', makeState('body1', 0, 0, 0), 1000);
+    interpolator.addSnapshot('body1', makeState('body1', 10, 0, 0), 2000);
+
+    // Midpoint
+    const state = interpolator.getInterpolatedState('body1', 1500);
+    expect(state).not.toBeNull();
+    // Hermite interpolation at t=0.5 with zero velocities should give midpoint
+    expect(state!.position.x).toBeCloseTo(5, 0);
+  });
+
+  it('should extrapolate after last snapshot', () => {
+    interpolator.addSnapshot('body1', makeState('body1', 0, 0, 0, 10, 0, 0), 1000);
+
+    // 0.1 seconds after the last snapshot
+    const state = interpolator.getInterpolatedState('body1', 1100);
+    expect(state).not.toBeNull();
+    // Should move in the x direction due to velocity
+    expect(state!.position.x).toBeGreaterThan(0);
+  });
+
+  it('should interpolate rotation via slerp', () => {
+    const state1: BodyState = {
+      id: 'body1',
+      position: { x: 0, y: 0, z: 0 },
+      rotation: { x: 0, y: 0, z: 0, w: 1 }, // identity
+      linVel: { x: 0, y: 0, z: 0 },
+      angVel: { x: 0, y: 0, z: 0 },
+    };
+    const state2: BodyState = {
+      id: 'body1',
+      position: { x: 0, y: 0, z: 0 },
+      rotation: { x: 0, y: 0.7071, z: 0, w: 0.7071 }, // 90deg around Y
+      linVel: { x: 0, y: 0, z: 0 },
+      angVel: { x: 0, y: 0, z: 0 },
+    };
+
+    interpolator.addSnapshot('body1', state1, 1000);
+    interpolator.addSnapshot('body1', state2, 2000);
+
+    const result = interpolator.getInterpolatedState('body1', 1500);
+    expect(result).not.toBeNull();
+
+    // Quaternion magnitude should be ~1
+    const q = result!.rotation;
+    const mag = Math.sqrt(q.x ** 2 + q.y ** 2 + q.z ** 2 + q.w ** 2);
+    expect(mag).toBeCloseTo(1, 2);
+  });
+
+  it('should remove a body', () => {
+    interpolator.addSnapshot('body1', makeState('body1', 0, 0, 0), 1000);
+    interpolator.removeBody('body1');
+    expect(interpolator.getInterpolatedState('body1', 1000)).toBeNull();
+  });
+
+  it('should clear all data', () => {
+    interpolator.addSnapshot('body1', makeState('body1', 0, 0, 0), 1000);
+    interpolator.addSnapshot('body2', makeState('body2', 5, 5, 5), 1000);
+    interpolator.clear();
+    expect(interpolator.getInterpolatedState('body1', 1000)).toBeNull();
+    expect(interpolator.getInterpolatedState('body2', 1000)).toBeNull();
+  });
+});

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

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { StateReconciler, needsCorrection, blendBodyState } from '../state-reconciler.js';
+import type { BodyState, RoomSnapshot } from '@rapierphysicsplugin/shared';
+
+function makeState(id: string, x: number, y: number, z: number): BodyState {
+  return {
+    id,
+    position: { x, y, z },
+    rotation: { x: 0, y: 0, z: 0, w: 1 },
+    linVel: { x: 0, y: 0, z: 0 },
+    angVel: { x: 0, y: 0, z: 0 },
+  };
+}
+
+describe('StateReconciler', () => {
+  let reconciler: StateReconciler;
+
+  beforeEach(() => {
+    reconciler = new StateReconciler();
+  });
+
+  it('should separate local and remote bodies', () => {
+    reconciler.addLocalBody('player1');
+
+    const timestamp = Date.now();
+    const snapshot: RoomSnapshot = {
+      tick: 10,
+      timestamp,
+      bodies: [
+        makeState('player1', 1, 2, 3),
+        makeState('enemy1', 4, 5, 6),
+      ],
+    };
+
+    const result = reconciler.processServerState(snapshot);
+    // Local body goes to corrections
+    expect(result.localCorrections.has('player1')).toBe(true);
+    // Remote body is fed to interpolator — query it at render time
+    const interpolated = reconciler.getInterpolatedRemoteState('enemy1', timestamp);
+    expect(interpolated).not.toBeNull();
+    expect(interpolated!.position.x).toBeCloseTo(4, 1);
+  });
+
+  it('should discard old pending inputs', () => {
+    reconciler.addPendingInput({ tick: 5, sequenceNum: 0, actions: [] });
+    reconciler.addPendingInput({ tick: 10, sequenceNum: 1, actions: [] });
+    reconciler.addPendingInput({ tick: 15, sequenceNum: 2, actions: [] });
+
+    reconciler.processServerState({
+      tick: 10,
+      timestamp: Date.now(),
+      bodies: [],
+    });
+
+    const pending = reconciler.getPendingInputs();
+    expect(pending).toHaveLength(1);
+    expect(pending[0].tick).toBe(15);
+  });
+
+  it('should track last server tick', () => {
+    reconciler.processServerState({
+      tick: 42,
+      timestamp: Date.now(),
+      bodies: [],
+    });
+    expect(reconciler.lastProcessedServerTick).toBe(42);
+  });
+
+  it('should clear all state', () => {
+    reconciler.addLocalBody('player1');
+    reconciler.addPendingInput({ tick: 5, sequenceNum: 0, actions: [] });
+    reconciler.clear();
+
+    expect(reconciler.getPendingInputs()).toHaveLength(0);
+    expect(reconciler.lastProcessedServerTick).toBe(0);
+  });
+});
+
+describe('needsCorrection', () => {
+  it('should return false for small differences', () => {
+    const a = makeState('body1', 1, 2, 3);
+    const b = makeState('body1', 1.01, 2.01, 3.01);
+    expect(needsCorrection(a, b)).toBe(false);
+  });
+
+  it('should return true for large differences', () => {
+    const a = makeState('body1', 1, 2, 3);
+    const b = makeState('body1', 2, 2, 3);
+    expect(needsCorrection(a, b)).toBe(true);
+  });
+});
+
+describe('blendBodyState', () => {
+  it('should blend positions toward target', () => {
+    const current = makeState('body1', 0, 0, 0);
+    const target = makeState('body1', 10, 0, 0);
+
+    const blended = blendBodyState(current, target);
+    expect(blended.position.x).toBeGreaterThan(0);
+    expect(blended.position.x).toBeLessThan(10);
+  });
+});

package/src/clock-sync.ts

@@ -0,0 +1,77 @@
+import {
+  MessageType,
+  CLOCK_SYNC_INTERVAL_MS,
+  CLOCK_SYNC_SAMPLES,
+  SERVER_TICK_RATE,
+  FIXED_TIMESTEP,
+  encodeMessage,
+} from '@rapierphysicsplugin/shared';
+import type { ClockSyncResponseMessage } from '@rapierphysicsplugin/shared';
+
+export class ClockSyncClient {
+  private rttSamples: number[] = [];
+  private offsetSamples: number[] = [];
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private sendFn: ((data: Uint8Array) => void) | null = null;
+
+  start(sendFn: (data: Uint8Array) => void): void {
+    this.sendFn = sendFn;
+    this.sendSyncRequest();
+    this.intervalId = setInterval(() => this.sendSyncRequest(), CLOCK_SYNC_INTERVAL_MS);
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    this.sendFn = null;
+  }
+
+  private sendSyncRequest(): void {
+    if (!this.sendFn) return;
+    this.sendFn(encodeMessage({
+      type: MessageType.CLOCK_SYNC_REQUEST,
+      clientTimestamp: Date.now(),
+    }));
+  }
+
+  handleResponse(message: ClockSyncResponseMessage): void {
+    const now = Date.now();
+    const rtt = now - message.clientTimestamp;
+    const offset = message.serverTimestamp - message.clientTimestamp - rtt / 2;
+
+    this.rttSamples.push(rtt);
+    if (this.rttSamples.length > CLOCK_SYNC_SAMPLES) {
+      this.rttSamples.shift();
+    }
+
+    this.offsetSamples.push(offset);
+    if (this.offsetSamples.length > CLOCK_SYNC_SAMPLES) {
+      this.offsetSamples.shift();
+    }
+  }
+
+  getRTT(): number {
+    if (this.rttSamples.length === 0) return 0;
+    return this.rttSamples.reduce((a, b) => a + b, 0) / this.rttSamples.length;
+  }
+
+  getClockOffset(): number {
+    if (this.offsetSamples.length === 0) return 0;
+    return this.offsetSamples.reduce((a, b) => a + b, 0) / this.offsetSamples.length;
+  }
+
+  getServerTime(): number {
+    return Date.now() + this.getClockOffset();
+  }
+
+  getServerTick(): number {
+    const serverTimeMs = this.getServerTime();
+    return Math.floor(serverTimeMs / (FIXED_TIMESTEP * 1000));
+  }
+
+  get isCalibrated(): boolean {
+    return this.rttSamples.length >= 3;
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { PhysicsSyncClient } from './sync-client.js';
+export { RapierPlugin } from './rapier-plugin.js';
+export { NetworkedRapierPlugin } from './networked-rapier-plugin.js';
+export type { NetworkedRapierPluginConfig } from './networked-rapier-plugin.js';
+export { ClockSyncClient } from './clock-sync.js';
+export { StateReconciler, needsCorrection, blendBodyState } from './state-reconciler.js';
+export { Interpolator } from './interpolator.js';
+export type { InterpolatorStats } from './interpolator.js';
+export { InputManager } from './input-manager.js';

package/src/input-manager.ts

@@ -0,0 +1,72 @@
+import type { ClientInput, InputAction } from '@rapierphysicsplugin/shared';
+import { MAX_INPUT_BUFFER, CLIENT_INPUT_RATE } from '@rapierphysicsplugin/shared';
+
+export class InputManager {
+  private pendingActions: InputAction[] = [];
+  private inputHistory: ClientInput[] = [];
+  private sequenceNum = 0;
+  private currentTick = 0;
+  private sendFn: ((input: ClientInput) => void) | null = null;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+
+  start(sendFn: (input: ClientInput) => void, getTickFn: () => number): void {
+    this.sendFn = sendFn;
+
+    const intervalMs = 1000 / CLIENT_INPUT_RATE;
+    this.intervalId = setInterval(() => {
+      this.currentTick = getTickFn();
+      this.flush();
+    }, intervalMs);
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    this.sendFn = null;
+  }
+
+  queueAction(action: InputAction): void {
+    this.pendingActions.push(action);
+  }
+
+  flush(): void {
+    if (this.pendingActions.length === 0) return;
+    if (!this.sendFn) return;
+
+    const input: ClientInput = {
+      tick: this.currentTick,
+      sequenceNum: this.sequenceNum++,
+      actions: [...this.pendingActions],
+    };
+
+    this.pendingActions = [];
+
+    // Store in history for reconciliation
+    this.inputHistory.push(input);
+    if (this.inputHistory.length > MAX_INPUT_BUFFER) {
+      this.inputHistory.shift();
+    }
+
+    this.sendFn(input);
+  }
+
+  getInputHistory(): ClientInput[] {
+    return this.inputHistory;
+  }
+
+  getInputsSince(tick: number): ClientInput[] {
+    return this.inputHistory.filter(input => input.tick > tick);
+  }
+
+  clearHistory(): void {
+    this.inputHistory = [];
+  }
+
+  clear(): void {
+    this.pendingActions = [];
+    this.inputHistory = [];
+    this.sequenceNum = 0;
+  }
+}

package/src/interpolator.ts

@@ -0,0 +1,256 @@
+import type { BodyState, Vec3, Quat } from '@rapierphysicsplugin/shared';
+import { INTERPOLATION_BUFFER_SIZE, BROADCAST_RATE } from '@rapierphysicsplugin/shared';
+
+interface Snapshot {
+  timestamp: number;
+  state: BodyState;
+}
+
+export interface InterpolatorStats {
+  /** Bodies that had two bracketing snapshots — true interpolation */
+  interpolatedCount: number;
+  /** Bodies where renderTime was past all snapshots — velocity extrapolation */
+  extrapolatedCount: number;
+  /** Bodies where renderTime was before all snapshots — returned earliest */
+  staleCount: number;
+  /** Bodies with empty buffer — returned null */
+  emptyCount: number;
+  /** Render delay being used (ms) */
+  renderDelay: number;
+  /** Sample body diagnostics (first dynamic body seen) */
+  sampleBodyId: string | null;
+  sampleBufferLen: number;
+  sampleRenderTime: number;
+  sampleBufferOldest: number;
+  sampleBufferNewest: number;
+  sampleT: number;
+}
+
+export class Interpolator {
+  private buffers: Map<string, Snapshot[]> = new Map();
+  private renderDelay: number;
+  private _stats: InterpolatorStats = this._emptyStats();
+
+  constructor(renderDelayMs?: number) {
+    // Default render delay: ~3x broadcast interval to absorb jitter
+    this.renderDelay = renderDelayMs ?? (3 * (1000 / BROADCAST_RATE));
+  }
+
+  private _emptyStats(): InterpolatorStats {
+    return {
+      interpolatedCount: 0,
+      extrapolatedCount: 0,
+      staleCount: 0,
+      emptyCount: 0,
+      renderDelay: this?.renderDelay ?? 0,
+      sampleBodyId: null,
+      sampleBufferLen: 0,
+      sampleRenderTime: 0,
+      sampleBufferOldest: 0,
+      sampleBufferNewest: 0,
+      sampleT: 0,
+    };
+  }
+
+  /** Reset stats at the start of each render frame, then call getInterpolatedState per body */
+  resetStats(): void {
+    this._stats = this._emptyStats();
+    this._stats.renderDelay = this.renderDelay;
+  }
+
+  getStats(): InterpolatorStats {
+    return this._stats;
+  }
+
+  addSnapshot(bodyId: string, state: BodyState, timestamp: number): void {
+    if (!this.buffers.has(bodyId)) {
+      this.buffers.set(bodyId, []);
+    }
+
+    const buffer = this.buffers.get(bodyId)!;
+
+    // Guard against duplicate or out-of-order timestamps (TCP can burst after stalls)
+    if (buffer.length > 0 && timestamp <= buffer[buffer.length - 1].timestamp) {
+      return;
+    }
+
+    buffer.push({ timestamp, state });
+
+    // Keep buffer limited
+    while (buffer.length > INTERPOLATION_BUFFER_SIZE + 1) {
+      buffer.shift();
+    }
+  }
+
+  getInterpolatedState(bodyId: string, currentTime: number): BodyState | null {
+    const buffer = this.buffers.get(bodyId);
+    if (!buffer || buffer.length === 0) {
+      this._stats.emptyCount++;
+      return null;
+    }
+
+    // Render time is behind real time by renderDelay
+    const renderTime = currentTime - this.renderDelay;
+
+    // Capture sample diagnostics for the first body we see with data
+    if (!this._stats.sampleBodyId) {
+      this._stats.sampleBodyId = bodyId;
+      this._stats.sampleBufferLen = buffer.length;
+      this._stats.sampleRenderTime = renderTime;
+      this._stats.sampleBufferOldest = buffer[0].timestamp;
+      this._stats.sampleBufferNewest = buffer[buffer.length - 1].timestamp;
+    }
+
+    // Find the two snapshots to interpolate between
+    let older: Snapshot | null = null;
+    let newer: Snapshot | null = null;
+
+    for (let i = 0; i < buffer.length - 1; i++) {
+      if (buffer[i].timestamp <= renderTime && buffer[i + 1].timestamp >= renderTime) {
+        older = buffer[i];
+        newer = buffer[i + 1];
+        break;
+      }
+    }
+
+    // If we have two bracketing snapshots, interpolate
+    if (older && newer) {
+      const dtMs = newer.timestamp - older.timestamp;
+      const t = (renderTime - older.timestamp) / dtMs;
+      const dtSec = dtMs / 1000;
+      this._stats.interpolatedCount++;
+      if (this._stats.sampleBodyId === bodyId) {
+        this._stats.sampleT = t;
+      }
+      return interpolateBodyState(older.state, newer.state, t, dtSec);
+    }
+
+    // If render time is past all snapshots, extrapolate from last
+    const last = buffer[buffer.length - 1];
+    if (renderTime > last.timestamp) {
+      const dt = (renderTime - last.timestamp) / 1000;
+      this._stats.extrapolatedCount++;
+      return extrapolateBodyState(last.state, dt);
+    }
+
+    // If render time is before all snapshots, return earliest
+    this._stats.staleCount++;
+    return buffer[0].state;
+  }
+
+  removeBody(bodyId: string): void {
+    this.buffers.delete(bodyId);
+  }
+
+  clear(): void {
+    this.buffers.clear();
+  }
+}
+
+function interpolateBodyState(a: BodyState, b: BodyState, t: number, dtSec: number): BodyState {
+  // Scale velocity tangents by dt so they match the Hermite parameter space (t: 0→1)
+  // Raw velocities are in units/second; tangents need to be in units/interval
+  const scaledVelA: Vec3 = { x: a.linVel.x * dtSec, y: a.linVel.y * dtSec, z: a.linVel.z * dtSec };
+  const scaledVelB: Vec3 = { x: b.linVel.x * dtSec, y: b.linVel.y * dtSec, z: b.linVel.z * dtSec };
+
+  return {
+    id: a.id,
+    position: hermiteInterpolateVec3(a.position, scaledVelA, b.position, scaledVelB, t),
+    rotation: slerpQuat(a.rotation, b.rotation, t),
+    linVel: lerpVec3(a.linVel, b.linVel, t),
+    angVel: lerpVec3(a.angVel, b.angVel, t),
+  };
+}
+
+function extrapolateBodyState(state: BodyState, dt: number): BodyState {
+  // Simple linear extrapolation with velocity decay
+  const decay = Math.max(0, 1 - dt * 2); // Decay over 0.5 seconds
+  return {
+    id: state.id,
+    position: {
+      x: state.position.x + state.linVel.x * dt * decay,
+      y: state.position.y + state.linVel.y * dt * decay,
+      z: state.position.z + state.linVel.z * dt * decay,
+    },
+    rotation: state.rotation, // Don't extrapolate rotation
+    linVel: {
+      x: state.linVel.x * decay,
+      y: state.linVel.y * decay,
+      z: state.linVel.z * decay,
+    },
+    angVel: {
+      x: state.angVel.x * decay,
+      y: state.angVel.y * decay,
+      z: state.angVel.z * decay,
+    },
+  };
+}
+
+function hermiteInterpolateVec3(
+  p0: Vec3, v0: Vec3,
+  p1: Vec3, v1: Vec3,
+  t: number
+): Vec3 {
+  // Hermite basis functions
+  const t2 = t * t;
+  const t3 = t2 * t;
+  const h00 = 2 * t3 - 3 * t2 + 1;
+  const h10 = t3 - 2 * t2 + t;
+  const h01 = -2 * t3 + 3 * t2;
+  const h11 = t3 - t2;
+
+  return {
+    x: h00 * p0.x + h10 * v0.x + h01 * p1.x + h11 * v1.x,
+    y: h00 * p0.y + h10 * v0.y + h01 * p1.y + h11 * v1.y,
+    z: h00 * p0.z + h10 * v0.z + h01 * p1.z + h11 * v1.z,
+  };
+}
+
+function lerpVec3(a: Vec3, b: Vec3, t: number): Vec3 {
+  return {
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    z: a.z + (b.z - a.z) * t,
+  };
+}
+
+function slerpQuat(a: Quat, b: Quat, t: number): Quat {
+  let dot = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+
+  // If dot is negative, negate one quaternion to take the shorter path
+  let bx = b.x, by = b.y, bz = b.z, bw = b.w;
+  if (dot < 0) {
+    dot = -dot;
+    bx = -bx; by = -by; bz = -bz; bw = -bw;
+  }
+
+  // If quaternions are very close, use linear interpolation
+  if (dot > 0.9995) {
+    return normalizeQuat({
+      x: a.x + (bx - a.x) * t,
+      y: a.y + (by - a.y) * t,
+      z: a.z + (bz - a.z) * t,
+      w: a.w + (bw - a.w) * t,
+    });
+  }
+
+  const theta0 = Math.acos(dot);
+  const theta = theta0 * t;
+  const sinTheta = Math.sin(theta);
+  const sinTheta0 = Math.sin(theta0);
+  const s0 = Math.cos(theta) - dot * sinTheta / sinTheta0;
+  const s1 = sinTheta / sinTheta0;
+
+  return {
+    x: s0 * a.x + s1 * bx,
+    y: s0 * a.y + s1 * by,
+    z: s0 * a.z + s1 * bz,
+    w: s0 * a.w + s1 * bw,
+  };
+}
+
+function normalizeQuat(q: Quat): Quat {
+  const len = Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
+  if (len === 0) return { x: 0, y: 0, z: 0, w: 1 };
+  return { x: q.x / len, y: q.y / len, z: q.z / len, w: q.w / len };
+}