Lishogi Bot

A bridge between Lishogi's Bot API and Lishogi USI Bots. In case you don't know English, view the Japanese Translation here (日本語翻訳).

How to Install

Mac/Linux:

• NOTE: Only Python 3.8 or later is supported!
• Download the repo into Lishogi-Bot directory.
• Navigate to the directory in cmd/Terminal: cd Lishogi-Bot.
• Install pip: apt install python3-pip.
• Install virtualenv: pip install virtualenv.
• Setup virtualenv: apt install python3-venv.

python3 -m venv venv  # if this fails you probably need to add Python3 to your PATH.
virtualenv venv -p python3  # if this fails you probably need to add Python3 to your PATH.
source ./venv/bin/activate
python3 -m pip install -r requirements.txt

• Copy config.yml.default to config.yml.
• Edit the config.yml file to your liking by changing the supported variants, timings, challenge modes and incoming challenges, so that it plays shogi the way you want it to (use "#" to disable certain ones).

Windows:

• NOTE: Only Python 3.8 or later is supported!
• If you don't have Python, you may download it here. When installing it, enable add Python to PATH, then go to custom installation (this may be not necessary, but on some computers it won't work otherwise) and enable all options (especially install for all users), except the last . It's better to install Python in a path without spaces, like C:\Python\.
• To type commands it's better to use PowerShell. Go to the Start menu and type PowerShell (you may use cmd too, but sometimes it may not work).
• Then you may need to upgrade pip. Execute python3 -m pip install --upgrade pip in PowerShell.
• Download the repo into Lishogi-Bot directory.
• Navigate to the directory in PowerShell: cd [folder's address] (example, cd C:\shogi\lishogi-bot).
• Install virtualenv: pip install virtualenv.
• Setup virtualenv:

python3 -m venv .venv  # if this fails you probably need to add Python3 to your PATH.
./.venv/Scripts/Activate.ps1  # `.\.venv\Scripts\activate.bat` should work in cmd in administrator mode. This may not work on Windows, and in this case you need to execute "Set-ExecutionPolicy RemoteSigned" first and choose "Y" there (you may need to run Powershell as administrator). After you execute the script, change execution policy back with "Set-ExecutionPolicy Restricted" and pressing "Y".
pip install -r requirements.txt

• Copy config.yml.default to config.yml.
• Edit the config.yml file to your liking by changing the supported variants, timings, challenge modes and incoming challenges, so that it plays shogi the way you want it to (use "#" to disable certain ones).

Lishogi OAuth

• Create an account for your bot on Lishogi.org.
• NOTE: If you have previously played games on an existing account, you will not be able to use it as a bot account.
• Once your account has been created and you are logged in, create a personal OAuth2 token with the "Play games with the bot API" ('bot:play') scope selected and a description added.
• A token (e.g. xxxxxxxxxxxxxxxx) will be displayed. Store this in the config.yml file as the token field. You can also set the token in the environment variable $LISHOGI_BOT_TOKEN.
• NOTE: You won't see this token again on Lishogi, so save it or store it somewhere.

Setup Engine

Within the file config.yml:

• Enter the directory containing the engine executable in the engine: dir field.
• Enter the executable name in the engine: name field (In Windows you may need to type a name with .exe, like YaneuraOu.exe)
• If you want the engine to run in a different directory (e.g., if the engine needs to read or write files at a certain location), enter that directory in the engine: working_dir field.
  • If this field is blank or missing, the current directory will be used.

As an optional convenience, there is a folder named engines within the Lishogi-Bot folder where you can copy your engine and all the files it needs. This is the default executable location in the config.yml.default file.

Engine Configuration

Besides the above, there are many possible options within config.yml for configuring the engine for use with Lishogi-Bot.

• protocol: Specify which protocol your engine uses.
  1. "usi" for the Universal Shogi Interface.
  2. "homemade" if you want to write your own engine in Python within Lishogi-Bot. See Creating a homemade bot below.
• ponder: Specify whether your bot will ponder, i.e., think while the bot's opponent is choosing a move.
• engine_options: Command line options to pass to the engine on startup. For example, the config.yml.default has the configuration

  engine_options:
    cpuct: 3.1

This would create the command-line option --cpuct=3.1 to be used when starting the engine. Any number of options can be listed here, each getting their own command-line option.

• usi_options: A list of options to pass to a USI engine after startup. Different engines have different options, so treat the options in config.yml.default as templates and not suggestions. When USI engines start, they print a list of configurations that can modify their behavior after receiving the string "usi". For example, to find out what options YaneuraOu v6.50 supports, run the executable in a terminal, type usi, and press Enter. The engine will print the following when run at the command line:

id name YaneuraOu NNUE 6.50
id author by yaneurao
option name Threads type spin default 4 min 1 max 512
option name USI_Hash type spin default 16 min 1 max 33554432
option name USI_Ponder type check default false
option name Stochastic_Ponder type check default false
option name MultiPV type spin default 1 min 1 max 800
option name NetworkDelay type spin default 120 min 0 max 10000
option name NetworkDelay2 type spin default 1120 min 0 max 10000
option name MinimumThinkingTime type spin default 2000 min 1000 max 100000
option name SlowMover type spin default 100 min 1 max 1000
option name MaxMovesToDraw type spin default 0 min 0 max 100000
option name DepthLimit type spin default 0 min 0 max 2147483647
option name NodesLimit type spin default 0 min 0 max 9223372036854775807
option name EvalDir type string default eval
option name WriteDebugLog type check default false
option name GenerateAllLegalMoves type check default false
option name EnteringKingRule type combo default CSARule27 var NoEnteringKing var CSARule24 var CSARule24H var CSARule27 var CSARule27H var TryRule
option name ThreadIdOffset type spin default 0 min 0 max 7
option name LargePageEnable type check default true
option name USI_OwnBook type check default true
option name NarrowBook type check default false
option name BookMoves type spin default 16 min 0 max 10000
option name BookIgnoreRate type spin default 0 min 0 max 100
option name BookFile type combo default standard_book.db var no_book var standard_book.db var yaneura_book1.db var yaneura_book2.db var yaneura_book3.db var yaneura_book4.db var user_book1.db var user_book2.db var user_book3.db var book.bin
option name BookDir type string default book
option name BookEvalDiff type spin default 30 min 0 max 99999
option name BookEvalBlackLimit type spin default 0 min -99999 max 99999
option name BookEvalWhiteLimit type spin default -140 min -99999 max 99999
option name BookDepthLimit type spin default 16 min 0 max 99999
option name BookOnTheFly type check default false
option name ConsiderBookMoveCount type check default false
option name BookPvMoves type spin default 8 min 1 max 246
option name IgnoreBookPly type check default false
option name SkillLevel type spin default 20 min 0 max 20
option name DrawValueBlack type spin default -2 min -30000 max 30000
option name DrawValueWhite type spin default -2 min -30000 max 30000
option name PvInterval type spin default 300 min 0 max 100000
option name ResignValue type spin default 99999 min 0 max 99999
option name ConsiderationMode type check default false
option name OutputFailLHPV type check default true
usiok

Any of the names following option name can be listed in usi_options in order to configure the YaneuraOu engine.

  usi_options:
    NetworkDelay: 100
    Skill Level: 10

The exceptions to this are the options Threads, USI_Ponder and MultiPv. These will be handled by Lishogi-Bot after a game starts and should not be listed in the config.yml file. Also, if an option is listed under usi_options that is not in the list printed by the engine, it will cause an error when the engine starts because the engine won't understand the option. The word after type indicates the expected type of the options: string for a text string, spin for a numeric value, check for a boolean True/False value.

One last option is go_commands. Beneath this option, arguments to the USI go command can be passed. For example,

  go_commands:
    nodes: 1
    depth: 5
    movetime: 1000

will append nodes 1 depth 5 movetime 1000 to the command to start thinking of a move: go startpos e2e4 e7e5 ....

• abort_time: How many seconds to wait before aborting a game due to opponent inaction. This only applies during the first six moves of the game.

• fake_think_time: Artificially slow down the engine to simulate a person thinking about a move. The amount of thinking time decreases as the game goes on.

• rate_limiting_delay: For extremely fast games, the lishogi.org servers may respond with an error if too many moves are played too quickly. This option avoids this problem by pausing for a specified number of milliseconds after submitting a move before making the next move.

• move_overhead: To prevent losing on time due to network lag, subtract this many milliseconds from the time to think on each move.

• correspondence These options control how the engine behaves during correspondence games.

  • move_time: How many seconds to think for each move.
  • checkin_period: How often (in seconds) to reconnect to games to check for new moves after disconnecting.
  • disconnect_time: How many seconds to wait after the bot makes a move for an opponent to make a move. If no move is made during the wait, disconnect from the game.
  • ponder: Whether the bot should ponder during the above waiting period.

• challenge: Control what kind of games for which the bot should accept challenges. All of the following options must be satisfied by a challenge to be accepted.

  • concurrency: The maximum number of games to play simultaneously.
  • sort_by: Whether to start games by the best rated/titled opponent "best" or by first-come-first-serve "first".
  • accept_bot: Whether to accept challenges from other bots.
  • only_bot: Whether to only accept challenges from other bots.
  • max_increment: The maximum value of time increment.
  • min_increment: The minimum value of time increment.
  • max_base: The maximum base time for a game.
  • min_base: The minimum base time for a game.

• variants: An indented list of shogi variants that the bot can handle.

  variants:
    - standard
    - minishogi

• time_controls: An indented list of acceptable time control types from ultraBullet to correspondence.

  time_controls:
    - ultraBullet
    - bullet
    - blitz
    - rapid
    - classical
    - correspondence

• modes: An indented list of acceptable game modes (rated and/or casual).

  modes:
    - rated
    - casual

• greeting: Send messages via chat to the bot's opponent. The string {me} will be replaced by the bot's lishogi account name. The string {opponent} will be replaced by the opponent's lishogi account name. Any other word between curly brackets will be removed. If you want to put a curly bracket in the message, use two: {{ or }}.
  • hello: Message to send to the opponent before the bot makes its first move.
  • goodbye: Message to send to the opponent once the game is over.

  greeting:
    hello: Hi, {opponent}! I'm {me}. Good luck!
    goodbye: Good game!

Lishogi Upgrade to Bot Account

WARNING: This is irreversible. Read more about upgrading to bot account.

• Run python3 lishogi-bot.py -u.

To Run

After activating the virtual environment created in the installation steps (the source line for Linux and Macs or the activate script for Windows), run

python3 lishogi-bot.py

The working directory for the engine execution will be the Lishogi-Bot directory. If your engine requires files located elsewhere, make sure they are specified by absolute path or copy the files to an appropriate location inside the Lishogi-Bot directory.

To output more information (including your engine's thinking output and debugging information), the -v option can be passed to Lishogi-Bot:

python3 lishogi-bot.py -v

If you want to record the output to a log file, add the -l or --logfile along with a file name:

python3 lishogi-bot.py --logfile log.txt

To Quit

• Press CTRL+C.
• It may take some time to quit.

Creating a homemade bot

As an alternative to creating an entire chess engine and implementing one of the communication protocols (USI), a bot can also be created by writing a single class with a single method. The search() method in this new class takes the current board and the game clock as arguments and should return a move based on whatever criteria you desires.

Steps to create a homemade bot:

1. Do all the steps mentioned in How to Install.
2. In the config.yml, change the engine protocol to homemade.
3. Create a class in some file that extends the MinimalEngine class (in the strategies.py file).
   • Look at the strategies.py file to see some examples.
   • If you don't know what to implement, look at the EngineWrapper or USIEngine class.
     • You don't have to create your own engine, even though it's an EngineWrapper class.
       The examples just implement search.
4. In the config.yml, change the name from engine_name to the name of your class.
   • In this case, you could change it to:
     name: "RandomMove"

Tips & Tricks

• You can specify a different config file with the --config argument.
• Here's an example systemd service definition:

[Unit]
Description=Lishogi-Bot
After=network-online.target
Wants=network-online.target

[Service]
Environment="PYTHONUNBUFFERED=1"
ExecStart=/usr/bin/python3/home/User/Lishogi-Bot/Lishogi-Bot.py
WorkingDirectory=/home/User/lishogi-bot/
User=UserName
Group=GroupName
Restart=always

[Install]
WantedBy=multi-user.target

Acknowledgements

Thanks to the Lichess Team for creating a repository that could be easily accessed and modified to help converting it to a format that supports Lishogi. Thanks to Tasuku SUENAGA a.k.a. gunyarakun and his python-shogi code which allows engine communication seamlessly. Thanks to WandererXII for all his effort and help.

License

Lishogi-Bot is licensed under the AGPLv3 (or any later version at your option). Check out the LICENSE file for the full text.