Usage

Online

Pychess-variants

On Pychess-variants you can play various chess variants against Fairy-Stockfish, e.g., Xiangqi, Shogi, Makruk, Janggi, and more.

FICS

To play bughouse against Fairy-Stockfish on FICS, you need to set up Fairy-Stockfish with XBoard/Winboard zippy mode.

GUIs

For offline usage of Fairy-Stockfish, download the latest release or compile it from source and use it together with one of the GUIs listed below or any other chess variant GUI that is compatible with the supported protocols. If you are unsure which version to download, use the most compatible versions for Windows or for Linux.

XBoard/WinBoard

Fairy-Stockfish also supports the CECP/XBoard protocol, so it can easily be used in XBoard/WinBoard. On Windows, it is recommended to use an up-to-date WinBoard version (as [old versions of Winboard might not work with Fairy-Stockfish]).

Setup steps on Windows

1. Download the Fairy-Stockfish executable from the latest release.
2. Download WinBoard and extract the zip archive.
3. Open the Winboard folder and double click the winboard.exe.
4. Click on Engines>Edit Engine List...
5. Add one line similar to "Fairy-SF" -fcp "C:\fairy-stockfish.exe" (adjust the path to where you put the .exe in step 1). Click on commit changes and OK.
6. Click on Engines>Load New 1st Engine... and double click on Fairy-SF.
7. Via File>New Variant... you should now be able to select variants supported by Fairy-Stockfish.

Troubleshooting

• If the variant you are looking for is not in the list in step 7 (as not all variants are displayed), you can enforce a variant by changing the engine command from step 5 into, e.g., "Fairy-SF" /variant=janggi -fcp "C:\fairy-stockfish.exe" (replace janggi by the variant of choice), then redo step 6. The variant should be loaded automatically.
• If an engine-defined variant uses special moves like non-standard castling or the like (e.g., Janggi, Shako, etc.), Test Legality under Options>General... needs to be disabled in order to allow the input of such special moves. In XBoard you furthermore need to disable Show target squares (not present in Winboard) in that case.
• In releases up to 10.3, Fairy-Stockfish does not support the XBoard protocol, so a UCI2WB adapter needs to be used. However, unless you have a good reason to use an old version, please consider to download the latest release, which does not need the adapter.

Setup steps on Linux

See this guide to compile XBoard on Linux. You can skip the --enable-zippy flag if you do not intend to use XBoard to run an engine on ICS/FICS.

Cutechess

Cutechess supports many of the built-in variants supported by Fairy-Stockfish. It is very well suited for playing games (engine/human), but analysis functionality is very limited.

Engines can be added via "Tools>Settings". Select the "Engines" tab, click on "+" and select the engine executable via the "Browse" dialog.

PyChess

PyChess also supports some of the variants, including Crazyhouse, Losers, Giveaway, Three-check, King of the Hill, ASEAN, Makruk, and Sittuyin.

Shogi GUIs (USI-compatible)

Fairy-Stockfish can be used in gShogi and other USI compatible GUIs to play Shogi by adding it as a USI engine. In case of problems make sure in the engine configuration that the options Protocol and UCI_Variant are set to their defaults for the USI protocol, namely usi and shogi, respectively, and that you downloaded the large-board version (fairy-stockfish-largeboard...).

Fairy-Stockfish also has basic support for byoyomi time controls that are supported by some Shogi GUIs.

Xiangqi GUIs (UCCI-compatible)

Fairy-Stockfish can be used in Xiangqi GUIs by adding it as a UCCI engine. In case of problems make sure in the engine configuration that the options Protocol and UCI_Variant are set to their defaults for the UCCI protocol, namely ucci and xiangqi, respectively, and that you downloaded the large-board version (fairy-stockfish-largeboard...).

CLI & API

Command line

Fairy-Stockfish supports the UCI, UCCI, USI, and CECP/XBoard protocol. A variant can be selected via the UCI_Variant option in UCI/UCCI/USI or with the variant command in CECP. For variants that are not supported by any GUI, the CECP protocol is the least verbose for manual use via the command line.

E.g., to begin a game of Kyoto shogi after starting Fairy-Stockfish, enter:

1. xboard to set the protocol.
2. variant kyotoshogi to select the variant.
3. (Optional) d to print a board representation.
4. E.g., b1b2+ to make your first move.
5. go to ask the engine to play its first move.
6. Repeat steps 3.-4. in order to show the board and play moves. The engine will reply automatically to your moves once you sent one go command.

See https://www.gnu.org/software/xboard/engine-intf.html for more info on the CECP/XBoard protocol, e.g., on how to set the time control or the like.

Python binding

A python binding is also maintained in the repository and can be installed via the setup.py or as pyffish via pip. It can be used to query the engine for legal moves, FEN, etc. from python.