Rust Chess Engine

A complete, fully hand-written chess engine in safe Rust (no unsafe, no chess-logic crates). Move generation is perft-verified against the canonical reference node counts, the search is a modern iterative-deepening PVS, and the whole thing ships with a UCI interface, PGN/SAN support, an opening book, an interactive terminal UI, observability hooks, and an extensive test suite.

   ██████╗ ██╗   ██╗███████╗████████╗     ██████╗██╗  ██╗███████╗███████╗███████╗
   ██╔══██╗██║   ██║██╔════╝╚══██╔══╝    ██╔════╝██║  ██║██╔════╝██╔════╝██╔════╝
   ██████╔╝██║   ██║███████╗   ██║       ██║     ███████║█████╗  ███████╗███████╗
   ██╔══██╗██║   ██║╚════██║   ██║       ██║     ██╔══██║██╔══╝  ╚════██║╚════██║
   ██║  ██║╚██████╔╝███████║   ██║       ╚██████╗██║  ██║███████╗███████║███████║
   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝        ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝

Table of contents

• Feature overview
• Architecture
• Build & run
• Usage modes
• Correctness: perft
• Testing
• Observability
• Module guide

Feature overview

Architecture

The engine is a layered stack of small, focused modules. Each layer depends only on the layers beneath it, which keeps the move generator independent of the search, the search independent of the protocols, and so on.

_{Diagram source: assets/architecture.excalidraw.}

Search pipeline (per move)

_{Diagram source: assets/search-pipeline.excalidraw.}

A deeper write-up (including the make/unmake + incremental-Zobrist scheme and the perft methodology) lives in ARCHITECTURE.md.

Build & run

Requires a recent stable Rust toolchain (edition 2024).

git clone <repo-url>
cd chess-engine
cargo build --release

Usage modes

The single binary dispatches on its first argument:

# Interactive terminal app (login, menus, colored board, game modes)
cargo run --release

# UCI engine: point Arena / Cute Chess / Banksia at the built binary, or:
cargo run --release -- uci

# Perft "divide" for a position (defaults to the start position)
cargo run --release -- perft 5
cargo run --release -- perft 4 "r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1"

# Fixed-depth search benchmark with telemetry
cargo run --release -- bench 9

Inside the interactive app you can type moves in either UCI (e2e4, e7e8q) or SAN (Nf3, O-O, exd5). Every in-game prompt (all game modes and analysis mode) also accepts:

Correctness: perft

The single strongest correctness guarantee is perft, counting the exact number of legal-move leaf nodes at a given depth and comparing against published reference values. The suite verifies the six canonical positions; the deep checks reach over 100 million nodes:

cargo test                          # fast suite (shallow perft + everything else)
cargo test --release -- --ignored   # deep perft (100M+ nodes), runs in seconds

Testing

cargo test                          # all unit + integration tests
cargo test --release -- --ignored   # deep perft
cargo bench                         # criterion micro-benchmarks

The suite includes: per-module unit tests, the perft suite, a tactical regression suite (mate-in-1/2, winning material, avoiding losing captures, promotion), random-game invariant fuzzing (incremental-key integrity, make/unmake reversibility, legality), an evaluation color-symmetry proof, and chess-rules edge cases (en-passant timing & pins, castling-right loss, under-promotion, the draw rules, FEN robustness).

Observability

• Set RUSTCHESS_LOG=off|error|warn|info|debug|trace to control leveled logging (written to stderr so it never corrupts UCI stdout).
• Every search returns SearchTelemetry: node/qnode counts, nodes-per-second, TT hit rate, and move-ordering quality (the fraction of beta cutoffs that occur on the first move). bench prints this summary.
• UCI emits standard info depth … score … nodes … pv … lines.

Module guide