This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This is a real-time multiplayer game engine implementing authoritative server architecture with client-side prediction, server reconciliation, and entity interpolation. The project is organized into separate client, server, and shared folders for proper separation of concerns.
Based on Gabriel Gambetta's articles, this implementation follows these core principles:
- Server owns all game state to prevent cheating
- Clients send inputs (not state changes) to the server
- Server validates inputs and broadcasts authoritative updates
- Challenge: Network latency (50-500ms) makes direct implementation feel unresponsive
- Clients immediately apply inputs locally for responsiveness
- Each input has a sequence number for tracking
- Pending inputs are stored in a buffer for later reconciliation
- Most predictions are correct in well-designed games
Algorithm implementation:
- Client sends input with sequence number
- Client applies input locally (prediction)
- Server processes input and returns last processed sequence
- Client receives server state update
- Client discards acknowledged inputs
- Client replays unacknowledged inputs from buffer
- Other players render 100ms in the past for smooth movement
- Position updates are buffered for interpolation
- Linear interpolation between known states prevents teleporting
- Trade-off: Visual delay for smoothness
- Ghost Visualization: Shows server's authoritative position as semi-transparent overlay
- Interpolation Visualization: Shows buffered positions for other entities
- Real-time Stats: Connection status, pending inputs, enabled features
realtime/
├── client/ # Browser-based game client
│ ├── index.html # Main game UI with dual canvas (game + debug)
│ └── Client.js # Client implementation with prediction/reconciliation
├── server/ # Node.js authoritative server
│ ├── Server.js # WebSocket server with game loop
│ └── package.json # Server dependencies (ws)
└── shared/ # Shared game logic
├── Entity.js # Game entity with position and movement
└── Input.js # Input data structure with serialization
- 2D position (x, y) with velocity
- Movement speed: 200 pixels/second
- Bounded to 800x600 canvas
- Position buffer for interpolation
- Delta-time based movement
- Sequence numbering for reconciliation
- Input validation on server (max 100ms deltaTime)
- Diagonal movement normalization
- WebSocket for real-time communication
- Message types: connected, worldState, playerJoined, playerLeft, input
- Server runs at 10Hz update rate
- Client runs at 60 FPS
- Main canvas: Rendered game state with prediction
- Debug canvas: Ghost positions, interpolation points, stats
- Toggle controls for all networking features
- Adjustable interpolation delay
cd server
npm install
npm start
Open
client/index.html
in a web browser. Connect multiple clients to test multiplayer features.
The implementation allows real-time toggling of:
- Client-side prediction
- Server reconciliation
- Entity interpolation
- Interpolation delay (0-500ms)
- Ghost visualization
This helps understand how each technique affects gameplay under various network conditions.
- Server validates all inputs to prevent cheating
- Entity movement is deterministic for accurate prediction
- Position updates include sequence numbers for reconciliation
- Debug view essential for understanding networking behavior