py-draughts

Fast, modern draughts library with move generation, validation, PDN support, and AI engines. HUB protocol for external engines communication

Important

Best optimized draughts library utilizing bitboards for ~200x faster move generation than alternatives.

Features: multiple variants • Built-in AI engine • (HUB protocol) External engine support (Scan, Kingsrow) • RL/ML ready • 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: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

Variant	Class	Board	Flying Kings	Max Capture
Standard	StandardBoard	10×10	Yes	Required
American	AmericanBoard	8×8	No	Not required
Frisian	FrisianBoard	10×10	Yes	Required
Russian	RussianBoard	8×8	Yes	Not required

>>> from draughts import StandardBoard, AmericanBoard, FrisianBoard, RussianBoard

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

Built-in alpha-beta engine with transposition tables and iterative deepening:

>>> from draughts import Board, AlphaBetaEngine

>>> board = Board()
>>> engine = AlphaBetaEngine(depth_limit=5)

>>> move = engine.get_best_move(board)
>>> move
Move: 32->28

>>> 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, AlphaBetaEngine

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

>>> print(stats)
============================================================
  BENCHMARK: AlphaBetaEngine (d=4) vs AlphaBetaEngine (d=6)
============================================================
  RESULTS: 2-12-6 (W-L-D)
  AlphaBetaEngine (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(), AlphaBetaEngine(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

Server

Interactive web interface for playing and engine testing:

from draughts import Board, Server, AlphaBetaEngine, HubEngine

server = Server(
    board=Board(),
    white_engine=AlphaBetaEngine(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:

Operation	py-draughts	pydraughts	Speedup
Board init	2.30 µs	547.10 µs	238x faster
FEN parse	21.00 µs	358.90 µs	17x faster
Legal moves	17.40 µs	3.61 ms	207x faster
Make move	0.90 µs	507.75 µs	564x faster

Engine search at various depths:

Depth	Time	Nodes
5	130 ms	3,525
6	350 ms	9,537
7	933 ms	25,202
8	4.9 s	122,168

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 4 variants - Standard, American, Frisian, Russian

Contributing

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

License

py-draughts is licensed under the GPL 3.