@gamerstake/game-core 0.1.0 → 0.2.0

package/src/client/types.ts

@@ -0,0 +1,247 @@
+/**
+ * Client SDK Types
+ *
+ * Type definitions for the game-core client SDK.
+ */
+
+import type { Socket } from 'socket.io-client';
+
+/**
+ * Game client configuration
+ */
+export interface GameClientConfig {
+  /** Server URL to connect to */
+  serverUrl: string;
+
+  /** Enable client-side prediction */
+  enablePrediction?: boolean;
+
+  /** Enable server reconciliation */
+  enableReconciliation?: boolean;
+
+  /** Enable entity interpolation */
+  enableInterpolation?: boolean;
+
+  /** Interpolation delay in milliseconds */
+  interpolationDelay?: number;
+
+  /** Maximum interpolation delay in milliseconds */
+  maxInterpolationDelay?: number;
+
+  /** Minimum interpolation delay in milliseconds */
+  minInterpolationDelay?: number;
+
+  /** Number of reconnection attempts */
+  reconnectAttempts?: number;
+
+  /** Delay between reconnection attempts in milliseconds */
+  reconnectDelay?: number;
+
+  /** Heartbeat interval in milliseconds */
+  heartbeatInterval?: number;
+
+  /** Heartbeat timeout in milliseconds */
+  heartbeatTimeout?: number;
+
+  /** Socket.io connection options */
+  socketOptions?: Partial<{
+    autoConnect: boolean;
+    reconnection: boolean;
+    reconnectionAttempts: number;
+    reconnectionDelay: number;
+    transports: string[];
+  }>;
+}
+
+/**
+ * Command sent from client to server
+ */
+export interface Command {
+  /** Command type */
+  type: string;
+
+  /** Action sequence number */
+  seq?: number;
+
+  /** Timestamp when command was created */
+  timestamp?: number;
+
+  /** Additional command data */
+  [key: string]: unknown;
+}
+
+/**
+ * Move command
+ */
+export interface MoveCommand extends Command {
+  type: 'move';
+  targetX: number;
+  targetZ: number;
+  actionId?: number;
+}
+
+/**
+ * Stop command
+ */
+export interface StopCommand extends Command {
+  type: 'stop';
+}
+
+/**
+ * Network statistics
+ */
+export interface NetworkStats {
+  /** Round-trip time in milliseconds */
+  rtt: number;
+
+  /** Network jitter in milliseconds */
+  jitter: number;
+
+  /** Estimated packet loss percentage */
+  packetLoss: number;
+
+  /** Total messages sent */
+  messagesSent: number;
+
+  /** Total messages received */
+  messagesReceived: number;
+
+  /** Whether connected to server */
+  connected: boolean;
+
+  /** Whether currently reconnecting */
+  reconnecting: boolean;
+
+  /** Number of unacknowledged inputs */
+  inputBufferSize: number;
+
+  /** Last state update time */
+  lastStateUpdateTime: number;
+}
+
+/**
+ * Time sync statistics
+ */
+export interface TimeSyncStats {
+  /** Current clock offset */
+  offset: number;
+
+  /** Round-trip time */
+  rtt: number;
+
+  /** Network jitter */
+  jitter: number;
+
+  /** Number of samples */
+  samples: number;
+}
+
+/**
+ * Event callbacks
+ */
+export interface GameClientEvents {
+  /** Called when connected to server */
+  onConnected?: (data?: unknown) => void;
+
+  /** Called when disconnected from server */
+  onDisconnected?: (data: unknown) => void;
+
+  /** Called when connection is lost */
+  onConnectionLost?: (data: unknown) => void;
+
+  /** Called when reconnected after disconnect */
+  onReconnect?: (data?: unknown) => void;
+
+  /** Called on connection error */
+  onError?: (data: unknown) => void;
+
+  /** Called when state update received */
+  onStateUpdate?: (data: unknown) => void;
+
+  /** Called when move acknowledgment received */
+  onMoveAck?: (data: unknown) => void;
+
+  /** Custom event handlers */
+  [key: string]: ((data?: unknown) => void) | undefined;
+}
+
+/**
+ * Input buffer entry
+ */
+export interface BufferedInput {
+  /** Sequence number */
+  seq: number;
+
+  /** Command data */
+  command: Command;
+
+  /** Timestamp */
+  timestamp: number;
+
+  /** Whether acknowledged by server */
+  acknowledged: boolean;
+}
+
+/**
+ * State snapshot for interpolation
+ */
+export interface StateSnapshot {
+  /** Timestamp */
+  timestamp: number;
+
+  /** Server tick number */
+  tick?: number;
+
+  /** Entity states */
+  entities?: any[];
+
+  /** Custom state data */
+  [key: string]: unknown;
+}
+
+/**
+ * Transport interface (abstraction for future protocols)
+ */
+export interface Transport {
+  connect(): Promise<void>;
+  disconnect(): void;
+  send(event: string, data: unknown): void;
+  on(event: string, handler: (data: unknown) => void): void;
+  off(event: string, handler: (data: unknown) => void): void;
+  once(event: string, handler: (data: unknown) => void): void;
+}
+
+/**
+ * Socket.io transport implementation
+ */
+export class SocketIOTransport implements Transport {
+  constructor(private socket: Socket) {}
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket.once('connect', () => resolve());
+      this.socket.once('connect_error', (error) => reject(error));
+      this.socket.connect();
+    });
+  }
+
+  disconnect(): void {
+    this.socket.disconnect();
+  }
+
+  send(event: string, data: unknown): void {
+    this.socket.emit(event, data);
+  }
+
+  on(event: string, handler: (data: unknown) => void): void {
+    this.socket.on(event, handler);
+  }
+
+  off(event: string, handler: (data: unknown) => void): void {
+    this.socket.off(event, handler);
+  }
+
+  once(event: string, handler: (data: unknown) => void): void {
+    this.socket.once(event, handler);
+  }
+}

package/src/index.ts

@@ -37,6 +37,14 @@ export type {
 export { Network } from './network/Network.js';
 export { Snapshot } from './network/Snapshot.js';
 
+// Adapters
+export { SocketIOAdapter } from './adapters/SocketIOAdapter.js';
+export type {
+  SocketIOAdapterConfig,
+  AdapterContext,
+  RoomMetadata,
+} from './adapters/SocketIOAdapter.js';
+
 // Utils
 export { RingBuffer } from './utils/RingBuffer.js';
 export {

package/tests/client/InputBuffer.test.ts

@@ -0,0 +1,118 @@
+/**
+ * InputBuffer Tests
+ */
+
+import { InputBuffer } from '../../src/client/InputBuffer';
+
+describe('InputBuffer', () => {
+  let buffer: InputBuffer;
+
+  beforeEach(() => {
+    buffer = new InputBuffer(10); // Small buffer for testing
+  });
+
+  describe('addInput', () => {
+    it('should add input and return sequence number', () => {
+      const seq = buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      expect(seq).toBe(1);
+      expect(buffer.size()).toBe(1);
+    });
+
+    it('should increment sequence numbers', () => {
+      const seq1 = buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      const seq2 = buffer.addInput({
+        type: 'move',
+        targetX: 200,
+        targetZ: 100,
+      });
+      expect(seq2).toBe(seq1 + 1);
+    });
+
+    it('should prevent buffer overflow', () => {
+      // Add more than maxSize
+      for (let i = 0; i < 15; i++) {
+        buffer.addInput({ type: 'move', targetX: i, targetZ: i });
+      }
+
+      expect(buffer.size()).toBeLessThanOrEqual(10);
+    });
+  });
+
+  describe('acknowledge', () => {
+    it('should acknowledge input', () => {
+      const seq = buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      buffer.acknowledge(seq);
+
+      expect(buffer.getUnackedCount()).toBe(0);
+    });
+
+    it('should remove acknowledged inputs', () => {
+      buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      const seq2 = buffer.addInput({
+        type: 'move',
+        targetX: 200,
+        targetZ: 100,
+      });
+      buffer.addInput({ type: 'move', targetX: 300, targetZ: 150 });
+
+      buffer.acknowledge(seq2);
+
+      // Should remove seq1 and seq2
+      expect(buffer.getUnackedCount()).toBe(1);
+    });
+  });
+
+  describe('getUnacknowledgedInputs', () => {
+    it('should return unacknowledged inputs in order', () => {
+      buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      buffer.addInput({ type: 'move', targetX: 200, targetZ: 100 });
+      buffer.addInput({ type: 'move', targetX: 300, targetZ: 150 });
+
+      const unacked = buffer.getUnacknowledgedInputs();
+      expect(unacked.length).toBe(3);
+      expect(unacked[0].seq).toBe(1);
+      expect(unacked[1].seq).toBe(2);
+      expect(unacked[2].seq).toBe(3);
+    });
+
+    it('should not return acknowledged inputs', () => {
+      const seq1 = buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      buffer.addInput({ type: 'move', targetX: 200, targetZ: 100 });
+
+      buffer.acknowledge(seq1);
+
+      const unacked = buffer.getUnacknowledgedInputs();
+      expect(unacked.length).toBe(1);
+      expect(unacked[0].seq).toBe(2);
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all inputs', () => {
+      buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+      buffer.addInput({ type: 'move', targetX: 200, targetZ: 100 });
+
+      buffer.clear();
+
+      expect(buffer.size()).toBe(0);
+      expect(buffer.isEmpty()).toBe(true);
+    });
+  });
+
+  describe('removeOlderThan', () => {
+    it('should remove old inputs', () => {
+      const now = Date.now();
+
+      buffer.addInput({ type: 'move', targetX: 100, targetZ: 50 });
+
+      // Wait a bit
+      setTimeout(() => {
+        buffer.addInput({ type: 'move', targetX: 200, targetZ: 100 });
+
+        buffer.removeOlderThan(now + 50);
+
+        expect(buffer.size()).toBe(1);
+      }, 100);
+    });
+  });
+});

package/tests/client/TimeSync.test.ts

@@ -0,0 +1,116 @@
+/**
+ * TimeSync Tests
+ */
+
+import { TimeSync } from '../../src/client/TimeSync';
+
+describe('TimeSync', () => {
+  let mockSocket: { emit: jest.Mock; on: jest.Mock };
+  let timeSync: TimeSync;
+
+  beforeEach(() => {
+    mockSocket = {
+      emit: jest.fn(),
+      on: jest.fn(),
+    };
+    timeSync = new TimeSync(mockSocket as any);
+  });
+
+  describe('start/stop', () => {
+    it('should start sending pings', () => {
+      timeSync.start();
+      expect(mockSocket.emit).toHaveBeenCalledWith('timeSyncPing', {
+        clientTime: expect.any(Number),
+      });
+    });
+
+    it('should stop sending pings', (done) => {
+      timeSync.start();
+      const initialCount = mockSocket.emit.mock.calls.length;
+      timeSync.stop();
+
+      // Wait a bit and verify no more pings sent
+      setTimeout(() => {
+        const finalCount = mockSocket.emit.mock.calls.length;
+        expect(finalCount).toBe(initialCount);
+        done();
+      }, 100);
+    });
+  });
+
+  describe('handlePong', () => {
+    it('should calculate offset correctly', () => {
+      const now = Date.now();
+      timeSync.handlePong({
+        clientTime: now - 50,
+        serverTime: now + 100,
+      });
+
+      const offset = timeSync.getOffset();
+      expect(offset).toBeGreaterThan(0);
+    });
+
+    it('should calculate RTT correctly', () => {
+      const now = Date.now();
+      timeSync.handlePong({
+        clientTime: now - 100,
+        serverTime: now,
+      });
+
+      const rtt = timeSync.getRTT();
+      expect(rtt).toBeGreaterThanOrEqual(100);
+    });
+
+    it('should use median for offset (robust to outliers)', () => {
+      // Add multiple samples with one outlier
+      const baseTime = Date.now();
+
+      for (let i = 0; i < 5; i++) {
+        timeSync.handlePong({
+          clientTime: baseTime - 50,
+          serverTime: baseTime + 100, // ~125ms offset
+        });
+      }
+
+      // Add outlier
+      timeSync.handlePong({
+        clientTime: baseTime - 50,
+        serverTime: baseTime + 1000, // ~1000ms offset (outlier)
+      });
+
+      const offset = timeSync.getOffset();
+      // Should be close to 125, not affected by outlier
+      expect(offset).toBeLessThan(500);
+    });
+  });
+
+  describe('getServerTime', () => {
+    it('should return server time estimate', () => {
+      const now = Date.now();
+      timeSync.handlePong({
+        clientTime: now - 100,
+        serverTime: now + 50,
+      });
+
+      const serverTime = timeSync.getServerTime();
+      expect(serverTime).toBeGreaterThan(now);
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear all statistics', () => {
+      timeSync.handlePong({
+        clientTime: Date.now() - 100,
+        serverTime: Date.now(),
+      });
+
+      expect(timeSync.getRTT()).toBeGreaterThan(0);
+
+      timeSync.reset();
+
+      expect(timeSync.getRTT()).toBe(0);
+      expect(timeSync.getOffset()).toBe(0);
+      expect(timeSync.getJitter()).toBe(0);
+    });
+  });
+});

package/tsup.config.ts

@@ -1,7 +1,10 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: {
+    index: 'src/index.ts',
+    'client/index': 'src/client/index.ts',
+  },
   format: ['esm'],
   dts: true,
   sourcemap: true,