@gamerstake/game-core 0.1.0

package/src/core/GameServer.ts

@@ -0,0 +1,200 @@
+/**
+ * Game Server
+ *
+ * Multi-room game server.
+ * Manages room lifecycle and routing.
+ */
+
+import type { Server } from 'socket.io';
+import { Room } from './Room.js';
+import type { GameRules } from './GameRules.js';
+import type { Entity } from '../entities/Entity.js';
+import { logger } from '../utils/Logger.js';
+import type { RoomConfig, ServerMetrics } from '../types/index.js';
+
+/**
+ * Multi-room game server.
+ *
+ * Orchestrates multiple game rooms and provides routing
+ * for Socket.io connections.
+ *
+ * @example
+ * ```typescript
+ * const server = new GameServer();
+ * server.setServer(io);
+ *
+ * const room = server.createRoom('room-1', new MyGameRules());
+ *
+ * // Later...
+ * server.destroyRoom('room-1');
+ * ```
+ */
+export class GameServer {
+  private readonly rooms = new Map<string, Room>();
+  private io: Server | null = null;
+
+  /**
+   * Set the Socket.io server instance.
+   *
+   * This should be called before creating rooms to enable
+   * network functionality.
+   */
+  setServer(io: Server): void {
+    this.io = io;
+
+    // Set server on all existing rooms
+    for (const room of this.rooms.values()) {
+      room.getNetwork().setServer(io);
+    }
+
+    logger.info('Socket.io server set');
+  }
+
+  /**
+   * Create a new room.
+   *
+   * @param id - Unique room identifier
+   * @param rules - Game-specific logic
+   * @param config - Room configuration
+   * @returns The created room
+   * @throws If room with same ID already exists
+   */
+  createRoom<TEntity extends Entity = Entity>(
+    id: string,
+    rules: GameRules<TEntity>,
+    config?: RoomConfig,
+  ): Room<TEntity> {
+    if (this.rooms.has(id)) {
+      throw new Error(`Room ${id} already exists`);
+    }
+
+    const room = new Room(id, rules, config);
+
+    // Set network server if available
+    if (this.io) {
+      room.getNetwork().setServer(this.io);
+    }
+
+    this.rooms.set(id, room as Room);
+    room.start();
+
+    logger.info({ roomId: id }, 'Room created and started');
+
+    return room;
+  }
+
+  /**
+   * Destroy a room.
+   *
+   * Stops the room's tick loop and removes it from the server.
+   *
+   * @param id - Room identifier
+   * @returns True if room was destroyed, false if not found
+   */
+  destroyRoom(id: string): boolean {
+    const room = this.rooms.get(id);
+    if (!room) {
+      logger.warn({ roomId: id }, 'Cannot destroy - room not found');
+      return false;
+    }
+
+    room.stop();
+    this.rooms.delete(id);
+
+    logger.info({ roomId: id }, 'Room destroyed');
+
+    return true;
+  }
+
+  /**
+   * Get a room by ID.
+   */
+  getRoom(id: string): Room | undefined {
+    return this.rooms.get(id);
+  }
+
+  /**
+   * Get a room with specific entity type.
+   *
+   * @param id - Room identifier
+   * @returns Room cast to specific entity type, or undefined
+   */
+  getRoomAs<TEntity extends Entity>(id: string): Room<TEntity> | undefined {
+    return this.rooms.get(id) as Room<TEntity> | undefined;
+  }
+
+  /**
+   * Check if room exists.
+   */
+  hasRoom(id: string): boolean {
+    return this.rooms.has(id);
+  }
+
+  /**
+   * Get all rooms.
+   */
+  getRooms(): Map<string, Room> {
+    return this.rooms;
+  }
+
+  /**
+   * Get room count.
+   */
+  getRoomCount(): number {
+    return this.rooms.size;
+  }
+
+  /**
+   * Get total player count across all rooms.
+   */
+  getTotalPlayerCount(): number {
+    let total = 0;
+    for (const room of this.rooms.values()) {
+      total += room.getPlayers().size;
+    }
+    return total;
+  }
+
+  /**
+   * Get server health metrics.
+   */
+  getMetrics(): ServerMetrics {
+    return {
+      roomCount: this.rooms.size,
+      totalPlayers: this.getTotalPlayerCount(),
+      rooms: Array.from(this.rooms.values()).map((room) => ({
+        id: room.id,
+        playerCount: room.getPlayers().size,
+        entityCount: room.getRegistry().size(),
+        tickCount: room.getTickCount(),
+        isRunning: room.isRunning(),
+        avgTickTime: room.getMetrics().avgTickTime,
+        ticksPerSecond: room.getMetrics().ticksPerSecond,
+      })),
+    };
+  }
+
+  /**
+   * Stop all rooms.
+   */
+  stopAll(): void {
+    logger.info({ roomCount: this.rooms.size }, 'Stopping all rooms');
+
+    for (const room of this.rooms.values()) {
+      room.stop();
+    }
+  }
+
+  /**
+   * Destroy all rooms.
+   */
+  destroyAll(): void {
+    logger.info({ roomCount: this.rooms.size }, 'Destroying all rooms');
+
+    for (const room of this.rooms.values()) {
+      room.stop();
+    }
+
+    this.rooms.clear();
+  }
+}

package/src/core/Room.ts

@@ -0,0 +1,368 @@
+/**
+ * Room
+ *
+ * A single game room/match instance.
+ * Manages entities, tick loop, and networking.
+ */
+
+import { GameLoop, type TickHandler } from './GameLoop.js';
+import type { GameRules } from './GameRules.js';
+import { Entity } from '../entities/Entity.js';
+import { Registry } from '../entities/Registry.js';
+import { Grid } from '../spatial/Grid.js';
+import { InputQueue } from '../input/InputQueue.js';
+import { Network } from '../network/Network.js';
+import { Snapshot } from '../network/Snapshot.js';
+import { logger } from '../utils/Logger.js';
+import type {
+  RoomConfig,
+  NetworkEvent,
+  StateSnapshot,
+} from '../types/index.js';
+import type { Command } from '../input/Command.js';
+
+/**
+ * A single game room/match.
+ *
+ * Orchestrates all game systems: tick loop, entities, spatial partitioning,
+ * input processing, and network synchronization.
+ *
+ * @example
+ * ```typescript
+ * const room = new Room('room-1', new MyGameRules(), {
+ *   tickRate: 20,
+ *   cellSize: 512,
+ * });
+ *
+ * room.start();
+ *
+ * // Add players
+ * const player = new Entity('player-1', 100, 100);
+ * room.addPlayer(player);
+ * ```
+ */
+export class Room<TEntity extends Entity = Entity> implements TickHandler {
+  /** Room identifier */
+  readonly id: string;
+
+  /** Game-specific logic */
+  readonly rules: GameRules<TEntity>;
+
+  // Core systems
+  private readonly registry: Registry<TEntity>;
+  private readonly grid: Grid;
+  private readonly loop: GameLoop;
+  private readonly inputQueue: InputQueue;
+  private readonly network: Network;
+
+  // State
+  private readonly players = new Map<string, TEntity>();
+  private tickCount = 0;
+  private startTime = 0;
+  private readonly config: Required<RoomConfig>;
+
+  /**
+   * Create a new room.
+   *
+   * @param id - Unique room identifier
+   * @param rules - Game-specific logic
+   * @param config - Room configuration
+   */
+  constructor(id: string, rules: GameRules<TEntity>, config?: RoomConfig) {
+    this.id = id;
+    this.rules = rules;
+
+    // Apply defaults
+    this.config = {
+      tickRate: config?.tickRate ?? 20,
+      cellSize: config?.cellSize ?? 512,
+      maxInputQueueSize: config?.maxInputQueueSize ?? 100,
+      maxEntities: config?.maxEntities ?? 1000,
+      visibilityRange: config?.visibilityRange ?? 1,
+    };
+
+    // Initialize systems
+    this.registry = new Registry<TEntity>();
+    this.grid = new Grid(this.config.cellSize);
+    this.loop = new GameLoop(this.config.tickRate);
+    this.inputQueue = new InputQueue(this.config.maxInputQueueSize);
+    this.network = new Network();
+
+    // Register tick handler
+    this.loop.addHandler(this);
+
+    logger.info({ roomId: id, config: this.config }, 'Room created');
+  }
+
+  /**
+   * Start the room (begins tick loop).
+   */
+  start(): void {
+    this.startTime = Date.now();
+
+    try {
+      this.rules.onRoomCreated(this);
+    } catch (error) {
+      logger.error({ error, roomId: this.id }, 'Error in onRoomCreated');
+    }
+
+    this.loop.start();
+    logger.info({ roomId: this.id }, 'Room started');
+  }
+
+  /**
+   * Stop the room (ends tick loop).
+   */
+  stop(): void {
+    this.loop.stop();
+    logger.info(
+      { roomId: this.id, totalTicks: this.tickCount },
+      'Room stopped',
+    );
+  }
+
+  /**
+   * Add a player to the room.
+   */
+  addPlayer(player: TEntity): void {
+    if (this.players.has(player.id)) {
+      logger.warn({ playerId: player.id }, 'Player already in room');
+      return;
+    }
+
+    this.players.set(player.id, player);
+    this.registry.add(player);
+    this.grid.addEntity(player.id, player.x, player.y);
+
+    try {
+      this.rules.onPlayerJoin(this, player);
+    } catch (error) {
+      logger.error({ error, playerId: player.id }, 'Error in onPlayerJoin');
+    }
+
+    logger.info({ roomId: this.id, playerId: player.id }, 'Player joined');
+  }
+
+  /**
+   * Remove a player from the room.
+   */
+  removePlayer(playerId: string): void {
+    const player = this.players.get(playerId);
+    if (!player) return;
+
+    this.players.delete(playerId);
+    this.registry.remove(playerId);
+    this.grid.removeEntity(playerId);
+    this.inputQueue.remove(playerId);
+
+    try {
+      this.rules.onPlayerLeave(this, playerId);
+    } catch (error) {
+      logger.error({ error, playerId }, 'Error in onPlayerLeave');
+    }
+
+    logger.info({ roomId: this.id, playerId }, 'Player left');
+  }
+
+  /**
+   * Spawn a non-player entity.
+   */
+  spawnEntity(entity: TEntity): void {
+    if (this.registry.size() >= this.config.maxEntities) {
+      logger.warn({ roomId: this.id }, 'Max entities reached, cannot spawn');
+      return;
+    }
+
+    this.registry.add(entity);
+    this.grid.addEntity(entity.id, entity.x, entity.y);
+
+    logger.debug({ entityId: entity.id }, 'Entity spawned');
+  }
+
+  /**
+   * Destroy an entity.
+   */
+  destroyEntity(entityId: string): void {
+    const entity = this.registry.get(entityId);
+    if (!entity) return;
+
+    this.registry.remove(entityId);
+    this.grid.removeEntity(entityId);
+
+    logger.debug({ entityId }, 'Entity destroyed');
+  }
+
+  /**
+   * Queue a player input.
+   */
+  queueInput(playerId: string, command: Command): void {
+    if (!this.players.has(playerId)) {
+      logger.warn({ playerId }, 'Input from non-player');
+      return;
+    }
+
+    this.inputQueue.push(playerId, command);
+  }
+
+  /**
+   * Broadcast event to all players.
+   */
+  broadcast(event: NetworkEvent): void {
+    this.network.broadcastToRoom(this.id, event);
+  }
+
+  /**
+   * Send event to specific player.
+   */
+  sendTo(playerId: string, event: NetworkEvent): void {
+    this.network.sendTo(playerId, event);
+  }
+
+  /**
+   * Get full state snapshot.
+   */
+  getSnapshot(): StateSnapshot {
+    return Snapshot.create(this.tickCount, this.registry.getAll());
+  }
+
+  /**
+   * Get delta snapshot (only dirty entities).
+   */
+  getDeltaSnapshot(): StateSnapshot {
+    return Snapshot.createDelta(
+      this.tickCount,
+      this.registry.getDirtyEntities(),
+    );
+  }
+
+  /**
+   * Main tick function (called by GameLoop).
+   */
+  onTick(tickNumber: number, deltaMs: number): void {
+    this.tickCount = tickNumber;
+
+    // Process all queued inputs
+    for (const [playerId] of this.players) {
+      const inputs = this.inputQueue.drain(playerId);
+      for (const input of inputs) {
+        try {
+          this.rules.onCommand(this, playerId, input);
+        } catch (error) {
+          logger.error(
+            { error, playerId, command: input.type },
+            'Error in onCommand',
+          );
+        }
+      }
+    }
+
+    // Run game logic
+    try {
+      this.rules.onTick(this, deltaMs);
+    } catch (error) {
+      logger.error({ error, tick: tickNumber }, 'Error in onTick');
+    }
+
+    // Broadcast dirty entities
+    const dirtyEntities = this.registry.getDirtyEntities();
+    if (dirtyEntities.length > 0) {
+      const delta = Snapshot.createDelta(this.tickCount, dirtyEntities);
+      this.broadcast({
+        op: 'S_UPDATE',
+        ...delta,
+      });
+    }
+
+    // Check if room should end
+    try {
+      if (this.rules.shouldEndRoom(this)) {
+        logger.info({ roomId: this.id }, 'Room ending per game rules');
+        this.stop();
+      }
+    } catch (error) {
+      logger.error({ error }, 'Error in shouldEndRoom');
+    }
+  }
+
+  // Getters
+
+  /**
+   * Get all players.
+   */
+  getPlayers(): Map<string, TEntity> {
+    return this.players;
+  }
+
+  /**
+   * Get entity registry.
+   */
+  getRegistry(): Registry<TEntity> {
+    return this.registry;
+  }
+
+  /**
+   * Get spatial grid.
+   */
+  getGrid(): Grid {
+    return this.grid;
+  }
+
+  /**
+   * Get network layer.
+   */
+  getNetwork(): Network {
+    return this.network;
+  }
+
+  /**
+   * Get input queue.
+   */
+  getInputQueue(): InputQueue {
+    return this.inputQueue;
+  }
+
+  /**
+   * Get current tick number.
+   */
+  getTickCount(): number {
+    return this.tickCount;
+  }
+
+  /**
+   * Get uptime in milliseconds.
+   */
+  getUptime(): number {
+    return Date.now() - this.startTime;
+  }
+
+  /**
+   * Check if room is running.
+   */
+  isRunning(): boolean {
+    return this.loop.isRunning();
+  }
+
+  /**
+   * Get room configuration.
+   */
+  getConfig(): Required<RoomConfig> {
+    return { ...this.config };
+  }
+
+  /**
+   * Get room metrics.
+   */
+  getMetrics() {
+    const loopMetrics = this.loop.getMetrics();
+    return {
+      roomId: this.id,
+      tickCount: this.tickCount,
+      uptime: this.getUptime(),
+      playerCount: this.players.size,
+      entityCount: this.registry.size(),
+      cellCount: this.grid.getCellCount(),
+      queuedInputs: this.inputQueue.getTotalSize(),
+      ...loopMetrics,
+    };
+  }
+}

package/src/entities/Entity.ts

@@ -0,0 +1,118 @@
+/**
+ * Entity System
+ *
+ * Base entity class for all game objects.
+ */
+
+/**
+ * Base entity class.
+ * All game objects (players, NPCs, items) extend this.
+ *
+ * Includes position, velocity, and dirty flag for
+ * efficient network synchronization.
+ */
+export class Entity {
+  /** Unique entity identifier */
+  readonly id: string;
+
+  /** World X position */
+  x: number;
+
+  /** World Y position */
+  y: number;
+
+  /** Velocity X (units/second) */
+  vx: number;
+
+  /** Velocity Y (units/second) */
+  vy: number;
+
+  /** Dirty flag - entity needs to be broadcast */
+  dirty: boolean;
+
+  /** Last update timestamp */
+  lastUpdate: number;
+
+  /**
+   * Create a new entity.
+   *
+   * @param id - Unique identifier
+   * @param x - Initial X position
+   * @param y - Initial Y position
+   */
+  constructor(id: string, x: number, y: number) {
+    this.id = id;
+    this.x = x;
+    this.y = y;
+    this.vx = 0;
+    this.vy = 0;
+    this.dirty = true; // New entities need to be broadcast
+    this.lastUpdate = Date.now();
+  }
+
+  /**
+   * Update position based on velocity and delta time.
+   *
+   * @param deltaMs - Time since last update (milliseconds)
+   */
+  updatePosition(deltaMs: number): void {
+    if (this.vx !== 0 || this.vy !== 0) {
+      const deltaSec = deltaMs / 1000;
+      this.x += this.vx * deltaSec;
+      this.y += this.vy * deltaSec;
+      this.dirty = true;
+      this.lastUpdate = Date.now();
+    }
+  }
+
+  /**
+   * Set velocity.
+   */
+  setVelocity(vx: number, vy: number): void {
+    if (this.vx !== vx || this.vy !== vy) {
+      this.vx = vx;
+      this.vy = vy;
+      this.dirty = true;
+      this.lastUpdate = Date.now();
+    }
+  }
+
+  /**
+   * Teleport to position (no velocity integration).
+   */
+  setPosition(x: number, y: number): void {
+    if (this.x !== x || this.y !== y) {
+      this.x = x;
+      this.y = y;
+      this.dirty = true;
+      this.lastUpdate = Date.now();
+    }
+  }
+
+  /**
+   * Mark entity as clean (after broadcast).
+   */
+  markClean(): void {
+    this.dirty = false;
+  }
+
+  /**
+   * Mark entity as dirty (needs broadcast).
+   */
+  markDirty(): void {
+    this.dirty = true;
+  }
+
+  /**
+   * Get entity as plain object for serialization.
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      id: this.id,
+      x: this.x,
+      y: this.y,
+      vx: this.vx,
+      vy: this.vy,
+    };
+  }
+}