KYLChiu / sporkfish

Chess engine in Python
MIT License
5 stars 0 forks source link

Sporkfish

Actions Status

Sporkfish is a Python-based chess engine. Chess programming techniques, although numerous, are not always well-documented. This project aims to bridge that gap by offering clear, working, and accessible code, providing a resource for developers interested in understanding and implementing chess engine algorithms.


Setup

See any of the following sections to quickly setup your development environment.

Using DevContainer with VSCode

Prerequisites:

Instructions:

  1. Make sure Docker Desktop is up and running.
  2. Open up the Command Palette and run Dev Containers: Rebuild Container
  3. The window should reload and you will see [Dev Container] in the URL bar as well as on the status bar bottom left of the window to indicate your setup is complete.

Using DevContainer with PyCharm

Prerequisites:

Instructions:

TODO - Please see jetbrains docs, PyCharm setup is similar to VSCode

https://www.jetbrains.com/help/pycharm/connect-to-devcontainer.html

Using Github Codespace

Prerequisites:

Instructions:

  1. In this Github repository, click on the Code dropdown, select Codespace and click Create.
  2. Confirm codespace settings, for Machine type select 2-core (this can be changed later if you require more power).

An active internet connection will be required for this. This will also use up your monthly allowance for Github codespace.

Using native Docker

Prerequisites:

After cloning the repository, from the root directory, run:

docker pull kylchiu/sporkfish-dev:latest
docker build -t kylchiu/sporkfish-dev:latest .
docker run -it kylchiu/sporkfish-dev:latest

This generates an interactive bash shell for you to run the program in.

Usage

Lichess

Check out the bot on lichess here! To run the bot, create a file in the root directory named api_token.txt. Add your Lichess bot API token. Then run:

python3 -O main.py

Once you create a game via your bot account, the bot will automatically play. We currently do not support simultaneous games.


Principles

Features

Search:

Move ordering:

Evaluation:

Communication:

Resources

Engines

References

Video (Youtube) Resources - beginner friendly

For developers

Run Tests

To run all tests (excluding slow tests):

python3 -m pytest -v

You may also run a specific test class or function, e.g.:

python3 -m pytest tests/test_searcher.py::TestMvvLvaHeuristic -sv

Slow tests are not run on CI. Developers should run these before raising PRs by doing (this can be very slow, so please be patient):

python3 -m pytest -sv --runslow

Sphinx auto docstring generation (with Github Copilot and devcontainer)

This may or may not work depending if Copilot is happy on that day. Simply ask Copilot to generate your class with Sphinx docstrings. If that does not work, you could try:

  1. Implement your class or function with type hints.
  2. Add a template Sphinx docstring at the class level, i.e. above __init__ function. This can be done using Ctrl + Shift + 2 (Windows, Linux) or Command + Shift + 2 (Mac). Add ":param:" in your string if it isn't auto generated.
  3. Using the Command Pallete, select "Github Copilot: Generate Docs" while your text cursor is inside the template Sphinx docstring. It should auto generate Sphinx docs for the entire class/function.