EngineBattle

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.

Example: Tournament GUI — follow live games, standings, and results with interactive visualizations.

---

🚀 Key Features

🧩 Puzzles

• ERET Puzzles: Test engine performance using The Eigenmann Rapid Engine Test (ERET) puzzles designed for precise evaluation of chess positions.
• Lichess Puzzles: Direct integration with Lichess puzzles, supporting policy head tests, value head tests, and combined evaluations.
• Visualization of Puzzles: Automatically visualize puzzles that engines fail, clearly showing correct versus incorrect moves on a chessboard.

🎯 Tournament Features

• Prevent Move Deviation option: Ensures consistent move ordering across game formats, beneficial in gauntlet and round-robin tournaments, even when transpositions occur.
• Fischer Random Chess (Chess960): Supports Chess960, facilitating tests and tournaments with randomized starting positions.
• Flexible Time Controls: Fully customizable time or node limits per engine, including asymmetric configurations.
• Reference PGN Files: Optionally enforce move consistency with reference PGNs from previous EngineBattle tournaments.
• Dynamic Engine Addition: Engines can be added to tournaments after they begin, with new engines seamlessly catching up.
• Tablebase Adjudication: Built-in GUI support for adjudicating endgames using chess tablebases.
• Opening Books: Create and utilize opening books based on FEN and PGN files.
• Move Delay Option: Specify delays between moves, useful for clearly demonstrating forced checkmate sequences.
• Node-Limited Matches: Conduct node-limited games (e.g., policy tests with single-node searches).
• Principal Variation (PV) Boards: Display real-time PV boards per engine, highlighting evaluation disagreements visually with colored arrows.

Tournament Modes

EngineBattle supports five tournament formats, configured via TournamentMode in tournament.json:

• Round Robin (RR): Every engine plays every other engine once (or twice in double round-robin).
• Gauntlet: One or more challengers play against a pool of opponents for fast benchmarking.
• Cup: Single-elimination knockout with configurable games per match and optional seeding.
• Swiss: Pairings are based on score each round, scaling well for larger fields.
  • With an odd number of players one engine receives a bye each round (worth 1 point), and byes are not repeated when possible.
• Ladder: Elimination-style climbing tournament where engines challenge upward by rating. The loser is eliminated and the winner keeps climbing until only one engine remains.

See TournamentConfig.md for configuration details, plus SwissMode.md, CupMode.md, and LadderMode.md for mode-specific notes.

🔍 Analysis Mode

• Intuitive Analysis Interface: User-friendly interface for convenient position analysis, featuring search charts similar to those used in tournament mode. Includes overlay options to display additional information for MCTS engines like Lc0 and Ceres.
• Dual-Engine Comparison: Compare two engines simultaneously with side-by-side analysis, move lists, and detailed graphical evaluations.
• Game Review: Lichess-style move-by-move accuracy analysis with win probability tracking, move classifications (Brilliant, Great, Best, Inaccuracy, Mistake, Blunder), critical moves panel, and annotated PGN export. Supports single-game and batch review.
• Focus Mode: Restrict engine search to specific candidate moves for targeted position exploration.
• UCI Script Loading: Load a text file of UCI commands to quickly configure engine parameters during analysis. setoption lines wait until the engine is idle (a running search restarts with them); search commands (go, stop, position, isready, ...) are skipped, because the panel runs the searches. Lines an engine prints outside the UCI protocol (for example the output of its own dump commands) are shown in the server output.
• Play vs Computer: Play against any engine with clocks and takeback, lichess-style: legal-move dots on a picked-up piece and premoves while the engine thinks. See PlayVsComputer.md.
• Lc0 Contempt: Lc0's contempt as settings rather than UCI options - analyze a position objectively and from one side's view at once, or train against Lc0 playing for the win. See Lc0Contempt.md.

📚 PGN and EPD Tools

• Speed Calculation: Benchmark chess engines by calculating their median and average speeds from a PGN file, including the out-of-book speed (first search).
• Ratings: Elo ratings of every engine from one fit of all the games (the model Ordo uses, computed by EngineBattle itself), with error bars and the confidence for superiority - in every standings table and on the Ratings page for any PGN. How to read them: Ratings.md.
• Opening Books from PGN: Create custom opening books from existing PGN archives (such as TCEC games).
• Opening Books from EPD: Generate opening books directly from EPD files.
• Chess960 Position Generation: Quickly generate random Chess960 positions (EPD format) for diverse testing scenarios.
• Remove an engine from a PGN-file: Remove a specific engine's games from a PGN file to clean up tournament results or resume a tournament without including that engine.
• Move Deviation Finder: Easily identify and visualize deviations by chess engines compared to a reference engine in a PGN file, presented clearly with summary tables and visualized with chessboards.
• Out-of-Book Evaluation: Evaluate opening positions right after book exits using one or more engines to filter out openings that are too drawish or too one-sided for engine matches.

📈 Visualization and Statistics

• Live MCTS Charts: Real-time visualization of Monte Carlo Tree Search (MCTS) engine internals, including N-Plot and Q-Plot charts for engines like Lc0 and Ceres.
• Evaluation Charts: Visual representation of engine evaluation statistics throughout tournaments.
• Time Usage Charts: Detailed graphical display of engine time management.
• Nodes Per Second (NPS) Charts: Track and visualize computational speed and efficiency.
• Nodes Per Move (NPM) Charts: Clearly depict nodes used per move by each engine in tournaments.
• Configurable Search Charts: Customize the number of moves displayed and configure delta Q values to filter inferior moves from visualizations.

💻 Console Mode

• Basic Console Mode: Minimalist console mode designed for quicker time controls and node-testing, supporting parallel execution of multiple games for quick benchmarking. The console ships as eb-cli in every download, next to the WebGUI (or build it from source, see Build from Source).
• Engine matches from the command line: match plays a match from one command line - rating reports, an SPRT that stops it, resume, exit codes - takes the fastchess command line (cutechess-cli style) and writes fastchess or cutechess output, so testing tools written for those can run EngineBattle. See MatchMode.md.
• 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 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 (Tools > EPD visualizer in the GUI menu).

⚙️ Global Settings

• Persistent Preferences: A dedicated settings page to configure default paths, search modes, MultiPV, analysis defaults, game review parameters, and more. Settings persist across sessions.

🎥 Streaming and Community Features

• Streamer-Friendly Tournaments: Optimized tournament mode for engaging chess engine streaming, making it easy to share standings and results in real time.
• Web Application: Runs seamlessly in browsers, providing live console logs, pairings, standings, and results, ideal for live updates via Discord and other community platforms.

---

📦 Quick Start

Pre-built binaries are available from GitHub Releases.

1. Download

Choose a variant:

Variant	Size	.NET Runtime Required?
Self-contained	~95 MB	No — everything is bundled
Framework-dependent	~22 MB	Yes — install .NET 10 Runtime first

Available platforms: win-x64, win-arm64, linux-x64, osx-x64, osx-arm64

Each zip has the WebGUI (EngineBattle) and the console (eb-cli) side by side, the way cutechess ships cutechess-cli with its GUI. The console runs engine matches from one command line (MatchMode.md) and the other console tools (eb-cli.md).

On Windows there is also EngineBattle-Desktop (EngineBattle-Desktop-win-x64.zip or -win-arm64): the same application in its own window, with a native menu, remembered zoom and F11 full screen - no browser involved. Pick it if you prefer an app to a browser tab; everything else is identical. The desktop zip holds only the window: download the matching EngineBattle-win-x64.zip (or -win-arm64) as well and extract both into the same folder, so that EngineBattleDesktop.exe sits next to EngineBattle.exe.

2. Run

Extract the zip and run:

• Windows: EngineBattle.exe (or EngineBattleDesktop.exe for the desktop app)
• Linux / macOS: ./EngineBattle

Your browser opens automatically. If not, navigate to the localhost URL shown in the console. To start the server without opening a browser, pass --no-browser or set ENGINEBATTLE_NO_BROWSER=1.

Windows note: Windows may show a SmartScreen warning for unsigned executables. To bypass this, right-click EngineBattle.exe → Properties → check Unblock → OK, then run it normally.

macOS note: the release builds are not signed or notarised, so macOS quarantines them on download and refuses to start them ("cannot be opened because the developer cannot be verified"). Clear the quarantine flag after extracting:

xattr -dr com.apple.quarantine EngineBattle eb-cli
./EngineBattle

Alternatively, right-click EngineBattle in Finder → Open → Open confirms it once for that file.

Linux note: the release zip keeps the executable bit, so ./EngineBattle should just work. If your extraction tool dropped permissions, restore it with chmod +x EngineBattle eb-cli.

3. First Run

EngineBattle plays chess engines against each other, so the first thing it needs is at least two engine definitions - a small JSON file each, pointing at an engine you already have on this machine (Stockfish, Lc0, Ceres, ...). The tournament page shows these three steps until they are done, with a button for each:

1. Engine definitions - Setup & Settings > Engine creator writes one for each engine (pick the executable, set its options).
2. Tournament setup - Tournament > New tournament (the Tournament creator) picks the engines, the time control, the openings, where the games are written, and the branding on the tournament page (description, main logo, logo sizes, and the machine shown in the banner - filled in from what the computer reports).
3. Run - back on the tournament page, press Ctrl+R.

Another tournament file is opened from Tournament > Open tournament in the menu (in the desktop app, File > Open Tournament): it becomes the current tournament.json, and the old one is kept beside it as tournament_<date_time>.json. Not while a tournament is running.

The tournament page until the engines are in place: the three steps, each with its button.

Nothing has to be typed into a file. A tournament.json is created in the wwwroot folder next to the executable on first startup and the creators write into it; the Configuration section below is the reference for anyone who prefers a text editor.

---

🛠 Build from Source

For developers who want to modify the code or run the latest unreleased changes. The CLI console commands are also in every release download, as eb-cli.

Prerequisites

.NET 10.0 SDK or later.

Clone and Run

git clone https://github.com/lepned/EngineBattle.git
cd EngineBattle/WebGUI
dotnet run -c release

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:

git pull origin main

Console Commands

The Console project is developer and server tooling - matches, batch runs, engine probing, PGN and position queries. In the release zip it is eb-cli (eb-cli <command> [arguments]); from a source clone, run it with dotnet run --project Console -c Release -- <command> [arguments]:

eb-cli tournament run <tournament.json>
eb-cli puzzle run <PuzzleConfig.json> [--json]
eb-cli puzzle eret <EretConfig.json>
eb-cli analyze <engine> [<fen>] [--nodes N | --movetime MS | --depth N]
eb-cli compare <engine1> <engine2> [--positions suite.epd]
eb-cli match -engine cmd=A -engine cmd=B -each tc=10+0.1 -rounds 100
eb-cli engine new <engine.exe> [--out-dir DIR] [--net FILE] [--syzygy DIR] [--uci NAME=VALUE]...
eb-cli tune run <tuner-config.json>
eb-cli position <fen|startpos> [--square SQ] [--pv "<line>"] [--json]
eb-cli tablebase <fen> [--syzygy DIR]
eb-cli pgn deviations <file.pgn>
eb-cli pgn parse <file.pgn>
eb-cli gui [<page>] [--port N]

eb-cli alone lists every command, eb-cli help <command> explains one. Every command follows the same rules - options, --json, exit codes, Ctrl+C - described in eb-cli.md, with the full reference.

Position queries (position)

For validator and tooling use - e.g. differential testing against python-chess with EB as an oracle - eb-cli position <fen> --json prints the position's facts as JSON on stdout (diagnostics go to stderr; without --json a short text summary). It has status (checkmate/stalemate/check/ok), insufficientMaterial (dead-position approximation: kings only, kings plus one minor, or kings plus same-colored bishops), the full legalMoves list as UCI + SAN pairs (castling SAN is spelled 0-0) with per-move predicates (isCapture, isCastling, isEnPassant, givesCheck - python-chess gives_check() parity), and both colors' insights (king, checkers, check-block squares, pins as attacker/pinned/king triples, king danger/escape squares, hanging pieces judged by static exchange evaluation, and the tactics family: forks (a safe piece attacking two or more losable targets or the king), skewers (kind skewer or relativePin for two enemy pieces on one slider ray), overloadedDefenders (sole defenders of two or more pieces that hang without them), discoveredAttacks (a slider unveils check or a winning attack when its own blocker moves), and removableDefenders (an enemy sole defender that can be captured without loss, winning what it defended)). --square e4 adds squareFacts: attackersWhite/attackersBlack, the piece's attack set (attacks), isPinned and the pinRay (full king-pinner line), and safeDestinations - every legal move of that piece with its net material outcome (net > 0 wins material, 0 safe, < 0 the piece can be won on that square). --pv "e2e4 e7e5 ..." adds sanPv, the numbered SAN rendering of a line (diffable against python-chess variation_san). --positions file.epd --json gives every position of a file, a full movegen + SAN differential test in one run. All squares are absolute names like e4; field names are camelCase.

Configuration

The creators in the menu (Setup & Settings > Engine creator, Tournament > New tournament) do all of this from the GUI, and the settings that decide how the tournament page looks - text sizes, chart heights, PV boards - are set on the page itself and remembered per screen (see Running a Tournament). What follows is the reference for the two files they write, for anyone who prefers a text editor.

Every engine needs an engine definition, and the tournament needs to know where they are. In tournament.json:

1. Edit the tournament.json file - Tournament Configuration Reference.
   • Release binaries: tournament.json is auto-created in the wwwroot folder next to the executable on first startup.
   • Source builds: tournament.json is located in the WebGUI/wwwroot folder and is auto-created on first startup if it doesn't exist.
2. Create and define the folder where all engineDefs are located. Set the path to this folder under the key: EngineDefFolder.
3. Every engine needs an EngineDef.json file - Engine Configuration Reference / LC0 Configuration Reference. Make a copy, configure each engine as you wish, and save it with a proper name like SFDef.json for Stockfish.
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.

     "EngineSetup": {
       "EngineDefFolder": "C:/Dev/Chess/Engines/EngineDefs",
        "EngineDefList": [
           "SFDef.json",
           "Lc0Def.json",
           "DragonDef.json"  ]}
   

Folder Structure Example

#folder structure example

Engines/
├── EngineDefs/
│   ├── SFDef.json
│   ├── Lc0Def.json
│   └── DragonDef.json
├── LC0/
│   └── Lc0.exe
├── SF/
│   └── SF.exe
└── Dragon/
    └── Dragon.exe

3. Set the OpeningsPath and the PgnOutPath and time settings. Time controls, MoveOverhead, and DelayBetweenGames (or any other time settings) are specified as hh:mm:ss or hh:mm:ss.fff (fff = milliseconds, after a dot).
4. Tablebase adjudication is on when TablebaseDirectory (under Adjudication.TBAdj) names a folder with Syzygy tables; draw and win adjudication each have an Enabled switch (see TournamentConfig.md).

After you have created and configured a tournament.json file on your computer, it is highly advisable to make a backup copy. This ensures you can quickly restore your settings if you need to reinstall the application or encounter any configuration issues.

Images

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.

Logs

Log files are written to a logs/ folder in the current working directory:

• webgui-<date>.log - the WebGUI, one file a day (a new one past 10 MB)
• eb-cli-<date>.log - the console, one file a day (a new one past 10 MB)
• engine_<name>_<time>.log - what was sent to and read from an analysis engine, one file per engine start

Running a Tournament

The page sizes itself: every table shrinks to fit its box and grows when there is room. To make the text bigger or smaller, move the pointer to the bottom-right corner of the tournament page - a control appears with A-/A+ for the text, off/S/M/L for the two PV boards, -/+ for the chart heights, Eval / NPS / Time / Nodes to choose which charts are shown, save to make what is on screen the baseline for this screen, and reset to go back to the defaults. Appearance (under Setup & Settings) has the rest: the size of each region on its own, chart lines and Q difference, nodes per move in the standings, the cores and memory each engine uses, where the crosstable goes (cycling with the standings, below them, or hidden), the crosstable between games, and the cycle time. Everything is remembered per screen, so a laptop and the monitor it docks to each keep their own numbers; no file is involved.

The corner control: text, PV boards, chart heights, which charts to show, save and reset - per screen.

Press F11 for full screen - recommended for streaming, in the browser and in the desktop app alike.

To operate a tournament, you only need two keys:

• To start a tournament run, press: ctrl + r
• To cancel a tournament run, press: ctrl + c

Other useful keys are:

• Validate your tournament.json, which includes basic validation of every engine definition: ctrl + v
• Update and refresh the tournament GUI: ctrl + u
• Open the tournament view dialog: ctrl + p
• Adjudicate the current game as a white win, black win or draw: ctrl + alt + w / b / d
• Table text smaller / larger / back to the defaults: ctrl + alt + - / + / numpad 0

It is strongly recommended to run validation before starting a tournament to ensure that all engine definitions are correct and that the tournament settings are valid.

When the tournament is running, you can use the GUI to follow the games, check the standings, and view the results. The GUI is designed to be user-friendly and intuitive, providing real-time updates and visualizations to enhance the tournament experience. The console window will display additional tournament progress, including pairings, game results, standings, and other relevant information that can be useful for monitoring the tournament.

Time Controls

Each time control in tournament.json has an Id, and each engine's def names the one it plays with TimeControlID - so two engines can play different time controls. Write them the way match takes them:

"TimeControl": {
  "TimeConfigs": [
    { "Id": 1, "Tc": "60+1" },
    { "Id": 2, "Tc": "40/5:00+2" },
    { "Id": 3, "St": 1 },
    { "Id": 4, "Nodes": 1 }
  ]
}

"Tc": "60+1" is 60 seconds plus 1 second per move ("2:30+2" for minutes and seconds, "40/5:00+2" for 5 minutes per 40 moves), "St": 1 is 1 second per move, and "Nodes": 1 is a node limit - the one to use for policy tests. The older long form ("Fixed": "00:01:00", "Increment": "00:00:01") still reads as before. All forms and rules: TournamentConfig.md.

It is recommended to run policy tests in Console Mode for optimal performance by running games in parallel, see below how to set that up. However, you can also run these tests using the GUI by setting a delay per move. To do this, configure the MinMoveTimeInMS parameter to i.e. 2000 milliseconds in the GUI settings. This allows you to watch every move play out during policy tests and can even be streamed.

Tournament Console Mode

The console mode is designed for quick and efficient testing, allowing users to run multiple games in parallel for benchmarking purposes. This mode is ideal for policy matches and very quick time controls, such as 20 + 0.3 seconds or less. In order to use the console mode, run eb-cli from the release folder (or, from a source clone, with dotnet run --project Console from the repo root) with the following command:

eb-cli tournament run <fullPathToYourTournament.json>

dotnet run --project Console -c Release -- tournament run <fullPathToYourTournament.json>

There is a setting in the tournament.json file that allows you to set the number of games that can be run in parallel. This top-level setting is called NumberOfGamesInParallel (a file with the older TestOptions block, or its older name NumberOfGamesInParallelConsoleOnly inside it, is still read) and can be set to any number you like; it is lowered automatically when one copy of each engine times that number does not fit in 70% of the available memory. Values up to 4 games can be recommended for a strong GPU.

Note that parallel play applies to Round Robin and Gauntlet tournaments; Cup, Swiss and Ladder modes manage their pairings round by round and always run sequentially.

Running Parallel Games in the WebGUI

Parallel play also works directly in the WebGUI: start a Round Robin or Gauntlet tournament with NumberOfGamesInParallel above 1 from the Tournament page (Ctrl+R) and the browser navigates to the multi-board grid (/tournament-grid) — one live tile per concurrent game, with standings and pentanomial stats filling in as games finish. Clicking a tile opens the single-board live view for that game. Single-game user adjudication (Ctrl+Alt+W/B/D) is not available during parallel runs.

Watching Parallel Console Games Live in the WebGUI

Parallel console games do not have to run invisibly either: the console runner can broadcast every game to the WebGUI's live grid, giving you one live board per concurrent game.

1. Start the WebGUI as usual (dotnet run --project WebGUI -c Release).
2. Add a LiveFeed section to your tournament.json (or set the EB_LIVEFEED_URL environment variable, which overrides the JSON):

"LiveFeed": {
  "Url": "http://localhost:5018/api/livefeed",
  "Source": "",
  "File": "",
  "Token": ""
}

3. Run the tournament in console mode as described above.
4. Open http://localhost:5018/tournament-grid in the browser: one tile per concurrent game playing live, with standings and pentanomial stats filling in as games finish. Clicking a tile opens the full single-board live view for that game.

The WebGUI does not have to run on the same machine as the tournament — point Url at the machine hosting the GUI instead of localhost. The File field can additionally record the feed to an NDJSON file for later replay. See LiveFeedContract.md for the full wire protocol, authentication token and replay options.

PreventMoveDeviation Feature

The "PreventMoveDeviation" feature is designed to enhance engine testing by enforcing a consistent move order across different game formats. Stockfish, for example, typically deviates from earlier games played in the same position—about twice per game—which can introduce inconsistencies in testing.

Note on parallel play: The feature also works with NumberOfGamesInParallel above 1 — the replay history is shared across concurrent games under a lock. Sequential execution remains the most deterministic setup, because with parallel games the order in which positions enter the shared history depends on game timing.

By strictly adhering to a reference-based move order and tracking position hashes, this feature ensures that recurring board states are consistently recognized, even when transpositions occur. This controlled approach is beneficial in both gauntlet tournaments—where one or more engines play against every other participant—and in normal round-robin tournaments, where engines are prevented from deviating from moves they have previously played in the same position. As a result, testers can evaluate and compare engine performance with greater precision under these uniform conditions.

Live Plot Charts for MCTS Engines

The live plot charts (N-Plot and Q-Plot) are particularly useful for visualizing the internal thinking or search process of Monte Carlo Tree Search (MCTS) engines like Lc0 and Ceres. These charts provide insights into how these engines evaluate positions and make decisions during the game.

• N-Plot Chart: Displays the top N moves by nodes visited (%) during the search window, along with Q (evaluation) and policy (P %) values. If the top policy move is not part of the top N moves, it will also show this move in red with Q and P values. This chart helps in understanding how the search is biased during gameplay and how strongly the policy prefers one move over another.
• Q-Plot Chart: Shows the top N moves by Q-value (evaluation) during the search window, along with nodes visited (N %) and policy (P %) values. If the top policy move is not part of the top N Q-moves, it will show this move in red with N and P values. This chart provides a detailed view of the engine's evaluation process and the influence of the policy network.

Evaluation Chart

• Eval Chart: Displays evaluation statistics for the tournament. It is referenced by evalChart.

Time Usage Chart

• Time Usage Chart: Shows the time usage statistics for the tournament. It is referenced by timeUsageChart.

Nodes Per Second (NPS) Chart

• NPS Chart: Displays the nodes per second statistics. It is referenced by npsChart.

Nodes Per Move (NPM) Chart

• NPM Chart: Shows the nodes per move statistics for the tournament. It is referenced by nodesChart.

These charts are conditionally rendered based on the tournament's layout options and settings, providing a comprehensive view of the tournament's progress and performance metrics.

End of game result

The ResultReason type defines various reasons for the outcome of a chess game. Each reason is represented by a specific code and an explanation. Below is a summary of the type:

• Checkmate (CM): The game ended in checkmate.
• Stalemate (SM): The game ended in a stalemate.
• AdjudicateTB (TB): The game was adjudicated based on tablebase knowledge.
• AdjudicateMaterial (AM): The game was adjudicated due to insufficient material.
• ExcessiveMoves (50m): The game ended due to excessive moves (50-move rule).
• Repetition (R3): The game ended in a draw by repetition.
• AdjudicatedEvaluation (AE): The game was adjudicated based on evaluation agreement.
• ForfeitLimits (FL): The game was forfeited due to time or node limits.
• Disconnected (DC): The game ended due to a disconnect.
• Stalled (ST): The engine stopped answering: no readyok to the isready sent before every move (15 s), or no bestmove within 10 s of a stop. It loses the game and is restarted before its next one.
• AdjudicatedByUser (AU): The game was adjudicated by a user.
• Cancel (XX): The game was canceled.
• Illegal (IM): The game ended due to an illegal move.
• Resignation (RS): A Winboard engine resigned.
• NotStarted (NS): The game has not started.

Each ResultReason has a corresponding explanation that provides more details about the reason for the game's outcome.

Analysis Mode

The analysis mode provides a user-friendly interface for analyzing chess positions and optionally comparing engine evaluations side by side.

Analysis mode picks its engine from the default engine set in Settings — open an engine definition on the analysis page and use Set as default, or set DefaultEnginePath on the Settings page. Single analysis uses that engine; dual analysis loads a second one from the engine panel.

The dual analysis mode is designed to compare two engines at a time, displaying their evaluations, moves, and search statistics in a clear and concise manner.

Example: Single engine analysis - policy overlay on the board, visited-move chart, PV lines and live move stats.

Dual analysis: Lc0 and Stockfish on the same position - visit shares and move stats for the MCTS engine, eval by depth and the iteration log for the alpha-beta one.

Puzzle Testing Mode

Lichess Puzzle Testing Mode

The puzzle testing mode allows users to evaluate chess engines using a variety of Lichess puzzles, providing insights into their performance on specific positions. This mode uses the PuzzleConfig.json file - Link to PuzzleConfig.json - to configure the engines, puzzle sources, and test parameters.

The PuzzleConfig.json file defines the engines to be used, the puzzle file path, and the testing parameters. In this mode, engines are tested on puzzles sampled from the specified file, with options to filter puzzles by type, rating, or specific characteristics. The configuration also supports running tests with node limits or concurrent engine instances for efficient benchmarking. This mode is ideal for developers and researchers who want to test engine capabilities on specific puzzle types, such as mate-in-N problems, endgame studies, or tactical motifs. The results can be visualized to identify areas where engines excel or struggle, providing valuable feedback for engine improvement. For more information about how to run Lichess puzzles, see LichessPuzzle.md.

Example: Visualization of a failed puzzle — the engine's move (red) vs. the correct move (green).

ERET Testing Mode

The ERET (Eigenmann Rapid Engine Test) testing mode is designed to evaluate chess engines using a set of carefully curated puzzles for rapid and precise performance assessment. This mode uses the EretConfig.json file - Link to EretConfig.json - to configure the engines, puzzle sources, and test parameters.

The EretConfig.json file specifies the engines to be tested, the puzzle file path, and the testing parameters such as time or node limits. It supports both time-based and node-limited testing, allowing users to choose the evaluation method that best suits their needs. The configuration also enables concurrent engine testing for efficient benchmarking.

This mode is ideal for developers and researchers who want to quickly assess engine performance on a diverse set of positions, providing valuable insights into engine strengths, weaknesses, and overall capabilities. For more information about how to run ERET puzzles, see EretPuzzles.md.

Licensing

EngineBattle License Summary

This application is licensed under the GNU General Public License (GPL) version 3. For more details, see the License.txt file.

For the full license text, please visit the official GNU website: GNU General Public License, version 3

Additional Licensing Information

This application uses the following libraries, which are licensed under their respective licenses:

• .NET - MIT License
• Blazor - MIT License
• MudBlazor - MIT License
• Serilog - Apache License 2.0
• Fathom - MIT License (the Syzygy prober in Syzygy/Syzygy.cs is a C# port of Jon Dart's fork; the licence notice, naming Ronald de Man, basil00 and Jon Dart, is at the top of that file)
• Toolbelt.Blazor.HotKeys2 - Mozilla Public License 2.0
• Chess piece images (cburnett/wikipedia set from the chessboardjs project, plus the kosal and merida sets; each folder under wwwroot/pieces carries its own licence) - MIT License
• plotly.js - MIT License