@gamerstake/game-core 0.1.0

package/examples/simple-game/server.ts

@@ -0,0 +1,233 @@
+/**
+ * Manual Testing Server
+ *
+ * A simple multiplayer game server for manual testing of game-core.
+ * Players can move around a 2D world and see each other.
+ */
+
+import { Server } from 'socket.io';
+import {
+  GameServer,
+  Room,
+  Entity,
+  GameRules,
+  Command,
+  MoveCommand,
+  ActionCommand,
+  logger,
+} from '../../dist/index.js';
+
+// ============================================================================
+// Simple Game Rules
+// ============================================================================
+
+class SimpleGameRules implements GameRules {
+  onRoomCreated(room: Room): void {
+    logger.info('Room created! Waiting for players...');
+
+    // Spawn some static objects (obstacles)
+    for (let i = 0; i < 5; i++) {
+      const obstacle = new Entity(`obstacle-${i}`,
+        Math.random() * 800 + 100,
+        Math.random() * 800 + 100
+      );
+      room.spawnEntity(obstacle);
+    }
+  }
+
+  onPlayerJoin(room: Room, player: Entity): void {
+    // Spawn player at random position
+    const x = Math.random() * 800 + 100;
+    const y = Math.random() * 800 + 100;
+    player.setPosition(x, y);
+
+    logger.info(`Player ${player.id} joined at (${x.toFixed(0)}, ${y.toFixed(0)})`);
+
+    // Broadcast to other players
+    room.broadcast({
+      op: 'PLAYER_JOINED',
+      playerId: player.id,
+      x: player.x,
+      y: player.y,
+    });
+  }
+
+  onPlayerLeave(room: Room, playerId: string): void {
+    logger.info(`Player ${playerId} left`);
+
+    room.broadcast({
+      op: 'PLAYER_LEFT',
+      playerId,
+    });
+  }
+
+  onTick(room: Room, delta: number): void {
+    // Update all entities with velocity
+    room.getRegistry().forEach((entity) => {
+      if (entity.vx !== 0 || entity.vy !== 0) {
+        entity.updatePosition(delta);
+
+        // Keep entities in bounds (0-1000)
+        if (entity.x < 0) entity.setPosition(0, entity.y);
+        if (entity.x > 1000) entity.setPosition(1000, entity.y);
+        if (entity.y < 0) entity.setPosition(entity.x, 0);
+        if (entity.y > 1000) entity.setPosition(entity.x, 1000);
+      }
+    });
+  }
+
+  onCommand(room: Room, playerId: string, command: Command): void {
+    const player = room.getRegistry().get(playerId);
+    if (!player) return;
+
+    if (command.type === 'move') {
+      const moveCmd = command as MoveCommand;
+      const speed = 200; // units per second
+
+      // Normalize direction
+      const len = Math.sqrt(moveCmd.dir.x ** 2 + moveCmd.dir.y ** 2);
+      if (len > 0) {
+        const nx = moveCmd.dir.x / len;
+        const ny = moveCmd.dir.y / len;
+        player.setVelocity(nx * speed, ny * speed);
+      }
+
+      logger.debug(`Player ${playerId} moving: (${moveCmd.dir.x}, ${moveCmd.dir.y})`);
+    }
+    else if (command.type === 'stop') {
+      player.setVelocity(0, 0);
+      logger.debug(`Player ${playerId} stopped`);
+    }
+    else if (command.type === 'action') {
+      logger.info(`Player ${playerId} performed action: ${JSON.stringify(command)}`);
+
+      // Example: broadcast action to nearby players
+      room.broadcast({
+        op: 'PLAYER_ACTION',
+        playerId,
+        action: (command as any).action,
+      });
+    }
+  }
+
+  shouldEndRoom(room: Room): boolean {
+    // Persistent world - never end
+    return false;
+  }
+}
+
+// ============================================================================
+// Server Setup
+// ============================================================================
+
+const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000;
+
+// Create Socket.io server
+const io = new Server(PORT, {
+  cors: {
+    origin: '*', // For manual testing only!
+  },
+});
+
+// Create game server
+const gameServer = new GameServer();
+gameServer.setServer(io);
+
+// Create a test room
+const room = gameServer.createRoom('test-room', new SimpleGameRules(), {
+  tickRate: 20, // 20 TPS
+  cellSize: 512,
+  maxEntities: 100,
+});
+
+logger.info(`Game server started on port ${PORT}`);
+logger.info(`Room: ${room.id}`);
+logger.info(`Tick rate: 20 TPS`);
+logger.info('');
+logger.info('Connect with: node examples/simple-game/client.js');
+logger.info('');
+
+// ============================================================================
+// Socket.io Connection Handling
+// ============================================================================
+
+io.on('connection', (socket) => {
+  const playerId = socket.id;
+  logger.info(`Socket connected: ${playerId}`);
+
+  // Create player entity
+  const player = new Entity(playerId, 0, 0);
+  room.addPlayer(player);
+
+  // Register socket for networking
+  room.getNetwork().registerSocket(playerId, socket);
+
+  // Send initial state to the new player
+  const snapshot = room.getSnapshot();
+  socket.emit('S_INIT', {
+    op: 'S_INIT',
+    playerId,
+    entities: snapshot.entities,
+    timestamp: Date.now(),
+  });
+
+  // Handle player inputs
+  socket.on('C_MOVE', (data) => {
+    room.queueInput(playerId, {
+      seq: data.seq,
+      type: 'move',
+      dir: data.dir,
+      timestamp: Date.now(),
+    } as MoveCommand);
+  });
+
+  socket.on('C_STOP', (data) => {
+    room.queueInput(playerId, {
+      seq: data.seq,
+      type: 'stop',
+      timestamp: Date.now(),
+    });
+  });
+
+  socket.on('C_ACTION', (data) => {
+    room.queueInput(playerId, {
+      seq: data.seq,
+      type: 'action',
+      action: data.action,
+      data: data.data,
+      timestamp: Date.now(),
+    } as ActionCommand);
+  });
+
+  socket.on('disconnect', () => {
+    logger.info(`Socket disconnected: ${playerId}`);
+    room.removePlayer(playerId);
+    room.getNetwork().unregisterSocket(playerId);
+  });
+});
+
+// ============================================================================
+// Metrics Logging
+// ============================================================================
+
+setInterval(() => {
+  const metrics = gameServer.getMetrics();
+  const roomMetrics = metrics.rooms[0];
+
+  if (roomMetrics) {
+    logger.info(`Room: ${roomMetrics.playerCount} players, ${roomMetrics.entityCount} entities, ` +
+               `Avg tick: ${roomMetrics.avgTickTime?.toFixed(2) ?? 'N/A'}ms`);
+  }
+}, 10000); // Log every 10 seconds
+
+// ============================================================================
+// Graceful Shutdown
+// ============================================================================
+
+process.on('SIGINT', () => {
+  logger.info('');
+  logger.info('Shutting down...');
+  gameServer.destroyRoom(room.id);
+  io.close();
+  process.exit(0);
+});

package/jest.config.ts

@@ -0,0 +1,39 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  displayName: 'game-core',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/tsconfig.json',
+        useESM: true,
+      },
+    ],
+  },
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  testMatch: ['<rootDir>/tests/**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/index.ts',
+    '!src/types/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+};
+
+export default config;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@gamerstake/game-core",
+  "version": "0.1.0",
+  "description": "Reusable multiplayer game engine for GamerStake platform",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "multiplayer",
+    "game-engine",
+    "websocket",
+    "real-time",
+    "networking"
+  ],
+  "author": "GamerStake",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "socket.io": "^4.7.4",
+    "pino": "^9.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3",
+    "tsup": "^8.0.0",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.12",
+    "ts-jest": "^29.1.2",
+    "socket.io-client": "^4.7.4",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/core/GameLoop.ts

@@ -0,0 +1,214 @@
+/**
+ * Game Loop
+ *
+ * Fixed tick rate server loop with drift compensation.
+ * Processes inputs, updates state, broadcasts changes.
+ */
+
+import { logger } from '../utils/Logger.js';
+import type { LoopMetrics } from '../types/index.js';
+
+/**
+ * Tick handler interface.
+ * Implement this to receive tick callbacks.
+ */
+export interface TickHandler {
+  onTick(tickNumber: number, deltaMs: number): void;
+}
+
+/**
+ * High-precision game loop using setTimeout with drift compensation.
+ */
+export class GameLoop {
+  private readonly tickRate: number;
+  private readonly tickMs: number;
+  private tickNumber = 0;
+  private lastTickTime = 0;
+  private running = false;
+  private timeout: NodeJS.Timeout | null = null;
+  private readonly handlers: TickHandler[] = [];
+
+  // Performance metrics
+  private tickTimes: number[] = [];
+  private readonly metricsWindowSize = 100;
+
+  /**
+   * Create a new game loop.
+   *
+   * @param tickRate - Ticks per second (default: 20)
+   */
+  constructor(tickRate = 20) {
+    this.tickRate = tickRate;
+    this.tickMs = 1000 / tickRate;
+  }
+
+  /**
+   * Register a tick handler.
+   */
+  addHandler(handler: TickHandler): void {
+    this.handlers.push(handler);
+  }
+
+  /**
+   * Remove a tick handler.
+   */
+  removeHandler(handler: TickHandler): void {
+    const index = this.handlers.indexOf(handler);
+    if (index !== -1) {
+      this.handlers.splice(index, 1);
+    }
+  }
+
+  /**
+   * Start the game loop.
+   */
+  start(): void {
+    if (this.running) {
+      logger.warn('Game loop already running');
+      return;
+    }
+
+    this.running = true;
+    this.lastTickTime = performance.now();
+    this.tickNumber = 0;
+
+    logger.info(
+      { tickRate: this.tickRate, tickMs: this.tickMs },
+      'Game loop started',
+    );
+
+    this.scheduleNextTick();
+  }
+
+  /**
+   * Stop the game loop.
+   */
+  stop(): void {
+    this.running = false;
+
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+      this.timeout = null;
+    }
+
+    logger.info({ totalTicks: this.tickNumber }, 'Game loop stopped');
+  }
+
+  /**
+   * Check if loop is running.
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Get current tick number.
+   */
+  getCurrentTick(): number {
+    return this.tickNumber;
+  }
+
+  /**
+   * Get tick rate (TPS).
+   */
+  getTickRate(): number {
+    return this.tickRate;
+  }
+
+  /**
+   * Get tick duration (ms).
+   */
+  getTickMs(): number {
+    return this.tickMs;
+  }
+
+  /**
+   * Get performance metrics.
+   */
+  getMetrics(): LoopMetrics {
+    if (this.tickTimes.length === 0) {
+      return {
+        avgTickTime: 0,
+        maxTickTime: 0,
+        minTickTime: 0,
+        ticksPerSecond: 0,
+      };
+    }
+
+    const sum = this.tickTimes.reduce((a, b) => a + b, 0);
+    const avg = sum / this.tickTimes.length;
+
+    return {
+      avgTickTime: avg,
+      maxTickTime: Math.max(...this.tickTimes),
+      minTickTime: Math.min(...this.tickTimes),
+      ticksPerSecond: 1000 / avg,
+    };
+  }
+
+  /**
+   * Schedule the next tick with drift compensation.
+   */
+  private scheduleNextTick(): void {
+    if (!this.running) return;
+
+    const now = performance.now();
+    const elapsed = now - this.lastTickTime;
+    const drift = elapsed - this.tickMs;
+
+    // Compensate for drift (but never go negative)
+    const nextDelay = Math.max(0, this.tickMs - drift);
+
+    this.timeout = setTimeout(() => this.tick(), nextDelay);
+  }
+
+  /**
+   * Execute one tick.
+   */
+  private tick(): void {
+    const tickStart = performance.now();
+    const deltaMs = tickStart - this.lastTickTime;
+    this.lastTickTime = tickStart;
+    this.tickNumber++;
+
+    try {
+      // Call all handlers
+      for (const handler of this.handlers) {
+        handler.onTick(this.tickNumber, deltaMs);
+      }
+    } catch (error) {
+      logger.error({ error, tick: this.tickNumber }, 'Error in tick handler');
+    }
+
+    // Record tick processing time
+    const tickDuration = performance.now() - tickStart;
+    this.recordTickTime(tickDuration);
+
+    // Warn if tick took too long (>80% of budget)
+    if (tickDuration > this.tickMs * 0.8) {
+      logger.warn(
+        {
+          tickNumber: this.tickNumber,
+          duration: tickDuration,
+          budget: this.tickMs,
+        },
+        'Tick took too long',
+      );
+    }
+
+    // Schedule next tick
+    this.scheduleNextTick();
+  }
+
+  /**
+   * Record tick time for metrics.
+   */
+  private recordTickTime(duration: number): void {
+    this.tickTimes.push(duration);
+
+    // Keep only last N samples
+    if (this.tickTimes.length > this.metricsWindowSize) {
+      this.tickTimes.shift();
+    }
+  }
+}

package/src/core/GameRules.ts

@@ -0,0 +1,103 @@
+/**
+ * Game Rules Interface
+ *
+ * Pluggable game logic interface.
+ * Implement this to create custom multiplayer games.
+ */
+
+import type { Room } from './Room.js';
+import type { Entity } from '../entities/Entity.js';
+import type { Command } from '../input/Command.js';
+
+/**
+ * Game-specific logic interface.
+ *
+ * This is the core abstraction that makes game-core reusable.
+ * All game-specific logic is implemented through this interface,
+ * keeping the engine generic.
+ *
+ * @example
+ * ```typescript
+ * class MyGameRules implements GameRules {
+ *   onRoomCreated(room: Room): void {
+ *     // Spawn initial entities
+ *   }
+ *
+ *   onPlayerJoin(room: Room, player: Entity): void {
+ *     // Setup player
+ *   }
+ *
+ *   onTick(room: Room, delta: number): void {
+ *     // Update game state
+ *   }
+ *
+ *   onCommand(room: Room, playerId: string, command: Command): void {
+ *     // Handle player input
+ *   }
+ *
+ *   onPlayerLeave(room: Room, playerId: string): void {
+ *     // Cleanup player
+ *   }
+ *
+ *   shouldEndRoom(room: Room): boolean {
+ *     // For match-based games, return true when match ends
+ *     // For persistent worlds, return false
+ *     return false;
+ *   }
+ * }
+ * ```
+ */
+export interface GameRules<TEntity extends Entity = Entity> {
+  /**
+   * Called once when room is created.
+   * Use for initialization (spawn items, set boundaries, etc).
+   *
+   * @param room - The newly created room
+   */
+  onRoomCreated(room: Room<TEntity>): void;
+
+  /**
+   * Called when a player joins the room.
+   *
+   * @param room - The room
+   * @param player - The entity representing the player
+   */
+  onPlayerJoin(room: Room<TEntity>, player: TEntity): void;
+
+  /**
+   * Called when a player leaves the room.
+   *
+   * @param room - The room
+   * @param playerId - The ID of the leaving player
+   */
+  onPlayerLeave(room: Room<TEntity>, playerId: string): void;
+
+  /**
+   * Called every tick (20 TPS by default).
+   * Process inputs, update game state, check win conditions.
+   *
+   * @param room - The room
+   * @param delta - Time since last tick (milliseconds)
+   */
+  onTick(room: Room<TEntity>, delta: number): void;
+
+  /**
+   * Called when a player sends a command.
+   *
+   * @param room - The room
+   * @param playerId - The player who sent the command
+   * @param command - The input command from the player
+   */
+  onCommand(room: Room<TEntity>, playerId: string, command: Command): void;
+
+  /**
+   * Check if the room should be destroyed.
+   *
+   * For match-based games, return true when match ends.
+   * For persistent worlds, return false.
+   *
+   * @param room - The room
+   * @returns True if room should end
+   */
+  shouldEndRoom(room: Room<TEntity>): boolean;
+}