A hybrid Python/C++ chess engine project built around a Python game/search layer and a native C++ core for attack generation, move-step helpers, and future performance-critical search components.
This repository is on GitHub because it shows a real engine-building workflow rather than a toy minimax demo: legal move generation, board state management, evaluation, iterative deepening, move ordering, transposition-table use, opening-book support, and a playable Pygame interface.
It is not presented as a finished grandmaster-strength engine, and it is not pretending to be Stockfish. The point of the project is more honest than that: it documents a serious attempt to build a stronger chess engine from scratch, optimise it over time, and progressively migrate hot paths into native code.
Example midgame position during engine play: Pygame interface for the engine, including move highlighting and move log display.
- Built a working chess engine with:
- legal move generation
- make/undo move logic
- evaluation heuristics
- iterative deepening search
- alpha-beta style pruning and move ordering
- transposition-table support
- opening-book integration
- a playable Pygame GUI
- Uses a hybrid architecture:
- Python currently handles most full engine logic
- C++ currently accelerates selected low-level operations and provides the foundation for deeper native migration
- Includes correctness/debugging utilities such as perft and perft divide
- The project is still a work in progress, but already strong enough to be a credible personal engine project
This project is a personal chess-engine build focused on two goals:
- Build a stronger engine over time
- Improve performance by moving critical logic from Python into C++
The current version already plays complete games, supports search and evaluation, and includes an opening book and UI. The longer-term direction is to shift more of the search and move-generation hot path into the native core.
- Full playable chess game flow
- Legal move generation in the Python engine
- Move validation, make/undo, and game-state tracking
- Check, checkmate, stalemate, repetition, 50-move rule, and insufficient-material handling
- Evaluation and search logic
- Iterative deepening
- Move ordering heuristics
- Transposition-table usage
- Opening-book probing via Polyglot
- Pygame interface with move log, highlights, and promotion handling
- Perft-style correctness testing utilities
- Full native legal move generation
- Full native search
- Native evaluation
- Stronger endgame conversion and evaluation stability
- More systematic benchmarking and automated testing
- Cleaner packaging around the GUI/runtime entry points
A lot of chess-engine repositories are either:
- tiny coursework-level demos, or
- huge mature engines with little visibility into how they were built
This repository sits in the middle.
It shows a real engine project at a meaningful stage:
- beyond a basic minimax toy
- with genuine engine concepts implemented
- with visible iteration and performance-minded design
- without pretending the work is finished
That makes it worth showcasing.
The Python layer currently handles most of the full engine logic, including:
- board representation
- legal move generation
- game-state updates
- search flow
- evaluation logic
- GUI integration
The C++ layer currently provides:
- attack-table initialisation
- attacked-square helpers
- packed move-step generators
- pin/check helper logic
- the foundation for future native movegen/search work
The goal is not hybrid design for its own sake. The goal is practical:
- keep development flexible in Python while the engine evolves
- move the hottest low-level paths into C++ where speed matters most
- preserve a clean Python-facing interface for experimentation, debugging, and UI work
- Legal move generation
- Make/undo move support
- Check / checkmate / stalemate handling
- Repetition detection
- 50-move rule detection
- Insufficient-material detection
- Perft and perft-divide helpers
- Static evaluation heuristics
- Iterative deepening search
- Transposition table
- Killer/history-style move ordering support
- Opening-book integration
- Playable Pygame chess board
- Piece images and board rendering
- Legal-move highlights
- Move log display
- Promotion prompt
- Endgame result display
- Optional engine-vs-human play flow
.
├── cpp/
│ ├── include/
│ │ └── chesscore/
│ │ ├── attacks.hpp
│ │ ├── eval.hpp
│ │ ├── game_state.hpp
│ │ ├── move.hpp
│ │ ├── movegen.hpp
│ │ ├── pins.hpp
│ │ ├── search.hpp
│ │ └── zobrist.hpp
│ └── src/
│ ├── attacks.cpp
│ ├── eval.cpp
│ ├── game_state.cpp
│ ├── move.cpp
│ ├── movegen.cpp
│ ├── pins.cpp
│ ├── search.cpp
│ └── bindings/
│ └── py_module.cpp
├── src/
│ └── cengine/
│ └── __init__.py
├── images/
│ ├── bB.png
│ ├── bK.png
│ ├── ...
│ └── wR.png
├── ChessAI.py
├── ChessEngine.py
├── ChessMain.py
├── opening_book.py
├── CMakeLists.txt
├── pyproject.toml
└── README.md
python >= 3.11chesspygame
scikit-build-corepybind11cmakeninja
git clone https://github.com/dvp2004/cengine.git
cd cenginepython -m venv .venv
source .venv/bin/activatepython -m venv .venv
.venv\Scripts\activatepython -m pip install --upgrade pippip install -e .pip install pygamepython ChessMain.pyThis opens the Pygame board and lets you play against the engine through the current interface.
The engine includes a lightweight Polyglot opening-book wrapper.
If you want opening-book support, place a Polyglot book file such as:
mainbook.bin
in the expected project location used by opening_book.py.
If no opening book is found, the engine still runs normally.
During development, I mainly tested the engine through:
- direct gameplay
- games against online bots
- internal engine iteration
- correctness checks such as
perft/perft-divide
Those tests are useful, but they are not the same thing as a rigorous Elo measurement.
So this repository does not claim a formal rating estimate.
The engine has shown that it can play competitive games and improve materially with search and evaluation updates, but the current public version should still be read as a serious personal engine project rather than a formally benchmarked engine release.
This project is worth looking at because it is doing real engine work:
- full move legality and game-state handling
- search/evaluation integration
- debugging-oriented utilities like
perft - a clear performance-motivated C++ bridge
- iterative optimisation over time rather than a one-shot class assignment
It is not just "I made a chess board". The engine work is the point.
- The strongest engine logic still lives mostly in Python
- Native move generation/search is not complete yet
- Public benchmarking is not yet systematic
- Endgame play can still be unstable in some positions
- The GUI/runtime layer is functional but not yet polished like a packaged release
- This is a personal engine project, not a production chess-engine distribution
If I spent more time on this project, the next priorities would be:
- Move more of the hot search path into C++
- Complete full native legal move generation
- Tighten endgame evaluation and conversion
- Add systematic benchmark scripts
- Add automated
perftand regression tests - Clean up the runtime/package structure further
A lot of engine repositories exaggerate strength based on a few games.
This README does not do that.
The value of the project is not that it "beat X bot once". The value is that it shows:
- meaningful engine architecture
- real search/evaluation work
- hybrid Python/C++ optimisation effort
- an honest in-progress state
That is a much stronger signal than inflated rating claims.
