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

The following steps (Installation and Run Application) show the process to install a development environment.

If you want a one-click-to-run version, you can download the executables in the Latest Build Actions section. (requires logging in to github)

◎ 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

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

-- Windows

::Build once (for end users)
npm run 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!

Supported Browsers

Most modern browsers should work, such as Google Chrome, Mozilla FireFox, Microsoft Edge, Apple Safari. Older browsers like Internet Explorer of any version are not supported.

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