LuckyChess

A strong, modern UCI chess engine written in Rust featuring an embedded NNUE evaluation network, cross-platform support (CLI, Web/WASM, Android).

---

Table of Contents

• Building
• Web & Docker
• Implemented Algorithms & Techniques
• UCI Protocol & Options
• Benchmarks & Testing
• Workspace Architecture
• Acknowledgments & Credits
• License

---

Building

Prerequisites

• Rust toolchain (Rust 1.85+ / 2024 edition compatible).
• Git LFS — the NNUE network weights (chess_engine/src/nnue/*.bin) are stored with Git LFS. Run git lfs pull after cloning if your git client doesn't fetch LFS objects automatically.

Compiling

Build the optimized release executable:

cargo build --release --bin lucky_chess

For maximum performance on your current machine:

RUSTFLAGS="-C target-cpu=native" cargo build --release --bin lucky_chess

The resulting binary will be at target/release/lucky_chess (or lucky_chess.exe on Windows).

---

Web & Docker

LuckyChess can run entirely in the browser via WebAssembly using Web Workers.

Running with Docker

docker build -t lucky-chess .
docker run -p 8080:8080 lucky-chess

Then visit http://localhost:8080 to play against the engine in your browser.

Building WASM Manually

cargo build-wasm

---

Implemented Algorithms & Techniques

Search

• Alpha-Beta Pruning (Negamax framework)
• Principal Variation Search (PVS)
• Iterative Deepening with Aspiration Windows
• Internal Iterative Reductions (IIR)
• Quiescence Search

Reductions & Pruning

• Late Move Reductions (LMR) with history-based adjustment
• Late Move Pruning (LMP)
• Null Move Pruning (NMP) with eval-scaled reduction
• Reverse Futility Pruning (RFP) & Futility Pruning
• SEE Pruning for captures and quiets
• History Pruning (linear depth-scaled margin)
• Delta Pruning & Global Delta Pruning (in Quiescence Search)

Move Ordering

• TT move (scored highest)
• Good captures (SEE + MVV-LVA)
• Killer Move Heuristic (2 killer moves per ply)
• History Heuristic with gravity updates (clamped to ±10,000)
• Multi-layer Continuation History (1-ply and 2-ply reads)
• Bad captures deferred after quiets

Evaluation

• NNUE: (768 → 1536)x2 → 8 architecture with output buckets by piece count
• Perspective network (vertically mirrored for black) with incremental accumulator updates
• Win-probability scaled evaluation (~400 units/pawn)
• Trained on Stockfish-generated data using the bullet framework

---

UCI Protocol & Options

Standard UCI Commands

uci, isready, setoption, ucinewgame, position, go, stop, quit.

Additional Commands

• bench [depth] — deterministic search over a fixed set of positions
• go perft <depth> — move generation/validation performance test

Configurable Options

Option	Type	Default	Range	Description
Hash	spin	64	1 – 1024 MB	Transposition table memory size
ClearHash	button	—	—	Clears the transposition table
Move Overhead	spin	10	0 – 5000 ms	Time buffer for communication / GUI lag

---

Workspace Architecture

├── chess_core/       # Core types, bitboards, board state, perft
├── chess_engine/     # Move generation, search, NNUE evaluation, time management, UCI protocol
├── chess_cli/        # Native CLI binary executable (lucky_chess)
├── chess_web/        # C-FFI / WebAssembly cdylib & browser frontend
├── chess_android/    # JNI bindings and Android / Wear OS companion app
├── nnue_trainer/     # NNUE training pipeline and utilities
└── benchmarks/       # SPRT testing scripts, opening books, gauntlet suites

---

Acknowledgments & Credits

While the codebase is original, LuckyChess stands on the shoulders of the open-source chess programming community:

• Stockfish
• Alexandria
• jw1912 — creator of the bullet training framework
• Chess Programming Wiki — invaluable resource for chess algorithms, magic bitboards, and search techniques
• Tools & Libraries:
  • uci-parser for UCI command parsing
  • fearless_simd for portable SIMD acceleration
  • fastchess for automated SPRT testing

---

Development Note & AI Usage

LuckyChess is an original engine. In the interest of transparency within the chess programming community, AI assistance (LLMs) was restricted exclusively to authoring unit tests and test fixtures. All algorithmic architecture — including move generation, search pruning and ordering heuristics, and the NNUE pipeline — was conceived and authored entirely by hand.

---

License

LuckyChess is free and open-source software licensed under the GNU General Public License v3.0.