You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Renamed config docs: TournamentConfig.md and EngineDefConfig.md replace old file names in all references and links.
- Major README overhaul: added Quick Start, Build from Source, console commands, log info, and clarified protocol support.
- Updated GUI and docs to use new config doc names.
- Set application icon via chessIcon.ico in WebGUI.csproj.
- Improved language, formatting, and consistency throughout documentation.
Copy file name to clipboardExpand all lines: README.md
+68-32Lines changed: 68 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
[](https://discord.gg/tRMYTbk5TE)
4
4
5
-
**EngineBattle** is a comprehensive tool designed for running tournaments, testing, analyzing, and comparing chess engines. It simplifies puzzle-based testing, detailed analysis, tournament management, and provides interactive visualizations, making it ideal for chess developers, researchers, and streamers.
5
+
**EngineBattle** is a comprehensive tool for running tournaments, testing, analyzing, and comparing chess engines. It supports engines using the **UCI** and **Winboard/XBoard** protocols. With puzzle-based testing, detailed analysis, tournament management, and interactive visualizations, it is ideal for chess developers, researchers, and streamers.
6
6
7
7
8
8
*Example: Tournament GUI — follow live games, standings, and results with interactive visualizations.*
@@ -40,7 +40,7 @@ EngineBattle supports four tournament formats configured via `TournamentMode` in
40
40
-**Swiss:** Pairings are based on score each round, scaling well for larger fields.
41
41
-**Swiss (odd players):** If the player count is odd, one engine receives a bye each round (worth 1 point) and byes are not repeated when possible.
42
42
43
-
See [Tournament.json.md](Tournament.json.md) for configuration details, plus [SwissMode.md](SwissMode.md) and [CupMode.md](CupMode.md) for mode-specific notes.
43
+
See [TournamentConfig.md](TournamentConfig.md) for configuration details, plus [SwissMode.md](SwissMode.md) and [CupMode.md](CupMode.md) for mode-specific notes.
44
44
45
45
46
46
### 🔍 Analysis Mode
@@ -69,7 +69,7 @@ See [Tournament.json.md](Tournament.json.md) for configuration details, plus [Sw
69
69
70
70
### 💻 Console Mode
71
71
72
-
-**Basic Console Mode:** Minimalist console mode designed for quicker time controls and node-testing, supporting parallel execution of multiple games for quick benchmarking.
72
+
-**Basic Console Mode:** Minimalist console mode designed for quicker time controls and node-testing, supporting parallel execution of multiple games for quick benchmarking. Console mode requires building from source (see [Build from Source](#-build-from-source) section).
73
73
-**Puzzle Testing in Console Mode:** Easily run automated engine tests on chess puzzles directly from the console. Configure puzzle sources, formats, and test parameters using the [PuzzleConfig.md](PuzzleConfig.md) file for flexible and reproducible puzzle-based benchmarking. Results can later be viewed and analyzed in the GUI by loading the generated .epd file for puzzle visualization (accessible via Tools > Test Canvas in the GUI menu).
74
74
75
75
### 🎥 Streaming and Community Features
@@ -79,50 +79,83 @@ See [Tournament.json.md](Tournament.json.md) for configuration details, plus [Sw
79
79
80
80
---
81
81
82
-
## ⚠️ Limitations
82
+
## 📦 Quick Start
83
83
84
-
-**UCI Engines Only:** EngineBattle exclusively supports chess engines using the Universal Chess Interface (UCI). Older or alternative protocols are not supported.
84
+
Pre-built binaries are available from [GitHub Releases](https://github.com/lepned/EngineBattle/releases).
85
+
86
+
### 1. Download
87
+
88
+
Choose a variant:
89
+
90
+
| Variant | Size | .NET Runtime Required? |
91
+
|---------|------|----------------------|
92
+
|**Self-contained**|~58 MB | No — everything is bundled |
Available platforms: **win-x64**, **linux-x64**, **osx-x64**, **osx-arm64**
96
+
97
+
### 2. Run
98
+
99
+
Extract the zip and run:
100
+
101
+
-**Windows:**`EngineBattle.exe`
102
+
-**Linux / macOS:**`./EngineBattle`
103
+
104
+
Your browser opens automatically. If not, navigate to the localhost URL shown in the console.
105
+
106
+
### 3. First Run
107
+
108
+
A blank `tournament.json` is auto-created next to the executable on first startup. See [Configuration](#configuration) below to set up your engines.
85
109
86
110
---
87
111
88
-
## ✨ Purpose and Goals
112
+
## 🛠 Build from Source
89
113
90
-
EngineBattle streamlines the process of testing, evaluating, and showcasing chess engines, offering powerful tools and intuitive interfaces designed for chess engine developers, enthusiasts, researchers, and streamers. Its primary focus is on creating enjoyable, interactive, and community-friendly engine tournaments and puzzle-based testing environments.
114
+
For developers who want to modify the code, use the CLI console commands, or run the latest unreleased changes.
91
115
92
-
Enjoy the powerful capabilities of EngineBattle and enhance your chess engine experience today!
116
+
### Prerequisites
93
117
118
+
[.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later.
To run the program, you will need to have .NET 10.0 or later installed. You can download it from the official [.NET website](https://dotnet.microsoft.com/download/dotnet/10.0).
128
+
A console application should now run with a link to the localhost URL. Ctrl + click on the link to open the URL in the browser. To keep your local copy updated:
99
129
100
-
## Installation
130
+
```bash
131
+
git pull origin main
132
+
```
101
133
102
-
1. Create a folder where the code is to be installed (e.g., `Chess` folder).
103
-
2. Open Terminal and change the directory to the folder you just created.
104
-
3. Run the following git command to clone the repository:
4. Change the directory to the `WebGUI` folder inside the newly created `EngineBattle` folder:
107
-
` cd EngineBattle/WebGUI `
108
-
109
-
5. Run the following dotnet command to start the application:
110
-
` dotnet run -c release `
134
+
### Console Commands (source builds only)
111
135
112
-
A console application should now run with a link to the localhost URL. Ctrl + click on the link to open the URL in the browser (most testing is done in Edge browser). You should now be able to see the web GUI in the browser.
113
-
To keep your local copy of this repo updated, navigate to the `EngineBattle` folder in the console and run:
136
+
The Console project provides CLI commands not included in the release binaries:
114
137
115
-
` git pull origin main `
138
+
```bash
139
+
cd Console
140
+
dotnet run -c release -- tournamentjson <fullPathToTournament.json>
141
+
dotnet run -c release -- puzzlejson <fullPathToPuzzleConfig.json>
142
+
dotnet run -c release -- eretjson <fullPathToEretConfig.json>
143
+
dotnet run -c release -- analyze <engine> [fen] [options]
144
+
dotnet run -c release -- compare <engine1><engine2> [options]
145
+
dotnet run -c release -- tune <fullPathToTunerConfig.json>
146
+
```
147
+
148
+
---
116
149
117
150
## Configuration
118
151
119
152
Before you can do much with the GUI, you need to configure all the engines you want to use. Follow these steps to configure `EngineSetup`:
120
153
121
-
1. Edit the `tournament.json` file located under the `wwwroot` folder in `WebGUI`- [Link to Tournament.json](Tournament.json.md).
122
-
-The tournament.json file will be automatically created and placed in the `wwwroot` folder on first startup if it doesn't already exist.
123
-
-If the tournament.json file is not present (for unknown reasons), you can create one by copying the `Tournament.json` file from the link above and pasting it into the `wwwroot` folder.
154
+
1. Edit the `tournament.json` file - [Tournament Configuration Reference](TournamentConfig.md).
155
+
-**Release binaries:**`tournament.json` is auto-created next to the executable on first startup.
156
+
-**Source builds:**`tournament.json`is located in the `WebGUI/wwwroot` folder and is auto-created on first startup if it doesn't exist.
124
157
2. Create and define the folder where all `engineDefs` are located. Set the path to this folder under the key: `EngineDefFolder`.
125
-
3. Every engine needs an `EngineDef.json` file - [Link to EngineDef.json](EngineDef.json.md) / [Link to LC0Def.json](LC0Def.json.md). Make a copy, configure each engine as you wish, and save it with a proper name like `SFDef.json` for Stockfish.
158
+
3. Every engine needs an `EngineDef.json` file - [Engine Configuration Reference](EngineDefConfig.md) / [LC0 Configuration Reference](LC0Config.md). Make a copy, configure each engine as you wish, and save it with a proper name like `SFDef.json` for Stockfish.
126
159
4. Add all your `EngineDef.json` files that will be part of the tournament under the key: `EngineDefList`. See below for an example of how to do this.
127
160
```
128
161
"EngineSetup": {
@@ -159,9 +192,13 @@ After you have created and configured a `tournament.json` file on your computer,
159
192
160
193
The `wwwroot` folder includes a selection of images used by the program, located in the Img subfolder. To add new images for engines you include in tournaments, simply place them in the `Img` folder as .png or .jpg files if the image does not already exist there. This allows you to customize the visual representation of each engine in your tournaments.
161
194
195
+
### Logs
196
+
197
+
Log files are written to a `logs/` folder in the current working directory. Logs use daily rolling files with a 10 MB size limit per file.
198
+
162
199
## Running a Tournament
163
200
164
-
Use your browser’s built-in zoom function to adjust the GUI size to your preference. For streaming, it’s recommended to set the zoom level to 80% or 90%, depending on your screen resolution and size.
201
+
Use your browser's built-in zoom function to adjust the GUI size to your preference. For streaming, it's recommended to set the zoom level to 80% or 90%, depending on your screen resolution and size.
165
202
Press F11 to enter full-screen mode — this is also recommended for the best streaming experience.
166
203
167
204
To operate a tournament, you only need two keys:
@@ -258,7 +295,7 @@ Each `ResultReason` has a corresponding explanation that provides more details a
258
295
259
296
## Analysis Mode
260
297
261
-
The analysis mode provides a user-friendly interface for analyzing chess positions and optionally comparing engine evaluations side by side.
298
+
The analysis mode provides a user-friendly interface for analyzing chess positions and optionally comparing engine evaluations side by side.
262
299
263
300
Analysis mode uses a `AnalyzeConfig.json` file - [Link to AnalyzeConfig.json](AnalyzeConfig.md) - to pick engines in order from top to bottom, so the first engine in the list will be picked for single analysis and the first two engines will be picked for dual analysis.
264
301
@@ -310,7 +347,6 @@ This application uses the following libraries, which are licensed under their re
0 commit comments