@gamerstake/game-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1266 @@
+import { Server, Socket } from 'socket.io';
+import pino from 'pino';
+
+/**
+ * Core type definitions for game-core package.
+ */
+/**
+ * Room configuration options.
+ */
+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.
+ */
+interface ServerMetrics {
+    /** Total number of active rooms */
+    roomCount: number;
+    /** Total players across all rooms */
+    totalPlayers: number;
+    /** Per-room metrics */
+    rooms: RoomMetrics[];
+}
+/**
+ * Per-room metrics.
+ */
+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.
+ */
+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.
+ */
+interface NetworkEvent {
+    /** Opcode identifying event type */
+    op: string;
+    /** Additional event data */
+    [key: string]: unknown;
+}
+/**
+ * Snapshot of entity state.
+ */
+interface EntitySnapshot {
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    [key: string]: unknown;
+}
+/**
+ * Full room state snapshot.
+ */
+interface StateSnapshot {
+    /** Current tick number */
+    tick: number;
+    /** All entities in room */
+    entities: EntitySnapshot[];
+    /** Timestamp */
+    timestamp: number;
+}
+
+/**
+ * Game Loop
+ *
+ * Fixed tick rate server loop with drift compensation.
+ * Processes inputs, updates state, broadcasts changes.
+ */
+
+/**
+ * Tick handler interface.
+ * Implement this to receive tick callbacks.
+ */
+interface TickHandler {
+    onTick(tickNumber: number, deltaMs: number): void;
+}
+/**
+ * High-precision game loop using setTimeout with drift compensation.
+ */
+declare class GameLoop {
+    private readonly tickRate;
+    private readonly tickMs;
+    private tickNumber;
+    private lastTickTime;
+    private running;
+    private timeout;
+    private readonly handlers;
+    private tickTimes;
+    private readonly metricsWindowSize;
+    /**
+     * Create a new game loop.
+     *
+     * @param tickRate - Ticks per second (default: 20)
+     */
+    constructor(tickRate?: number);
+    /**
+     * Register a tick handler.
+     */
+    addHandler(handler: TickHandler): void;
+    /**
+     * Remove a tick handler.
+     */
+    removeHandler(handler: TickHandler): void;
+    /**
+     * Start the game loop.
+     */
+    start(): void;
+    /**
+     * Stop the game loop.
+     */
+    stop(): void;
+    /**
+     * Check if loop is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get current tick number.
+     */
+    getCurrentTick(): number;
+    /**
+     * Get tick rate (TPS).
+     */
+    getTickRate(): number;
+    /**
+     * Get tick duration (ms).
+     */
+    getTickMs(): number;
+    /**
+     * Get performance metrics.
+     */
+    getMetrics(): LoopMetrics;
+    /**
+     * Schedule the next tick with drift compensation.
+     */
+    private scheduleNextTick;
+    /**
+     * Execute one tick.
+     */
+    private tick;
+    /**
+     * Record tick time for metrics.
+     */
+    private recordTickTime;
+}
+
+/**
+ * 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.
+ */
+declare 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);
+    /**
+     * Update position based on velocity and delta time.
+     *
+     * @param deltaMs - Time since last update (milliseconds)
+     */
+    updatePosition(deltaMs: number): void;
+    /**
+     * Set velocity.
+     */
+    setVelocity(vx: number, vy: number): void;
+    /**
+     * Teleport to position (no velocity integration).
+     */
+    setPosition(x: number, y: number): void;
+    /**
+     * Mark entity as clean (after broadcast).
+     */
+    markClean(): void;
+    /**
+     * Mark entity as dirty (needs broadcast).
+     */
+    markDirty(): void;
+    /**
+     * Get entity as plain object for serialization.
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Command types for player input.
+ */
+/**
+ * Base command interface.
+ */
+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.
+ */
+interface MoveCommand extends Command {
+    type: 'move';
+    dir: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Stop command.
+ */
+interface StopCommand extends Command {
+    type: 'stop';
+}
+/**
+ * Generic action command.
+ */
+interface ActionCommand extends Command {
+    type: 'action';
+    action: string;
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Game Rules Interface
+ *
+ * Pluggable game logic interface.
+ * Implement this to create custom multiplayer games.
+ */
+
+/**
+ * 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;
+ *   }
+ * }
+ * ```
+ */
+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;
+}
+
+/**
+ * Entity Registry
+ *
+ * Manages entity lifecycle and provides efficient queries.
+ */
+
+/**
+ * Entity registry with lifecycle management.
+ *
+ * Provides zero-allocation queries using pre-allocated buffers
+ * to minimize GC pressure in hot paths.
+ */
+declare class Registry<TEntity extends Entity = Entity> {
+    private readonly entities;
+    private readonly dirtyEntities;
+    private readonly dirtyBuffer;
+    private readonly allBuffer;
+    /**
+     * Add an entity to the registry.
+     */
+    add(entity: TEntity): void;
+    /**
+     * Remove an entity from the registry.
+     */
+    remove(entityId: string): boolean;
+    /**
+     * Get an entity by ID.
+     */
+    get(entityId: string): TEntity | undefined;
+    /**
+     * Check if entity exists.
+     */
+    has(entityId: string): boolean;
+    /**
+     * Mark an entity as dirty (needs broadcast).
+     */
+    markDirty(entityId: string): void;
+    /**
+     * 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[];
+    /**
+     * Get all entities.
+     * OPTIMIZED: Reuses buffer array to avoid allocations.
+     *
+     * @returns Array of all entities (reused buffer - don't store reference!)
+     */
+    getAll(): TEntity[];
+    /**
+     * Get entity count.
+     */
+    size(): number;
+    /**
+     * Get dirty entity count.
+     */
+    dirtyCount(): number;
+    /**
+     * Clear all entities.
+     */
+    clear(): void;
+    /**
+     * Execute callback for each entity.
+     */
+    forEach(callback: (entity: TEntity) => void): void;
+    /**
+     * Filter entities by predicate.
+     *
+     * @param predicate - Filter function
+     * @returns New array of matching entities
+     */
+    filter(predicate: (entity: TEntity) => boolean): TEntity[];
+}
+
+/**
+ * Grid System
+ *
+ * Spatial partitioning using a fixed-size grid.
+ * Enables O(1) lookup for nearby entities.
+ */
+/**
+ * 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.
+ */
+declare class Grid {
+    private readonly cellSize;
+    private readonly cells;
+    private readonly entityCells;
+    /**
+     * Create a new spatial grid.
+     *
+     * @param cellSize - Size of each cell in world units (default: 512)
+     */
+    constructor(cellSize?: number);
+    /**
+     * Convert world coordinates to cell key.
+     */
+    getCellKey(worldX: number, worldY: number): string;
+    /**
+     * Get or create a cell at world coordinates.
+     */
+    private getCell;
+    /**
+     * Add an entity to the grid.
+     */
+    addEntity(entityId: string, x: number, y: number): void;
+    /**
+     * Remove an entity from the grid.
+     */
+    removeEntity(entityId: string): void;
+    /**
+     * 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;
+    /**
+     * 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?: number): string[];
+    /**
+     * Get entities in a specific cell.
+     */
+    getEntitiesInCell(worldX: number, worldY: number): string[];
+    /**
+     * Get the cell an entity is in.
+     */
+    getEntityCell(entityId: string): string | undefined;
+    /**
+     * Get total number of active cells.
+     */
+    getCellCount(): number;
+    /**
+     * Get total entities in grid.
+     */
+    getEntityCount(): number;
+    /**
+     * Clear all cells and entities.
+     */
+    clear(): void;
+}
+
+/**
+ * Input Queue
+ *
+ * Buffers player inputs for processing in the game loop.
+ * Uses RingBuffer for O(1) push/pop operations.
+ */
+
+/**
+ * Input queue manager using RingBuffer for O(1) operations.
+ *
+ * Manages input queues for multiple players, with automatic
+ * overflow handling (drops oldest inputs when full).
+ */
+declare class InputQueue {
+    private readonly queues;
+    private readonly maxQueueSize;
+    /**
+     * Create a new input queue manager.
+     *
+     * @param maxQueueSize - Maximum inputs per player (default: 100)
+     */
+    constructor(maxQueueSize?: number);
+    /**
+     * Get or create a player's queue.
+     */
+    private getQueue;
+    /**
+     * Add an input to a player's queue. O(1)
+     */
+    push(playerId: string, input: Command): void;
+    /**
+     * Get and remove the next input for a player. O(1)
+     */
+    pop(playerId: string): Command | undefined;
+    /**
+     * Peek at the next input without removing. O(1)
+     */
+    peek(playerId: string): Command | undefined;
+    /**
+     * Get all inputs for a player and clear.
+     */
+    drain(playerId: string): Command[];
+    /**
+     * Get queue size for a player.
+     */
+    size(playerId: string): number;
+    /**
+     * Clear a player's queue.
+     */
+    clear(playerId: string): void;
+    /**
+     * Remove a player's queue entirely.
+     */
+    remove(playerId: string): void;
+    /**
+     * Clear all queues.
+     */
+    clearAll(): void;
+    /**
+     * Get total queued inputs across all players.
+     */
+    getTotalSize(): number;
+}
+
+/**
+ * Network Layer
+ *
+ * Broadcast and send utilities for game events.
+ */
+
+/**
+ * Network layer for broadcasting game events.
+ *
+ * Wraps Socket.io with game-specific utilities.
+ */
+declare class Network {
+    private io;
+    private readonly sockets;
+    /**
+     * Set the Socket.io server instance.
+     */
+    setServer(io: Server): void;
+    /**
+     * Register a socket connection.
+     */
+    registerSocket(playerId: string, socket: Socket): void;
+    /**
+     * Unregister a socket connection.
+     */
+    unregisterSocket(playerId: string): void;
+    /**
+     * Get a socket by player ID.
+     */
+    getSocket(playerId: string): Socket | undefined;
+    /**
+     * Broadcast event to all connected players.
+     */
+    broadcast(event: NetworkEvent): void;
+    /**
+     * Broadcast event to all players in a room.
+     */
+    broadcastToRoom(roomId: string, event: NetworkEvent): void;
+    /**
+     * Send event to a specific player.
+     */
+    sendTo(playerId: string, event: NetworkEvent): void;
+    /**
+     * Send event to multiple players.
+     */
+    sendToMany(playerIds: string[], event: NetworkEvent): void;
+    /**
+     * Get connected player count.
+     */
+    getPlayerCount(): number;
+    /**
+     * Clear all sockets.
+     */
+    clear(): void;
+}
+
+/**
+ * Room
+ *
+ * A single game room/match instance.
+ * Manages entities, tick loop, and networking.
+ */
+
+/**
+ * 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);
+ * ```
+ */
+declare class Room<TEntity extends Entity = Entity> implements TickHandler {
+    /** Room identifier */
+    readonly id: string;
+    /** Game-specific logic */
+    readonly rules: GameRules<TEntity>;
+    private readonly registry;
+    private readonly grid;
+    private readonly loop;
+    private readonly inputQueue;
+    private readonly network;
+    private readonly players;
+    private tickCount;
+    private startTime;
+    private readonly config;
+    /**
+     * 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);
+    /**
+     * Start the room (begins tick loop).
+     */
+    start(): void;
+    /**
+     * Stop the room (ends tick loop).
+     */
+    stop(): void;
+    /**
+     * Add a player to the room.
+     */
+    addPlayer(player: TEntity): void;
+    /**
+     * Remove a player from the room.
+     */
+    removePlayer(playerId: string): void;
+    /**
+     * Spawn a non-player entity.
+     */
+    spawnEntity(entity: TEntity): void;
+    /**
+     * Destroy an entity.
+     */
+    destroyEntity(entityId: string): void;
+    /**
+     * Queue a player input.
+     */
+    queueInput(playerId: string, command: Command): void;
+    /**
+     * Broadcast event to all players.
+     */
+    broadcast(event: NetworkEvent): void;
+    /**
+     * Send event to specific player.
+     */
+    sendTo(playerId: string, event: NetworkEvent): void;
+    /**
+     * Get full state snapshot.
+     */
+    getSnapshot(): StateSnapshot;
+    /**
+     * Get delta snapshot (only dirty entities).
+     */
+    getDeltaSnapshot(): StateSnapshot;
+    /**
+     * Main tick function (called by GameLoop).
+     */
+    onTick(tickNumber: number, deltaMs: number): void;
+    /**
+     * Get all players.
+     */
+    getPlayers(): Map<string, TEntity>;
+    /**
+     * Get entity registry.
+     */
+    getRegistry(): Registry<TEntity>;
+    /**
+     * Get spatial grid.
+     */
+    getGrid(): Grid;
+    /**
+     * Get network layer.
+     */
+    getNetwork(): Network;
+    /**
+     * Get input queue.
+     */
+    getInputQueue(): InputQueue;
+    /**
+     * Get current tick number.
+     */
+    getTickCount(): number;
+    /**
+     * Get uptime in milliseconds.
+     */
+    getUptime(): number;
+    /**
+     * Check if room is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get room configuration.
+     */
+    getConfig(): Required<RoomConfig>;
+    /**
+     * Get room metrics.
+     */
+    getMetrics(): {
+        avgTickTime: number;
+        maxTickTime: number;
+        minTickTime: number;
+        ticksPerSecond: number;
+        roomId: string;
+        tickCount: number;
+        uptime: number;
+        playerCount: number;
+        entityCount: number;
+        cellCount: number;
+        queuedInputs: number;
+    };
+}
+
+/**
+ * Game Server
+ *
+ * Multi-room game server.
+ * Manages room lifecycle and routing.
+ */
+
+/**
+ * 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');
+ * ```
+ */
+declare class GameServer {
+    private readonly rooms;
+    private io;
+    /**
+     * Set the Socket.io server instance.
+     *
+     * This should be called before creating rooms to enable
+     * network functionality.
+     */
+    setServer(io: Server): void;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * Get a room by ID.
+     */
+    getRoom(id: string): Room | undefined;
+    /**
+     * 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;
+    /**
+     * Check if room exists.
+     */
+    hasRoom(id: string): boolean;
+    /**
+     * Get all rooms.
+     */
+    getRooms(): Map<string, Room>;
+    /**
+     * Get room count.
+     */
+    getRoomCount(): number;
+    /**
+     * Get total player count across all rooms.
+     */
+    getTotalPlayerCount(): number;
+    /**
+     * Get server health metrics.
+     */
+    getMetrics(): ServerMetrics;
+    /**
+     * Stop all rooms.
+     */
+    stopAll(): void;
+    /**
+     * Destroy all rooms.
+     */
+    destroyAll(): void;
+}
+
+/**
+ * AABB Collision Detection
+ *
+ * Axis-Aligned Bounding Box collision detection.
+ */
+
+/**
+ * Axis-Aligned Bounding Box.
+ */
+interface AABB {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * AABB collision detection utilities.
+ */
+declare class AABBCollision {
+    /**
+     * Check if two AABBs overlap.
+     */
+    static overlaps(a: AABB, b: AABB): boolean;
+    /**
+     * Check if a point is inside an AABB.
+     */
+    static containsPoint(aabb: AABB, x: number, y: number): boolean;
+    /**
+     * Create AABB from entity.
+     */
+    static fromEntity(entity: Entity, width: number, height: number): AABB;
+    /**
+     * Get the distance between two AABBs.
+     * Returns 0 if overlapping.
+     */
+    static distance(a: AABB, b: AABB): number;
+    /**
+     * 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;
+    };
+}
+
+/**
+ * Movement Physics
+ *
+ * Velocity integration and boundary constraints.
+ */
+
+/**
+ * Boundary constraints for movement.
+ */
+interface Boundary {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * Movement physics utilities.
+ */
+declare 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;
+    /**
+     * Apply velocity to entity.
+     */
+    static applyVelocity(entity: Entity, vx: number, vy: number): void;
+    /**
+     * Stop entity movement.
+     */
+    static stop(entity: Entity): void;
+    /**
+     * 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;
+    /**
+     * Calculate distance between two entities.
+     */
+    static distance(a: Entity, b: Entity): number;
+    /**
+     * Normalize a direction vector.
+     */
+    static normalize(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Calculate velocity from direction and speed.
+     */
+    static velocityFromDirection(dirX: number, dirY: number, speed: number): {
+        vx: number;
+        vy: number;
+    };
+}
+
+/**
+ * Snapshot System
+ *
+ * Full state snapshots for network synchronization.
+ */
+
+/**
+ * Snapshot generator.
+ *
+ * Creates full state snapshots for sending to clients.
+ * Used for initial sync and periodic full updates.
+ */
+declare 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;
+    /**
+     * Convert an entity to a snapshot.
+     */
+    static entityToSnapshot(entity: Entity): EntitySnapshot;
+    /**
+     * 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;
+}
+
+/**
+ * Ring Buffer
+ *
+ * O(1) insert and remove, fixed capacity, no allocations in hot path.
+ * Used for input queues, position history, etc.
+ */
+declare class RingBuffer<T> {
+    private readonly capacity;
+    private readonly buffer;
+    private head;
+    private tail;
+    private count;
+    constructor(capacity: number);
+    /**
+     * Add item to buffer. O(1)
+     * Returns false if buffer is full.
+     */
+    push(item: T): boolean;
+    /**
+     * Add item, overwriting oldest if full. O(1)
+     */
+    pushOverwrite(item: T): T | undefined;
+    /**
+     * Remove and return oldest item. O(1)
+     */
+    shift(): T | undefined;
+    /**
+     * Peek at oldest item without removing. O(1)
+     */
+    peek(): T | undefined;
+    /**
+     * Get current size.
+     */
+    size(): number;
+    /**
+     * Check if empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if full.
+     */
+    isFull(): boolean;
+    /**
+     * Clear all items. O(1)
+     */
+    clear(): void;
+    /**
+     * Get capacity.
+     */
+    getCapacity(): number;
+}
+
+/**
+ * Logger utility
+ *
+ * Wrapper around pino for structured logging.
+ * Consumers can override this with their own logger.
+ */
+
+/**
+ * Logger instance.
+ * Can be replaced by consumers.
+ */
+declare let logger: pino.Logger<never, boolean>;
+/**
+ * Set a custom logger instance.
+ *
+ * @param customLogger - Custom pino logger
+ */
+declare function setLogger(customLogger: pino.Logger): void;
+/**
+ * Create a child logger with additional context.
+ *
+ * @param bindings - Additional context fields
+ */
+declare function createChildLogger(bindings: Record<string, unknown>): pino.Logger;
+/**
+ * Logger class for dependency injection.
+ */
+declare class Logger {
+    private logger;
+    constructor(bindings?: Record<string, unknown>);
+    debug(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    info(obj: object, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: object, msg?: string): void;
+    error(msg: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+
+/**
+ * Network protocol definitions.
+ *
+ * Opcodes and message formats for client-server communication.
+ */
+/**
+ * Client → Server opcodes.
+ */
+declare 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.
+ */
+declare 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.
+ */
+interface C_Move {
+    op: ClientOpcode.C_MOVE;
+    seq: number;
+    dir: {
+        x: number;
+        y: number;
+    };
+    timestamp: number;
+}
+/**
+ * Client stop input.
+ */
+interface C_Stop {
+    op: ClientOpcode.C_STOP;
+    seq: number;
+    timestamp: number;
+}
+/**
+ * Client action input.
+ */
+interface C_Action {
+    op: ClientOpcode.C_ACTION;
+    seq: number;
+    action: string;
+    data?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Server initial state.
+ */
+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.
+ */
+interface S_Update {
+    op: ServerOpcode.S_UPDATE;
+    tick: number;
+    entities: Array<{
+        id: string;
+        x: number;
+        y: number;
+        vx: number;
+        vy: number;
+        seq?: number;
+    }>;
+}
+/**
+ * Server entity spawn.
+ */
+interface S_Spawn {
+    op: ServerOpcode.S_SPAWN;
+    entity: {
+        id: string;
+        x: number;
+        y: number;
+        vx: number;
+        vy: number;
+    };
+}
+/**
+ * Server entity despawn.
+ */
+interface S_Despawn {
+    op: ServerOpcode.S_DESPAWN;
+    entityId: string;
+    reason?: string;
+}
+/**
+ * Server custom event.
+ */
+interface S_Event {
+    op: ServerOpcode.S_EVENT;
+    event: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Server error message.
+ */
+interface S_Error {
+    op: ServerOpcode.S_ERROR;
+    code: string;
+    message: string;
+}
+/**
+ * Union of all client messages.
+ */
+type ClientMessage = C_Move | C_Stop | C_Action;
+/**
+ * Union of all server messages.
+ */
+type ServerMessage = S_Init | S_Update | S_Spawn | S_Despawn | S_Event | S_Error;
+
+export { type AABB, AABBCollision, type ActionCommand, type Boundary, type C_Action, type C_Move, type C_Stop, type ClientMessage, ClientOpcode, type Command, Entity, type EntitySnapshot, GameLoop, type GameRules, GameServer, Grid, InputQueue, Logger, type LoopMetrics, type MoveCommand, Movement, Network, type NetworkEvent, Registry, RingBuffer, Room, type RoomConfig, type RoomMetrics, type S_Despawn, type S_Error, type S_Event, type S_Init, type S_Spawn, type S_Update, type ServerMessage, type ServerMetrics, ServerOpcode, Snapshot, type StateSnapshot, type StopCommand, type TickHandler, createChildLogger, logger, setLogger };