@gamerstake/game-core 0.1.0

package/src/entities/Registry.ts

@@ -0,0 +1,161 @@
+/**
+ * Entity Registry
+ *
+ * Manages entity lifecycle and provides efficient queries.
+ */
+
+import { Entity } from './Entity.js';
+import { logger } from '../utils/Logger.js';
+
+/**
+ * Entity registry with lifecycle management.
+ *
+ * Provides zero-allocation queries using pre-allocated buffers
+ * to minimize GC pressure in hot paths.
+ */
+export class Registry<TEntity extends Entity = Entity> {
+  private readonly entities = new Map<string, TEntity>();
+  private readonly dirtyEntities = new Set<string>();
+
+  // Pre-allocated buffers to avoid allocations in hot paths
+  private readonly dirtyBuffer: TEntity[] = [];
+  private readonly allBuffer: TEntity[] = [];
+
+  /**
+   * Add an entity to the registry.
+   */
+  add(entity: TEntity): void {
+    if (this.entities.has(entity.id)) {
+      logger.warn({ entityId: entity.id }, 'Entity already exists in registry');
+      return;
+    }
+
+    this.entities.set(entity.id, entity);
+    this.dirtyEntities.add(entity.id);
+
+    logger.debug({ entityId: entity.id }, 'Entity added to registry');
+  }
+
+  /**
+   * Remove an entity from the registry.
+   */
+  remove(entityId: string): boolean {
+    const entity = this.entities.get(entityId);
+    if (!entity) return false;
+
+    this.entities.delete(entityId);
+    this.dirtyEntities.delete(entityId);
+
+    logger.debug({ entityId }, 'Entity removed from registry');
+
+    return true;
+  }
+
+  /**
+   * Get an entity by ID.
+   */
+  get(entityId: string): TEntity | undefined {
+    return this.entities.get(entityId);
+  }
+
+  /**
+   * Check if entity exists.
+   */
+  has(entityId: string): boolean {
+    return this.entities.has(entityId);
+  }
+
+  /**
+   * Mark an entity as dirty (needs broadcast).
+   */
+  markDirty(entityId: string): void {
+    if (this.entities.has(entityId)) {
+      this.dirtyEntities.add(entityId);
+    }
+  }
+
+  /**
+   * Get all dirty entities and clear dirty flags.
+   * OPTIMIZED: Reuses buffer array to avoid allocations.
+   *
+   * @returns Array of dirty entities (reused buffer - don't store reference!)
+   */
+  getDirtyEntities(): TEntity[] {
+    // Reset buffer without reallocation
+    this.dirtyBuffer.length = 0;
+
+    for (const entityId of this.dirtyEntities) {
+      const entity = this.entities.get(entityId);
+      if (entity) {
+        this.dirtyBuffer.push(entity);
+        entity.markClean();
+      }
+    }
+
+    this.dirtyEntities.clear();
+
+    return this.dirtyBuffer;
+  }
+
+  /**
+   * Get all entities.
+   * OPTIMIZED: Reuses buffer array to avoid allocations.
+   *
+   * @returns Array of all entities (reused buffer - don't store reference!)
+   */
+  getAll(): TEntity[] {
+    this.allBuffer.length = 0;
+    for (const entity of this.entities.values()) {
+      this.allBuffer.push(entity);
+    }
+    return this.allBuffer;
+  }
+
+  /**
+   * Get entity count.
+   */
+  size(): number {
+    return this.entities.size;
+  }
+
+  /**
+   * Get dirty entity count.
+   */
+  dirtyCount(): number {
+    return this.dirtyEntities.size;
+  }
+
+  /**
+   * Clear all entities.
+   */
+  clear(): void {
+    this.entities.clear();
+    this.dirtyEntities.clear();
+    logger.debug('Registry cleared');
+  }
+
+  /**
+   * Execute callback for each entity.
+   */
+  forEach(callback: (entity: TEntity) => void): void {
+    for (const entity of this.entities.values()) {
+      callback(entity);
+    }
+  }
+
+  /**
+   * Filter entities by predicate.
+   *
+   * @param predicate - Filter function
+   * @returns New array of matching entities
+   */
+  filter(predicate: (entity: TEntity) => boolean): TEntity[] {
+    const result: TEntity[] = [];
+    for (const entity of this.entities.values()) {
+      if (predicate(entity)) {
+        result.push(entity);
+      }
+    }
+    return result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @gamerstake/game-core
+ *
+ * Reusable multiplayer game engine for GamerStake platform.
+ *
+ * @packageDocumentation
+ */
+
+// Core
+export { GameServer } from './core/GameServer.js';
+export { Room } from './core/Room.js';
+export { GameLoop } from './core/GameLoop.js';
+export type { GameRules } from './core/GameRules.js';
+export type { TickHandler } from './core/GameLoop.js';
+
+// Entities
+export { Entity } from './entities/Entity.js';
+export { Registry } from './entities/Registry.js';
+
+// Spatial
+export { Grid } from './spatial/Grid.js';
+
+// Physics
+export { AABBCollision, type AABB } from './physics/AABB.js';
+export { Movement, type Boundary } from './physics/Movement.js';
+
+// Input
+export { InputQueue } from './input/InputQueue.js';
+export type {
+  Command,
+  MoveCommand,
+  StopCommand,
+  ActionCommand,
+} from './input/Command.js';
+
+// Network
+export { Network } from './network/Network.js';
+export { Snapshot } from './network/Snapshot.js';
+
+// Utils
+export { RingBuffer } from './utils/RingBuffer.js';
+export {
+  Logger,
+  logger,
+  setLogger,
+  createChildLogger,
+} from './utils/Logger.js';
+
+// Types
+export * from './types/index.js';
+export * from './types/protocol.js';

package/src/input/Command.ts

@@ -0,0 +1,41 @@
+/**
+ * Command types for player input.
+ */
+
+/**
+ * Base command interface.
+ */
+export interface Command {
+  /** Client sequence number for reconciliation */
+  readonly seq: number;
+
+  /** Command type */
+  readonly type: string;
+
+  /** Timestamp when command was created */
+  readonly timestamp: number;
+}
+
+/**
+ * Movement command.
+ */
+export interface MoveCommand extends Command {
+  type: 'move';
+  dir: { x: number; y: number };
+}
+
+/**
+ * Stop command.
+ */
+export interface StopCommand extends Command {
+  type: 'stop';
+}
+
+/**
+ * Generic action command.
+ */
+export interface ActionCommand extends Command {
+  type: 'action';
+  action: string;
+  data?: Record<string, unknown>;
+}

package/src/input/InputQueue.ts

@@ -0,0 +1,130 @@
+/**
+ * Input Queue
+ *
+ * Buffers player inputs for processing in the game loop.
+ * Uses RingBuffer for O(1) push/pop operations.
+ */
+
+import { logger } from '../utils/Logger.js';
+import { RingBuffer } from '../utils/RingBuffer.js';
+import type { Command } from './Command.js';
+
+/**
+ * Input queue manager using RingBuffer for O(1) operations.
+ *
+ * Manages input queues for multiple players, with automatic
+ * overflow handling (drops oldest inputs when full).
+ */
+export class InputQueue {
+  private readonly queues = new Map<string, RingBuffer<Command>>();
+  private readonly maxQueueSize: number;
+
+  /**
+   * Create a new input queue manager.
+   *
+   * @param maxQueueSize - Maximum inputs per player (default: 100)
+   */
+  constructor(maxQueueSize = 100) {
+    this.maxQueueSize = maxQueueSize;
+  }
+
+  /**
+   * Get or create a player's queue.
+   */
+  private getQueue(playerId: string): RingBuffer<Command> {
+    let queue = this.queues.get(playerId);
+    if (!queue) {
+      queue = new RingBuffer<Command>(this.maxQueueSize);
+      this.queues.set(playerId, queue);
+    }
+    return queue;
+  }
+
+  /**
+   * Add an input to a player's queue. O(1)
+   */
+  push(playerId: string, input: Command): void {
+    const queue = this.getQueue(playerId);
+
+    // Push with overwrite (drops oldest if full)
+    const dropped = queue.pushOverwrite(input);
+    if (dropped) {
+      logger.debug({ playerId }, 'Input queue overflow, dropped oldest');
+    }
+  }
+
+  /**
+   * Get and remove the next input for a player. O(1)
+   */
+  pop(playerId: string): Command | undefined {
+    const queue = this.queues.get(playerId);
+    if (!queue) return undefined;
+    return queue.shift();
+  }
+
+  /**
+   * Peek at the next input without removing. O(1)
+   */
+  peek(playerId: string): Command | undefined {
+    const queue = this.queues.get(playerId);
+    return queue?.peek();
+  }
+
+  /**
+   * Get all inputs for a player and clear.
+   */
+  drain(playerId: string): Command[] {
+    const queue = this.queues.get(playerId);
+    if (!queue) return [];
+
+    const inputs: Command[] = [];
+    while (!queue.isEmpty()) {
+      const input = queue.shift();
+      if (input) inputs.push(input);
+    }
+    return inputs;
+  }
+
+  /**
+   * Get queue size for a player.
+   */
+  size(playerId: string): number {
+    return this.queues.get(playerId)?.size() ?? 0;
+  }
+
+  /**
+   * Clear a player's queue.
+   */
+  clear(playerId: string): void {
+    const queue = this.queues.get(playerId);
+    if (queue) {
+      queue.clear();
+    }
+    // Don't delete the queue itself - reuse it
+  }
+
+  /**
+   * Remove a player's queue entirely.
+   */
+  remove(playerId: string): void {
+    this.queues.delete(playerId);
+  }
+
+  /**
+   * Clear all queues.
+   */
+  clearAll(): void {
+    this.queues.clear();
+  }
+
+  /**
+   * Get total queued inputs across all players.
+   */
+  getTotalSize(): number {
+    let total = 0;
+    for (const queue of this.queues.values()) {
+      total += queue.size();
+    }
+    return total;
+  }
+}

package/src/network/Network.ts

@@ -0,0 +1,112 @@
+/**
+ * Network Layer
+ *
+ * Broadcast and send utilities for game events.
+ */
+
+import type { Server, Socket } from 'socket.io';
+import { logger } from '../utils/Logger.js';
+import type { NetworkEvent } from '../types/index.js';
+
+/**
+ * Network layer for broadcasting game events.
+ *
+ * Wraps Socket.io with game-specific utilities.
+ */
+export class Network {
+  private io: Server | null = null;
+  private readonly sockets = new Map<string, Socket>();
+
+  /**
+   * Set the Socket.io server instance.
+   */
+  setServer(io: Server): void {
+    this.io = io;
+  }
+
+  /**
+   * Register a socket connection.
+   */
+  registerSocket(playerId: string, socket: Socket): void {
+    this.sockets.set(playerId, socket);
+    logger.debug({ playerId }, 'Socket registered');
+  }
+
+  /**
+   * Unregister a socket connection.
+   */
+  unregisterSocket(playerId: string): void {
+    this.sockets.delete(playerId);
+    logger.debug({ playerId }, 'Socket unregistered');
+  }
+
+  /**
+   * Get a socket by player ID.
+   */
+  getSocket(playerId: string): Socket | undefined {
+    return this.sockets.get(playerId);
+  }
+
+  /**
+   * Broadcast event to all connected players.
+   */
+  broadcast(event: NetworkEvent): void {
+    if (!this.io) {
+      logger.warn('Cannot broadcast - no Socket.io server set');
+      return;
+    }
+
+    this.io.emit(event.op, event);
+    logger.debug({ opcode: event.op }, 'Broadcast event');
+  }
+
+  /**
+   * Broadcast event to all players in a room.
+   */
+  broadcastToRoom(roomId: string, event: NetworkEvent): void {
+    if (!this.io) {
+      logger.warn('Cannot broadcast - no Socket.io server set');
+      return;
+    }
+
+    this.io.to(roomId).emit(event.op, event);
+    logger.debug({ roomId, opcode: event.op }, 'Broadcast to room');
+  }
+
+  /**
+   * Send event to a specific player.
+   */
+  sendTo(playerId: string, event: NetworkEvent): void {
+    const socket = this.sockets.get(playerId);
+    if (!socket) {
+      logger.warn({ playerId }, 'Cannot send - socket not found');
+      return;
+    }
+
+    socket.emit(event.op, event);
+    logger.debug({ playerId, opcode: event.op }, 'Sent to player');
+  }
+
+  /**
+   * Send event to multiple players.
+   */
+  sendToMany(playerIds: string[], event: NetworkEvent): void {
+    for (const playerId of playerIds) {
+      this.sendTo(playerId, event);
+    }
+  }
+
+  /**
+   * Get connected player count.
+   */
+  getPlayerCount(): number {
+    return this.sockets.size;
+  }
+
+  /**
+   * Clear all sockets.
+   */
+  clear(): void {
+    this.sockets.clear();
+  }
+}

package/src/network/Snapshot.ts

@@ -0,0 +1,59 @@
+/**
+ * Snapshot System
+ *
+ * Full state snapshots for network synchronization.
+ */
+
+import type { Entity } from '../entities/Entity.js';
+import type { StateSnapshot, EntitySnapshot } from '../types/index.js';
+
+/**
+ * Snapshot generator.
+ *
+ * Creates full state snapshots for sending to clients.
+ * Used for initial sync and periodic full updates.
+ */
+export class Snapshot {
+  /**
+   * Create a full state snapshot from entities.
+   *
+   * @param tick - Current tick number
+   * @param entities - Array of entities to snapshot
+   * @returns Full state snapshot
+   */
+  static create(tick: number, entities: Entity[]): StateSnapshot {
+    return {
+      tick,
+      timestamp: Date.now(),
+      entities: entities.map((e) => this.entityToSnapshot(e)),
+    };
+  }
+
+  /**
+   * Convert an entity to a snapshot.
+   */
+  static entityToSnapshot(entity: Entity): EntitySnapshot {
+    return {
+      id: entity.id,
+      x: entity.x,
+      y: entity.y,
+      vx: entity.vx,
+      vy: entity.vy,
+    };
+  }
+
+  /**
+   * Create a delta snapshot (only dirty entities).
+   *
+   * @param tick - Current tick number
+   * @param dirtyEntities - Array of dirty entities
+   * @returns Delta snapshot
+   */
+  static createDelta(tick: number, dirtyEntities: Entity[]): StateSnapshot {
+    return {
+      tick,
+      timestamp: Date.now(),
+      entities: dirtyEntities.map((e) => this.entityToSnapshot(e)),
+    };
+  }
+}

package/src/physics/AABB.ts

@@ -0,0 +1,104 @@
+/**
+ * AABB Collision Detection
+ *
+ * Axis-Aligned Bounding Box collision detection.
+ */
+
+import type { Entity } from '../entities/Entity.js';
+
+/**
+ * Axis-Aligned Bounding Box.
+ */
+export interface AABB {
+  x: number; // Center X
+  y: number; // Center Y
+  width: number; // Total width
+  height: number; // Total height
+}
+
+/**
+ * AABB collision detection utilities.
+ */
+export class AABBCollision {
+  /**
+   * Check if two AABBs overlap.
+   */
+  static overlaps(a: AABB, b: AABB): boolean {
+    const aHalfW = a.width / 2;
+    const aHalfH = a.height / 2;
+    const bHalfW = b.width / 2;
+    const bHalfH = b.height / 2;
+
+    return (
+      Math.abs(a.x - b.x) < aHalfW + bHalfW &&
+      Math.abs(a.y - b.y) < aHalfH + bHalfH
+    );
+  }
+
+  /**
+   * Check if a point is inside an AABB.
+   */
+  static containsPoint(aabb: AABB, x: number, y: number): boolean {
+    const halfW = aabb.width / 2;
+    const halfH = aabb.height / 2;
+
+    return (
+      x >= aabb.x - halfW &&
+      x <= aabb.x + halfW &&
+      y >= aabb.y - halfH &&
+      y <= aabb.y + halfH
+    );
+  }
+
+  /**
+   * Create AABB from entity.
+   */
+  static fromEntity(entity: Entity, width: number, height: number): AABB {
+    return {
+      x: entity.x,
+      y: entity.y,
+      width,
+      height,
+    };
+  }
+
+  /**
+   * Get the distance between two AABBs.
+   * Returns 0 if overlapping.
+   */
+  static distance(a: AABB, b: AABB): number {
+    const dx = Math.abs(a.x - b.x);
+    const dy = Math.abs(a.y - b.y);
+    const combinedHalfW = (a.width + b.width) / 2;
+    const combinedHalfH = (a.height + b.height) / 2;
+
+    const gapX = Math.max(0, dx - combinedHalfW);
+    const gapY = Math.max(0, dy - combinedHalfH);
+
+    return Math.sqrt(gapX * gapX + gapY * gapY);
+  }
+
+  /**
+   * Compute the overlap amount between two AABBs.
+   * Returns { x: 0, y: 0 } if not overlapping.
+   */
+  static overlap(a: AABB, b: AABB): { x: number; y: number } {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+
+    const combinedHalfW = (a.width + b.width) / 2;
+    const combinedHalfH = (a.height + b.height) / 2;
+
+    const overlapX = combinedHalfW - Math.abs(dx);
+    const overlapY = combinedHalfH - Math.abs(dy);
+
+    if (overlapX > 0 && overlapY > 0) {
+      return {
+        x: overlapX * Math.sign(dx),
+        y: overlapY * Math.sign(dy),
+      };
+    }
+
+    return { x: 0, y: 0 };
+  }
+}