@gamerstake/game-core 0.1.0

package/src/utils/RingBuffer.ts

@@ -0,0 +1,116 @@
+/**
+ * Ring Buffer
+ *
+ * O(1) insert and remove, fixed capacity, no allocations in hot path.
+ * Used for input queues, position history, etc.
+ */
+
+export class RingBuffer<T> {
+  private readonly buffer: (T | undefined)[];
+  private head = 0; // Next write position
+  private tail = 0; // Next read position
+  private count = 0;
+
+  constructor(private readonly capacity: number) {
+    this.buffer = new Array(capacity);
+  }
+
+  /**
+   * Add item to buffer. O(1)
+   * Returns false if buffer is full.
+   */
+  push(item: T): boolean {
+    if (this.count >= this.capacity) {
+      return false; // Full
+    }
+
+    this.buffer[this.head] = item;
+    this.head = (this.head + 1) % this.capacity;
+    this.count++;
+    return true;
+  }
+
+  /**
+   * Add item, overwriting oldest if full. O(1)
+   */
+  pushOverwrite(item: T): T | undefined {
+    let dropped: T | undefined;
+
+    if (this.count >= this.capacity) {
+      // Drop oldest
+      dropped = this.buffer[this.tail];
+      this.tail = (this.tail + 1) % this.capacity;
+      this.count--;
+    }
+
+    this.buffer[this.head] = item;
+    this.head = (this.head + 1) % this.capacity;
+    this.count++;
+
+    return dropped;
+  }
+
+  /**
+   * Remove and return oldest item. O(1)
+   */
+  shift(): T | undefined {
+    if (this.count === 0) {
+      return undefined;
+    }
+
+    const item = this.buffer[this.tail];
+    this.buffer[this.tail] = undefined; // Help GC
+    this.tail = (this.tail + 1) % this.capacity;
+    this.count--;
+
+    return item;
+  }
+
+  /**
+   * Peek at oldest item without removing. O(1)
+   */
+  peek(): T | undefined {
+    if (this.count === 0) {
+      return undefined;
+    }
+    return this.buffer[this.tail];
+  }
+
+  /**
+   * Get current size.
+   */
+  size(): number {
+    return this.count;
+  }
+
+  /**
+   * Check if empty.
+   */
+  isEmpty(): boolean {
+    return this.count === 0;
+  }
+
+  /**
+   * Check if full.
+   */
+  isFull(): boolean {
+    return this.count >= this.capacity;
+  }
+
+  /**
+   * Clear all items. O(1)
+   */
+  clear(): void {
+    // Don't need to clear array, just reset pointers
+    this.head = 0;
+    this.tail = 0;
+    this.count = 0;
+  }
+
+  /**
+   * Get capacity.
+   */
+  getCapacity(): number {
+    return this.capacity;
+  }
+}

package/tests/AABB.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from '@jest/globals';
+import { AABBCollision, type AABB } from '../src/physics/AABB.js';
+import { Entity } from '../src/entities/Entity.js';
+
+describe('AABBCollision', () => {
+  it('detects overlap between AABBs', () => {
+    const a: AABB = { x: 0, y: 0, width: 10, height: 10 };
+    const b: AABB = { x: 5, y: 0, width: 10, height: 10 };
+    const c: AABB = { x: 20, y: 0, width: 10, height: 10 };
+
+    expect(AABBCollision.overlaps(a, b)).toBe(true);
+    expect(AABBCollision.overlaps(a, c)).toBe(false);
+  });
+
+  it('checks point containment', () => {
+    const a: AABB = { x: 0, y: 0, width: 10, height: 10 };
+    expect(AABBCollision.containsPoint(a, 1, 1)).toBe(true);
+    expect(AABBCollision.containsPoint(a, 10, 10)).toBe(false);
+  });
+
+  it('creates AABB from entity', () => {
+    const entity = new Entity('e1', 5, 6);
+    const aabb = AABBCollision.fromEntity(entity, 10, 12);
+    expect(aabb).toEqual({ x: 5, y: 6, width: 10, height: 12 });
+  });
+
+  it('calculates overlap and distance', () => {
+    const a: AABB = { x: 0, y: 0, width: 10, height: 10 };
+    const b: AABB = { x: 4, y: 4, width: 10, height: 10 };
+
+    const overlap = AABBCollision.overlap(a, b);
+    expect(Math.abs(overlap.x)).toBeGreaterThan(0);
+    expect(Math.abs(overlap.y)).toBeGreaterThan(0);
+
+    const distance = AABBCollision.distance(a, b);
+    expect(distance).toBe(0);
+  });
+});

package/tests/Entity.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from '@jest/globals';
+import { Entity } from '../src/entities/Entity.js';
+
+describe('Entity', () => {
+  it('updates position based on velocity and delta time', () => {
+    const entity = new Entity('e1', 0, 0);
+    entity.setVelocity(100, -50);
+    entity.updatePosition(1000); // 1 second
+
+    expect(entity.x).toBe(100);
+    expect(entity.y).toBe(-50);
+    expect(entity.dirty).toBe(true);
+  });
+
+  it('does not update position when velocity is zero', () => {
+    const entity = new Entity('e1', 10, 20);
+    entity.markClean();
+    entity.updatePosition(1000);
+
+    expect(entity.x).toBe(10);
+    expect(entity.y).toBe(20);
+    expect(entity.dirty).toBe(false);
+  });
+
+  it('sets position and velocity with dirty tracking', () => {
+    const entity = new Entity('e1', 0, 0);
+    entity.markClean();
+    entity.setPosition(5, 6);
+    expect(entity.dirty).toBe(true);
+
+    entity.markClean();
+    entity.setVelocity(1, 2);
+    expect(entity.dirty).toBe(true);
+  });
+});

package/tests/GameLoop.test.ts

@@ -0,0 +1,58 @@
+import {
+  describe,
+  it,
+  expect,
+  jest,
+  beforeEach,
+  afterEach,
+} from '@jest/globals';
+import { GameLoop, type TickHandler } from '../src/core/GameLoop.js';
+
+describe('GameLoop', () => {
+  let nowSpy: ReturnType<typeof jest.spyOn>;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    nowSpy = jest
+      .spyOn(performance, 'now')
+      .mockImplementation(() => Date.now());
+  });
+
+  afterEach(() => {
+    nowSpy.mockRestore();
+    jest.useRealTimers();
+  });
+
+  it('runs tick handlers at a fixed rate', () => {
+    const loop = new GameLoop(1); // 1 TPS
+    const handler: TickHandler = { onTick: jest.fn() };
+
+    loop.addHandler(handler);
+    loop.start();
+
+    // First tick fires after ~2000ms due to drift compensation on start
+    jest.advanceTimersByTime(2000);
+
+    expect(handler.onTick).toHaveBeenCalledTimes(1);
+    expect(loop.isRunning()).toBe(true);
+
+    loop.stop();
+    expect(loop.isRunning()).toBe(false);
+  });
+
+  it('can remove handlers', () => {
+    const loop = new GameLoop(1);
+    const handler: TickHandler = { onTick: jest.fn() };
+
+    loop.addHandler(handler);
+    loop.start();
+    jest.advanceTimersByTime(2000);
+    expect(handler.onTick).toHaveBeenCalledTimes(1);
+
+    loop.removeHandler(handler);
+    jest.advanceTimersByTime(2000);
+    expect(handler.onTick).toHaveBeenCalledTimes(1);
+
+    loop.stop();
+  });
+});

package/tests/GameServer.test.ts

@@ -0,0 +1,64 @@
+import {
+  describe,
+  it,
+  expect,
+  jest,
+  beforeEach,
+  afterEach,
+} from '@jest/globals';
+import { GameServer } from '../src/core/GameServer.js';
+import type { GameRules } from '../src/core/GameRules.js';
+import { Entity } from '../src/entities/Entity.js';
+
+describe('GameServer', () => {
+  let nowSpy: ReturnType<typeof jest.spyOn>;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    nowSpy = jest
+      .spyOn(performance, 'now')
+      .mockImplementation(() => Date.now());
+  });
+
+  afterEach(() => {
+    nowSpy.mockRestore();
+    jest.useRealTimers();
+  });
+
+  it('creates and destroys rooms', () => {
+    const server = new GameServer();
+    const rules: GameRules<Entity> = {
+      onRoomCreated: jest.fn(),
+      onPlayerJoin: jest.fn(),
+      onPlayerLeave: jest.fn(),
+      onTick: jest.fn(),
+      onCommand: jest.fn(),
+      shouldEndRoom: jest.fn(() => false),
+    };
+
+    const room = server.createRoom('room-1', rules);
+    expect(server.hasRoom('room-1')).toBe(true);
+    expect(room.id).toBe('room-1');
+
+    const destroyed = server.destroyRoom('room-1');
+    expect(destroyed).toBe(true);
+    expect(server.hasRoom('room-1')).toBe(false);
+  });
+
+  it('throws when creating duplicate rooms', () => {
+    const server = new GameServer();
+    const rules: GameRules<Entity> = {
+      onRoomCreated: jest.fn(),
+      onPlayerJoin: jest.fn(),
+      onPlayerLeave: jest.fn(),
+      onTick: jest.fn(),
+      onCommand: jest.fn(),
+      shouldEndRoom: jest.fn(() => false),
+    };
+
+    server.createRoom('room-1', rules);
+    expect(() => server.createRoom('room-1', rules)).toThrow(
+      'Room room-1 already exists',
+    );
+  });
+});

package/tests/Grid.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from '@jest/globals';
+import { Grid } from '../src/spatial/Grid.js';
+
+describe('Grid', () => {
+  it('adds, moves, and removes entities', () => {
+    const grid = new Grid(10);
+    grid.addEntity('e1', 0, 0);
+    expect(grid.getEntityCount()).toBe(1);
+    expect(grid.getEntityCell('e1')).toBe('0,0');
+
+    const moved = grid.moveEntity('e1', 0, 0, 25, 0);
+    expect(moved).toBe(true);
+    expect(grid.getEntityCell('e1')).toBe('2,0');
+
+    grid.removeEntity('e1');
+    expect(grid.getEntityCount()).toBe(0);
+  });
+
+  it('returns nearby entities within range', () => {
+    const grid = new Grid(10);
+    grid.addEntity('a', 0, 0);
+    grid.addEntity('b', 15, 0); // cell 1,0
+    grid.addEntity('c', 50, 0); // cell 5,0
+
+    const nearby = grid.getNearbyEntities(0, 0, 1);
+    expect(nearby.sort()).toEqual(['a', 'b']);
+  });
+});

package/tests/InputQueue.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from '@jest/globals';
+import { InputQueue } from '../src/input/InputQueue.js';
+import type { MoveCommand } from '../src/input/Command.js';
+
+const move = (seq: number): MoveCommand => ({
+  seq,
+  type: 'move',
+  dir: { x: 1, y: 0 },
+  timestamp: seq,
+});
+
+describe('InputQueue', () => {
+  it('pushes and pops inputs per player', () => {
+    const queue = new InputQueue(10);
+    queue.push('p1', move(1));
+    queue.push('p1', move(2));
+
+    expect(queue.pop('p1')?.seq).toBe(1);
+    expect(queue.pop('p1')?.seq).toBe(2);
+    expect(queue.pop('p1')).toBeUndefined();
+  });
+
+  it('drops oldest when full', () => {
+    const queue = new InputQueue(2);
+    queue.push('p1', move(1));
+    queue.push('p1', move(2));
+    queue.push('p1', move(3)); // drop seq=1
+
+    const drained = queue.drain('p1').map((c) => c.seq);
+    expect(drained).toEqual([2, 3]);
+  });
+
+  it('drains and clears per player', () => {
+    const queue = new InputQueue(5);
+    queue.push('p1', move(1));
+    queue.push('p1', move(2));
+
+    const drained = queue.drain('p1').map((c) => c.seq);
+    expect(drained).toEqual([1, 2]);
+    expect(queue.size('p1')).toBe(0);
+  });
+});

package/tests/Movement.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from '@jest/globals';
+import { Movement } from '../src/physics/Movement.js';
+import { Entity } from '../src/entities/Entity.js';
+
+describe('Movement', () => {
+  it('integrates velocity into position', () => {
+    const entity = new Entity('e1', 0, 0);
+    entity.setVelocity(50, 100);
+    Movement.integrate(entity, 1000);
+    expect(entity.x).toBe(50);
+    expect(entity.y).toBe(100);
+  });
+
+  it('constrains entity to boundary', () => {
+    const entity = new Entity('e1', -5, 20);
+    const clamped = Movement.constrainToBoundary(entity, {
+      minX: 0,
+      maxX: 100,
+      minY: 0,
+      maxY: 50,
+    });
+
+    expect(clamped).toBe(true);
+    expect(entity.x).toBe(0);
+    expect(entity.y).toBe(20);
+  });
+
+  it('normalizes direction and computes velocity', () => {
+    const normalized = Movement.normalize(3, 4);
+    expect(normalized.x).toBeCloseTo(0.6);
+    expect(normalized.y).toBeCloseTo(0.8);
+
+    const velocity = Movement.velocityFromDirection(0, 2, 10);
+    expect(velocity.vx).toBe(0);
+    expect(velocity.vy).toBe(10);
+  });
+});

package/tests/Network.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, jest } from '@jest/globals';
+import type { Server, Socket } from 'socket.io';
+import { Network } from '../src/network/Network.js';
+
+describe('Network', () => {
+  it('registers sockets and sends events', () => {
+    const network = new Network();
+    const socket = { emit: jest.fn() } as unknown as Socket;
+
+    network.registerSocket('p1', socket);
+    network.sendTo('p1', { op: 'S_TEST', foo: 'bar' });
+
+    expect(socket.emit).toHaveBeenCalledWith('S_TEST', {
+      op: 'S_TEST',
+      foo: 'bar',
+    });
+  });
+
+  it('broadcasts to all and to room', () => {
+    const network = new Network();
+    const emit = jest.fn();
+    const roomEmit = jest.fn();
+
+    const io = {
+      emit,
+      to: jest.fn().mockReturnValue({ emit: roomEmit }),
+    } as unknown as Server;
+
+    network.setServer(io);
+    network.broadcast({ op: 'S_ALL', value: 1 });
+    network.broadcastToRoom('room-1', { op: 'S_ROOM', value: 2 });
+
+    expect(emit).toHaveBeenCalledWith('S_ALL', { op: 'S_ALL', value: 1 });
+    expect(roomEmit).toHaveBeenCalledWith('S_ROOM', {
+      op: 'S_ROOM',
+      value: 2,
+    });
+  });
+});

package/tests/Registry.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from '@jest/globals';
+import { Registry } from '../src/entities/Registry.js';
+import { Entity } from '../src/entities/Entity.js';
+
+describe('Registry', () => {
+  it('adds and removes entities', () => {
+    const registry = new Registry<Entity>();
+    const entity = new Entity('e1', 0, 0);
+
+    registry.add(entity);
+    expect(registry.has('e1')).toBe(true);
+
+    registry.remove('e1');
+    expect(registry.has('e1')).toBe(false);
+  });
+
+  it('tracks dirty entities and clears dirty flags', () => {
+    const registry = new Registry<Entity>();
+    const entity = new Entity('e1', 0, 0);
+    registry.add(entity);
+
+    const dirty = registry.getDirtyEntities();
+    expect(dirty.map((e) => e.id)).toEqual(['e1']);
+    expect(entity.dirty).toBe(false);
+    expect(registry.dirtyCount()).toBe(0);
+  });
+
+  it('filters entities by predicate', () => {
+    const registry = new Registry<Entity>();
+    registry.add(new Entity('e1', 0, 0));
+    registry.add(new Entity('e2', 10, 10));
+
+    const result = registry.filter((e) => e.x > 0);
+    expect(result.map((e) => e.id)).toEqual(['e2']);
+  });
+});

package/tests/RingBuffer.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from '@jest/globals';
+import { RingBuffer } from '../src/utils/RingBuffer.js';
+
+describe('RingBuffer', () => {
+  it('pushes and shifts items in order', () => {
+    const buffer = new RingBuffer<number>(3);
+    expect(buffer.push(1)).toBe(true);
+    expect(buffer.push(2)).toBe(true);
+    expect(buffer.push(3)).toBe(true);
+    expect(buffer.push(4)).toBe(false);
+
+    expect(buffer.shift()).toBe(1);
+    expect(buffer.shift()).toBe(2);
+    expect(buffer.shift()).toBe(3);
+    expect(buffer.shift()).toBeUndefined();
+  });
+
+  it('overwrites oldest when full', () => {
+    const buffer = new RingBuffer<number>(2);
+    buffer.push(10);
+    buffer.push(20);
+
+    const dropped = buffer.pushOverwrite(30);
+    expect(dropped).toBe(10);
+    expect(buffer.shift()).toBe(20);
+    expect(buffer.shift()).toBe(30);
+  });
+
+  it('clears state without reallocating', () => {
+    const buffer = new RingBuffer<number>(2);
+    buffer.push(1);
+    buffer.push(2);
+    buffer.clear();
+    expect(buffer.size()).toBe(0);
+    expect(buffer.isEmpty()).toBe(true);
+    expect(buffer.shift()).toBeUndefined();
+  });
+});

package/tests/Room.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, jest } from '@jest/globals';
+import { Room } from '../src/core/Room.js';
+import type { GameRules } from '../src/core/GameRules.js';
+import { Entity } from '../src/entities/Entity.js';
+import type { MoveCommand } from '../src/input/Command.js';
+
+const move = (seq: number): MoveCommand => ({
+  seq,
+  type: 'move',
+  dir: { x: 1, y: 0 },
+  timestamp: seq,
+});
+
+describe('Room', () => {
+  it('adds and removes players', () => {
+    const rules: GameRules<Entity> = {
+      onRoomCreated: jest.fn(),
+      onPlayerJoin: jest.fn(),
+      onPlayerLeave: jest.fn(),
+      onTick: jest.fn(),
+      onCommand: jest.fn(),
+      shouldEndRoom: jest.fn(() => false),
+    };
+
+    const room = new Room('room-1', rules, { cellSize: 10 });
+    const player = new Entity('p1', 0, 0);
+
+    room.addPlayer(player);
+    expect(rules.onPlayerJoin).toHaveBeenCalledWith(room, player);
+    expect(room.getRegistry().has('p1')).toBe(true);
+
+    room.removePlayer('p1');
+    expect(rules.onPlayerLeave).toHaveBeenCalledWith(room, 'p1');
+    expect(room.getRegistry().has('p1')).toBe(false);
+    expect(room.getGrid().getEntityCount()).toBe(0);
+  });
+
+  it('processes input commands on tick', () => {
+    const rules: GameRules<Entity> = {
+      onRoomCreated: jest.fn(),
+      onPlayerJoin: jest.fn(),
+      onPlayerLeave: jest.fn(),
+      onTick: jest.fn(),
+      onCommand: jest.fn(),
+      shouldEndRoom: jest.fn(() => false),
+    };
+
+    const room = new Room('room-1', rules);
+    const player = new Entity('p1', 0, 0);
+    room.addPlayer(player);
+    room.queueInput('p1', move(1));
+
+    room.onTick(1, 16);
+
+    expect(rules.onCommand).toHaveBeenCalledTimes(1);
+    expect(rules.onTick).toHaveBeenCalledTimes(1);
+  });
+
+  it('creates snapshots and clears dirty entities', () => {
+    const rules: GameRules<Entity> = {
+      onRoomCreated: jest.fn(),
+      onPlayerJoin: jest.fn(),
+      onPlayerLeave: jest.fn(),
+      onTick: jest.fn(),
+      onCommand: jest.fn(),
+      shouldEndRoom: jest.fn(() => false),
+    };
+
+    const room = new Room('room-1', rules);
+    const player = new Entity('p1', 0, 0);
+    room.addPlayer(player);
+
+    const snapshot = room.getSnapshot();
+    expect(snapshot.entities).toHaveLength(1);
+
+    const delta = room.getDeltaSnapshot();
+    expect(delta.entities).toHaveLength(1);
+    expect(room.getRegistry().dirtyCount()).toBe(0);
+  });
+});

package/tests/Snapshot.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from '@jest/globals';
+import { Snapshot } from '../src/network/Snapshot.js';
+import { Entity } from '../src/entities/Entity.js';
+
+describe('Snapshot', () => {
+  it('creates full and delta snapshots', () => {
+    const e1 = new Entity('e1', 1, 2);
+    const e2 = new Entity('e2', 3, 4);
+    e2.setVelocity(5, 6);
+
+    const full = Snapshot.create(10, [e1, e2]);
+    expect(full.tick).toBe(10);
+    expect(full.entities).toHaveLength(2);
+
+    const delta = Snapshot.createDelta(11, [e2]);
+    expect(delta.tick).toBe(11);
+    expect(delta.entities).toEqual([{ id: 'e2', x: 3, y: 4, vx: 5, vy: 6 }]);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  splitting: false,
+  treeshake: true,
+  minify: false,
+  target: 'es2022',
+  outDir: 'dist',
+});