How merzlikin-matvey/chess works
1. What this repository is
- A C++ chess engine/library with multiple entry points: a reusable core library, a UCI command-line engine, test/perft binaries, examples, and a WASM-targeted demo.
- The code is organized around bitboard-based move generation and a search/evaluation pipeline.
2. Public API boundary
- include/chess-lib.hpp is the main umbrella header for consumers.
- The include/headers/ subtree exposes the engine’s public types and subsystems: board state, moves, notation, FEN, UCI, AI/search, transposition table, Zobrist hashing, masks, and constants.
3. Board and game-state subsystem
- src/board/ and include/headers/board.hpp implement the mutable chess position model.
- This layer handles core state transitions such as:
- initializing and ending a game,
- parsing/serializing FEN,
- move legality and check/checkmate detection,
- history tracking,
- output/pretty-printing of positions.
- This is the central state boundary used by both the engine and the tools/tests.
4. Move representation and notation
- move, move_array, and notations define how moves are stored, manipulated, and converted to human-readable or protocol formats.
- These modules sit between board state and consumers like UCI, tests, and examples.
5. Bitboard-based move generation
- The engine uses bitboards heavily, with masks and bit operations isolated under include/headers/masks/, bitboard_operations.hpp, and bitboard_lines.hpp.
- Piece-specific attack/move masks exist for pawns, kings/knights, bishops, and rooks.
- Sliding-piece support is optimized through magic-bitboard infrastructure:
- magic_numbers_constants.hpp
- magic_numbers_generators/*
- precomputed attack tables/masks for bishops, rooks, and pin directions.
- This is the main low-level performance subsystem feeding legal move generation.
6. Legal move generation pipeline
- src/board/get_legal_moves.cpp is the main boundary where pseudo-legal attacks, pin/check constraints, and board state combine into legal moves.
- Supporting files such as check_and_checkmate.cpp and the various pin-mask headers show that legality is enforced with attack maps and pin analysis rather than a high-level search-only filter.
7. Search and evaluation subsystem
- src/ai/ contains the engine’s decision-making stack:
- minimax.cpp for search,
- quiescence.cpp for tactical extension,
- move_sorting.cpp for ordering,
- evaluate_position.cpp for static evaluation.
- Evaluation is driven by pst.hpp and evaluating_constants.hpp, indicating piece-square tables and tuned heuristics.
- ai.hpp is the public interface for invoking search.
8. Search state and pruning support
- zobrist.hpp/.cpp and transposition_table.hpp provide position hashing and cached search results.
- These are used to avoid re-evaluating repeated positions and to speed up alpha-beta style search.
- Together with move ordering, they form the core performance layer above legal move generation.
9. Protocol and interface layer
- src/uci.cpp plus uci/main.cpp implement the UCI engine interface, so external chess GUIs can talk to the engine.
- This layer translates protocol commands into board updates and search calls, then emits best moves and status text.
- example/, stateless-example/, and wasm-html-example/ show alternative integration paths:
- embedding the library in a C++ app,
- using it without persistent engine state,
- driving it from a browser/WASM target.
10. Validation and benchmarking
- tests/legal_moves/ contains JSON fixtures for move-legality regression coverage across starting positions, openings, promotions, castling, checks/checkmates, and stalemates.
- performance/tests/perft.cpp validates move generation by counting legal move trees; performance/tests/alpha_beta.cpp benchmarks search behavior.
- This means correctness is checked both at the move-generator boundary and at the search boundary.
11. Build and deployment structure
- The project is CMake-driven at the root, with separate CMake targets for the library, UCI binary, tests, performance tools, and examples.
- scripts/wasm.sh and the WASM HTML example indicate a specialized browser build path, separate from the native CLI/test workflow.
12. End-to-end data flow
- Typical engine flow is:
- input position via FEN or UCI,
- board state updated,
- legal moves generated from bitboards/masks,
- search explores moves with evaluation, quiescence, and transposition-table lookup,
- best move returned through UCI or example output.
- Perft and legal-move tests reuse the same board/move-generation core, which helps ensure the engine’s correctness across both interactive and benchmark modes.
Main entry points: board Board · headers Engine API · ai Search · get_legal_moves.cpp Legal moves
Components 18
Public API
Umbrella and exported headers for consumers
- chess-lib.hpp · Main public include for library consumers
include/chess-lib.hpp - Engine API · Exported board, moves, UCI, hashing, and evaluation interfaces
include/headers
Core State
Board model, FEN, moves, and notation
- Board · Mutable chess position and core game-state transitions
src/board - FEN · Position parsing and serialization
src/board/fen.cpp - Moves · Move storage and move arrays
src/move.cpp - Notation · Human-readable and protocol move formatting
src/notations.cpp - Legal moves · Legal move generation with check and pin constraints
src/board/get_legal_moves.cpp
Bitboards
Masks, attacks, and magic-bitboard support
- Masks · Piece and pin masks for attack generation
include/headers/masks - Bit ops · Shared bitboard utilities and line helpers
include/headers/bitboard_operations.hpp - Magic tables · Magic-bitboard constants and generated attack infrastructure
include/headers/magic_numbers_constants.hpp - Magic gen · Generators for bishop, rook, and pin-mask magics
src/magic_numbers_generators
Search
Evaluation, move ordering, and tree search
Interfaces
UCI, examples, and browser-facing entry points
Validation
Tests and performance harnesses
- Tests & perf · Legal-move fixtures and perft/search benchmarks
tests
Connections 24
- chess-lib.hpp → Engine API: re-exports · Umbrella header gathers the public API surface
- Engine API → Board: exposes · Board state is a primary public subsystem
- Engine API → Moves: exposes · Move representations are part of the API
- Engine API → Notation: exposes · Notation helpers are shared across interfaces
- Engine API → AI API: exposes · Search entry points are public
- Board → FEN: uses · Board state is initialized and serialized through FEN
- Board → Moves: updates · Position transitions apply moves
- Board → Legal moves: feeds · Board state drives legality calculation
- Legal moves → Masks: depends on · Legality uses attack and pin masks
- Legal moves → Bit ops: depends on · Bitboard utilities support move generation
- Masks → Magic tables: uses · Sliding attacks rely on precomputed tables
- Magic gen → Magic tables: produces · Generators build or validate magic attack data
- AI API → Search: invokes · Search interface forwards into the search stack
- Search → Eval: scores with · Search uses static evaluation
- Search → Hashing: caches with · Search reuses repeated positions through hashing and TT
- Search → Legal moves: expands · Search explores legal moves from the board layer
- Eval → Board: reads · Evaluation inspects board state
- UCI → Board: drives · UCI commands update positions
- UCI → AI API: queries · UCI requests engine search results
- UCI → Notation: formats · Protocol output uses notation helpers
- Examples → Board: embeds · Examples show direct library use
- Examples → AI API: embeds · Examples may invoke search directly
- Tests & perf → Legal moves: validates · Fixtures and perft exercise move generation
- Tests & perf → Search: benchmarks · Alpha-beta benchmark covers search behavior