Full-featured WebSocket checkers platform with real-time synchronization
Checkers Online is a full-featured, real-time multiplayer checkers (draughts) platform built with WebSocket technology. This project demonstrates advanced WebSocket implementation patterns, real-time game state synchronization, complete checkers rules validation including king promotions and forced captures, and a polished user experience for competitive online checkers matches.
The platform supports multiple concurrent games, player matchmaking based on skill level, move validation with American checkers rules, game history tracking, spectator mode, and real-time chat. Built with scalability and performance in mind, it can handle thousands of simultaneous players with minimal latency.
Complete American checkers rules including regular and king pieces, forced captures, multi-jump sequences, backward king moves, and automatic win/draw detection.
Bidirectional real-time communication using Socket.io for instant move synchronization, game updates, and player notifications with automatic reconnection handling.
ELO-based matchmaking system, custom game creation with friend invites, and quick match for instant gameplay with similarly skilled opponents.
Automatic king promotion when reaching the opposite end, with enhanced movement capabilities allowing backward moves and longer jump sequences.
Automatic detection and enforcement of mandatory captures. If a capture is available, the player must make a capturing move following official checkers rules.
Support for consecutive captures in a single turn. Players can execute multiple jumps in sequence when valid capture opportunities exist.
Watch live games with move history, player information, and real-time updates. Support for multiple spectators per game without performance impact.
Real-time text chat between players with emoji support, quick chat messages, and chat moderation for a friendly gaming environment.
ELO rating system, comprehensive win/loss statistics, game history with replay functionality, and performance analytics tracking.
The Checkers Online platform follows a modern, scalable architecture with clear separation of concerns:
Built with React and TypeScript for type safety. Uses React hooks for state management, Context API for global state, and custom hooks for WebSocket connection management. The checkers board is rendered using CSS Grid with smooth animations for piece movements and captures.
Node.js server with Express for REST API and Socket.io for WebSocket connections. Game state is managed in-memory with Redis for distributed caching. The checkers engine validates all moves according to official American checkers rules.
Client emits move → Server validates move → Engine updates state → Redis cache updated → Server broadcasts to connected clients → MongoDB persists game → Clients update UI
// server.js - Socket.io server configuration
const express = require('express');
const http = require('http');
const socketIo = require('socket.io');
const Redis = require('ioredis');
const app = express();
const server = http.createServer(app);
const io = socketIo(server, {
cors: {
origin: process.env.CLIENT_URL,
methods: ['GET', 'POST']
},
pingTimeout: 60000,
pingInterval: 25000
});
// Redis for pub/sub across multiple server instances
const redisPublisher = new Redis(process.env.REDIS_URL);
const redisSubscriber = new Redis(process.env.REDIS_URL);
redisSubscriber.subscribe('checkers:games');
redisSubscriber.on('message', (channel, message) => {
const event = JSON.parse(message);
io.to(event.gameId).emit(event.type, event.data);
});
// Active game sessions
const activeSessions = new Map();
io.on('connection', (socket) => {
console.log(`Player connected: ${socket.id}`);
// Authenticate user
const token = socket.handshake.auth.token;
const user = verifyToken(token);
if (!user) {
socket.disconnect();
return;
}
socket.userId = user.id;
socket.join(`user:${user.id}`);
// Load game handlers
require('./handlers/checkersHandlers')(io, socket, redisPublisher);
require('./handlers/chatHandlers')(io, socket);
require('./handlers/matchmakingHandlers')(io, socket);
socket.on('disconnect', () => {
handlePlayerDisconnect(socket);
console.log(`Player disconnected: ${socket.id}`);
});
});
server.listen(3000, () => {
console.log('Checkers server running on port 3000');
});
// handlers/checkersHandlers.js
const CheckersEngine = require('../engine/checkersEngine');
const GameModel = require('../models/Game');
module.exports = (io, socket, redisPublisher) => {
// Join game
socket.on('game:join', async (gameId) => {
try {
const game = await GameModel.findById(gameId);
if (!game) {
return socket.emit('error', { message: 'Game not found' });
}
const isPlayer = game.red.equals(socket.userId) ||
game.black.equals(socket.userId);
socket.join(`game:${gameId}`);
if (isPlayer) {
socket.join(`game:${gameId}:players`);
} else {
socket.join(`game:${gameId}:spectators`);
}
// Send current game state
socket.emit('game:state', {
board: game.board,
turn: game.turn,
status: game.status,
redPieces: game.redPieces,
blackPieces: game.blackPieces
});
socket.to(`game:${gameId}`).emit('player:joined', {
userId: socket.userId,
isSpectator: !isPlayer
});
} catch (error) {
socket.emit('error', { message: 'Failed to join game' });
}
});
// Handle move
socket.on('game:move', async ({ gameId, from, to }) => {
try {
const game = await GameModel.findById(gameId);
if (!game) {
return socket.emit('error', { message: 'Game not found' });
}
// Verify turn
const isRed = game.red.equals(socket.userId);
const isBlack = game.black.equals(socket.userId);
if ((game.turn === 'red' && !isRed) || (game.turn === 'black' && !isBlack)) {
return socket.emit('error', { message: 'Not your turn' });
}
// Validate and execute move
const engine = new CheckersEngine(game.board);
const result = engine.makeMove(from, to, game.turn);
if (!result.valid) {
return socket.emit('error', { message: result.error });
}
// Update game state
game.board = result.board;
game.moves.push({
from,
to,
captured: result.captured,
kinged: result.kinged,
timestamp: new Date()
});
// Check for multi-jump
if (result.canContinueJump) {
game.mustContinueFrom = to;
} else {
game.turn = game.turn === 'red' ? 'black' : 'red';
game.mustContinueFrom = null;
}
// Check for game over
if (engine.isGameOver(game.turn === 'red' ? 'black' : 'red')) {
game.status = 'finished';
game.winner = game.turn === 'red' ? game.black : game.red;
}
await game.save();
// Broadcast move
const moveData = {
gameId,
from,
to,
board: game.board,
turn: game.turn,
captured: result.captured,
kinged: result.kinged,
canContinueJump: result.canContinueJump,
status: game.status
};
io.to(`game:${gameId}`).emit('game:move', moveData);
// Publish to Redis
redisPublisher.publish('checkers:games', JSON.stringify({
type: 'game:move',
gameId,
data: moveData
}));
} catch (error) {
socket.emit('error', { message: 'Failed to process move' });
}
});
// Handle resignation
socket.on('game:resign', async (gameId) => {
const game = await GameModel.findById(gameId);
if (!game) return;
game.status = 'resigned';
game.winner = game.red.equals(socket.userId) ? game.black : game.red;
await game.save();
io.to(`game:${gameId}`).emit('game:ended', {
status: 'resigned',
winner: game.winner
});
});
};
// hooks/useCheckersSocket.ts
import { useEffect, useRef, useState } from 'react';
import io, { Socket } from 'socket.io-client';
export const useCheckersSocket = (token: string) => {
const socketRef = useRef(null);
const [connected, setConnected] = useState(false);
const [currentGameId, setCurrentGameId] = useState(null);
useEffect(() => {
socketRef.current = io(process.env.REACT_APP_SERVER_URL!, {
auth: { token },
reconnection: true,
reconnectionAttempts: 5
});
const socket = socketRef.current;
socket.on('connect', () => {
console.log('Connected to checkers server');
setConnected(true);
if (currentGameId) {
socket.emit('game:join', currentGameId);
}
});
socket.on('disconnect', () => {
console.log('Disconnected from server');
setConnected(false);
});
return () => {
socket.disconnect();
};
}, [token]);
const joinGame = (gameId: string) => {
if (socketRef.current) {
socketRef.current.emit('game:join', gameId);
setCurrentGameId(gameId);
}
};
const makeMove = (from: number, to: number) => {
if (socketRef.current && currentGameId) {
socketRef.current.emit('game:move', {
gameId: currentGameId,
from,
to
});
}
};
const resign = () => {
if (socketRef.current && currentGameId) {
socketRef.current.emit('game:resign', currentGameId);
}
};
return {
socket: socketRef.current,
connected,
joinGame,
makeMove,
resign
};
};
// engine/checkersEngine.js
class CheckersEngine {
constructor(board = null) {
// Board represented as array of 64 positions (0-63)
// null = empty, 'r' = red, 'R' = red king, 'b' = black, 'B' = black king
this.board = board || this.initBoard();
}
initBoard() {
const board = new Array(64).fill(null);
// Place black pieces (top)
for (let i = 0; i < 12; i++) {
const row = Math.floor(i / 4);
const col = (i % 4) * 2 + (row % 2);
board[row * 8 + col] = 'b';
}
// Place red pieces (bottom)
for (let i = 0; i < 12; i++) {
const row = 5 + Math.floor(i / 4);
const col = (i % 4) * 2 + (row % 2);
board[row * 8 + col] = 'r';
}
return board;
}
makeMove(from, to, player) {
const piece = this.board[from];
if (!piece || !this.isPlayerPiece(piece, player)) {
return { valid: false, error: 'Invalid piece selection' };
}
// Check for forced captures
const captures = this.getCaptures(player);
if (captures.length > 0 && !this.isCapture(from, to)) {
return { valid: false, error: 'Must make a capture move' };
}
// Validate move
if (this.isCapture(from, to)) {
return this.executeCapture(from, to, piece);
} else {
return this.executeRegularMove(from, to, piece);
}
}
isCapture(from, to) {
const rowDiff = Math.abs(Math.floor(to / 8) - Math.floor(from / 8));
return rowDiff === 2;
}
executeCapture(from, to, piece) {
const fromRow = Math.floor(from / 8);
const fromCol = from % 8;
const toRow = Math.floor(to / 8);
const toCol = to % 8;
// Get middle position
const midRow = (fromRow + toRow) / 2;
const midCol = (fromCol + toCol) / 2;
const midPos = midRow * 8 + midCol;
const capturedPiece = this.board[midPos];
if (!capturedPiece) {
return { valid: false, error: 'No piece to capture' };
}
// Execute capture
const newBoard = [...this.board];
newBoard[from] = null;
newBoard[midPos] = null;
newBoard[to] = piece;
// Check for king promotion
const kinged = this.checkKingPromotion(to, piece);
if (kinged) {
newBoard[to] = piece.toUpperCase();
}
this.board = newBoard;
// Check for additional captures
const canContinueJump = !kinged && this.hasCaptures(to, piece);
return {
valid: true,
board: newBoard,
captured: midPos,
kinged,
canContinueJump
};
}
executeRegularMove(from, to, piece) {
const fromRow = Math.floor(from / 8);
const toRow = Math.floor(to / 8);
const rowDiff = toRow - fromRow;
// Check direction (regular pieces can only move forward)
if (!this.isKing(piece)) {
const validDirection = piece === 'r' ? rowDiff < 0 : rowDiff > 0;
if (!validDirection) {
return { valid: false, error: 'Invalid move direction' };
}
}
// Check if destination is valid
if (this.board[to] !== null) {
return { valid: false, error: 'Destination occupied' };
}
// Execute move
const newBoard = [...this.board];
newBoard[from] = null;
newBoard[to] = piece;
// Check for king promotion
const kinged = this.checkKingPromotion(to, piece);
if (kinged) {
newBoard[to] = piece.toUpperCase();
}
this.board = newBoard;
return {
valid: true,
board: newBoard,
captured: null,
kinged,
canContinueJump: false
};
}
checkKingPromotion(pos, piece) {
const row = Math.floor(pos / 8);
if (piece === 'r' && row === 0) return true;
if (piece === 'b' && row === 7) return true;
return false;
}
isKing(piece) {
return piece === 'R' || piece === 'B';
}
isPlayerPiece(piece, player) {
return piece.toLowerCase() === player[0];
}
getCaptures(player) {
const captures = [];
for (let i = 0; i < 64; i++) {
const piece = this.board[i];
if (piece && this.isPlayerPiece(piece, player)) {
const moves = this.getPieceCaptures(i, piece);
if (moves.length > 0) {
captures.push({ from: i, moves });
}
}
}
return captures;
}
getPieceCaptures(pos, piece) {
const captures = [];
const directions = this.isKing(piece)
? [[-2, -2], [-2, 2], [2, -2], [2, 2]]
: piece.toLowerCase() === 'r'
? [[-2, -2], [-2, 2]]
: [[2, -2], [2, 2]];
const row = Math.floor(pos / 8);
const col = pos % 8;
for (const [dr, dc] of directions) {
const newRow = row + dr;
const newCol = col + dc;
if (newRow >= 0 && newRow < 8 && newCol >= 0 && newCol < 8) {
const midRow = row + dr / 2;
const midCol = col + dc / 2;
const midPos = midRow * 8 + midCol;
const newPos = newRow * 8 + newCol;
const midPiece = this.board[midPos];
const destPiece = this.board[newPos];
if (midPiece && !this.isPlayerPiece(midPiece, piece) && !destPiece) {
captures.push(newPos);
}
}
}
return captures;
}
hasCaptures(pos, piece) {
return this.getPieceCaptures(pos, piece).length > 0;
}
isGameOver(player) {
// Check if player has any valid moves
for (let i = 0; i < 64; i++) {
const piece = this.board[i];
if (piece && this.isPlayerPiece(piece, player)) {
if (this.getValidMoves(i, piece).length > 0) {
return false;
}
}
}
return true;
}
getValidMoves(pos, piece) {
const moves = [];
const captures = this.getPieceCaptures(pos, piece);
if (captures.length > 0) {
return captures;
}
// Regular moves
const directions = this.isKing(piece)
? [[-1, -1], [-1, 1], [1, -1], [1, 1]]
: piece.toLowerCase() === 'r'
? [[-1, -1], [-1, 1]]
: [[1, -1], [1, 1]];
const row = Math.floor(pos / 8);
const col = pos % 8;
for (const [dr, dc] of directions) {
const newRow = row + dr;
const newCol = col + dc;
if (newRow >= 0 && newRow < 8 && newCol >= 0 && newCol < 8) {
const newPos = newRow * 8 + newCol;
if (!this.board[newPos]) {
moves.push(newPos);
}
}
}
return moves;
}
}
module.exports = CheckersEngine;
Click on your piece (red) to select it, then click on a valid square to move!
You play as Red (bottom). Computer plays as Black (top).
# Dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build EXPOSE 3000 HEALTHCHECK --interval=30s --timeout=3s \ CMD node healthcheck.js CMD ["node", "server.js"]
# docker-compose.yml
version: '3.8'
services:
checkers-app:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- MONGODB_URI=mongodb://mongo:27017/checkers
- REDIS_URL=redis://redis:6379
depends_on:
- mongo
- redis
restart: unless-stopped
deploy:
replicas: 3
mongo:
image: mongo:6
volumes:
- mongo-data:/data/db
restart: unless-stopped
redis:
image: redis:7-alpine
volumes:
- redis-data:/data
command: redis-server --appendonly yes
restart: unless-stopped
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
depends_on:
- checkers-app
restart: unless-stopped
volumes:
mongo-data:
redis-data:
Implementing Redis Pub/Sub for horizontal scaling while maintaining real-time game synchronization across multiple server instances.
Efficient board representation and move validation algorithms optimized for performance with minimal memory footprint.
Complete checkers rules including forced captures, multi-jump sequences, and king promotion logic.
Automatic reconnection with game state recovery to handle network interruptions gracefully without losing game progress.
Simple but effective AI using minimax algorithm for single-player practice mode and testing.