https://github.com/alexandengstrom/blundernet-chess-engine
A neural network-based chess engine that predicts the next move without traditional search. Includes a Pygame GUI for local play and Lichess API integration for online games.
https://github.com/alexandengstrom/blundernet-chess-engine
chess engine lichess network neural pygame tensorflow
Last synced: about 2 months ago
JSON representation
A neural network-based chess engine that predicts the next move without traditional search. Includes a Pygame GUI for local play and Lichess API integration for online games.
- Host: GitHub
- URL: https://github.com/alexandengstrom/blundernet-chess-engine
- Owner: alexandengstrom
- Created: 2025-05-01T15:50:49.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-12T07:24:33.000Z (about 1 year ago)
- Last Synced: 2025-06-21T23:03:26.793Z (about 1 year ago)
- Topics: chess, engine, lichess, network, neural, pygame, tensorflow
- Language: Python
- Homepage:
- Size: 127 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Blundernet
Welcome to Blundernet! This is my personal recreational project where I am trying to create a chess engine using neural networks. My goal is not to create the best chess engine since i am not using any techniques such as minimax, instead i want to explore using only neural networks. Every move the engine makes is decided only by what the neural network outputs. The only exception is if the engine is playing as white, then we will force some more variation into the first move.
The repo is built so that it is easy to train new models. It also contains a simple Pygame GUI where you can play the models, and also a Lichess-bridge so you can let your models play online.
## Features:
- **Neural Network Driven**: Every move the engine makes is determined entirely by the neural network’s output, with no traditional chess algorithms involved.
- **Model Training**: The repository is designed for easy training of new models, so you can experiment with different architectures and training data.
- **Pygame GUI**: A simple GUI using Pygame is included which allows you to play against your models in a local environment.
- **Lichess Bridge**: With the Lichess integration, you can pit your models against real opponents online by letting them play on Lichess.
## Installation:
To get started with the project, first clone the repo:
```bash
git clone https://github.com/alexandengstrom/blundernet-chess-engine
```
Navigate to the project directory:
```bash
cd blundernet-chess-engine
```
Install the project with `make` command:
```bash
make
```
## Usage:
Interact with the project using `make`. These are the commands available:
- `make game`: Starts the Pygame GUI where you can play locally against your models.
- `make dataset`: This will generate a dataset in a format that the current layout of the input and output layer of the neural network will understand. You can experiment with different architectures inside the network, but you can not change the input and outout layer without also changing the format of the training data.
The training data is generated by sampling board positions from real chess games, then we are using **Stockfish** to predict the best move in this position. The first time this command is run it will also download necessary files, like the Stockfish binary and PGN-file.
- `make model NAME=your_model_name`: This starts the training process of a model with a given name. If the model already exists it will continue training it.
- `make bot MODEL=your_model_name`: This starts the **Lichess**-bridge which lets your engine play online.
- `make check`: Mostly for development, but runs linting and typechecking for the project.
## Model
If you dont want to train your own model. You can use the **blundernet**-model. This is the model represented by the Model-class included in the repo.
The model's input is a tensor representing the state of the chessboard, with 17 channels encoding both the pieces on the board and additional information like castling rights. If you'd like to use a different input format, you can implement your own `board_to_matrix` method.
The output is a vector with a length corresponding to the total number of possible moves in uci-format, including both legal and illegal moves.
## Lichess
When running the Lichess-bridge. We will start to listens for incoming requests but also challenge other bot accounts. By default we will allow five games to be played at the same time. When challenging other bots, we will try to find matches that are close to us in ranking. When receiving challenges we will accept everything.