Command line¶

The dame command plays in the terminal, analyses positions and connects the engine to draughts GUIs over the Hub protocol.

Install¶

The dame-rs package on PyPI ships the dame command, so the quickest install is:

uv tool install dame-rs          # or: pipx install dame-rs

Inside an environment that has dame-rs installed, dame and python -m dame work too. It is the same Rust code as the binary below, run from the Python extension.

Or install it with Cargo; dame lands in ~/.cargo/bin. Add --tag <version>, e.g. --tag 0.1.0, for a specific release:

cargo install --locked --git https://github.com/KarelZe/dame-rs dame-cli

Or build it from a checkout:

cargo install --path crates/dame-cli

Play in the terminal¶

dame play                        # you play White, 2 s per engine move
dame play --color black --time 5
dame play --fen "W:W28,32:B17,23,27"

Enter moves in standard notation: 32-28 for a quiet move and 28x19 for a capture. When two captures share their start and end square, list the captured pieces as well, e.g. 28x10x14x23. The commands moves, hint, undo and quit do what you would expect.

Opening book¶

An opening book is a PDN file of games; the engine follows the first ten moves of each (see Opening book). Any game collection works, e.g. a download from a game database. Set DAME_BOOK to the file and the engine opens games from it, in dame play and dame hub:

export DAME_BOOK=~/draughts/games.pdn
dame play                        # the engine plays book moves while it has them

DAME_BOOK_PLIES sets how many plies (half-moves) of each game the engine follows, from 1 to 200; the default is 20, ten moves per side:

DAME_BOOK_PLIES=12 dame play     # only the first six moves of each game

While a position is in the book, the engine plays a book move without searching; dame play marks it with (book). A missing file or an illegal move in it is an error. dame search always searches, so it ignores the book.

Getting games¶

dame ships no games. A ready source is the engine Moby Dam by Harm Jetten: its book/games folder has 26 PDN files with about 900 master games and opening lines. They are GPL-3.0 licensed, so use them locally rather than adding them to this repository. Join them into one file and point DAME_BOOK at it:

git clone --depth 1 https://github.com/rhalbersma/mobydam.git ~/draughts/mobydam
cat ~/draughts/mobydam/book/games/*.pdn > ~/draughts/mobydam.pdn
export DAME_BOOK=~/draughts/mobydam.pdn   # add to ~/.zshrc to keep it
dame play

In a GUI: the Hub protocol¶

dame hub speaks the Hub protocol (version 2) on standard input and output, so any Hub GUI can run it, e.g. Fabien Letouzey's Hub. Point hub.ini at the binary (which dame shows where it was installed):

engine-dir = /path/to/dame-rs/target/release
engine-command = ./dame hub

The engine declares three parameters:

A GUI that sets book-file or book-plies overrides DAME_BOOK or DAME_BOOK_PLIES; an empty book-file turns the book off. The book is loaded on init, and a file that cannot be loaded is reported with an error line.

Other commands¶

dame search --time 5             # analyse the start position
dame search --fen "B:W18,24:BK3" --depth 20
dame perft 9                     # move generator node count
dame perft 3 --divide

Colored output¶

In a terminal, dame play, dame search, dame perft and the help are colored: White's pieces bold and Black's red, the last move's squares yellow, moves cyan, and scores green or red for the side to move. Output that is piped or redirected stays plain, and dame hub is never colored because GUIs read it. The usual environment variables change that, as in ruff, ty or uv:

NO_COLOR=1 dame play             # no colors
FORCE_COLOR=1 dame search | less -R   # colors even through a pipe

NO_COLOR wins over FORCE_COLOR (and CLICOLOR_FORCE). On Windows, colors are on in Windows Terminal and Unix-like terminals such as Git Bash; the classic console needs FORCE_COLOR=1, and only shows them if it supports ANSI codes.