Master-Chess is a UCI-compatible chess engine that fuses classical α-β search with a Hybrid Search-Transformer architecture. The engine exposes a clean callback interface so that a Gemini (or any large language model) orchestration layer can inject policy weights and positional evaluations at runtime — without touching the core search logic.
- Screenshots / Terminal Preview
- Features
- Architecture Overview
- Requirements
- Building
- Usage
- Engine Configuration
- Project Structure
- Testing
- Wiki / Extended Documentation
- Contributing
- Roadmap
- License
View as text
$ ./build/master-chess
id name MasterChess (Michael Defense)
id author Hybrid Search-Transformer System
option name Hash type spin default 64 min 1 max 8192
option name GeminiEnabled type check default false
option name PeaceTopN type spin default 3 min 1 max 10
uciok
isready
readyok
position startpos moves e2e4 e7e5
go depth 8
info depth 1 score cp 14 nodes 21 nps 21000 pv g1f3
info depth 2 score cp 0 nodes 87 nps 43500 pv g1f3 b8c6
info depth 3 score cp 30 nodes 312 nps 78000 pv g1f3 b8c6 f1b5
info depth 4 score cp 15 nodes 1248 nps 156000 pv g1f3 b8c6 f1b5 a7a6
info depth 5 score cp 28 nodes 6140 nps 307000 pv g1f3 b8c6 f1b5 a7a6 b5a4
info depth 6 score cp 18 nodes 24320 nps 486400 pv g1f3 g8f6 f1b5 ...
info depth 7 score cp 22 nodes 97831 nps 652206 pv g1f3 b8c6 d2d4 ...
info depth 8 score cp 20 nodes 341274 nps 682548 pv g1f3 b8c6 d2d4 ...
bestmove g1f3
View as text
+---+---+---+---+---+---+---+---+
8 | r | n | b | q | k | b | n | r |
+---+---+---+---+---+---+---+---+
7 | p | p | p | p | p | p | p | p |
+---+---+---+---+---+---+---+---+
6 | . | . | . | . | . | . | . | . |
+---+---+---+---+---+---+---+---+
5 | . | . | . | . | . | . | . | . |
+---+---+---+---+---+---+---+---+
4 | . | . | . | . | . | . | . | . |
+---+---+---+---+---+---+---+---+
3 | . | . | . | . | . | . | . | . |
+---+---+---+---+---+---+---+---+
2 | P | P | P | P | P | P | P | P |
+---+---+---+---+---+---+---+---+
1 | R | N | B | Q | K | B | N | R |
+---+---+---+---+---+---+---+---+
a b c d e f g h
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
- Full UCI protocol — plug into any UCI-compatible GUI (Arena, CuteChess, Scid, Banksia, etc.)
- Bitboard representation — 64-bit
uint64_tboards with hardwarepopcount/lsbvia C++20<bit> - Classical attack tables — pre-computed knight, king, and pawn attack tables; classical fill for sliding pieces
- Alpha-Beta search — negamax with:
- Iterative deepening
- Principal Variation (PV) extraction
- Null-move pruning
- Killer-move heuristic (2 slots per ply)
- History heuristic
- Quiescence search (depth 8)
- Transposition table — two-bucket (depth-preferred + always-replace) with mate-score normalisation and age-based replacement
- Peace Protocol — optional Gemini policy-head callback that re-orders root moves, shrinking the effective branching factor toward the top-N strategically preferred moves
- Gemini evaluation hook — at shallow depths (≤
TRANSFORMER_THRESHOLD), the engine can delegate leaf evaluation to a GPU-accelerated Gemini model - FEN I/O — full FEN parsing and generation including castling rights, en passant, half-move clock, and full-move number
- Zobrist hashing — incremental hash updates on make/unmake; used for TT keying and repetition detection
┌──────────────────────────────────────────────────────────┐
│ UCI Loop │
│ (uci.cpp / uci.h) stdin ↔ stdout │
└────────────────────┬─────────────────────────────────────┘
│
┌──────────▼──────────┐
│ Search │ Alpha-Beta + Quiescence
│ (search.cpp/.h) │ Iterative deepening
│ │ Peace Protocol callback
└──┬──────────────┬───┘
│ │
┌─────────▼──┐ ┌───────▼────────────┐
│ MoveGen │ │ TranspositionTable │
│(movegen.*) │ │ (transposition.*) │
└─────────┬──┘ └────────────────────┘
│
┌─────────▼──────────┐
│ Board │ FEN I/O, make/unmake, Zobrist
│ (board.cpp/.h) │ static PST evaluation
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ Bitboard │ Attack tables, bit utilities
│ (bitboard.cpp/.h) │ File/rank masks, shift helpers
└────────────────────┘
The Gemini bridge is an optional external layer. It communicates with the engine through two callbacks registered on the Search object:
| Callback | Type | Purpose |
|---|---|---|
GeminiPolicyCb |
PolicyWeights(const Board&) |
Returns per-move policy scores used to re-order root moves (Peace Protocol) |
GeminiEvalCb |
int(const Board&) |
Returns a centipawn score used instead of static PST eval at shallow depths |
When neither callback is registered the engine operates entirely on classical evaluation and move ordering.
| Dependency | Version |
|---|---|
| C++ compiler | C++20 (GCC ≥ 10, Clang ≥ 12, MSVC ≥ 19.29) |
| CMake | ≥ 3.16 |
No third-party libraries are required. The Gemini integration callbacks are injected at runtime and the engine compiles and runs fully without them.
# Clone the repository
git clone https://github.com/GizzZmo/Master-Chess.git
cd Master-Chess
# Configure (Release by default)
cmake -B build -DCMAKE_BUILD_TYPE=Release
# Build
cmake --build build --parallel
# The engine binary is at:
./build/master-chesscmake -B build-debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build-debug --parallel./build/master-chessThe engine waits for UCI commands on standard input. It self-identifies as MasterChess (Michael Defense).
For a quick sanity check, type uci followed by Enter:
uci
id name MasterChess (Michael Defense)
id author Hybrid Search-Transformer System
option name Hash type spin default 64 min 1 max 8192
option name Threads type spin default 1 min 1 max 1
option name GeminiEnabled type check default false
option name GeminiModel type string default gemini-2.5-pro
option name PeaceTopN type spin default 3 min 1 max 10
option name TransformerThreshold type spin default 4 min 0 max 12
option name SyzygyPath type string default <empty>
uciok
The non-standard d command prints the current position as ASCII art and its FEN:
d
+---+---+---+---+---+---+---+---+
8 | r | n | b | q | k | b | n | r |
+---+---+---+---+---+---+---+---+
7 | p | p | p | p | p | p | p | p |
+---+---+---+---+---+---+---+---+
...
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
The eval command prints the static evaluation of the current position in centipawns:
eval
Static eval: 14 cp
| Command | Description |
|---|---|
uci |
Identify the engine and list options |
isready |
Synchronise — engine replies readyok |
ucinewgame |
Reset for a new game (clears TT) |
position [startpos|fen <fen>] [moves <m1> ...] |
Set the board position |
go [depth N] [movetime N] [wtime N btime N winc N binc N movestogo N] [infinite] [ponder] |
Start search |
stop |
Abort the current search immediately |
setoption name <N> value <V> |
Set a UCI option |
quit |
Exit the engine |
d |
(non-standard) Print current position as ASCII art + FEN |
eval |
(non-standard) Print static evaluation in centipawns |
| Option | Type | Default | Range | Description |
|---|---|---|---|---|
Hash |
spin | 64 | 1 – 8192 | Transposition table size in MB |
Threads |
spin | 1 | 1 – 1 | Number of search threads (single-threaded in v1.x) |
GeminiEnabled |
check | false | — | Enable Gemini LLM callbacks (requires Gabriel bridge) |
GeminiModel |
string | gemini-2.5-pro |
— | Gemini model identifier passed to the bridge |
PeaceTopN |
spin | 3 | 1 – 10 | Number of policy-preferred moves boosted by the Peace Protocol |
TransformerThreshold |
spin | 4 | 0 – 12 | Depth ≤ this triggers Gemini leaf evaluation instead of static PST eval |
SyzygyPath |
string | <empty> |
— | Path to a directory containing Syzygy endgame tablebase files |
The following compile-time constants in search.h control the hybrid behaviour:
| Constant | Default | Description |
|---|---|---|
TRANSFORMER_THRESHOLD |
4 | Remaining depth ≤ this value triggers GeminiEvalCb instead of static PST eval |
PEACE_TOP_N |
3 | Number of top policy moves that receive an ordering bonus from GeminiPolicyCb |
QUIESCENCE_DEPTH |
8 | Maximum quiescence search depth |
These defaults can also be overridden at runtime via the corresponding UCI options (TransformerThreshold, PeaceTopN).
Master-Chess/
├── CMakeLists.txt # Build system
├── LICENSE
├── README.md
├── CONTRIBUTING.md # Development guidelines
├── ROADMAP.md # Planned features and milestones
├── docs/
│ └── architecture.md # Detailed component documentation
├── src/
│ └── engine/
│ ├── types.h # Square, Piece, Move types and constants
│ ├── bitboard.h/.cpp # Bitboard utilities and attack tables
│ ├── board.h/.cpp # Board state, FEN I/O, make/unmake, Zobrist, PST eval
│ ├── movegen.h/.cpp # Pseudo-legal move generation and move scoring
│ ├── transposition.h/.cpp # Two-bucket transposition table
│ ├── search.h/.cpp # Iterative-deepening alpha-beta + Peace Protocol
│ ├── uci.h/.cpp # UCI protocol loop
│ └── main.cpp # Entry point
└── tests/
├── test_bitboard.cpp # Bitboard and attack-table unit tests
├── test_board.cpp # Board state, FEN, and move execution tests
└── test_search.cpp # Search, TT, and Peace Protocol unit tests
# Build and run all unit tests
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failureOr run the test binary directly for verbose output:
./build/master-chess-testsExpected output:
=== Results: N passed, 0 failed ===
Detailed documentation is available in the docs/wiki/ directory:
| Page | Description |
|---|---|
| Home | Overview and quick links |
| Installation | Platform-specific install guides (Linux, macOS, Windows) |
| Getting Started | First-run walkthrough and basic commands |
| Using with Chess GUIs | Arena, CuteChess, Scid, BanksiaGUI, and Lichess-bot setup |
| Engine Configuration | All UCI options and compile-time constants explained |
| Hybrid Search-Transformer | Deep dive into the Gemini / LLM integration layer |
| Search Algorithms | Alpha-beta, iterative deepening, heuristics, and quiescence |
| FAQ | Frequently asked questions |
See CONTRIBUTING.md for development guidelines, code style, branching strategy, and the pull-request process.
See ROADMAP.md for the planned feature milestones and long-term vision.
This project is licensed under the terms in the LICENSE file.