EngineDefConfig.md

EngineDef.json Configuration

This document provides an overview of the EngineDef.json configuration file used in the EngineBattle application. This file defines the settings and parameters for configuring a chess engine.

You rarely write one by hand. Setup & Settings > Engine creator in the GUI, and eb-cli engine new in the console, both ask the engine itself: they start it, read what it answers to uci (name, author, every option with its default) and write the def from that. The two share one implementation.

eb-cli engine new C:/Engines/stockfish.exe --out-dir C:/Chess/EngineDefs --syzygy D:/syzygy --uci Threads=8 --uci Hash=4096
eb-cli engine new C:/Engines/lc0.exe --net C:/Networks/BT4-332.pb.gz --out-dir C:/Chess/EngineDefs

--net goes into the engine's own network option (Lc0's WeightsFile, Ceres' Network - found on the option, not the engine's name) and its folder into NetworkPath; an engine without a network option refuses it. --syzygy fills SyzygyPath when the engine has one and names no folder yet. --uci NAME=VALUE overrides a default and must name an option the engine reported. --base def.json carries the option values and the display fields of an existing def over onto a fresh probe. --dry-run shows the def instead of writing it; an existing file is never overwritten without --force. The file is named after the engine without spaces (Stockfish19.json).

Given a def instead of an executable, engine new copies it with another network - the same engine, options and settings, the network option and NetworkPath pointing at --net:

eb-cli engine new Lc0_BT4_332.json --net C:/Nets/BT5.pb.gz            # BT5.json, named BT5
eb-cli engine new Lc0_BT4_332.json --net C:/Nets/BT5.pb.gz --name "LC0 BT5"
eb-cli engine new Ceres_arm_400M.json --net C:/Nets/arm_800003840.onnx  # Ceres_arm_800M.json

The copy is named after the net, or --name. A training checkpoint's def - named <prefix>_<step>M[_ema].json, for a net whose name ends in its position counter - gets the new net's step instead, in the file name and wherever the old step label stood (Name, Alias). It is written next to the def unless --out-dir says otherwise.

Configuration Fields

A def is refused when any of the required fields - Name, TimeControlID, Version, Rating, LogoPath, Protocol, Path, NetworkPath and Options - is missing, or when TimeControlID is not a JSON number. The check is on presence: an engine without a network still writes "NetworkPath": "", and one without options "Options": {}. Every other field is optional.

General Information

• Name (required): The full name of the chess engine.
• Alias (optional): A short name or nickname for the engine.
• Version (required): The engine's version or additional descriptive information.
• TimeControlID (required, a number): Identifier for the associated time control configuration defined in tournament.json.
• Rating (required): The engine's rating, typically represented by an Elo value.
• Dev (optional): Information about the engine's developer(s).
• LogoPath (required): The file path for the engine's logo image.
• Protocol (required): The communication protocol (e.g., UCI, Winboard, XBoard) used by the engine.
• DeviceOption / DeviceTemplate (optional): for tournaments that run games in parallel on several GPUs. DeviceOption names the UCI option that selects the device and DeviceTemplate is its value with {0} standing for the GPU index - e.g. "DeviceOption": "Device", "DeviceTemplate": "GPU:{0}#TensorRTNative" for Ceres, or "DeviceOption": "BackendOptions", "DeviceTemplate": "gpu={0}" for Lc0. Each running instance of the engine (one per game played at once) gets its id from GPUs in tournament.json, instance i taking GPUs[i % GPUs.Length]; a value already present in Options has its numbers replaced in place. Left empty (the default), every game sends the option exactly as written.
• IsChallenger is not written in the file: EngineBattle sets it at run time for the challengers of a gauntlet.

Winboard-Specific Configuration

For engines using the Winboard/XBoard protocol, you can optionally specify WinboardConfig to control protocol-specific behavior:

• WinboardConfig (optional): Configuration object for Winboard engines. If omitted, default values are used.
  • SideToMovePOV (bool): If true, the engine reports its scores from White's point of view (Crafty does), and EngineBattle turns them to the side to move. If false (default), the engine reports from the side to move, as the protocol expects. The name says the opposite of what it does; it is kept so existing defs keep working. Default: false
  • TimeControlStrategy (string): Time control strategy for this engine. Default: "LevelWithTime"
    • "LevelWithTime": Standard V2 approach (send level once per game + time/otim every move)
    • "TimeOtimOnly": For V1 engines or engines with broken level command (send time/otim only)
    • "StWithTime": Safety mode (send st + time/otim for better time management) - for engines that ignore time/otim. The st is the time left over the moves to go plus the increment, rounded down to whole seconds and never more than half the time left
    • "StOnly": Legacy mode (send st only, may cause poor time management)
    • "AutoDetect": Probe level command at runtime, fallback to TimeOtimOnly on error
  • StartupCommands (array of strings): Commands to send to the engine after initialization (after post and easy). Useful for engines requiring specific setup commands. Default: []
  • PreGoDelayMs (int): pause between the time commands (time/otim, or st) and go, so an engine without ping support has read its clock before it starts thinking. An engine with ping gets go at once (CommandDelayMs still pauses before it). Default: 100; 0 sends go at once.
  • MinLevelIncrement (int): the least increment, in whole seconds, the level command states. level takes whole seconds and the increment is rounded down (0.1 s is sent as 0, 0.5 s as 0), so the engine is never told more than it gets; an engine that only searches with an increment of at least 1 gets 1 here. A game without any increment (10+0) is sent as it is. Default: 0
  • CommandDelayMs (int): pause in milliseconds before each line after the first when several are sent at once (force, setboard, st, time, otim, and at start-up post, easy, level, the feature replies and the StartupCommands). For an engine that fails when commands arrive together (for example 20). The clock starts after go, so the pause costs the engine no time. Default: 0
  • ForceV1Mode (bool): If true, forces Winboard V1 protocol mode (skips protover 2 negotiation, uses conservative defaults). Use this for very old engines that don't understand protover 2 at all. Default: false
  • RequiresLevelForThinkingOutput (bool): If true, sends a dummy level 0 5 0 command at startup to enable standard thinking output format. It is sudden death, so an engine that keeps it never budgets for a clock it thinks comes back at move 40. Use this for engines that need level to enable output but have broken level-based time management. Note: This is compatible with TimeOtimOnly strategy - the dummy level is sent only at startup, while time/otim are used during games. Default: false
  • Use4FieldFen (bool): If true, sends 4-field FEN format (position, side, castling, en passant) instead of full 6-field FEN (which includes halfmove clock and fullmove number) in setboard commands. Use this for very old engines that crash or hang on 6-field FEN. Default: false

Contempt Settings

• ContemptEnabled (optional): Option to enable or disable contempt settings for the engine.
• NegativeContemptAllowed (optional): Option to allow negative contempt values.

Paths and Execution

• Path (required): The file system path to the engine's executable.
• NetworkPath (required, may be empty): The directory where the engine neural network files reside.
• Args (optional): Additional command-line arguments for the engine.

Options

Options is required; {} when the engine gets no options.

• Threads: Number of threads the engine should use.
• Hash: Size of the hash memory in megabytes.
• SyzygyPath: The directory path for Syzygy tablebases.
• Ponder: Set by EngineBattle from the tournament's AllowPondering; a value here is overridden in tournaments.
• UCI_ShowWDL: Determines whether the engine displays Win/Draw/Loss statistics in UCI mode.
• Move overhead (Move Overhead, MoveOverheadMs, ...): used in tournaments and Play vs Computer. The analysis pages always set the engine's own overhead option to 0, whatever the def says: a fixed search time there should be searched in full, not answered early.
• Any other UCI option you want to pass to the engine.

EngineDef.json Examples

UCI Engine Example

{
  "Name": "Stockfish 17",
  "Alias": "SF 17",
  "Version": "NNUE with 2 cores",
  "TimeControlID": 1,
  "Rating": 3600,
  "Dev": "by The Stockfish developers.",
  "LogoPath": "Img/SF-TCEC.png",
  "Protocol": "UCI",
  "ContemptEnabled": false,
  "NegativeContemptAllowed": false,
  "Path": "C:/Dev/Chess/Engines/SF/sf17.exe",
  "NetworkPath": "C:/Dev/Chess/Networks",
  "Args": null,
  "Options": {
    "Threads": 2,
    "Hash": 2048,
    "SyzygyPath": "C:/Dev/Chess/TableBases/syzygy",
    "Ponder": false,
    "UCI_ShowWDL": true
  }
}

Winboard Engine Examples

Standard Winboard Engine (Crafty)

{
  "Name": "Crafty",
  "Alias": "Crafty",
  "Version": "25.2",
  "TimeControlID": 1,
  "Rating": 2500,
  "Dev": "Robert Hyatt",
  "LogoPath": "Img/imgEB/Crafty.png",
  "Protocol": "Winboard",
  "ContemptEnabled": false,
  "NegativeContemptAllowed": false,
  "Path": "C:/Dev/Chess/Engines/Crafty.exe",
  "NetworkPath": "",
  "Args": "--xboard",
  "Options": {}
}

Winboard Engine with a Broken level Command

For an engine whose level command breaks its time management but which needs a level to print thinking output: TimeOtimOnly for the clock, and RequiresLevelForThinkingOutput for the output.

{
  "Name": "OldEngine",
  "Alias": "OldEngine",
  "Version": "1.0",
  "TimeControlID": 1,
  "Rating": 2200,
  "Dev": "N/A",
  "LogoPath": "Img/engine.png",
  "Protocol": "Winboard",
  "ContemptEnabled": false,
  "NegativeContemptAllowed": false,
  "Path": "C:/Engines/OldEngine.exe",
  "NetworkPath": "",
  "Args": "",
  "Options": {},
  "WinboardConfig": {
    "SideToMovePOV": false,
    "TimeControlStrategy": "TimeOtimOnly",
    "RequiresLevelForThinkingOutput": true
  }
}

Winboard Engine with Startup Commands

{
  "Name": "CustomEngine",
  "Alias": "Custom",
  "Version": "1.0",
  "TimeControlID": 1,
  "Rating": 2400,
  "Dev": "Developer Name",
  "LogoPath": "Img/engine.png",
  "Protocol": "Winboard",
  "ContemptEnabled": false,
  "NegativeContemptAllowed": false,
  "Path": "C:/Dev/Chess/Engines/Custom.exe",
  "NetworkPath": "",
  "Args": "",
  "Options": {},
  "WinboardConfig": {
    "SideToMovePOV": true,
    "TimeControlStrategy": "LevelWithTime",
    "StartupCommands": ["level 16"]
  }
}