Repository files navigation

Chust is a Rust-based tool that leverages machine learning to detect chessboards and pieces from images. It can extract Forsyth-Edwards Notation (FEN) from a chessboard image, mark detected pieces, and even play a game of chess for you as a bot.

• Bot Gameplay - A chess bot; plays chess automatically for you.
• Chessboard and Piece Detection - Extracts the position of chess pieces from an image.
• FEN Generation - Converts detected chessboard positions into FEN notation.
• Visual Marking - Highlights detected pieces for verification.
• Refined Search Mode - Enhances accuracy by performing a secondary detection on a cropped chessboard.

You can find prebuilt binaries for Windows (thanks to@SenZmaKi) and Linux on theReleases page. For macOS and other platforms, you will need to compile Chust manually.

Ensure you have Rust and Cargo installed. On Windows, you also needVisual Studio 2022 (≥ 17.11) installed.

git clone https://github.com/Zai-Kun/chust&&cd chustcargo build --release

The compiled binary will be available in the./target/release folder.

To embed the machine learning model directly into Chust, use:

cargo build --release --features embed_model

Make sure the model is downloaded and placed in the Chust directory before building.

Chust provides two primary commands:

• process - Analyze an image for chessboard detection and FEN extraction.
• play - Play a game of chess automatically.

Not needed if compiled withembed_model. If using a prebuilt binary, this is required.

Download the ONNX model from the2D Chess Pieces Detection page. Ensure it is saved aschess_detection.onnx in the same directory as Chust or specify its path with--model-path.

Stockfish is required for Chust to play chess as a bot.

• Download fromStockfish Chess.
• On Arch Linux, install viayay -S stockfish.

chust play

• --castle-w - Enable castling for white.
• --castle-b - Enable castling for black.
• --pov - Choose to play as black (b) or white (w).
• --stockfish-path - Path to the Stockfish engine executable.
• --stockfish-depth - Depth for Stockfish analysis.
• --model-path - Path to the machine learning model.

If Chust does not support automatic screen capturing and clicking on your OS, you can specify custom commands:

• --screenshot-command - Command that outputs a screenshot to stdout for Chust to process.
• --click-command - Command to simulate a mouse click at coordinates{x} and{y}.

For more details:

chust play --help

chust play --pov w --screenshot-delay=0.3 --stockfish-depth=10

chust play --pov w --screenshot-delay=0.4 --stockfish-depth=20 --recheck-after-change

chust play --castle-w --castle-b

• Promotion is not automatic: If a pawn reaches the last rank, you will need to manually promote it.
• False move detection: Sometimes Chust may think that the opponent has moved when they actually haven't. If this happpens to you, you may need to adjust--screenshot-delay and you may need to add--recheck-after-change.
• Model failure: The model isn't perfect and it may fail in some cases but that rarely happens.

This project is licensed under the MIT License.

Contributions are welcome! Feel free to open issues and submit pull requests.

Made with ❤️ in Rust by Zai.