@gamerstake/game-core 0.1.0

package/MANUAL_TESTING.md

@@ -0,0 +1,369 @@
+# Manual Testing Guide
+
+This guide explains how to manually test the `@gamerstake/game-core` package with a live server and clients.
+
+## Why Manual Testing?
+
+While automated tests verify individual components, **manual testing lets you**:
+
+See the game engine running in real-time
+Test networking and state synchronization
+Monitor performance metrics
+Simulate real player behavior
+Debug issues interactively
+
+## Quick Start
+
+### Step 1: Build the Package
+
+```bash
+cd /Users/nbjekovic/GAMESTAKES/gamerstake/packages/game-core
+pnpm build
+```
+
+### Step 2: Start the Test Server
+
+```bash
+node examples/simple-game/server.js
+```
+
+**Expected output:**
+
+```
+ Game server started on port 3000
+ Room: test-room
+ Tick rate: 20 TPS
+
+ Connect with: node examples/simple-game/client.js
+```
+
+The server:
+
+- Runs a game loop at **20 TPS** (50ms per tick)
+- Creates a persistent world (1000x1000 units)
+- Spawns 5 random obstacle entities
+- Logs player activity and metrics
+
+### Step 3: Connect Clients
+
+**In a new terminal:**
+
+```bash
+node examples/simple-game/client.js
+```
+
+**Expected output:**
+
+```
+ Connecting to server: http://localhost:3000
+ Connected! Socket ID: abc123
+ Initialized! Player ID: abc123
+ Initial entities: 6
+ You are at (542, 789)
+
+ Starting movement test...
+
+ Moving right
+ Position: (592, 789) | Velocity: (200, 0) | Total entities: 6
+ Moving down
+ Position: (592, 839) | Velocity: (0, 200) | Total entities: 6
+```
+
+The client:
+
+- Connects to the server
+- Receives initial game state
+- **Automatically moves in patterns** (right, down, left, up, diagonal)
+- Logs position updates every 20 ticks
+- Demonstrates all command types (move, stop, action)
+
+### Step 4: Test with Multiple Clients
+
+**Open 3-4 more terminals and run:**
+
+```bash
+node examples/simple-game/client.js # Terminal 3
+node examples/simple-game/client.js # Terminal 4
+node examples/simple-game/client.js # Terminal 5
+```
+
+**On the server, you'll see:**
+
+```
+ Socket connected: def456
+ Player def456 joined at (234, 567)
+ Player def456 joined at (234, 567)
+
+ Socket connected: ghi789
+ Player ghi789 joined at (890, 123)
+```
+
+## What to Observe
+
+### On the Server Side
+
+**Player Lifecycle**
+
+```
+ Socket connected: <id>
+ Player <id> joined at (x, y)
+ Player <id> moving: (dx, dy)
+⏸ Player <id> stopped
+ Player <id> performed action: {"action":"jump","height":100}
+ Player <id> left
+```
+
+**Performance Metrics** (every 10 seconds)
+
+```
+ Room: 3 players, 8 entities, Avg tick: 12.34ms
+```
+
+**Good tick time:** < 40ms (80% of 50ms budget)
+**Warning:** > 40ms means optimization needed
+**Critical:** > 50ms means dropped frames
+
+### On the Client Side
+
+**State Synchronization**
+
+```
+ Position: (100, 200) | Velocity: (200, 0) | Total entities: 8
+```
+
+- Position updates smoothly as player moves
+- Total entities increases as more players join
+- Other players' positions are received in updates
+
+  **Multiplayer Events**
+
+```
+ Player def456 joined at (234, 567)
+ Player ghi789 performed action: jump
+ Player def456 left
+```
+
+## Testing Scenarios
+
+### Scenario 1: Basic Functionality
+
+**Goal:** Verify core features work
+
+1. Start server
+2. Connect 1 client
+3. Watch client move automatically
+4. Verify position updates on both sides
+
+**Expected:**
+
+- Player spawns at random position
+- Movement commands processed correctly
+- State broadcasted every tick (50ms)
+
+### Scenario 2: Multiplayer
+
+**Goal:** Test multiple players
+
+1. Start server
+2. Connect 3-5 clients simultaneously
+3. Watch all clients move in different patterns
+4. Stop one client (Ctrl+C), verify others continue
+
+**Expected:**
+
+- All players see each other
+- State synchronized across clients
+- Server handles disconnections gracefully
+- No crashes or errors
+
+### Scenario 3: Performance
+
+**Goal:** Verify performance under load
+
+1. Start server
+2. Connect 10+ clients
+3. Watch server metrics logs
+4. Monitor tick time
+
+**Expected:**
+
+- Tick time stays < 40ms
+- No memory leaks over time
+- Smooth updates for all clients
+
+### Scenario 4: Connection Stability
+
+**Goal:** Test network reliability
+
+1. Start server with 2-3 clients
+2. Stop and restart a client
+3. Stop and restart the server
+4. Simulate poor network (if possible)
+
+**Expected:**
+
+- Clients reconnect successfully
+- State resynchronized on reconnect
+- Graceful error handling
+
+### Scenario 5: Commands
+
+**Goal:** Verify input processing
+
+The automated client cycles through:
+
+- **Move commands** (right, down, left, up, diagonal)
+- **Stop command** (velocity = 0)
+- **Action command** (custom game event)
+
+**Expected:**
+
+- All command types processed
+- Server logs show correct commands
+- State updated accordingly
+
+## Customizing Tests
+
+### Change Server Port
+
+```bash
+PORT=4000 node examples/simple-game/server.js
+```
+
+```bash
+SERVER_URL=http://localhost:4000 node examples/simple-game/client.js
+```
+
+### Modify Client Behavior
+
+Edit `examples/simple-game/client.ts` to:
+
+- Change movement patterns
+- Add custom commands
+- Test specific scenarios
+- Simulate player behavior
+
+### Modify Server Rules
+
+Edit `examples/simple-game/server.ts` to:
+
+- Change world size or boundaries
+- Add collision detection
+- Implement game mechanics
+- Test custom logic
+
+## Troubleshooting
+
+### Server won't start
+
+**"Port 3000 already in use"**
+
+**Solution:**
+
+```bash
+PORT=4000 node examples/simple-game/server.js
+```
+
+Or kill the process using port 3000:
+
+```bash
+lsof -ti:3000 | xargs kill
+```
+
+---
+
+**"Cannot find module './dist/index.js'"**
+
+**Solution:** Build the package first:
+
+```bash
+pnpm build
+```
+
+### Client can't connect
+
+**"Connection error: xhr poll error"**
+
+**Check:**
+
+1. Is the server running?
+2. Is the port correct? (default: 3000)
+3. Is there a firewall blocking?
+4. Try `localhost` vs `127.0.0.1`
+
+---
+
+**Client connects but no updates**
+
+**Check:**
+
+1. Are you seeing `S_INIT` event?
+2. Check server logs for errors
+3. Verify client is sending commands
+
+### Performance Issues
+
+**Tick time > 50ms**
+
+**Causes:**
+
+- Too many entities
+- Expensive operations in `onTick()`
+- Not using spatial grid for queries
+- Memory leak (growing entity count)
+
+**Solutions:**
+
+- Profile with console.time()
+- Use grid for spatial queries
+- Limit entity count
+- Check for memory leaks
+
+## Interpreting Results
+
+### Success Indicators
+
+- Server starts without errors
+- Clients connect successfully
+- Position updates smoothly
+- Tick time < 40ms consistently
+- Multiple clients work simultaneously
+- No crashes or disconnects
+
+### Warning Signs
+
+- Tick time 40-50ms (optimization recommended)
+- Occasional disconnects
+- Delayed state updates
+- Growing memory usage
+
+### Failure Indicators
+
+- Tick time > 50ms (dropping frames)
+- Clients can't connect
+- Frequent crashes
+- State desync between clients
+- Memory leaks
+
+## Next Steps
+
+After manual testing works:
+
+1. **Build your game** - Use this as a template
+2. **Add game mechanics** - Combat, items, scoring
+3. **Create a UI client** - Web-based with Canvas/Phaser
+4. **Add automated tests** - For your game rules
+5. **Deploy** - Docker, cloud hosting
+
+See the **Developer Guide** for building complete games!
+
+## Additional Resources
+
+- **[Quick Start](./QUICK_START.md)** - Get started in 5 minutes
+- **[Developer Guide](./DEVELOPER_GUIDE.md)** - Complete game development guide
+- **[Example Code](./examples/simple-game/)** - Server and client source code
+- **[Automated Tests](./tests/)** - Unit test examples
+
+---
+
+**Happy testing! **

package/QUICK_START.md

@@ -0,0 +1,368 @@
+# Quick Start Guide
+
+**Get a multiplayer game running in 5 minutes!**
+
+## Prerequisites
+
+```bash
+node --version # Should be 20+
+```
+
+## 1. Installation
+
+```bash
+pnpm add @gamerstake/game-core socket.io
+pnpm add -D socket.io-client typescript @types/node
+```
+
+## 2. Create Game Rules
+
+Create `server.ts`:
+
+```typescript
+import { Server } from 'socket.io';
+import { GameServer, GameRules, Room, Entity, Command, MoveCommand } from '@gamerstake/game-core';
+
+// Step 1: Define your game logic
+class MyGameRules implements GameRules {
+  onRoomCreated(room: Room) {
+    console.log(' Room created!');
+  }
+
+  onPlayerJoin(room: Room, player: Entity) {
+    // Spawn player at random position
+    player.setPosition(Math.random() * 1000, Math.random() * 1000);
+    console.log(` Player ${player.id} joined`);
+  }
+
+  onPlayerLeave(room: Room, playerId: string) {
+    console.log(` Player ${playerId} left`);
+  }
+
+  onTick(room: Room, delta: number) {
+    // Update all moving entities
+    room.getRegistry().forEach((entity) => {
+      if (entity.vx !== 0 || entity.vy !== 0) {
+        entity.updatePosition(delta);
+      }
+    });
+  }
+
+  onCommand(room: Room, playerId: string, command: Command) {
+    const player = room.getRegistry().get(playerId);
+    if (!player) return;
+
+    if (command.type === 'move') {
+      const moveCmd = command as MoveCommand;
+      const speed = 200;
+
+      // Normalize direction and apply speed
+      const len = Math.hypot(moveCmd.dir.x, moveCmd.dir.y);
+      if (len > 0) {
+        player.setVelocity((moveCmd.dir.x / len) * speed, (moveCmd.dir.y / len) * speed);
+      }
+    } else if (command.type === 'stop') {
+      player.setVelocity(0, 0);
+    }
+  }
+
+  shouldEndRoom(room: Room) {
+    return false; // Persistent world
+  }
+}
+
+// Step 2: Create server and room
+const io = new Server(3000, { cors: { origin: '*' } });
+const gameServer = new GameServer();
+gameServer.setServer(io);
+
+const room = gameServer.createRoom('my-room', new MyGameRules(), {
+  tickRate: 20,
+  cellSize: 512,
+});
+
+// Step 3: Handle connections
+io.on('connection', (socket) => {
+  const playerId = socket.id;
+
+  // Create player entity
+  const player = new Entity(playerId, 0, 0);
+  room.addPlayer(player);
+  room.getNetwork().registerSocket(playerId, socket);
+
+  // Send initial state
+  socket.emit('S_INIT', {
+    playerId,
+    ...room.getSnapshot(),
+  });
+
+  // Handle player inputs
+  socket.on('C_MOVE', (data) => {
+    room.queueInput(playerId, {
+      seq: data.seq,
+      type: 'move',
+      dir: data.dir,
+      timestamp: Date.now(),
+    });
+  });
+
+  socket.on('C_STOP', (data) => {
+    room.queueInput(playerId, {
+      seq: data.seq,
+      type: 'stop',
+      timestamp: Date.now(),
+    });
+  });
+
+  socket.on('disconnect', () => {
+    room.removePlayer(playerId);
+    room.getNetwork().unregisterSocket(playerId);
+  });
+});
+
+console.log(' Server running on http://localhost:3000');
+```
+
+## 3. Run the Server
+
+```bash
+npx tsx server.ts
+```
+
+You should see:
+
+```
+ Server running on http://localhost:3000
+```
+
+## 4. Create a Test Client
+
+Create `client.ts`:
+
+```typescript
+import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:3000');
+let seq = 0;
+
+socket.on('S_INIT', (data) => {
+  console.log(' Connected! Player ID:', data.playerId);
+  console.log(' Entities:', data.entities.length);
+
+  // Start moving right after 1 second
+  setTimeout(() => {
+    console.log(' Moving right...');
+    socket.emit('C_MOVE', {
+      seq: ++seq,
+      dir: { x: 1, y: 0 },
+    });
+  }, 1000);
+});
+
+socket.on('S_UPDATE', (data) => {
+  const player = data.entities?.find((e) => e.id === socket.id);
+  if (player && seq % 20 === 0) {
+    console.log(` Position: (${player.x.toFixed(0)}, ${player.y.toFixed(0)})`);
+  }
+});
+
+socket.on('connect_error', (err) => {
+  console.error(' Connection failed:', err.message);
+});
+```
+
+## 5. Run the Client
+
+In a new terminal:
+
+```bash
+npx tsx client.ts
+```
+
+You should see:
+
+```
+ Connected! Player ID: abc123
+ Entities: 1
+ Moving right...
+ Position: (50, 0)
+ Position: (100, 0)
+```
+
+## 6. Test with Multiple Clients
+
+Open more terminals and run more clients:
+
+```bash
+npx tsx client.ts # Terminal 3
+npx tsx client.ts # Terminal 4
+npx tsx client.ts # Terminal 5
+```
+
+Watch the server logs to see all players connecting!
+
+## What Just Happened?
+
+You created a **multiplayer game server** with game-core
+The server runs a **game loop at 20 TPS** (20 ticks per second)
+Players can **join and move around** in real-time
+The server **broadcasts state updates** to all clients
+All inputs are **processed server-side** (authoritative)
+
+## Next Steps
+
+### 1. Manual Testing
+
+Use the built-in example:
+
+```bash
+# Build the package
+pnpm build
+
+# Run the example server
+node examples/simple-game/server.js
+
+# In another terminal, run a client
+node examples/simple-game/client.js
+```
+
+### 2. Build a Real Game
+
+Check out the **Developer Guide** (`DEVELOPER_GUIDE.md`) for:
+
+- Complete tag game tutorial
+- Custom entity types
+- Collision detection
+- Advanced patterns
+- Performance optimization
+
+### 3. Add a Client UI
+
+Create a web-based client with:
+
+- **Canvas** for 2D rendering
+- **Phaser** for game development
+- **Three.js** for 3D graphics
+
+### 4. Add Features
+
+- **Combat system** - Health, damage, abilities
+- **Inventory** - Items, equipment, crafting
+- **Persistence** - Save/load game state
+- **Matchmaking** - Create/join rooms
+- **Chat** - In-game messaging
+
+## Common Issues
+
+### "Cannot find module '@gamerstake/game-core'"
+
+If developing locally in a monorepo, build the package first:
+
+```bash
+pnpm build
+```
+
+### "Port 3000 already in use"
+
+Change the port:
+
+```typescript
+const io = new Server(4000, { cors: { origin: '*' } });
+```
+
+### Client can't connect
+
+Check:
+
+1. Server is running
+2. Port matches (default 3000)
+3. No firewall blocking
+
+## Architecture Quick Reference
+
+```
+Client Server
+
+ C_MOVE > [InputQueue]
+
+ [Game Tick]
+ - onCommand()
+ - onTick()
+
+ < S_UPDATE [Network]
+
+ [Render]
+```
+
+## API Cheat Sheet
+
+### Server Side
+
+```typescript
+// Create room
+const room = gameServer.createRoom(id, rules, config);
+
+// Add/remove players
+room.addPlayer(entity);
+room.removePlayer(playerId);
+
+// Spawn/destroy entities
+room.spawnEntity(entity);
+room.destroyEntity(entityId);
+
+// Networking
+room.broadcast(event);
+room.sendTo(playerId, event);
+
+// Get state
+const snapshot = room.getSnapshot();
+const entity = room.getRegistry().get(id);
+```
+
+### Client Side
+
+```typescript
+// Connect
+const socket = io('http://localhost:3000');
+
+// Receive events
+socket.on('S_INIT', (data) => {
+  /* initial state */
+});
+socket.on('S_UPDATE', (data) => {
+  /* delta update */
+});
+
+// Send inputs
+socket.emit('C_MOVE', { seq: 1, dir: { x: 1, y: 0 } });
+socket.emit('C_STOP', { seq: 2 });
+```
+
+## Testing
+
+```bash
+# Run unit tests
+pnpm test
+
+# Run with coverage
+pnpm test:coverage
+
+# Type check
+pnpm typecheck
+
+# Build
+pnpm build
+```
+
+## Resources
+
+- **Developer Guide** - `DEVELOPER_GUIDE.md` - Complete guide with examples
+- **Examples** - `examples/` - Working game examples
+- **Tests** - `tests/` - Usage patterns
+- **API Docs** - `README.md` - Full API reference
+
+---
+
+**You're ready to build multiplayer games! **
+
+For more advanced usage, see the **Developer Guide**.