fairyground

This is an attempt to have a simple demo and playground for Fairy-Stockfish in the browser, using its WebAssembly port, its ffish.js library, and the graphical chessgroundx library. It is based on the demo for Fairy-Stockfish WASM and ffish-test.

You can see it deployed at: https://fairyground.vercel.app/

Usage

To get a one-click-to-run version, you can download the executables in the Latest Build Actions section. (Requires logging in to GitHub)

The artifacts may be expired if the latest build happened long ago. In this case please raise an issue to tell maintainers of this repository to re-run build actions.

Usage (Developers)

Installation and Run Application show the process to install a development environment.

Build with custom Fairy-Stockfish shows the process on how to use Fairy-Stockfish with your code changes in fairyground.

◎ Installation

⊙ Prerequisites

Install Node.js first.

⊙ Setup

1. Open your console and switch the working directory to this directory (the directory that contains this README). All of the following commands should be executed in this console.

2. Install dependencies

npm install

3. Bundle JavaScript

-- Linux/macOS

# Build once (for end users)
npm run build

# Build once (for developers, faster build without file compression & mangling)
npm run debug-build

# or, continuously run in background and watch for changes (for developers)
npm run watch-build

-- Windows

:: Build once (for end users)
npm run buildwithcmd

:: Build once (for developers, faster build without file compression & mangling)
npm run debug-buildwithcmd

:: or, continuously run in background and watch for changes (for developers)
npm run watch-build

◎ Run Application

1. Open your console and switch the working directory to this directory (the directory that contains this README). All of the following commands should be executed in this console.

2. Start server (Choose one of the following commands)

#Static website, no back end required. This can be accessed remotely.
npm run serve

#Enable binary engine loading feature. Can be only accessed on local host.
node server.js

3. Then, browse to http://localhost:5000 (Static website) or http://localhost:5015 (Enable binary engine loading feature)

Enjoy!

◎ Build with custom Fairy-Stockfish

If you want to use fairyground to test your experimental Fairy-Stockfish build, please follow these steps:

1. Download (If you haven't) and make changes to Fairy-Stockfish repository (https://github.com/fairy-stockfish/Fairy-Stockfish/).

2. Download (If you haven't) and make corresponding changes to Fairy-Stockfish WebAssembly repository (https://github.com/fairy-stockfish/fairy-stockfish.wasm/).

3. Build ffish.js and Fairy-Stockfish WebAssembly. See following guides to know how to build them:

• ffish.js: https://github.com/fairy-stockfish/Fairy-Stockfish/tree/master/tests/js#compile-in-docker
• Fairy-Stockfish WebAssembly: https://github.com/fairy-stockfish/fairy-stockfish.wasm/tree/nnue/src/emscripten#buildrun-in-docker

4. Go to fairyground root directory (The directory containing this README), run npm install (If you have already executed npm install, you can skip this step).

5. Go to <fairyground root directory>\node_modules, locate ffish_es6 and fairy-stockfish-nnue.wasm directory.

6. Perform following file replacement actions:

• Replace all things in ffish_es6 with all things in <your downloaded Fairy-Stockfish repository>\tests\js (ffish.js build output)
• Replace all things in fairy-stockfish-nnue.wasm with all things in <your downloaded Fairy-Stockfish WebAssembly repository>\src\emscripten\public (Fairy-Stockfish WebAssembly build output)

7. Go to fairyground root directory (The directory containing this README), open your console and run npm run build (Linux/macOS) or npm run buildwithcmd (Windows).

8. Run node server.js in the console, and then go to http://localhost:5015/public/advanced.html.

9. The page displayed now is using your version of Fairy-Stockfish, and you can begin your test.

Supported Browsers

Full Support

• Google Chrome
• Microsoft Edge
• Mozilla Firefox

Limited Support

• Apple Safari

No Support

• Microsoft Internet Explorer
• Opera Browser
• Brave Browser

Support for browsers not mentioned above are not clear. You need to check it yourself.

Run Engines Remotely

Warning

All binary engine loading features are experimental

The definition of the terms used in this section:

Server: The computer that runs the fairyground server (a console application) and the binary engines.

Client: The computer that runs the browser and the UI (a graphical user interface, GUI).

You will need to use port forwarding (local forwarding) to forward one of the open port on the client to the port that the server listens. Any software that provides port forwarding is OK. In this guide we use SSH as the tool for instance.

This requires the server to install a SSH server and allows port forwarding. If the server runs Windows, You can install OpenSSH For Windows.

For example, the server is running at http://192.168.1.10:5015 (which means IP: 192.168.1.10, Port: 5015), and then the WebSocket Server will be launched at ws://192.168.1.10:5016 (which means IP: 192.168.1.10, Port: 5016, the port of WebSocket server will be port of HTTP +1), while 2 of the open ports on the client are 9999 and 10000, then the command would be:

ssh -g -f -N -L 9999:192.168.1.10:5015 192.168.1.10
ssh -g -f -N -L 10000:192.168.1.10:5016 192.168.1.10

You need to build two connections, 9999 for HTTP and 9999 + 1 = 10000 for WebSocket in order to make it work.

Then browse to http://localhost:9999 on the client and if you see <Engine Management> button it works. Note that all the paths are paths on the server, NOT the path on the client. The binary executables of the engines need to be placed at respective paths on the server.

Run External Binary Engines In Online Versions

Warning

All binary engine loading features are experimental

The definition of the terms used in this section:

Webpage Server: The computer that provides the webpage of fairyground. It is the server specified in the URL. For example, https://fairyground.vercel.app

Engine Server: The computer that runs the fairyground server (a console application) and the binary engines. For example, http://localhost:5015

Client: The computer that runs the browser and the UI (a graphical user interface, GUI).

Note: If the engine server and the client are on different computers, please refer to the previous chapter when doing step 4. This guide assumes that the engine server and the client are on the same computer.

Steps to connect external binary engines:

1. Type the address of the webpage server in the browser and go to it. You will see the webpage of fairyground.
2. Run fairyground server. It will be the engine server. (run node server.js in the console or run the executable if you downloaded the release)
3. Check the WebSocket port of the engine server. By default it is 5016.
4. Click <CONNECT> button at the top of the page. In the prompt dialog, enter the WebSocket port of the engine server. (If the engine server and the client are on different computers, you need to use port forwarding to make this work. See previous chapter)
5. If connected, you will see <Engine Management> button. Click it to load your engines. Note that all the paths are paths on the engine server, NOT the path on the client. The binary executables of the engines need to be placed at respective paths on the engine server.

Make A Release

See README.md

Attribution

See COPYING.md