realtime-multiplayer

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.

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

```javascript

// 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);

});

});

```

Game Rooms Pattern

Each game instance should be a Socket.io room:

```javascript

// 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

```javascript

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)

});

}

```

Event Types

Define clear event categories:

```javascript

// 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

```javascript

// 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

```javascript

// 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

}

});

```

Reconnection Strategy

```javascript

// 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

```javascript

// 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 Timer Implementation

```javascript

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

```javascript

// 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 };

}

```

Client-Side Pattern

```javascript

// 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);

});

}

```

Never Trust the Client

```javascript

// 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

```javascript

const rateLimit = require('socket.io-rate-limit');

io.use(rateLimit({

windowMs: 1000,

max: 10 // Max 10 messages per second per client

}));

```

Simulating Multiple Clients

```javascript

// 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

```javascript

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();

});

```

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