@gamerstake/game-core 0.1.0 → 0.2.0

package/docs/N4-testing-validation.md

@@ -0,0 +1,390 @@
+# N4: @gamerstake/game-core - Testing & Validation Guide
+
+> **Version:** 0.1.0  
+> **Last Updated:** January 2026
+
+---
+
+## Table of Contents
+
+1. [Testing Overview](#1-testing-overview)
+2. [Unit Testing](#2-unit-testing)
+3. [Integration Testing](#3-integration-testing)
+4. [Manual Testing](#4-manual-testing)
+5. [Performance Testing](#5-performance-testing)
+6. [Coverage Requirements](#6-coverage-requirements)
+7. [Validation Checklist](#7-validation-checklist)
+
+---
+
+## 1. Testing Overview
+
+### 1.1 Testing Stack
+
+| Tool             | Purpose                  |
+| ---------------- | ------------------------ |
+| Jest             | Test runner & assertions |
+| ts-jest          | TypeScript support       |
+| socket.io-client | Client mocking           |
+
+### 1.2 Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run with coverage
+pnpm test:coverage
+
+# Run in watch mode
+pnpm test:watch
+
+# Type checking
+pnpm typecheck
+```
+
+---
+
+## 2. Unit Testing
+
+### 2.1 Entity Tests
+
+```typescript
+import { describe, it, expect } from '@jest/globals';
+import { Entity } from '@gamerstake/game-core';
+
+describe('Entity', () => {
+  it('creates entity with initial position', () => {
+    const entity = new Entity('test-1', 100, 200);
+
+    expect(entity.id).toBe('test-1');
+    expect(entity.x).toBe(100);
+    expect(entity.y).toBe(200);
+    expect(entity.dirty).toBe(true);
+  });
+
+  it('updates position based on velocity', () => {
+    const entity = new Entity('test-1', 0, 0);
+    entity.setVelocity(100, 50);
+
+    entity.updatePosition(1000); // 1 second
+
+    expect(entity.x).toBe(100);
+    expect(entity.y).toBe(50);
+  });
+
+  it('marks dirty when position changes', () => {
+    const entity = new Entity('test-1', 0, 0);
+    entity.markClean();
+
+    entity.setPosition(10, 20);
+
+    expect(entity.dirty).toBe(true);
+  });
+});
+```
+
+### 2.2 Room Tests
+
+```typescript
+import { describe, it, expect, jest } from '@jest/globals';
+import { Room, Entity, GameRules } from '@gamerstake/game-core';
+
+const createMockRules = (): GameRules<Entity> => ({
+  onRoomCreated: jest.fn(),
+  onPlayerJoin: jest.fn(),
+  onPlayerLeave: jest.fn(),
+  onTick: jest.fn(),
+  onCommand: jest.fn(),
+  shouldEndRoom: jest.fn(() => false),
+});
+
+describe('Room', () => {
+  it('adds and removes players', () => {
+    const rules = createMockRules();
+    const room = new Room('room-1', rules);
+    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);
+  });
+
+  it('processes input commands on tick', () => {
+    const rules = createMockRules();
+    const room = new Room('room-1', rules);
+    const player = new Entity('p1', 0, 0);
+    room.addPlayer(player);
+
+    room.queueInput('p1', {
+      seq: 1,
+      type: 'move',
+      dir: { x: 1, y: 0 },
+      timestamp: Date.now(),
+    });
+
+    room.onTick(1, 50);
+
+    expect(rules.onCommand).toHaveBeenCalledTimes(1);
+    expect(rules.onTick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### 2.3 Custom Entity Tests
+
+```typescript
+describe('Player Entity', () => {
+  it('handles damage correctly', () => {
+    const player = new Player('p1', 0, 0, 'blue');
+    player.health = 100;
+
+    const died = player.takeDamage(30);
+
+    expect(player.health).toBe(70);
+    expect(died).toBe(false);
+    expect(player.dirty).toBe(true);
+  });
+
+  it('detects death', () => {
+    const player = new Player('p1', 0, 0, 'blue');
+    player.health = 20;
+
+    const died = player.takeDamage(50);
+
+    expect(player.health).toBe(0);
+    expect(died).toBe(true);
+  });
+});
+```
+
+---
+
+## 3. Integration Testing
+
+### 3.1 GameServer Integration
+
+```typescript
+describe('GameServer Integration', () => {
+  it('manages multiple rooms', () => {
+    const server = new GameServer();
+    const rules = createMockRules();
+
+    const room1 = server.createRoom('room-1', rules);
+    const room2 = server.createRoom('room-2', rules);
+
+    expect(server.getRoomCount()).toBe(2);
+    expect(server.getRoom('room-1')).toBe(room1);
+  });
+
+  it('prevents duplicate room IDs', () => {
+    const server = new GameServer();
+    const rules = createMockRules();
+
+    server.createRoom('room-1', rules);
+
+    expect(() => server.createRoom('room-1', rules)).toThrow('already exists');
+  });
+
+  it('provides aggregated metrics', () => {
+    const server = new GameServer();
+    const rules = createMockRules();
+
+    const room1 = server.createRoom('room-1', rules);
+    room1.addPlayer(new Entity('p1', 0, 0));
+    room1.addPlayer(new Entity('p2', 0, 0));
+
+    const metrics = server.getMetrics();
+
+    expect(metrics.roomCount).toBe(1);
+    expect(metrics.totalPlayers).toBe(2);
+  });
+});
+```
+
+---
+
+## 4. Manual Testing
+
+### 4.1 Setup
+
+```bash
+# Build the package
+cd packages/game-core
+pnpm build
+
+# Start test server
+node examples/simple-game/server.js
+
+# In another terminal, start client
+node examples/simple-game/client.js
+```
+
+### 4.2 Test Scenarios
+
+| Scenario     | Steps                      | Expected Result               |
+| ------------ | -------------------------- | ----------------------------- |
+| Connection   | Start server, start client | "Connected! Player ID: xxx"   |
+| Movement     | Connect, wait 1s           | Position updates logged       |
+| Multi-player | Start 3+ clients           | All clients see each other    |
+| Disconnect   | Kill client (Ctrl+C)       | Server logs "Player xxx left" |
+
+### 4.3 Manual Testing Checklist
+
+```markdown
+## Connection Tests
+
+- [ ] Single client connects successfully
+- [ ] Multiple clients connect simultaneously
+- [ ] Client receives S_INIT with player ID
+
+## Movement Tests
+
+- [ ] Player moves when C_MOVE sent
+- [ ] Player stops when C_STOP sent
+- [ ] Position updates broadcast to all clients
+
+## Disconnection Tests
+
+- [ ] Client disconnect handled gracefully
+- [ ] Other clients notified of disconnect
+- [ ] Server continues running after disconnect
+```
+
+---
+
+## 5. Performance Testing
+
+### 5.1 Benchmark Setup
+
+```typescript
+async function runBenchmark(entityCount: number, iterations: number) {
+  const room = new Room('benchmark', new BenchmarkRules(), { cellSize: 512 });
+
+  // Spawn entities
+  for (let i = 0; i < entityCount; i++) {
+    const entity = new Entity(`e${i}`, Math.random() * 1000, Math.random() * 1000);
+    entity.setVelocity(Math.random() * 100, Math.random() * 100);
+    room.spawnEntity(entity);
+  }
+
+  // Benchmark
+  const times: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    room.onTick(i, 50);
+    times.push(performance.now() - start);
+  }
+
+  const avg = times.reduce((a, b) => a + b, 0) / times.length;
+  console.log(`Entities: ${entityCount}, Avg tick: ${avg.toFixed(2)}ms`);
+}
+```
+
+### 5.2 Performance Criteria
+
+| Metric                  | Pass   | Warn     | Fail    |
+| ----------------------- | ------ | -------- | ------- |
+| Avg tick (100 entities) | < 10ms | 10-30ms  | > 30ms  |
+| Avg tick (500 entities) | < 25ms | 25-40ms  | > 40ms  |
+| Max tick                | < 50ms | 50-100ms | > 100ms |
+
+---
+
+## 6. Coverage Requirements
+
+### 6.1 Minimum Coverage
+
+```javascript
+// jest.config.ts
+coverageThreshold: {
+  global: {
+    branches: 80,
+    functions: 80,
+    lines: 80,
+    statements: 80,
+  },
+}
+```
+
+### 6.2 Coverage by Module
+
+| Module     | Target |
+| ---------- | ------ |
+| Entity     | 90%    |
+| Registry   | 85%    |
+| Room       | 85%    |
+| GameServer | 80%    |
+| Grid       | 80%    |
+| InputQueue | 85%    |
+| Network    | 75%    |
+
+---
+
+## 7. Validation Checklist
+
+### 7.1 Pre-Release Validation
+
+```markdown
+## Code Quality
+
+- [ ] All unit tests passing
+- [ ] Coverage >= 80%
+- [ ] No TypeScript errors
+- [ ] No lint errors
+- [ ] Build succeeds
+
+## Integration Tests
+
+- [ ] GameServer manages rooms correctly
+- [ ] Room tick cycle works
+- [ ] Player join/leave handled
+- [ ] Input processing works
+- [ ] State broadcasting works
+
+## Manual Testing
+
+- [ ] Connection test passed
+- [ ] Movement test passed
+- [ ] Multi-player test passed
+- [ ] Disconnection test passed
+
+## Performance
+
+- [ ] Avg tick < 40ms (100 entities)
+- [ ] Max tick < 50ms
+- [ ] No memory leaks
+- [ ] 20 TPS maintained under load
+```
+
+### 7.2 Integration Validation
+
+```markdown
+## Setup Validation
+
+- [ ] Package installed correctly
+- [ ] Imports working
+- [ ] TypeScript types available
+
+## Implementation Validation
+
+- [ ] GameRules implemented completely
+- [ ] All callbacks implemented
+- [ ] Custom entities serialize correctly
+
+## Runtime Validation
+
+- [ ] Room starts and ticks
+- [ ] Players can join
+- [ ] Inputs processed correctly
+- [ ] State synchronized
+```
+
+---
+
+**Previous:** [N3 - Implementation Guide](./N3-implementation-guide.md)  
+**Next:** [N5 - Integration Checklist](./N5-integration-checklist.md)

package/docs/N5-integration-checklist.md

@@ -0,0 +1,90 @@
+# N5: Integration Checklist
+
+> Version: 0.1.0
+
+## Phase 1: Environment Setup
+
+### Prerequisites
+
+- [ ] Node.js 20+ installed
+- [ ] pnpm available
+- [ ] TypeScript installed
+
+### Installation
+
+```bash
+pnpm add @gamerstake/game-core socket.io
+pnpm add -D typescript @types/node tsx
+```
+
+## Phase 2: Implementation
+
+### GameRules Checklist
+
+- [ ] onRoomCreated implemented
+- [ ] onPlayerJoin implemented
+- [ ] onPlayerLeave implemented
+- [ ] onTick implemented
+- [ ] onCommand implemented
+- [ ] shouldEndRoom implemented
+
+### Server Checklist
+
+- [ ] Socket.io server created
+- [ ] GameServer instance created
+- [ ] Room created with config
+- [ ] Connection handler with addPlayer
+- [ ] C_MOVE and C_STOP handlers
+- [ ] Disconnect handler with removePlayer
+
+## Phase 3: Testing
+
+### Unit Tests
+
+- [ ] Entity tests passing
+- [ ] Room tests passing
+- [ ] GameRules tests passing
+
+### Manual Tests
+
+- [ ] Server starts
+- [ ] Client connects
+- [ ] Movement works
+- [ ] Multiple players work
+- [ ] Disconnect handled
+
+## Phase 4: Verification
+
+| Feature               | Pass |
+| --------------------- | ---- |
+| S_INIT received       | [ ]  |
+| S_UPDATE received     | [ ]  |
+| Movement works        | [ ]  |
+| Other players visible | [ ]  |
+
+### Performance
+
+- [ ] Avg tick < 40ms
+- [ ] Max tick < 50ms
+- [ ] 20 TPS maintained
+
+## Phase 5: Production
+
+- [ ] Error handling added
+- [ ] Graceful shutdown
+- [ ] Input validation
+- [ ] Logging configured
+
+## Sign-Off
+
+| Phase          | Complete |
+| -------------- | -------- |
+| Environment    | [ ]      |
+| Implementation | [ ]      |
+| Testing        | [ ]      |
+| Verification   | [ ]      |
+| Production     | [ ]      |
+
+---
+
+**Previous:** [N4 - Testing](./N4-testing-validation.md)

package/docs/README.md

@@ -0,0 +1,137 @@
+# @gamerstake/game-core - Package Documentation
+
+> **For External Teams**  
+> **Version:** 0.1.0  
+> **Last Updated:** January 2026
+
+---
+
+## Welcome
+
+This documentation package provides everything you need to integrate `@gamerstake/game-core` into your multiplayer game. The package is a battle-tested, high-performance multiplayer game engine that handles real-time networking, game loops, entity management, and state synchronization.
+
+---
+
+## Document Index
+
+| Document                                                    | Description                                    | Audience      |
+| ----------------------------------------------------------- | ---------------------------------------------- | ------------- |
+| [N1 - Package Overview](./N1-package-overview.md)           | Executive summary, requirements, core concepts | Everyone      |
+| [N2 - API Reference](./N2-api-reference.md)                 | Complete API documentation                     | Developers    |
+| [N3 - Implementation Guide](./N3-implementation-guide.md)   | Step-by-step implementation tutorial           | Developers    |
+| [N4 - Testing & Validation](./N4-testing-validation.md)     | Testing requirements and patterns              | QA/Developers |
+| [N5 - Integration Checklist](./N5-integration-checklist.md) | Verification checklist for integration         | All Teams     |
+
+---
+
+## Quick Navigation
+
+### Just Getting Started?
+
+1. **Read** [N1 - Package Overview](./N1-package-overview.md) to understand what game-core provides
+2. **Follow** [N3 - Implementation Guide](./N3-implementation-guide.md) Quick Start section
+3. **Use** [N5 - Integration Checklist](./N5-integration-checklist.md) to verify your setup
+
+### Need API Details?
+
+- [N2 - API Reference](./N2-api-reference.md) has complete documentation for all exports
+
+### Setting Up Testing?
+
+- [N4 - Testing & Validation](./N4-testing-validation.md) covers unit tests, integration tests, and performance testing
+
+---
+
+## What game-core Provides
+
+- **Fixed tick-rate game loop** (20 TPS with drift compensation)
+- **Authoritative server architecture** (server is source of truth)
+- **Client-server networking** (via Socket.io)
+- **State synchronization** (full snapshots + delta updates)
+- **Input buffering** (reliable command processing)
+- **Entity management** (ECS-lite with dirty tracking)
+- **Spatial partitioning** (grid-based O(1) queries)
+- **Basic 2D physics** (velocity, position, AABB collision)
+
+## What You Provide
+
+- **Game rules** (implement the `GameRules` interface)
+- **Game client** (render game state, send inputs)
+- **Persistence** (optional - save/load game state)
+- **Authentication** (optional - player identity)
+
+---
+
+## Minimum Example
+
+```typescript
+// 1. Implement GameRules
+import { GameRules, Room, Entity, Command, MoveCommand } from '@gamerstake/game-core';
+
+class MyGameRules implements GameRules {
+  onRoomCreated(room: Room): void {}
+  onPlayerJoin(room: Room, player: Entity): void {
+    player.setPosition(Math.random() * 800, Math.random() * 600);
+  }
+  onPlayerLeave(room: Room, playerId: string): void {}
+  onTick(room: Room, delta: number): void {
+    room.getRegistry().forEach((e) => e.updatePosition(delta));
+  }
+  onCommand(room: Room, playerId: string, command: Command): void {
+    const player = room.getRegistry().get(playerId);
+    if (!player) return;
+    if (command.type === 'move') {
+      const { dir } = command as MoveCommand;
+      player.setVelocity(dir.x * 200, dir.y * 200);
+    }
+  }
+  shouldEndRoom(room: Room): boolean {
+    return false;
+  }
+}
+
+// 2. Create server
+import { Server } from 'socket.io';
+import { GameServer, Entity } from '@gamerstake/game-core';
+
+const io = new Server(3000);
+const gameServer = new GameServer();
+gameServer.setServer(io);
+
+const room = gameServer.createRoom('main', new MyGameRules());
+
+io.on('connection', (socket) => {
+  const player = new Entity(socket.id, 0, 0);
+  room.addPlayer(player);
+  room.getNetwork().registerSocket(socket.id, socket);
+
+  socket.emit('S_INIT', { playerId: socket.id, ...room.getSnapshot() });
+
+  socket.on('C_MOVE', (data) => {
+    room.queueInput(socket.id, { ...data, type: 'move', timestamp: Date.now() });
+  });
+
+  socket.on('disconnect', () => {
+    room.removePlayer(socket.id);
+    room.getNetwork().unregisterSocket(socket.id);
+  });
+});
+```
+
+---
+
+## Version History
+
+| Version | Date         | Changes         |
+| ------- | ------------ | --------------- |
+| 0.1.0   | January 2026 | Initial release |
+
+---
+
+## Support
+
+For questions or issues, contact the GamerStake engineering team.
+
+---
+
+**Start with:** [N1 - Package Overview](./N1-package-overview.md)

package/examples/simple-game/README.md

@@ -27,6 +27,7 @@ node examples/simple-game/server.js
 ```
 
 You should see:
+
 ```
 Game server started on port 3000
 Room: test-room
@@ -40,6 +41,7 @@ node examples/simple-game/client.js
 ```
 
 The client will:
+
 - Connect to the server
 - Receive initial game state
 - Automatically move around in different patterns
@@ -75,6 +77,7 @@ Each client is a separate player. You'll see them join in the server logs!
 ### Test 1: Movement
 
 The client automatically cycles through movement patterns:
+
 - Right, Down, Left, Up
 - Diagonal movement
 - Stop command
@@ -83,6 +86,7 @@ The client automatically cycles through movement patterns:
 ### Test 2: Multiple Players
 
 Run 3-5 clients simultaneously to test:
+
 - Multiple players in the same room
 - State synchronization
 - Network broadcasting
@@ -91,6 +95,7 @@ Run 3-5 clients simultaneously to test:
 ### Test 3: Performance
 
 Monitor the server metrics logs:
+
 ```
 Room: X players, Y entities, Avg tick: Zms
 ```
@@ -100,6 +105,7 @@ Tick time should stay well below 50ms (the tick budget for 20 TPS).
 ### Test 4: Connection Stability
 
 Try:
+
 - Stopping clients (Ctrl+C) and reconnecting
 - Stopping the server and restarting
 - Network interruptions
@@ -119,6 +125,7 @@ SERVER_URL=http://localhost:4000 node examples/simple-game/client.js
 ### Modify Game Rules
 
 Edit `server.ts` and change the `SimpleGameRules` class:
+
 - Spawn different entities
 - Change movement speed
 - Add collision detection
@@ -127,14 +134,15 @@ Edit `server.ts` and change the `SimpleGameRules` class:
 ### Add More Commands
 
 In `server.ts`, add new socket event handlers:
+
 ```typescript
 socket.on('C_CUSTOM', (data) => {
- room.queueInput(playerId, {
- seq: data.seq,
- type: 'custom',
- // ...custom data
- timestamp: Date.now(),
- });
+  room.queueInput(playerId, {
+    seq: data.seq,
+    type: 'custom',
+    // ...custom data
+    timestamp: Date.now(),
+  });
 });
 ```
 
@@ -145,6 +153,7 @@ Then handle it in `onCommand()`.
 ### "Cannot find module './dist/index.js'"
 
 You need to build the package first:
+
 ```bash
 pnpm build
 ```
@@ -152,6 +161,7 @@ pnpm build
 ### "Port 3000 already in use"
 
 Change the port:
+
 ```bash
 PORT=4000 node examples/simple-game/server.js
 ```
@@ -159,6 +169,7 @@ PORT=4000 node examples/simple-game/server.js
 ### Client can't connect
 
 Make sure:
+
 1. Server is running
 2. Port matches (default 3000)
 3. No firewall blocking