Allow "engine debugging" to be enabled.

config.yml.default

@@ -4,6 +4,7 @@ url: "https://lichess.org/"        # Lichess base URL.
 engine:                            # Engine settings.
   dir: "./engines/"                # Directory containing the engine. This can be an absolute path or one relative to lichess-bot/.
   name: "engine_name"              # Binary name of the engine to use.
+  debug: False                     # When enabled, log all startup communication with the engine.
 # interpreter: "java"
 # interpreter_options:
 #   - "-jar"

lib/engine_wrapper.py

@@ -67,7 +67,8 @@ def create_engine(engine_config: Configuration, game: model.Game | None = None)
             f"    Invalid engine type: {engine_type}. Expected xboard, uci, or homemade.")
     options = remove_managed_options(cfg.lookup(f"{engine_type}_options") or Configuration({}))
     logger.debug(f"Starting engine: {commands}")
-    return Engine(commands, options, stderr, cfg.draw_or_resign, game, cwd=cfg.working_dir)
+    return Engine(commands, options, stderr, cfg.draw_or_resign, game, cfg.debug,
+                  cwd=cfg.working_dir)
 
 
 def remove_managed_options(config: Configuration) -> OPTIONS_GO_EGTB_TYPE:
@@ -478,7 +479,8 @@ class UCIEngine(EngineWrapper):
     """The class used to communicate with UCI engines."""
 
     def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stderr: int | None,
-                 draw_or_resign: Configuration, game: model.Game | None, **popen_args: str) -> None:
+                 draw_or_resign: Configuration, game: model.Game | None, debug: bool,
+                 **popen_args: str) -> None:
         """
         Communicate with UCI engines.
 
@@ -487,10 +489,11 @@ def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stder
         :param stderr: Whether we should silence the stderr.
         :param draw_or_resign: Options on whether the bot should resign or offer draws.
         :param game: The first Game message from the game stream.
+        :param debug: Wether to debug or not.
         :param popen_args: The cwd of the engine.
         """
         super().__init__(options, draw_or_resign)
-        self.engine = chess.engine.SimpleEngine.popen_uci(commands, timeout=60., debug=False, setpgrp=True, stderr=stderr,
+        self.engine = chess.engine.SimpleEngine.popen_uci(commands, timeout=60., debug=debug, setpgrp=True, stderr=stderr,
                                                           **popen_args)
         self.configure(options, game)
 
@@ -499,7 +502,8 @@ class XBoardEngine(EngineWrapper):
     """The class used to communicate with XBoard engines."""
 
     def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stderr: int | None,
-                 draw_or_resign: Configuration, game: model.Game | None, **popen_args: str) -> None:
+                 draw_or_resign: Configuration, game: model.Game | None, debug: bool,
+                 **popen_args: str) -> None:
         """
         Communicate with XBoard engines.
 
@@ -508,10 +512,11 @@ def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stder
         :param stderr: Whether we should silence the stderr.
         :param draw_or_resign: Options on whether the bot should resign or offer draws.
         :param game: The first Game message from the game stream.
+        :param debug: Wether to debug or not.
         :param popen_args: The cwd of the engine.
         """
         super().__init__(options, draw_or_resign)
-        self.engine = chess.engine.SimpleEngine.popen_xboard(commands, timeout=60., debug=False, setpgrp=True,
+        self.engine = chess.engine.SimpleEngine.popen_xboard(commands, timeout=60., debug=debug, setpgrp=True,
                                                              stderr=stderr, **popen_args)
         egt_paths = cast(EGTPATH_TYPE, options.pop("egtpath", {}) or {})
         protocol = cast(chess.engine.XBoardProtocol, self.engine.protocol)

test_bot/homemade.py

@@ -17,9 +17,10 @@ class Stockfish(ExampleEngine):
     """A homemade engine that uses Stockfish."""
 
     def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stderr: int | None,
-                 draw_or_resign: Configuration, game: model.Game | None, **popen_args: str) -> None:
+                 draw_or_resign: Configuration, game: model.Game | None, debug: bool,
+                 **popen_args: str) -> None:
         """Start Stockfish."""
-        super().__init__(commands, options, stderr, draw_or_resign, game, **popen_args)
+        super().__init__(commands, options, stderr, draw_or_resign, game, debug, **popen_args)
         self.engine = chess.engine.SimpleEngine.popen_uci(f"./TEMP/sf{file_extension}")
 
     def search(self, board: chess.Board, time_limit: chess.engine.Limit, ponder: bool, draw_offered: bool,

wiki/Configure-lichess-bot.md

@@ -17,6 +17,7 @@ Lichess allows a bot to play 100 games against other bots in a single day (games
 ## Engine options
 - `interpreter`: Specify whether your engine requires an interpreter to run (e.g. `java`, `python`).
 - `interpreter_options`: A list of options passed to the interpreter (e.g. `-jar` for `java`).
+- `debug`: When enabled, log all startup communication with the engine.
 - `protocol`: Specify which protocol your engine uses. Choices are:
     1. `"uci"` for the [Universal Chess Interface](https://wbec-ridderkerk.nl/html/UCIProtocol.html)
     2. `"xboard"` for the XBoard/WinBoard/[Chess Engine Communication Protocol](https://www.gnu.org/software/xboard/engine-intf.html)