Everything you need to integrate Moddable Chess into your project or extend it with new variants. Three ways to integrate: embed via iframe, mount directly via JavaScript, or query from an AI assistant.
The engine uses native ES modules. Import what you need:
<script type="module">
import MCE from './js/chess-engine.js';
import './js/chess-moves.js';
import './js/chess-play.js';
import './js/chess-variants.js';
import './js/board-renderer.js';
const game = MCE.createGame('standard');
MCE.renderBoard(document.getElementById('board'), game, {
size: 480,
onSquareClick: (sq) => { /* handle click */ }
});
</script>Or use the game controller for a complete interactive experience (AI, undo, animation):
<script type="module">
import MCE from './js/chess-engine.js';
import './js/chess-moves.js';
import './js/chess-play.js';
import './js/chess-variants.js';
import './js/board-renderer.js';
import './js/chess-ai.js';
import { createGameController } from './js/game-controller-core.js';
const game = MCE.createGame('atomic');
const ctrl = createGameController(
document.getElementById('board'), game,
{ players: { w: 'human', b: 'ai' }, aiDepth: 4 }
);
</script>The engine is split into focused ESM modules. Each extends the MCE namespace via side-effect imports:
| File | Exports | Purpose |
|---|---|---|
chess-engine.js | MCE (default), createGame, loadFEN, toFEN, positionKey, registerVariant, registerPiece, effects API | Core: board state, FEN, coordinates, variant/piece registry, effects system, board mutations |
chess-moves.js | pseudoLegalMoves, legalMoves, inCheck | Move generation for all piece types including custom pieces |
chess-play.js | makeMove, unmakeMove, getStatus | Move execution, undo, draw detection (threefold, insufficient material, 50-move) |
chess-variants.js | variantLegalMoves, getVariantStatus | 70 variant plugins with rule overrides |
chess-units.js | registerUnit, buildUnitHandler, getUnit | Unit template system for declarative piece definitions |
chess-ai.js | aiPickMove, AI_DIFFICULTIES, loadOpeningBook | Alpha-beta search, difficulty presets, opening book support |
board-renderer.js | renderBoard, setTheme, setPieceStyle, captureBurst | SVG board rendering, themes, animations |
game-controller-core.js | createGameController | Full interaction loop: human/AI players, undo, move animation, callbacks (demo) |
game-controller.js | (play page orchestrator) | Imports all modules + variants, handles embed postMessage API |
replay.js | createReplay | Step through completed games move-by-move |
ai-worker.js | (Web Worker entry) | Offloads AI search to a background thread |
mcp/tools.js | 8 MCP tool handlers | AI-callable chess analysis and puzzle generation |
mcp/server.js | (MCP server entry) | Stdio MCP server for Claude Code / Claude Desktop |
Embed a playable chess board in any page with a single iframe:
<iframe
src="https://chess.moddable.games/play/?embed=1&variant=atomic&boardonly=1"
width="480" height="480" frameborder="0"
></iframe>See API: Embedding for all parameters (themes, player names, accent colours, game modes).
The engine is available as an MCP server for Claude Code, Claude Desktop, or any MCP-compatible AI client. Eight tools expose game creation, move generation, position analysis, board rendering, and puzzle generation.
# Add to Claude Code
claude mcp add --transport stdio moddable-chess node mcp/server.js| Tool | Description |
|---|---|
chess_list_variants | All 70 variants with board sizes, win conditions, and descriptions |
chess_get_legal_moves | Legal moves for a position (FEN or variant start) |
chess_analyze_position | AI evaluation with best move, score, and material balance |
chess_validate_move | Check if a move is legal and get the resulting position |
chess_make_moves | Play a sequence of moves and return the final position |
chess_get_opening_book | Opening book moves for a variant (where available) |
chess_generate_puzzle | Generate tactical puzzles from random positions |
chess_render_svg | Render any position as a self-contained SVG image (no DOM required) |
See API: MCP Server for full parameter documentation and examples.
The board is a flat array of size rows × cols. Index 0 is the top-left square (a8 in standard chess). Pieces are single characters — uppercase for White, lowercase for Black:
| Char | Piece | Variants |
|---|---|---|
P/p | Pawn | All |
N/n | Knight | All |
B/b | Bishop | All |
R/r | Rook | All |
Q/q | Queen | All |
K/k | King | All |
A/a | Archbishop (B+N) | Capablanca, Grand |
C/c | Chancellor (R+N) | Capablanca, Grand |
S/s | Sage (1-step any direction) | Courier |
M/m | Maharaja (Q+N compound) | Maharaja, Amazon Chess |
The engine supports arbitrary rectangular boards. Each game object has rows and cols properties. All coordinate functions accept an optional game context:
MCE.sq(row, col, game) // → index
MCE.rc(index, game) // → [row, col]
MCE.onBoard(row, col, game) // → boolean| Key | Board | Win Condition |
|---|---|---|
standard | 8×8 | Checkmate |
chess960 | 8×8 | Checkmate |
noCastling | 8×8 | Checkmate |
torpedo | 8×8 | Checkmate |
chigorin | 8×8 | Checkmate |
almostChess | 8×8 | Checkmate |
amazonChess | 8×8 | Checkmate |
upsideDown | 8×8 | Checkmate |
kingOfTheHill | 8×8 | Checkmate or king to centre |
threeCheck | 8×8 | Checkmate or 3 checks |
singleCheck | 8×8 | 1 check |
fiveCheck | 8×8 | Checkmate or 5 checks |
atomic | 8×8 | Explode opponent's king |
rifle | 8×8 | Checkmate |
extinction | 8×8 | Eliminate a piece type |
antichess | 8×8 | Lose all pieces (stalemate = win) |
giveaway | 8×8 | Lose all pieces (stalemate = loss) |
suicideChess | 8×8 | Lose all pieces (stalemate = draw) |
stalemateWins | 8×8 | Checkmate or stalemate opponent |
codrus | 8×8 | Lose your king |
racingKings | 8×8 | King to rank 8 |
marseillais | 8×8 | Checkmate (2 moves/turn) |
progressive | 8×8 | Checkmate (escalating moves) |
monsterChess | 8×8 | Checkmate (White: 2 moves) |
duckChess | 8×8 | Capture king |
fogOfWar | 8×8 | Capture king |
horde | 8×8 | Checkmate or eliminate horde |
maharaja | 8×8 | Checkmate |
knightmate | 8×8 | Checkmate knight (royal) |
makpong | 8×8 | Checkmate (king can't flee) |
endgameChess | 8×8 | Checkmate |
peasantsRevolt | 8×8 | Checkmate |
pawnsOnly | 8×8 | Checkmate |
breakthrough | 7×7 | Reach far rank |
losAlamos | 6×6 | Checkmate |
minichess | 5×5 | Checkmate |
capablanca | 10×8 | Checkmate |
grand | 10×10 | Checkmate |
courier | 12×8 | Checkmate |
diceChess | 8×8 | Checkmate (die constrains piece type) |
gridChess | 8×8 | Checkmate (must cross grid lines) |
checklessChess | 8×8 | Checkmate (no check unless mate) |
noRetreat | 8×8 | Checkmate (no backward moves) |
weakChess | 8×8 | Checkmate (weakest piece must move) |
patrolChess | 8×8 | Checkmate (capture only when defended) |
madrasiChess | 8×8 | Checkmate (same-type pieces paralyse) |
omnicide | 8×8 | Lose all pieces (no forced captures) |
darkChess | 8×8 | Capture king (total fog) |
berserkChess | 8×8 | Checkmate (check grants bonus move) |
benedictChess | 8×8 | Convert opponent's king |
andernachChess | 8×8 | Checkmate (captures flip colour) |
halfChess | 4×8 | Checkmate |
dianaChess | 6×6 | Checkmate |
pettyChess | 5×6 | Checkmate |
berolinaChess | 8×8 | Checkmate (pawns move diagonally) |
cylinderChess | 8×8 | Checkmate (files wrap a↔h) |
toroidalChess | 8×8 | Checkmate (board wraps both axes) |
leganChess | 8×8 | Checkmate (Berolina pawns, swapped royals) |
hoppelPoppel | 8×8 | Checkmate (knights/bishops swap captures) |
makruk | 8×8 | Checkmate (Thai chess) |
ordaChess | 8×8 | Checkmate (asymmetric Mongol army) |
einsteinChess | 8×8 | Checkmate (moves demote, captures promote) |
displacementChess | 8×8 | Checkmate (swap with adjacent friendlies) |
shatar | 8×8 | Bare king (Mongolian chess) |
crazyhouse | 8×8 | Checkmate (drop captured pieces) |
recruitmentChess | 8×8 | Checkmate (captured pieces join your army) |
teleportChess | 8×8 | Checkmate (teleport to empty squares) |
poisonChess | 8×8 | Checkmate (capture squares become toxic) |
medusaChess | 8×8 | Checkmate (pieces petrify on sight) |
immunizationChess | 8×8 | Checkmate (pieces gain capture immunity) |
Moddable Chess handles rectangular boards only. For other geometries: