✨ Features

• 📸 One-click capture. An always-on-top camera button grabs the screen in milliseconds and hides itself so it never appears in the shot.
• 🧠 Offline board recognition. Classic template matching with OpenCV. No internet, no neural network, no GPU.
• ♞ Stockfish integration. Optional; shows the best move in UCI format (e2e4) in a small Board window.
• 🎨 Chess-themed setup window. A Tkinter app that walks you through screenshot → calibration → piece templates.
• 🔄 Automatic side detection. Your color is detected from the king's position, so there is nothing to switch.
• 🪶 Lightweight. The overlay is a single native .exe with no runtime that uses almost no memory while idle.

🧩 How it works

flowchart LR
    A["📷 Click the camera button"] --> B["C++ overlay<br/>hides itself and captures the screen (BitBlt)"]
    B --> C["screenshots/shot.bmp"]
    C --> D["Python: board_reader.py<br/>template matching with OpenCV"]
    D --> E["8x8 matrix → FEN"]
    E --> F["Stockfish (UCI)"]
    F --> G["♟️ Best move in the Board window"]

The project has two parts:

📁 Project structure

Chess cheat/
├── src/
│   ├── main.cpp             # overlay entry point
│   ├── screenshot.cpp       # overlay button, screenshot, launches Python
│   ├── screenshot.h
│   ├── app.py               # setup window (screenshot, calibration, templates, launcher)
│   ├── board_reader.py      # board recognition + Stockfish query
│   ├── board_config.json    # created by app.py (board position, settings)
│   └── templates.npz        # created by app.py (piece templates)
├── screenshots/
│   └── shot.bmp             # created on every screenshot
├── engine/
│   └── stockfish.exe        # downloaded separately
├── Chess cheat.sln
└── Chess cheat.vcxproj

[!NOTE] The overlay looks for its files in Desktop\Chess cheat\ (see InitPaths in screenshot.cpp). Keep the project there or change that path.

🚀 Quick start

1. Requirements

2. Build the overlay

Visual Studio

1. Open Chess cheat.sln.
2. Make sure the project contains only main.cpp, screenshot.cpp and screenshot.h.
3. Choose Release and platform x64.
4. Build → Rebuild Solution. The .exe ends up in x64\Release\.

Command line (Developer Command Prompt for VS, inside src)

cl /EHsc /O2 main.cpp screenshot.cpp /Fe:overlay.exe /link /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup

#pragma comment(linker, "/SUBSYSTEM:WINDOWS")
#pragma comment(linker, "/ENTRY:mainCRTStartup")

3. One-time setup

Piece templates are tied to a specific board color scheme and piece style. If you change the theme or the site, repeat these steps.

cd src
python app.py

A check mark next to a step means it is done.

🎮 Usage

1. In the setup window choose Move for:
   • my side (auto): your color is detected from the king's position;
   • White / Black: a fixed color.
2. Press Launch overlay button and select the overlay .exe the first time (the path is remembered). The setup window minimizes so it stays out of screenshots.
3. Open a game and click the camera button in the top-left corner of the screen. It changes color while recognition is running.
4. The Board window shows Stockfish's best move (or an error message).
5. Right-click the button to close the overlay. The setup window comes back.

There is also a Test: screenshot + best move button that does the same thing without the overlay.

Reading the result

The best move is printed in UCI format: e2e4 means move the piece from e2 to e4. A trailing letter (e7e8q) marks a pawn promotion: q queen, r rook, b bishop, n knight.

[!WARNING] Castling rights and en passant cannot be known from a single screenshot, so the FEN sent to Stockfish assumes full castling rights and no en passant. That is fine for "best move right now" analysis, but in rare positions it can suggest an illegal castling move.

⚙️ Configuration

src/board_config.json is created and updated by app.py. Every key is optional.

💻 Command line

python board_reader.py templates [shot.bmp]     :: build piece templates
python board_reader.py move [w|b] [shot.bmp]    :: best move; turn defaults to config
python board_reader.py [shot.bmp]               :: print the 8x8 matrix

🛠️ Troubleshooting

If the Board window (or the log in app.py) shows an error message:

[!TIP] The overlay button is still on screen after closing app.py? It is a separate process. Right-click the button, or end overlay.exe in Task Manager.

⚠️ Disclaimer

Using tools like this in rated games on chess.com, lichess and similar platforms violates their terms of service and can get an account banned. For reviewing finished games, working through puzzles offline, playing against bots or practice, this restriction doesn't apply. Use it responsibly.