Engineering Headless Board Game Engines & Heuristic AI in TypeScript
Why tightly coupled game UI components fail at scale, and how designing pure functional state reducers unlocks cross-platform execution across Node.js servers, Web Workers, React Native, and modern web clients.
Key Architectural Takeaways
(state, move) => nextState without touching DOM or canvas elements.GameEngine<TState, TMove> contract across 12 diverse strategy games.1. The Pitfalls of UI-Coupled Game Architecture
Most web-based board games intertwine DOM event listeners, canvas redraw loops, and rule validation into monolithic React components. While this approach appears quick to prototype, it creates critical engineering bottlenecks:
- Impossible Server-Side Validation: A backend Node.js server cannot validate whether a user’s move was legal without mocking the entire DOM.
- No Background AI Processing: Running complex Minimax tree searches on the main thread locks the UI frame rate.
- Zero Multi-Platform Reusability: React web games must be completely rewritten to run on React Native, iOS, Android, or terminal CLIs.
By decoupling each game into a pure, zero-dependency headless engine, the core game rules become mathematical state machines that execute identically in any JavaScript runtime.
2. The Universal GameEngine Contract
To manage 12 fundamentally different game mechanics (from grid-based chess to track-based Backgammon and card-based Solitaire), we designed a universal TypeScript contract:
export interface GameEngine<TState = unknown, TMove = unknown> {
type: GameType;
// Initialize a clean, deterministic game state
getInitialState(player1Id: string): TState;
// Validate legality of proposed move (e.g. check pin, jump continuity, turn order)
validateMove(gameState: TState, player: GamePlayer, move: TMove): Promise<ValidationResult> | ValidationResult;
// Pure state transition: produces immutable next state
executeMove(gameState: TState, move: TMove, playerColor: string): TState;
// Check victory conditions, draws, checkmates, or forfeits
checkWinCondition(gameState: TState, player: GamePlayer): WinResult | null;
// Generate automated AI bot response based on difficulty
getAIMoves(gameState: TState, difficulty: AIDifficulty): Promise<TMove[]> | TMove[];
// Turn management resolver
getNextTurn(gameState: TState, currentTurn: string | null, players: GamePlayer[]): string | null;
}3. Building High-Performance Heuristic AI Bots
In classical games like Chess, Checkers, and Othello, single-player engagement relies on capable computer opponents. We built multi-tiered AI evaluators:
Easy Tier
Randomized move selection among legal moves with basic capture preference.
Medium Tier
1-ply shallow search with material value scoring and center-control weighting.
Hard Tier
Deep Minimax tree search with Alpha-Beta pruning, mobility scoring, and positional matrices.
// Alpha-Beta Pruned Minimax Decision Tree
function minimax(state: ChessGameState, player: PlayerColor, depth: number, alpha: number, beta: number, isMaximizing: boolean): number {
if (depth === 0 || state.gamePhase === 'checkmate') {
return evaluatePosition(state, player);
}
const moves = getValidMoves(state, isMaximizing ? player : getOpponent(player));
if (isMaximizing) {
let maxEval = -Infinity;
for (const move of moves) {
const nextState = executeMove(state, move, player);
const evalScore = minimax(nextState, player, depth - 1, alpha, beta, false);
maxEval = Math.max(maxEval, evalScore);
alpha = Math.max(alpha, evalScore);
if (beta <= alpha) break; // Prune sub-tree branch
}
return maxEval;
} else {
let minEval = Infinity;
for (const move of moves) {
const nextState = executeMove(state, move, getOpponent(player));
const evalScore = minimax(nextState, player, depth - 1, alpha, beta, true);
minEval = Math.min(minEval, evalScore);
beta = Math.min(beta, evalScore);
if (beta <= alpha) break; // Prune sub-tree branch
}
return minEval;
}
}4. The 12 Open-Source Engines in @epheos/arcade
The open-source @epheos/arcade suite packages full rule validation and bots for 12 games:
Chess
Full FEN support, castling, en passant, promotion, and checkmate detection.
Backgammon (Tavla)
Pip counting, bearing off, doubling cube, and bar recovery.
Othello (Reversi)
Dynamic 8-direction flip matrices and mobility heuristic AI.
Checkers (Dama)
Mandatory multi-jump captures and kinging logic.
Battleship
Fleet placement collision checks and parity hunting AI.
Connect Four
Bitboard vertical, horizontal, and diagonal streak resolution.
Mancala (Kalah)
Circular pit sow logic, extra turn triggers, and opposite-pit captures.
Gin Rummy & Cribbage
Deadwood calculation, melds (runs/sets), and 15-2 pegging point count.
Available Open Source on npm & GitHub
Install @epheos/arcade in your projects or play all 12 games live in the Epheos Arcade web client.