py-draughts — fastest Python draughts & checkers library

py-draughts (import name: draughts) is a fast, modern Python library for draughts (also known as checkers). Bitboard-backed move generation, PDN/FEN parsing, built-in engines (the ML-trained TurboEngine plus a general-purpose SimpleEngine), a HUB protocol bridge for external engines like Scan and Kingsrow, an interactive web UI, and tensor exports for RL / ML — all in one package.

py-draughts vs pydraughts

Full comparison →

Features: 8 variants • Built-in AI engine • External engines via HUB protocol (Scan, Kingsrow) • RL/ML ready (tensors, masks) • SVG rendering • Web UI

Installation

pip install py-draughts

Core

>>> import draughts
>>> board = draughts.Board()

>>> board.legal_moves
[Move: 31->27, Move: 31->26, Move: 32->28, ...]

>>> board.push_uci("31-27")
>>> board.push_uci("18-22")
>>> board.push_uci("27x18")
>>> board.push_uci("12x23")

>>> board
 . b . b . b . b . b
 b . b . b . b . b .
 . b . b . . . b . b
 . . . . b . b . b .
 . . . b . . . . . .
 . . . . . . . . . .
 . w . w . w . w . w
 w . w . w . w . w .
 . w . w . w . w . w
 w . w . w . w . w .

>>> board.pop()  # Unmake the last move
Move: 12->23

>>> board.turn
Color.WHITE

Make and unmake moves

>>> board.push_uci("32-28")  # Make a move
>>> board.pop()              # Unmake the last move
Move: 32->28

Show ASCII board

>>> board = draughts.Board()
>>> print(board)
 . b . b . b . b . b     .  1 .  2 .  3 .  4 .  5
 b . b . b . b . b .      6 .  7 .  8 .  9 . 10 .
 . b . b . b . b . b     . 11 . 12 . 13 . 14 . 15
 b . b . b . b . b .     16 . 17 . 18 . 19 . 20 .
 . . . . . . . . . .     . 21 . 22 . 23 . 24 . 25
 . . . . . . . . . .     26 . 27 . 28 . 29 . 30 .
 . w . w . w . w . w     . 31 . 32 . 33 . 34 . 35
 w . w . w . w . w .     36 . 37 . 38 . 39 . 40 .
 . w . w . w . w . w     . 41 . 42 . 43 . 44 . 45
 w . w . w . w . w .     46 . 47 . 48 . 49 . 50 .

Detects draws and game end

>>> board.is_draw
False
>>> board.is_threefold_repetition
False
>>> board.game_over
False
>>> board.result
'-'

FEN parsing and writing

>>> board.fen
'[FEN "W:W31,32,33,...:B1,2,3,..."]'

>>> board = draughts.Board.from_fen("W:WK10,K20:BK35,K45")
>>> board
 . . . . . . . B . .
 . . . . . . . . . .
 . . . . . . . . . .
 . . . . . . . . . .
 . . . . . . . . . .
 . . . . . . . . . .
 . . . . W . . . . .
 . . . . . . . . . .
 . . . . W . . . . .
 B . . . . . . . . .

PDN parsing and writing

>>> board = draughts.Board()
>>> board.push_uci("32-28")
>>> board.push_uci("18-23")
>>> board.pdn
'[GameType "20"]
[Variant "Standard (international) checkers"]
[Result "-"]
1. 32-28 18-23'

>>> board = draughts.Board.from_pdn('[GameType "20"]\n1. 32-28 19-23 2. 28x19 14x23')

Variants

>>> from draughts import (
...     StandardBoard,
...     AmericanBoard,
...     FrisianBoard,
...     RussianBoard,
...     BrazilianBoard,
...     AntidraughtsBoard,
...     BreakthroughBoard,
...     FryskBoard,
... )

>>> board = AmericanBoard()
>>> board
 . b . b . b . b
 b . b . b . b .
 . b . b . b . b
 . . . . . . . .
 . . . . . . . .
 w . w . w . w .
 . w . w . w . w
 w . w . w . w .

SVG Rendering

>>> import draughts
>>> board = draughts.Board()
>>> draughts.svg.board(board, size=400)  # Returns SVG string

>>> board = draughts.Board.from_fen("W:WK10,K20:BK35,K45")
>>> draughts.svg.board(board, size=400)

Engine

Two built-in engines.

TurboEngine (strongest, recommended)

For the standard international (10x10) board, TurboEngine combines Scan's 63-bit bitboard layout, a PVS search, and a machine-learned pattern evaluation trained on Scan self-play — it is the strongest built-in engine:

>>> from draughts import Board, TurboEngine

>>> engine = TurboEngine(time_limit=0.5)  # or depth_limit=...
>>> move, score = engine.get_best_move(Board(), with_evaluation=True)

SimpleEngine (all variants)

SimpleEngine is a lightweight general-purpose engine — alpha-beta with transposition tables and iterative deepening — that works on every variant (TurboEngine is international-only):

>>> from draughts import Board, SimpleEngine

>>> engine = SimpleEngine(depth_limit=5)
>>> move, score = engine.get_best_move(Board(), with_evaluation=True)
>>> score
0.15

External Engines (Hub Protocol)

Use external engines like Scan via the Hub protocol:

>>> from draughts import Board, HubEngine

>>> with HubEngine("path/to/scan.exe", time_limit=1.0) as engine:
...     board = Board()
...     move, score = engine.get_best_move(board, with_evaluation=True)
...     print(f"Best: {move}, Score: {score}")
Best: 32-28, Score: 0.15

Compatible engines:

• Scan - World champion level, supports 10x10
• Kingsrow - Multiple variants, endgame databases
• Any engine implementing the Hub protocol

Engine Benchmarking

Compare engines against each other with comprehensive statistics:

>>> from draughts import Benchmark, SimpleEngine

>>> stats = Benchmark(
...     SimpleEngine(depth_limit=4),
...     SimpleEngine(depth_limit=6),
...     games=20
... ).run()

>>> print(stats)
============================================================
  BENCHMARK: SimpleEngine (d=4) vs SimpleEngine (d=6)
============================================================
  RESULTS: 2-12-6 (W-L-D)
  SimpleEngine (d=4) win rate: 25.0%
  Elo difference: -191
  ...

Writing Your Own AI

Build custom agents with neural networks, MCTS, or any algorithm:

>>> from draughts import Board, BaseAgent, AgentEngine, Benchmark

>>> class GreedyAgent(BaseAgent):
...     def select_move(self, board):
...         return max(board.legal_moves, key=lambda m: len(m.captured_list))

>>> board = Board()
>>> agent = GreedyAgent()
>>> move = agent.select_move(board)

# Use with Benchmark
>>> stats = Benchmark(agent.as_engine(), SimpleEngine(depth_limit=4), games=10).run()

ML-ready features:

>>> board.to_tensor()        # (4, 50) tensor for neural networks
>>> board.legal_moves_mask() # Boolean mask for policy outputs
>>> board.features()         # Material, mobility, game phase
>>> clone = board.copy()     # Fast cloning for tree search

Example: a neural net that learns to play

examples/train_value_net.py trains a small evaluation network (~630K parameters) for 10x10 International draughts on a laptop CPU — no GPU. It is taught by the world-class Scan engine over the Hub protocol, using the same data recipe as chess NNUE nets:

1. Data. Scan plays games from random openings; we keep only quiet positions (no capture pending), each with Scan's evaluation and the game's result, and deduplicate them.
2. Target. Blend the squashed engine eval with the game result — a WDL label.
3. Features. Hand the small MLP a few scalars it can't extract from raw bits — material balance and parity ("the move") — next to the board planes.
4. Augment + train. Double the data with the board's 180° rotation (a valid symmetry), weight decisive positions more, and regress with early stopping.
5. Play with a negamax + alpha-beta search that has quiescence: it never evaluates a position with a pending capture, so every leaf is quiet — the distribution the net was trained on.

The lesson: representation beats optimisation. Once the data was clean, the net plateaued — more data and training tricks (EMA, LR schedules) barely moved it. The jump at fixed size and speed came from what the net sees: adding material and parity features (a flat MLP can't recover a sum or a mod‑2 count from 200 raw bits) plus the 180° augmentation. Same ~630K params, ~0.2 s/move (25–40 games each):

Load the trained weights and play:

import torch
import torch.nn as nn
from draughts.boards.standard import Board  # 10x10 International

def board_features(x):   # material + parity — what a flat MLP can't see in raw bits
    c = x.sum(2); om, ok, pm, pk = c[:, 0], c[:, 1], c[:, 2], c[:, 3]; total = c.sum(1)
    return torch.stack([om/15, ok/5, pm/15, pk/5, (om + 3*ok - pm - 3*pk)/15,
                        (ok - pk)/5, total/40, total % 2, (om + ok) % 2,
                        om % 2, pm % 2], dim=1)

class ValueNet(nn.Module):                    # ~630K params
    def __init__(self, h=512):
        super().__init__()
        self.body = nn.Sequential(
            nn.Linear(4*50 + 11, h), nn.ReLU(), nn.Dropout(0.3),
            nn.Linear(h, h), nn.ReLU(), nn.Dropout(0.3),
            nn.Linear(h, h), nn.ReLU(),
            nn.Linear(h, 1), nn.Tanh(),
        )
    def forward(self, x):
        flat = x.reshape(x.shape[0], -1)
        return self.body(torch.cat([flat, board_features(x)], dim=1)).squeeze(-1)

net = ValueNet(); net.load_state_dict(torch.load("examples/value_net_standard.pt")); net.eval()

@torch.no_grad()
def evaluate(board):                          # score for the side to move
    return float(net(torch.from_numpy(board.to_tensor()).unsqueeze(0)))

@torch.no_grad()
def search(board, depth, alpha=-1e9, beta=1e9):
    moves = board.legal_moves
    if not moves:
        return -1.0                           # side to move has lost
    quiet = not moves[0].captured_list
    if depth <= 0 and quiet:
        return evaluate(board)                # only ever score quiet leaves
    depth = depth if not quiet else depth - 1  # quiescence: captures are "free"
    best = -2.0
    for m in moves:
        child = board.copy(); child.push(m)
        best = max(best, -search(child, depth, -beta, -alpha))
        alpha = max(alpha, best)
        if alpha >= beta:
            break
    return best

def after(board, move):
    child = board.copy(); child.push(move); return child

board = Board()
# 3-ply search: play the move that leaves the opponent worst off.
best = max(board.legal_moves, key=lambda m: -search(after(board, m), 2))
board.push(best)

The example script packages this as a ValueAgent (a normal BaseAgent) and a Benchmark harness. To retrain, download Scan (SCAN_EXE=/path/to/scan.exe) and run python examples/train_value_net.py; without Scan it falls back to the built-in engine as a weaker teacher.

Aside: unlike chess, a 10x10 draughts board has no left-right mirror symmetry on its playable squares (reflecting columns flips square colour), so there is no free spatial data augmentation — the only board symmetry is a 180° rotation, which the side-to-move-relative tensor already encodes.

Server

Interactive web interface for playing and engine testing:

from draughts import Board, Server, SimpleEngine, HubEngine

server = Server(
    board=Board(),
    white_engine=SimpleEngine(depth_limit=6),
    black_engine=HubEngine("path/to/scan.exe", time_limit=1.0)
)
server.run() # Open http://localhost:8000

Performance

Legal moves generation in ~10-30 microseconds:

Engine search at various depths:

Testing

Comprehensive test suite with 260+ tests covering all variants and edge cases:

pytest test/ -v

Tests include:

• Move generation - Push/pop roundtrips, legal move validation
• Real game replays - PDN games from Lidraughts for all variants
• Edge cases - Complex king captures, promotion mid-capture, draw rules
• Engine correctness - Hash stability, transposition tables, board immutability
• All 8 variants - Standard, American, Frisian, Russian, Brazilian, Antidraughts, Breakthrough, Frysk!

Contributing

Contributions welcome! Please open an issue or submit a pull request.

License

py-draughts is licensed under the GPL 3.