Allow "engine debugging" to be enabled. (#1152)

* Allow "engine debugging" to be enabled.

* Adapt test-code for debug-mode change.

* Corrected description of debug-flag in config.yml.default

* Updated wiki for engine debug-flag.

* Add debug parameter to ScholarsMate engine

Parameter is unused.

* Typos

* Add debug to Minimal Engine

Remove unused name parameter (no other code uses it) and replace it with
debug so all EngineWrapper classes have same __init__().

Remove default argument values to ensure __init__() is called correctly.

---------

Co-authored-by: Mark Harrison <MarkZH@users.noreply.github.com>

Author: folkertvanheusden

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: Whether 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: Whether 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)
@@ -539,7 +544,7 @@ class MinimalEngine(EngineWrapper):
     """
 
     def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stderr: int | None,  # noqa: ARG002
-                 draw_or_resign: Configuration, game: model.Game | None = None, name: str | None = None,  # noqa: ARG002
+                 draw_or_resign: Configuration, game: model.Game | None, debug: bool,  # noqa: ARG002
                  **popen_args: str) -> None:  # noqa: ARG002 Unused argument popen_args
         """
         Initialize the values of the engine that all homemade engines inherit.
@@ -548,9 +553,7 @@ def __init__(self, commands: COMMANDS_TYPE, options: OPTIONS_GO_EGTB_TYPE, stder
         :param draw_or_resign: Options on whether the bot should resign or offer draws.
         """
         super().__init__(options, draw_or_resign)
-
-        self.engine_name = self.__class__.__name__ if name is None else name
-
+        self.engine_name = self.__class__.__name__
         self.engine = FillerEngine(self, name=self.engine_name)
 
     def get_pid(self) -> str:

test_bot/homemade.py

@@ -13,9 +13,9 @@ class ScholarsMate(ExampleEngine):
     """A homemade engine that plays the scholar's mate."""
 
     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:
         """Set up engine."""
-        super().__init__(commands, options, stderr, draw_or_resign, game, **popen_args)
+        super().__init__(commands, options, stderr, draw_or_resign, game, debug, **popen_args)
 
     def search(self, board: chess.Board, time_limit: chess.engine.Limit, ponder: bool, draw_offered: bool,
                root_moves: MOVE) -> chess.engine.PlayResult:

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)