@gamerstake/game-core 0.1.0

package/src/physics/Movement.ts

@@ -0,0 +1,124 @@
+/**
+ * Movement Physics
+ *
+ * Velocity integration and boundary constraints.
+ */
+
+import type { Entity } from '../entities/Entity.js';
+
+/**
+ * Boundary constraints for movement.
+ */
+export interface Boundary {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+}
+
+/**
+ * Movement physics utilities.
+ */
+export class Movement {
+  /**
+   * Update entity position based on velocity.
+   *
+   * @param entity - Entity to update
+   * @param deltaMs - Time delta in milliseconds
+   */
+  static integrate(entity: Entity, deltaMs: number): void {
+    if (entity.vx === 0 && entity.vy === 0) return;
+
+    const deltaSec = deltaMs / 1000;
+    entity.x += entity.vx * deltaSec;
+    entity.y += entity.vy * deltaSec;
+    entity.markDirty();
+  }
+
+  /**
+   * Apply velocity to entity.
+   */
+  static applyVelocity(entity: Entity, vx: number, vy: number): void {
+    entity.setVelocity(vx, vy);
+  }
+
+  /**
+   * Stop entity movement.
+   */
+  static stop(entity: Entity): void {
+    entity.setVelocity(0, 0);
+  }
+
+  /**
+   * Constrain entity to boundary.
+   *
+   * @param entity - Entity to constrain
+   * @param boundary - Boundary constraints
+   * @returns True if entity was clamped
+   */
+  static constrainToBoundary(entity: Entity, boundary: Boundary): boolean {
+    let clamped = false;
+
+    if (entity.x < boundary.minX) {
+      entity.x = boundary.minX;
+      entity.vx = 0;
+      clamped = true;
+    } else if (entity.x > boundary.maxX) {
+      entity.x = boundary.maxX;
+      entity.vx = 0;
+      clamped = true;
+    }
+
+    if (entity.y < boundary.minY) {
+      entity.y = boundary.minY;
+      entity.vy = 0;
+      clamped = true;
+    } else if (entity.y > boundary.maxY) {
+      entity.y = boundary.maxY;
+      entity.vy = 0;
+      clamped = true;
+    }
+
+    if (clamped) {
+      entity.markDirty();
+    }
+
+    return clamped;
+  }
+
+  /**
+   * Calculate distance between two entities.
+   */
+  static distance(a: Entity, b: Entity): number {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  /**
+   * Normalize a direction vector.
+   */
+  static normalize(x: number, y: number): { x: number; y: number } {
+    const length = Math.sqrt(x * x + y * y);
+    if (length === 0) return { x: 0, y: 0 };
+    return {
+      x: x / length,
+      y: y / length,
+    };
+  }
+
+  /**
+   * Calculate velocity from direction and speed.
+   */
+  static velocityFromDirection(
+    dirX: number,
+    dirY: number,
+    speed: number,
+  ): { vx: number; vy: number } {
+    const normalized = this.normalize(dirX, dirY);
+    return {
+      vx: normalized.x * speed,
+      vy: normalized.y * speed,
+    };
+  }
+}

package/src/spatial/Grid.ts

@@ -0,0 +1,202 @@
+/**
+ * Grid System
+ *
+ * Spatial partitioning using a fixed-size grid.
+ * Enables O(1) lookup for nearby entities.
+ */
+
+import { logger } from '../utils/Logger.js';
+
+/**
+ * A single cell in the grid.
+ */
+interface GridCell {
+  readonly x: number;
+  readonly y: number;
+  readonly entities: Set<string>;
+}
+
+/**
+ * Grid-based spatial partitioning system.
+ *
+ * Uses a hash map of cells for O(1) entity tracking.
+ * Automatically cleans up empty cells to prevent memory leaks.
+ */
+export class Grid {
+  private readonly cellSize: number;
+  private readonly cells = new Map<string, GridCell>();
+  private readonly entityCells = new Map<string, string>(); // entityId -> cellKey
+
+  /**
+   * Create a new spatial grid.
+   *
+   * @param cellSize - Size of each cell in world units (default: 512)
+   */
+  constructor(cellSize = 512) {
+    this.cellSize = cellSize;
+  }
+
+  /**
+   * Convert world coordinates to cell key.
+   */
+  getCellKey(worldX: number, worldY: number): string {
+    const cellX = Math.floor(worldX / this.cellSize);
+    const cellY = Math.floor(worldY / this.cellSize);
+    return `${cellX},${cellY}`;
+  }
+
+  /**
+   * Get or create a cell at world coordinates.
+   */
+  private getCell(worldX: number, worldY: number): GridCell {
+    const key = this.getCellKey(worldX, worldY);
+    let cell = this.cells.get(key);
+
+    if (!cell) {
+      const cellX = Math.floor(worldX / this.cellSize);
+      const cellY = Math.floor(worldY / this.cellSize);
+      cell = { x: cellX, y: cellY, entities: new Set() };
+      this.cells.set(key, cell);
+    }
+
+    return cell;
+  }
+
+  /**
+   * Add an entity to the grid.
+   */
+  addEntity(entityId: string, x: number, y: number): void {
+    const cell = this.getCell(x, y);
+    cell.entities.add(entityId);
+    this.entityCells.set(entityId, this.getCellKey(x, y));
+
+    logger.debug(
+      { entityId, cellX: cell.x, cellY: cell.y },
+      'Entity added to grid',
+    );
+  }
+
+  /**
+   * Remove an entity from the grid.
+   */
+  removeEntity(entityId: string): void {
+    const cellKey = this.entityCells.get(entityId);
+    if (!cellKey) return;
+
+    const cell = this.cells.get(cellKey);
+    if (cell) {
+      cell.entities.delete(entityId);
+
+      // Clean up empty cells
+      if (cell.entities.size === 0) {
+        this.cells.delete(cellKey);
+      }
+    }
+
+    this.entityCells.delete(entityId);
+
+    logger.debug({ entityId }, 'Entity removed from grid');
+  }
+
+  /**
+   * Move an entity to a new position.
+   * Returns true if the entity changed cells.
+   */
+  moveEntity(
+    entityId: string,
+    oldX: number,
+    oldY: number,
+    newX: number,
+    newY: number,
+  ): boolean {
+    const oldKey = this.getCellKey(oldX, oldY);
+    const newKey = this.getCellKey(newX, newY);
+
+    // Same cell, no update needed
+    if (oldKey === newKey) {
+      return false;
+    }
+
+    // Remove from old cell
+    const oldCell = this.cells.get(oldKey);
+    if (oldCell) {
+      oldCell.entities.delete(entityId);
+      if (oldCell.entities.size === 0) {
+        this.cells.delete(oldKey);
+      }
+    }
+
+    // Add to new cell
+    const newCell = this.getCell(newX, newY);
+    newCell.entities.add(entityId);
+    this.entityCells.set(entityId, newKey);
+
+    logger.debug({ entityId, oldKey, newKey }, 'Entity moved to new cell');
+
+    return true;
+  }
+
+  /**
+   * Get all entities in nearby cells.
+   *
+   * @param worldX - World X coordinate
+   * @param worldY - World Y coordinate
+   * @param range - Range in grid cells (default: 1 = 3x3 area)
+   */
+  getNearbyEntities(worldX: number, worldY: number, range = 1): string[] {
+    const centerCellX = Math.floor(worldX / this.cellSize);
+    const centerCellY = Math.floor(worldY / this.cellSize);
+
+    const entities: string[] = [];
+
+    for (let dx = -range; dx <= range; dx++) {
+      for (let dy = -range; dy <= range; dy++) {
+        const key = `${centerCellX + dx},${centerCellY + dy}`;
+        const cell = this.cells.get(key);
+        if (cell) {
+          entities.push(...cell.entities);
+        }
+      }
+    }
+
+    return entities;
+  }
+
+  /**
+   * Get entities in a specific cell.
+   */
+  getEntitiesInCell(worldX: number, worldY: number): string[] {
+    const cell = this.cells.get(this.getCellKey(worldX, worldY));
+    return cell ? Array.from(cell.entities) : [];
+  }
+
+  /**
+   * Get the cell an entity is in.
+   */
+  getEntityCell(entityId: string): string | undefined {
+    return this.entityCells.get(entityId);
+  }
+
+  /**
+   * Get total number of active cells.
+   */
+  getCellCount(): number {
+    return this.cells.size;
+  }
+
+  /**
+   * Get total entities in grid.
+   */
+  getEntityCount(): number {
+    return this.entityCells.size;
+  }
+
+  /**
+   * Clear all cells and entities.
+   */
+  clear(): void {
+    this.cells.clear();
+    this.entityCells.clear();
+    logger.debug('Grid cleared');
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Core type definitions for game-core package.
+ */
+
+/**
+ * Room configuration options.
+ */
+export interface RoomConfig {
+  /** Ticks per second (default: 20) */
+  tickRate?: number;
+
+  /** Grid cell size in world units (default: 512) */
+  cellSize?: number;
+
+  /** Maximum buffered inputs per player (default: 100) */
+  maxInputQueueSize?: number;
+
+  /** Maximum entities per room (default: 1000) */
+  maxEntities?: number;
+
+  /** Visibility range in grid cells (default: 1 = 3x3 area) */
+  visibilityRange?: number;
+}
+
+/**
+ * Server metrics for monitoring.
+ */
+export interface ServerMetrics {
+  /** Total number of active rooms */
+  roomCount: number;
+
+  /** Total players across all rooms */
+  totalPlayers: number;
+
+  /** Per-room metrics */
+  rooms: RoomMetrics[];
+}
+
+/**
+ * Per-room metrics.
+ */
+export interface RoomMetrics {
+  /** Room ID */
+  id: string;
+
+  /** Number of players in room */
+  playerCount: number;
+
+  /** Total entities in room */
+  entityCount: number;
+
+  /** Current tick number */
+  tickCount: number;
+
+  /** Is the room running */
+  isRunning: boolean;
+
+  /** Average tick time (ms) */
+  avgTickTime?: number;
+
+  /** Actual ticks per second */
+  ticksPerSecond?: number;
+}
+
+/**
+ * Game loop performance metrics.
+ */
+export interface LoopMetrics {
+  /** Average tick processing time (ms) */
+  avgTickTime: number;
+
+  /** Maximum tick time (ms) */
+  maxTickTime: number;
+
+  /** Minimum tick time (ms) */
+  minTickTime: number;
+
+  /** Actual ticks per second */
+  ticksPerSecond: number;
+}
+
+/**
+ * Network event base type.
+ */
+export interface NetworkEvent {
+  /** Opcode identifying event type */
+  op: string;
+
+  /** Additional event data */
+  [key: string]: unknown;
+}
+
+/**
+ * Snapshot of entity state.
+ */
+export interface EntitySnapshot {
+  id: string;
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Full room state snapshot.
+ */
+export interface StateSnapshot {
+  /** Current tick number */
+  tick: number;
+
+  /** All entities in room */
+  entities: EntitySnapshot[];
+
+  /** Timestamp */
+  timestamp: number;
+}

package/src/types/protocol.ts

@@ -0,0 +1,161 @@
+/**
+ * Network protocol definitions.
+ *
+ * Opcodes and message formats for client-server communication.
+ */
+
+/**
+ * Client → Server opcodes.
+ */
+export enum ClientOpcode {
+  /** Player movement input */
+  C_MOVE = 'C_MOVE',
+
+  /** Player stop input */
+  C_STOP = 'C_STOP',
+
+  /** Generic action */
+  C_ACTION = 'C_ACTION',
+}
+
+/**
+ * Server → Client opcodes.
+ */
+export enum ServerOpcode {
+  /** Initial state on join */
+  S_INIT = 'S_INIT',
+
+  /** Delta state update */
+  S_UPDATE = 'S_UPDATE',
+
+  /** Entity spawned */
+  S_SPAWN = 'S_SPAWN',
+
+  /** Entity destroyed */
+  S_DESPAWN = 'S_DESPAWN',
+
+  /** Custom game event */
+  S_EVENT = 'S_EVENT',
+
+  /** Error message */
+  S_ERROR = 'S_ERROR',
+}
+
+/**
+ * Client movement input.
+ */
+export interface C_Move {
+  op: ClientOpcode.C_MOVE;
+  seq: number;
+  dir: { x: number; y: number };
+  timestamp: number;
+}
+
+/**
+ * Client stop input.
+ */
+export interface C_Stop {
+  op: ClientOpcode.C_STOP;
+  seq: number;
+  timestamp: number;
+}
+
+/**
+ * Client action input.
+ */
+export interface C_Action {
+  op: ClientOpcode.C_ACTION;
+  seq: number;
+  action: string;
+  data?: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * Server initial state.
+ */
+export interface S_Init {
+  op: ServerOpcode.S_INIT;
+  playerId: string;
+  tick: number;
+  entities: Array<{
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+  }>;
+}
+
+/**
+ * Server delta update.
+ */
+export interface S_Update {
+  op: ServerOpcode.S_UPDATE;
+  tick: number;
+  entities: Array<{
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    seq?: number; // Echo client seq for reconciliation
+  }>;
+}
+
+/**
+ * Server entity spawn.
+ */
+export interface S_Spawn {
+  op: ServerOpcode.S_SPAWN;
+  entity: {
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+  };
+}
+
+/**
+ * Server entity despawn.
+ */
+export interface S_Despawn {
+  op: ServerOpcode.S_DESPAWN;
+  entityId: string;
+  reason?: string;
+}
+
+/**
+ * Server custom event.
+ */
+export interface S_Event {
+  op: ServerOpcode.S_EVENT;
+  event: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Server error message.
+ */
+export interface S_Error {
+  op: ServerOpcode.S_ERROR;
+  code: string;
+  message: string;
+}
+
+/**
+ * Union of all client messages.
+ */
+export type ClientMessage = C_Move | C_Stop | C_Action;
+
+/**
+ * Union of all server messages.
+ */
+export type ServerMessage =
+  | S_Init
+  | S_Update
+  | S_Spawn
+  | S_Despawn
+  | S_Event
+  | S_Error;

package/src/utils/Logger.ts

@@ -0,0 +1,112 @@
+/**
+ * Logger utility
+ *
+ * Wrapper around pino for structured logging.
+ * Consumers can override this with their own logger.
+ */
+
+import pino from 'pino';
+
+/**
+ * Default logger configuration.
+ */
+const defaultLogger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport:
+    process.env.NODE_ENV === 'development'
+      ? {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'HH:MM:ss',
+            ignore: 'pid,hostname',
+          },
+        }
+      : undefined,
+  base: {
+    package: '@gamerstake/game-core',
+  },
+});
+
+/**
+ * Logger instance.
+ * Can be replaced by consumers.
+ */
+export let logger = defaultLogger;
+
+/**
+ * Set a custom logger instance.
+ *
+ * @param customLogger - Custom pino logger
+ */
+export function setLogger(customLogger: pino.Logger): void {
+  logger = customLogger;
+}
+
+/**
+ * Create a child logger with additional context.
+ *
+ * @param bindings - Additional context fields
+ */
+export function createChildLogger(
+  bindings: Record<string, unknown>,
+): pino.Logger {
+  return logger.child(bindings);
+}
+
+/**
+ * Logger class for dependency injection.
+ */
+export class Logger {
+  private logger: pino.Logger;
+
+  constructor(bindings?: Record<string, unknown>) {
+    this.logger = bindings ? logger.child(bindings) : logger;
+  }
+
+  debug(obj: object, msg?: string): void;
+  debug(msg: string): void;
+  debug(objOrMsg: object | string, msg?: string): void {
+    if (typeof objOrMsg === 'string') {
+      this.logger.debug(objOrMsg);
+    } else {
+      this.logger.debug(objOrMsg, msg);
+    }
+  }
+
+  info(obj: object, msg?: string): void;
+  info(msg: string): void;
+  info(objOrMsg: object | string, msg?: string): void {
+    if (typeof objOrMsg === 'string') {
+      this.logger.info(objOrMsg);
+    } else {
+      this.logger.info(objOrMsg, msg);
+    }
+  }
+
+  warn(obj: object, msg?: string): void;
+  warn(msg: string): void;
+  warn(objOrMsg: object | string, msg?: string): void {
+    if (typeof objOrMsg === 'string') {
+      this.logger.warn(objOrMsg);
+    } else {
+      this.logger.warn(objOrMsg, msg);
+    }
+  }
+
+  error(obj: object, msg?: string): void;
+  error(msg: string): void;
+  error(objOrMsg: object | string, msg?: string): void {
+    if (typeof objOrMsg === 'string') {
+      this.logger.error(objOrMsg);
+    } else {
+      this.logger.error(objOrMsg, msg);
+    }
+  }
+
+  child(bindings: Record<string, unknown>): Logger {
+    const childLogger = new Logger();
+    childLogger.logger = this.logger.child(bindings);
+    return childLogger;
+  }
+}