Table of Contents
About
elephantchess.io is a web application to play and
study Chinese chess (or xiangqi 象棋).
By default, the project is under GPL-3.0 license. Libraries (like the Kotlin xiangqi-core or the
JavaScript board-gui) are under LGPL-3.0 license to allow
for a more permissive use (i.e. to re-use the libraries in a commercial application).
The releases and tags are only ever used to version the libraries (see below), i.e. packages xiangqi-core,
xiangqicore-test-utils, engine-api, etc. The webapp itself is not really versioned. The changelog.html file tracks
the changes to the webapp.
We have a little Discord server for open discussion.
Features
The webapp offers the following features:
- Play against other players (or PvP), where users can play against each other in real-time and chat. Users can find
each other in the Lobby or create a game and share the link with friends.
- Play against the bot (PvB), where user can play against the computer (i.e. the engine).
- Puzzles (or tactics), where users have to find the best moves from a given position.
- Database of tournaments games, events, players and statistic. To avoid confusion with the PostgreSQL database, we'll
try to specify when we talk about the "PostgreSQL database" or the "Database" as a feature.
- Analysis board, where users can create complex analysis, with engine evaluation, multiple embedded variations,
annotations (i.e.
??, ?! symbols) and comments.
- Manchu chess variant (also called Yitong): Black's pieces are set up and move the same as in xiangqi, but horses,
cannons, and one of the chariots are absent for Red. The remaining chariot has the combined powers of the chariot,
horse, and cannon.
- By default, users are assigned a temporary guest user id. They can also sign up with an email and password to keep
their data across devices and access all features.
Principles
- Keep the webapp free to use
- Keep the webapp ads free (although we sometimes cross-promote with other projects, and we use Google Ads to increase
traffic)
- Minimize overall annoyances (banners, emails, notifications, etc.)
- Keep the GUI simple and intuitive, and that works properly even on older or cheaper devices
- Be transparent on how user data is used
- Keep the user in control
- We're trying to reach a financially self-sustained platform, based on users donations and merch, with the quality of
the service as the priority
Glossary
- The engines are AI (or bots) used for the Play-against-bot (PvB) or Analysis Board features. In the chess community,
the term "engine" is preferred over AI or bot.
- In chess in general, the "columns" of the board are named "files" and the "rows" are named "ranks".
- The Forsyth–Edwards Notation (or FEN) is a standard notation to represent chess positions as a single line of text. In
Chinese chess, the starting position is encoded as
rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 0. It is convenient for data transfer and
indexing.
- The algebraic notation is a standard notation to represent chess moves. The files are numbered from
a to i and the
ranks are numbered from 1 to 10. So the move C2=5 is represented in algebraic notation as h3e3 (i.e. move the
piece from file h, rank 3 to file e, rank 3), or h2e2 in UCI notation (see below).
- The UCI (Universal Chess Interface) is a standard protocol to communicate with chess engines. It defines a set of
commands and responses that allow a chess engine to be controlled by a user interface. For example, the command
position fen rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 0 tells the engine to set up the
board with the given FEN position; and the command go depth 10 tells the engine to start calculating the best move
from that position with a search depth of 10.
- The UCI move notation is similar to the algebraic notation, except that the ranks are 0-based. Therefore, any
move can be encoded as 4 characters. For example, move
h3e3 is encoded in UCI as h2e2.
- The WXF notation is the traditional Chinese chess notation (e.g.
C2=5), widely in use. It's not as convenient
technically because move can be ambiguous and the files are numbered from the right to the left relative to the
player (so it's not the same numbers for the red and black players). Therefore, it's not used in code, except for
labeling moves in the GUI.
- OTB: Over The Board, i.e. in-person chess games, as opposed to online games.
Run Locally
This section describes how to run the back-end and front-end of elephantchess.io locally for
development or learning purposes.
TL;DR
You just need Docker to run PostgreSQL and Java 25 to run the app.
Pre-requisites
Java 25
You need a JDK installed to run the back-end, version 25 or higher.
Docker
You need Docker to run a local PostgreSQL instance. To check if you have Docker installed, you can run the following
command in your terminal:
➜ ~ docker --version
Docker version 29.4.2, build 055a478
Set-up
Engines
Note: for the sake of simplicity, the engine binaries have been added to this repo, so you don't have anything else to
do to be able to run the webapp locally with the engines features. Nevertheless, this section covers engine set-up.
Note: The bundled Pikafish binary targets x86-64 Linux and does not work on ARM64 machines. Pikafish publishes several
x86-64 binaries optimized for different CPU instruction sets; elephantchess uses the sse41-popcnt build for broad
compatibility.
The webapp assumes engine binaries can be found locally. So you need to create folder engines at the root of this
repository, download the binaries from their repositories and copying them in this format:
$ tree engines
engines
├── fairy
│ ├── 11.2
│ │ └── fairy-stockfish
│ └── 14.0.1
│ └── fairy-stockfish
└── pikafish
└── 2026-01-02
├── pikafish-sse41-popcnt
└── pikafish.nnue
Pikafish binaries can be found at https://github.com/official-pikafish/Pikafish/releases. As of now,
elephantchess uses Pikafish 2026-01-02 with the sse41-popcnt binary.
Fairy Stockfish binaries can be found at https://github.com/fairy-stockfish/Fairy-Stockfish/releases. As of now
elephantchess uses 11.2 but is planning to upgrade to 14.0.1.
You can run the webapp locally without the engines by setting engines=false in the properties file, but of course you
won't be able to play against the bot or run analysis.
PostgreSQL Docker container
You need to run a local PostgreSQL instance to run the webapp locally. The easiest way to do that is to run a PostgreSQL
Docker container with the following command:
docker run -d --rm \
--name xiangqi-db \
-p 5432:5432 \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=xiangqi \
postgres:18.4
Once the container is running, you should see it in the list of running containers:
➜ ~ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c4e5aa14100b postgres:18.4 "docker-entrypoint.s…" 9 seconds ago Up 8 seconds 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp xiangqi-db
You can then import the dev database (which contains a few games, puzzles and test users):
docker exec -i xiangqi-db \
pg_restore --no-privileges --no-owner --verbose \
-U postgres -d xiangqi -1 < dev_dataset.pgsql
Build and Run
To build (we can skip unit tests to speed it up):
./gradlew clean build -x test
To run:
java -jar webapp/build/libs/webapp.jar
Then you should be able to access the webapp at http://localhost:8080.
Alternatively, you can launch the Main from your IDE of choice.
Code Style
Kotlin code is formatted with ktlint (rules configured in .editorconfig).
The CI fails if the formatting is not respected.
# check formatting
./gradlew ktlintCheck
# fix formatting
./gradlew ktlintFormat
Common Issues
Port 8080 blocked
If you stop the process, it's possible that the 8080 port remains blocked when you try to re-start it later. You need to
check how to kill the zombie process still blocking the port.
On macOS, you can run the following command to kill the process blocking the port:
lsof -ti :8080 | xargs kill -9
On Linux (on Mint):
fuser -k 8080/tcp
Invalid guest session
If you run the webapp locally with a new database instance, you might see an error in the browser and in the console
that the guest user is invalid. This is perfectly normal since the token lives in the browser and on a new database
instance, that guest user will not be found. A new guest session will be created automatically and the page will
refresh.
Back-End (Kotlin)
The back-end is written in Kotlin and based on KTor to serve REST and WebSocket endpoints for the front-end, as well as
HTML pages. The back-end also uses Koin for dependency injection.
The Main class is pretty concise:
fun main(args: Array<String>) {
// read args, to know how to fetch the app_<profile>.properties
val argsConfig = parseArgs(args)
logger.info { "args: ${args.joinToString(" ")}" }
logger.info { "starting with $argsConfig" }
// dependency injection with Koin
startKoin {
modules(
// one module for services (independent of any routing)
serviceLayerModule(
argConfig = argsConfig,
eagerAllowed = true
),
// one module for webapp (KTor, routes, endpoints, JavaScript and CSS assets, etc.)
webAppKoinModule(eagerAllowed = true)
)
}
// start the Ktor server
embeddedServer(factory = Netty, port = 8080, module = Application::kTorModule)
.start(wait = true)
}
private fun Application.kTorModule() {
// default headers
configureDefaultHeaders()
// handle exceptions and return proper HTTP status codes and error pages
exceptionHandler()
// rate limits database access (for crawlers)
databaseRateLimitModule()
// serves static assets like JS, CSS, images
staticAssetsModule()
// serves endpoints for the front-end API
apiServiceModule()
// renders, maps and serves HTML pages
htmlRoutingModule()
// serves sitemap.xml
sitemapRoutingModule()
// serves /.well-known requests
wellKnownRoutingModule()
// handles graceful shutdown of components
shutdownModule()
// serves Kubernetes health probes
healthCheckModule()
}
Except for KTor, Koin, a Kubernetes client, Apache Commons, the project has few dependencies.
Gradle Modules
If you check the settings.gradle.kts file, you will see that the project is made of several modules:
include("utils")
include("engine-api")
include("xiangqi-core")
include("xiangqi-core-test-utils")
include("seven-kingdoms-core")
include("seven-kingdoms-core-test-utils")
include("webapp-config")
include("webapp-dao")
include("webapp-dao-migration")
include("webapp-html-renderer")
include("webapp-model-common")
include("webapp-service-layer")
include("webapp")
include("scripts")
utils
Small module with a couple of utility functions.
webapp-model-common
Small module with mostly enum which can be re-use by both DAO (i.e. for PostgreSQL database) and DTO.
webapp-config
Small module to parse and load configuration properties files. Properties files names use the format
app_<profile>.properties where profile can be e.g. local or prod. This profile is passed to Main which resolves
the correct file.
This repository provides app_local.properties with default values for local development.
webapp-dao
Contains "DAO services" like PlayerVsPlayerGameDaoService or UserDaoService that contains SQL queries.
Those services rely on the generated code by jOOQ. The POJO and fields are generated. The generation happens
automatically during the build.
For example, in the following function, table and columns USER, USER.EMAIL, etc. are generated by jOOQ codegen tool.
suspend fun fetchEmail(userId: String): String? {
return dslContext
.select(USER.EMAIL)
.from(USER)
.where(USER.ID.eq(userId))
.and(USER.USER_TYPE.eq(AUTHENTICATED))
.awaitSingleValue()
}
In order to generate the dao code, jOOQ needs the latest DDL. To do this, it loads the Liquibase migrations on a
in-memory H2 database to access tables definitions.
One quirk about this is that this H2 instance doesn't support some changes, so there is another version of the
liquibase-changelog.xml file (liquibase-changelog-generation.xml) which is generated from a script. So any change to
liquibase-changelog.xml should be followed by an execution of LiquibaseGeneration script before re-building, in
order to get the updated generated code.
Check the Gradle task dao-code-gen in the build file for more details.
The underlying driver is R2DBC which is a reactive driver, so queries are non-blocking and can be used in a coroutine
context.
webapp-dao-migration
Tiny module to manage the Liquibase migration. The reason it's separated from webapp-dao is because it uses JDBC
driver which shouldn't be exposed to the rest of the app.
webapp-html-renderer
Custom HTML renderer with custom template management.
It's a bit of a weird design choice. I had experimented with frameworks like Thymeleaf or Velocity, and I wasn't very
fond of them. Furthermore, at the beginning of the project, the HTML from the backend were very empty and the JavaScript
was filling the data in (which is still the case for games pages (PvP, PvB, puzzles)). So there was little need to
introduce a fancy framework.
Nowadays, the back-end produces a bit more dynamic HTML in a somewhat ad-hoc manner. But at the end of the day, it is
easy to maintain and allows quite some flexibility.
For example, it has the ability to fetch JavaScript and CSS assets from either the JAR or the CDN; as well as either the
minified or plain versions; remove HTML comments, cache the rendered HTML, etc.
webapp-service-layer
Probably the largest module, since it contains the main business logic of the app, for example all the CRUD services to
manage games (create, play move, browse, analyze, etc.).
This module should not contain a dependency to KTor.
webapp
KTor-based modules that links the service layer to the REST and WebSocket endpoints, as well as the HTML pages. It also
contains the JavaScript, CSS, images, etc. assets.
Libraries
Below are the Gradle modules designed to be used as libraries and are published on JitPack.
engine-api
Kotlin API to launch and communicate with chess engines running as system processes.
The entry point is the EnginePool service, which is a coroutine-safe pool of engine processes. It allows multiple
users to use the same pool of engine processes concurrently. For example, on elephantchess,
multiple users can play against the bot at different depths. Their queries are "queued" so multiple PvB games can happen
at the same time (even though technically, at a given time, a given process is used by max one user, as the process is
lockable).
You can decide e.g. to run multiple engine processes of a given engine (by increasing poolSize) with 1 thread for
each (numberOfThreads option) if you want to optimize for concurrency; or choose to run fewer engine processes but
with more threads for each instance if you want to optimize for responsiveness.
On elephantchess for example, each Kubernetes pod has an EnginePool with one instance of
Pikafish and one instance of Fairy Stockfish, with one thread each (so the engine processes don't use more than one CPU
core and the rest of the app remains responsive, as each pod only has 2 CPU cores at the moment). It would probably be
sensible to use a similar setup on an Android app, given that not all mobile devices have a lot of CPU cores.
The numberOfThreads option is not used in the EnginePool itself, but is simply passed along to the engine process.
In Pikafish for example, it's passed to the engine process with command setoption name Threads value 8 (you don't need
to input that command yourself, as it's abstracted away by the engine-api library).
The engines are queries with the FEN notation. In
xiangqi, the starting position is encoded as rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 0.
Configuration
Engines binaries location is configured by implementing EngineProcessLocator.
If the engines folder is located at the root of this repository (excluded by .gitignore), you can use the default
LocalProcessLocator:
package io.elephantchess.engines.protocol.commands
object LocalProcessLocator : EngineProcessLocator {
override fun launchCommand(binFileName: String) = "./engines/$binFileName"
}
It assumes folder engines is structured as follows:
$ tree engines
engines
├── fairy
│ ├── 11.2
│ │ └── fairy-stockfish
│ └── 14.0.1
│ └── fairy-stockfish
└── pikafish
├── 2022-12-26
│ ├── pikafish-modern
│ └── pikafish.nnue
├── 2023-02-16
│ ├── pikafish-modern
│ └── pikafish.nnue
├── 2023-03-05
│ ├── pikafish-modern
│ └── pikafish.nnue
└── 2026-01-02
├── pikafish-sse41-popcnt
└── pikafish.nnue
8 directories, 10 files
In the above example, multiple binaries and versions are available, but you can use the engine-api library with just
one version:
engines
└── pikafish
└── 2026-01-02
├── pikafish-sse41-popcnt
└── pikafish.nnue
You can create your own EngineProcessLocator. For example, on elephantchess, we use this
Dockerized version:
object DockerizedProcessLocator : EngineProcessLocator {
override fun launchCommand(binFileName: String) =
"/bin/bash -lc /app/engines/$binFileName"
}
Pikafish binaries can be found at https://github.com/official-pikafish/Pikafish/releases. Releases before 2026 use the
pikafish-modern executable name in this project; releases from 2026 onward use pikafish-sse41-popcnt. As of now,
elephantchess uses Pikafish 2026-01-02.
Fairy Stockfish binaries can be found at https://github.com/fairy-stockfish/Fairy-Stockfish/releases. As of now
elephantchess supports versions 11.2 and 14.0.1, stored under the fairy/<version> folder.
Example 1
In this example, we create a pool with one Pikafish process that uses 8 physical threads. So it will have good response
time, even with large depth values, but if it runs on a machine that has 8 CPU cores or less, it will use all the CPU
when queried.
import io.elephantchess.engines.process.EngineConfig
import io.elephantchess.engines.process.PikafishEngineId
import kotlinx.coroutines.runBlocking
import java.util.concurrent.Executors.newFixedThreadPool
fun main() {
val engineConfig = EngineConfig("2026-01-02", poolSize = 1, numberOfThreads = 8)
val enginePool = EnginePool(mapOf(PikafishEngineId to engineConfig), newFixedThreadPool(2))
runBlocking {
val fen = "rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 0"
val infoLinesResult = enginePool.queryForDepth(fen, PikafishEngineId, 10)
val infoLineResult = infoLinesResult?.deepestResult()
println("parsed engine result: $infoLineResult")
println("best move: ${infoLineResult?.pv?.first()}")
}
enginePool.close()
}
outputs
10:21:17.168 [pool-1-thread-1] INFO i.e.e.process.PikafishEngineProcess - running Pikafish engine, launching ./engines/pikafish/2026-01-02/pikafish-sse41-popcnt
10:21:17.199 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - sending to engine: setoption name Threads value 8
10:21:17.200 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - Pikafish 2026-01-02 by the Pikafish developers (see AUTHORS file)
10:21:17.222 [main] INFO i.e.e.process.PikafishEngineProcess - Pikafish process has started
10:21:17.224 [main] DEBUG i.e.e.process.PikafishEngineProcess - sending to engine: isready
10:21:17.641 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - readyok
10:21:17.735 [main] INFO i.e.e.process.PikafishEngineProcess - Pikafish process is ready
10:21:17.742 [main] DEBUG i.e.e.process.PikafishEngineProcess - sending to engine: position fen rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 0
10:21:17.742 [main] DEBUG i.e.e.process.PikafishEngineProcess - sending to engine: go depth 10
10:21:17.743 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info string NNUE evaluation using pikafish.nnue enabled
10:21:17.744 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 1 seldepth 1 multipv 1 score cp 5 nodes 97 nps 48500 hashfull 0 tbhits 0 time 2 pv h0g2
10:21:17.744 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 2 seldepth 2 multipv 1 score cp 24 nodes 238 nps 79333 hashfull 0 tbhits 0 time 3 pv h2e2
10:21:17.745 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 3 seldepth 2 multipv 1 score cp 30 nodes 406 nps 135333 hashfull 0 tbhits 0 time 3 pv b2e2
10:21:17.745 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 4 seldepth 2 multipv 1 score cp 331 nodes 476 nps 158666 hashfull 0 tbhits 0 time 3 pv h2e2
10:21:17.745 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 5 seldepth 2 multipv 1 score cp 353 nodes 543 nps 135750 hashfull 0 tbhits 0 time 4 pv b2e2
10:21:17.745 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 6 seldepth 3 multipv 1 score cp 1095 nodes 597 nps 149250 hashfull 0 tbhits 0 time 4 pv b2e2
10:21:17.749 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 7 seldepth 6 multipv 1 score cp 76 nodes 1560 nps 222857 hashfull 0 tbhits 0 time 7 pv b2e2 c9e7 b0c2
10:21:17.760 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 8 seldepth 6 multipv 1 score cp 60 nodes 4139 nps 229944 hashfull 1 tbhits 0 time 18 pv h2e2 h9g7 h0g2 h7h5 i0h0 i9h9
10:21:17.774 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 9 seldepth 8 multipv 1 score cp 54 nodes 7331 nps 222151 hashfull 3 tbhits 0 time 33 pv h2e2 b9c7 h0g2 h7e7 i0h0 h9g7
10:21:17.799 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - info depth 10 seldepth 11 multipv 1 score cp 44 nodes 14722 nps 253827 hashfull 6 tbhits 0 time 58 pv h2e2 b9c7 h0g2 b7a7 i0h0 a9b9
10:21:17.799 [pool-1-thread-1] DEBUG i.e.e.process.PikafishEngineProcess - bestmove h2e2 ponder b9c7
10:21:17.843 [main] DEBUG i.e.e.process.PikafishEngineProcess - sending to engine: stop
parsed engine result: InfoLineResult(depth=10, time=55, mate=null, cp=32, pv=[h2e2, h9g7, h0g2, c6c5, i0h0, i9h9, h0h4, b9c7, b0c2], line=info depth 10 seldepth 13 multipv 1 score cp 32 nodes 151567 nps 2755763 hashfull 45 tbhits 0 time 55 pv h2e2 h9g7 h0g2 c6c5 i0h0 i9h9 h0h4 b9c7 b0c2)
best move: h2e2
10:21:17.868 [main] DEBUG i.e.e.process.PikafishEngineProcess - sending to engine: quit
xiangqi-core
Kotlin library providing a representation of a Chinese chess board. Supports both standard Xiangqi and the Manchu
chess (Yitong) variant.
Example 1
import io.elephantchess.xiangqi.Board
fun main() {
val board = Board()
println(board.outputFen())
println()
println(board.print())
println()
println()
board.registerMove("h2e2") // C2=5
board.registerMove("h9g7") // H8+7
println(board.outputFen())
println()
println(board.print())
}
outputs
rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 0
a b c d e f g h i
9 r n b a k a b n r
8 . . . . . . . . .
7 . c . . . . . c .
6 p . p . p . p . p
5 . . . . . . . . .
4 . . . . . . . . .
3 P . P . P . P . P
2 . C . . . . . C .
1 . . . . . . . . .
0 R N B A K A B N R
rnbakab1r/9/1c4nc1/p1p1p1p1p/9/9/P1P1P1P1P/1C2C4/9/RNBAKABNR w - - 0 1
a b c d e f g h i
9 r n b a k a b . r
8 . . . . . . . . .
7 . c . . . . n c .
6 p . p . p . p . p
5 . . . . . . . . .
4 . . . . . . . . .
3 P . P . P . P . P
2 . C . . C . . . .
1 . . . . . . . . .
0 R N B A K A B N R
xiangqi-core-test-utils
Test data for unit tests of xiangqi-core.
seven-kingdoms-core
This is the logic for the Seven Kingdoms xiangqi variant, which is still in
development.
csv-dump-parser
Kotlin library to parse the PvP games CSV dumps exported from elephantchess (via the
ExtractPvpMovesToCsv script). It turns the pvp_game_moves_*.csv files (or the zipped archive of them) into
typed PvpGame / PvpMoveRecord objects, reusing HalfMove from xiangqi-core and InfoLineResult from
engine-api.
The datasets themselves can be found at https://elephantchess.io/about/datasets.
Libraries Usage
At the moment, you can use the libraries via JitPack. You only need to add the JitPack repository to your build
file:
repositories {
maven { url 'https://jitpack.io' }
}
Then you can use the dependencies:
implementation "com.github.benckx.elephantchess:xiangqi-core:2.1.1"
implementation "com.github.benckx.elephantchess:engine-api:2.1.1"
implementation "com.github.benckx.elephantchess:seven-kingdoms-core:2.1.1"
implementation "com.github.benckx.elephantchess:csv-dump-parser:2.1.1"
We added a sample project that uses the libraries
https://github.com/benckx/elephantchess-library-usage
Front-End
HTML
As mentioned earlier in the webapp-html-renderer section, HTML rendering relies on a custom
system of templating, based on tags {{tag_name}}.
Tags can be resolved from static fragments of HTML, simple values, dynamic renderers or something custom.
Static HTML fragments
For example, the base_css.html file contains all the CSS files we want to link in basically all the HTML pages:
<link rel="stylesheet" href="/css/style.css">
<link rel="stylesheet" href="/css/board.css">
<link rel="stylesheet" href="/css/style-reactive.css">
<link rel="preload" href="/css/play-bot-modal.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<link rel="preload" href="/css/new-game-modal.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
It can be referred from another HTML fragment, in this case header_init.html, which the header bits we need in each
page:
{{google_tag_manager_head}}
{{base_js}}
{{base_css}}
{{google_analytics}}
... which in turn can be resolved from a page:
<head>
{{header_init}}
<title>About elephantchess.io</title>
<link rel="stylesheet" href="/css/about.css"/>
<script defer src="/js/default-base-page.js"></script>
</head>
... rendering the final HTML page with - among other things - all the CSS and JavaScript assets we need:
Iterations
There is also the ability to inject key, values pairs and to repeat the pattern, like what we do for game thumbs:
{{game_thumb}}[[iterations:3; {gameType: 'pvp', parentClass: 'latest-pvp-game-thumb'}]]
Where i is the iterated value (0, 1, 2), and the key, value pairs (gameType and parentClass) are injected into the
resolved content:
<div class="game-thumb ${parentClass} game-thumb-placeholder">
<div class="board-outer-container">
<div class="board-inner-container">
<a class="board-outer-container-link-mask"></a>
<div id="last-${gameType}-game-board-${i}"
class="board-container mini-board-container board-container-placeholder">
</div>
</div>
<!-- [...] -->
</div>
</div>
JavaScript
The front-end doesn't use any framework. It's only vanilla JavaScript with a few libraries (dayjs, ApexCharts,
vanillajs-datepicker, jsdiff).
Under webapp/src/main/resources/public/js there's usually a sub-folder for each "app", i.e.:
analysis-boardplayer-vs-playerplayer-vs-botpuzzles- etc.
Complex app like PvP is usually organized with a page which updates the GUI, a controller which connects to
WebSockets and/or calls REST endpoints, sometimes a DTO file and/or a separate REST client file.
JavaScript tests
The move parsers (parser-common, parser-pgn, parser-uci, parser-iccs, parser-wxf) are covered by JavaScript
unit tests located under webapp/src/test/js. They rely only on Node's built-in test runner (no extra dependencies),
loading the production parser scripts into a shared VM context (mirroring how the browser loads them as <script>
tags). The fixtures under webapp/src/test/js/parsers/fixtures are real PGN / UCI / WXF games.
Run them with Node (24+):
cd webapp/src/test/js
node --test
The same command runs in the CI build.
Page tests (E2E)
End-to-end browser tests live under webapp/src/test/e2e and use
Playwright. They drive the real front-end in a headless
Chromium, exercising the full online PvP workflow: two guests, live button
updates when the opponent joins, a scripted game played out to checkmate, and the
game-over modal with the Elo update.
Requirements:
- A running app on
http://localhost:8080 (override with BASE_URL). See
Run Locally; make sure PostgreSQL is up and the dev dataset is
imported (dev_dataset.pgsql) so caches such as the puzzle cache are populated.
- Node 24+.
First time (and whenever dependencies change), install the Node packages and the
Chromium browser Playwright drives (the playwright binary is provided by the
local @playwright/test dependency, so npm install must run before
npx playwright install):
cd webapp/src/test/e2e
npm ci # or: npm install
npx playwright install chromium # downloads the browser Playwright drives
Then run the tests (the app must already be running):
npm test
To watch the browsers while the tests run (each spec opens two windows, one per player):
npm run test:headed # headed browsers
npx playwright test --ui # interactive runner: watch, re-run, time-travel through steps
npx playwright test --debug # headed + Playwright Inspector, pauses on each step
The install and npm test steps run in the e2e job of the CI build, which spins up PostgreSQL, loads
dev_dataset.pgsql, starts the app, and publishes the HTML report as the playwright-report artifact. The
deploy-e2e-report job then pushes it to the gh-pages branch, viewable at
https://benckx.github.io/elephantchess/e2e/pr-<number>/ (or e2e/main/); the link is in the job summary.
JavaScript Libraries
Some widgets from the https://elephantchess.io front-end are available as JavaScript
libraries. At the moment only board-gui is available. The plan would be to make the move-tree also available.
https://elephantchess.io/about/developers/board-gui-example
Minification
JavaScript and CSS assets are minified locally via the small Node project in
scripts/minifier: JavaScript with SWC and CSS with
Lightning CSS. The minifier dependencies are installed automatically (npm install) the
first time the task runs, which also handles modern syntax such as ES6 private
class fields out of the box.
The task looks for node and npm on the PATH as well as common install locations (nvm, fnm, asdf,
Homebrew). If they live somewhere else (or aren't picked up when running from an IDE), point the task at
them explicitly with the NODE_BIN and NPM_BIN environment variables.
