Real-Time Multiplayer Skill
Overview
This skill provides expertise for building real-time multiplayer games using WebSockets and Socket.io. It covers connection management, state synchronization, latency handling, and the specific challenges of turn-based games with real-time updates.
Core Architecture
Client-Server Model for Games
┌─────────────┐ WebSocket ┌─────────────┐
│ Client │◄──────────────────►│ Server │
│ (Browser) │ │ (Node.js) │
└─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Local UI │ │ Game State │
│ State │ │ (Source │
│ (Optimistic) │ of Truth) │
└─────────────┘ └─────────────┘Key Principle: The server is the authoritative source of truth. Clients can have optimistic local state for responsiveness, but server state always wins on conflict.
Socket.io Setup Pattern
// Server setup
const io = require('socket.io')(server, {
cors: { origin: process.env.CLIENT_URL },
pingTimeout: 60000,
pingInterval: 25000
});
io.on('connection', (socket) => {
// Join game room
socket.on('join-game', ({ gameId, playerId }) => {
socket.join(`game:${gameId}`);
socket.gameId = gameId;
socket.playerId = playerId;
});
// Handle game actions
socket.on('game-action', async (action) => {
const result = await processAction(socket.gameId, socket.playerId, action);
if (result.success) {
// Broadcast to all players in game
io.to(`game:${socket.gameId}`).emit('state-update', result.newState);
} else {
// Send error only to acting player
socket.emit('action-error', result.error);
}
});
// Handle disconnection
socket.on('disconnect', () => {
handlePlayerDisconnect(socket.gameId, socket.playerId);
});
});Room Management
Game Rooms Pattern
Each game instance should be a Socket.io room:
// Room naming convention
const roomName = `game:${gameId}`;
// Player joins game
socket.join(roomName);
// Broadcast to all players in game
io.to(roomName).emit('event', data);
// Send to specific player
io.to(playerSocketId).emit('private-event', data);
// Send to all except sender
socket.to(roomName).emit('event', data);Player Presence Tracking
const gamePresence = new Map(); // gameId -> Set of playerIds
function trackPresence(gameId, playerId, isOnline) {
if (!gamePresence.has(gameId)) {
gamePresence.set(gameId, new Set());
}
const players = gamePresence.get(gameId);
if (isOnline) {
players.add(playerId);
} else {
players.delete(playerId);
}
// Notify other players
io.to(`game:${gameId}`).emit('presence-update', {
playerId,
isOnline,
onlinePlayers: Array.from(players)
});
}State Synchronization
Event Types
Define clear event categories:
// Server -> Client events
const ServerEvents = {
STATE_SYNC: 'state-sync', // Full state (on join/reconnect)
STATE_UPDATE: 'state-update', // Partial state change
ACTION_RESULT: 'action-result', // Response to player action
PLAYER_JOINED: 'player-joined',
PLAYER_LEFT: 'player-left',
GAME_STARTED: 'game-started',
TURN_CHANGED: 'turn-changed',
GAME_ENDED: 'game-ended'
};
// Client -> Server events
const ClientEvents = {
JOIN_GAME: 'join-game',
LEAVE_GAME: 'leave-game',
GAME_ACTION: 'game-action',
REQUEST_SYNC: 'request-sync',
PING: 'ping'
};Delta Updates vs Full Sync
// Send delta updates for efficiency
function sendDelta(gameId, changes) {
io.to(`game:${gameId}`).emit('state-update', {
type: 'delta',
changes,
version: gameState.version
});
}
// Send full state on reconnect or desync
function sendFullSync(socket, gameState) {
socket.emit('state-sync', {
type: 'full',
state: gameState,
version: gameState.version
});
}Version Vectors for Consistency
// Track state version to detect desync
let stateVersion = 0;
function applyAction(action) {
// Validate and apply
const newState = reducer(currentState, action);
stateVersion++;
return {
state: newState,
version: stateVersion
};
}
// Client requests sync if versions mismatch
socket.on('state-update', ({ version, changes }) => {
if (version !== localVersion + 1) {
socket.emit('request-sync'); // Ask for full state
}
});Handling Disconnections
Reconnection Strategy
// Client-side reconnection
const socket = io(SERVER_URL, {
reconnection: true,
reconnectionAttempts: 10,
reconnectionDelay: 1000,
reconnectionDelayMax: 5000
});
socket.on('connect', () => {
if (currentGameId) {
// Rejoin game room after reconnect
socket.emit('join-game', {
gameId: currentGameId,
playerId: myPlayerId,
lastVersion: localStateVersion // For delta sync
});
}
});
socket.on('disconnect', () => {
showReconnectingUI();
});Grace Period for Disconnects
// Server-side: Don't immediately remove disconnected players
const disconnectTimers = new Map();
function handlePlayerDisconnect(gameId, playerId) {
// Mark as disconnected but give grace period
updatePresence(gameId, playerId, false);
const timer = setTimeout(() => {
// After grace period, handle as true disconnect
handlePlayerTimeout(gameId, playerId);
}, 60000); // 60 second grace period
disconnectTimers.set(`${gameId}:${playerId}`, timer);
}
function handlePlayerReconnect(gameId, playerId) {
// Cancel timeout if player reconnects
const key = `${gameId}:${playerId}`;
if (disconnectTimers.has(key)) {
clearTimeout(disconnectTimers.get(key));
disconnectTimers.delete(key);
}
updatePresence(gameId, playerId, true);
}Turn-Based Game Patterns
Turn Timer Implementation
class TurnTimer {
constructor(gameId, onTimeout) {
this.gameId = gameId;
this.onTimeout = onTimeout;
this.timer = null;
}
start(playerId, durationMs) {
this.clear();
const endTime = Date.now() + durationMs;
// Broadcast timer start to all clients
io.to(`game:${this.gameId}`).emit('turn-timer', {
playerId,
endTime,
durationMs
});
this.timer = setTimeout(() => {
this.onTimeout(playerId);
}, durationMs);
}
clear() {
if (this.timer) {
clearTimeout(this.timer);
this.timer = null;
}
}
}Action Validation
// Always validate on server
async function processAction(gameId, playerId, action) {
const game = await getGame(gameId);
// Validate it's player's turn
if (game.currentPlayer !== playerId) {
return { success: false, error: 'Not your turn' };
}
// Validate action is legal
const validationResult = validateAction(game.state, action);
if (!validationResult.valid) {
return { success: false, error: validationResult.reason };
}
// Apply action
const newState = applyAction(game.state, action);
await saveGame(gameId, newState);
return { success: true, newState };
}Optimistic Updates
Client-Side Pattern
// For responsive UI, apply optimistically then reconcile
function handlePlayerAction(action) {
// 1. Optimistically apply locally
const optimisticState = reducer(localState, action);
renderUI(optimisticState);
// 2. Send to server
socket.emit('game-action', action, (response) => {
if (response.success) {
// 3a. Server confirmed - update to authoritative state
localState = response.state;
} else {
// 3b. Server rejected - rollback
localState = previousState;
showError(response.error);
}
renderUI(localState);
});
}Security Considerations
Never Trust the Client
// BAD: Client sends new state
socket.on('update-state', (newState) => {
gameState = newState; // Never do this!
});
// GOOD: Client sends action, server validates and applies
socket.on('game-action', (action) => {
if (isValidAction(gameState, action, socket.playerId)) {
gameState = applyAction(gameState, action);
broadcast(gameState);
}
});Rate Limiting
const rateLimit = require('socket.io-rate-limit');
io.use(rateLimit({
windowMs: 1000,
max: 10 // Max 10 messages per second per client
}));Testing Multiplayer
Simulating Multiple Clients
// Test helper for multiple socket connections
async function createTestClients(count, gameId) {
const clients = [];
for (let i = 0; i < count; i++) {
const socket = io(SERVER_URL);
await new Promise(resolve => socket.on('connect', resolve));
socket.emit('join-game', { gameId, playerId: `player-${i}` });
clients.push(socket);
}
return clients;
}Testing Reconnection
it('should handle reconnection gracefully', async () => {
const client = await createTestClient(gameId);
// Force disconnect
client.disconnect();
// Wait and reconnect
await sleep(1000);
client.connect();
// Should receive full state sync
const state = await waitForEvent(client, 'state-sync');
expect(state).toBeDefined();
});When This Skill Activates
Use this skill when:
- Setting up WebSocket/Socket.io connections
- Implementing game room management
- Building state synchronization
- Handling player disconnection/reconnection
- Implementing turn timers
- Adding optimistic updates
- Securing multiplayer communications