1. Introduction

 

If the majority of shogi programs support a standard protocol, it becomes easy to run automatic tournament and matches between shogi programs. This is very useful for programmers, because a big number of games is often necessary in order to decide whether some change to a shogi program improves the strength.

For users of shogi software, a standardized protocol would make it possible to run several shogi engines in a single graphical interface. Instead of having to switch from one GUI to another whenever they want to use a different shogi program, they can use their favorite shogi GUI all the time, and load individual engines into the GUI.

 

 

All communication between the engine and the GUI is done by 7-bit ASCII text, and the English language is used in the names of the various commands. English letters are used to denote the various piece types ("P" for pawn, "L" for lance, etc.). This may seem like a strange choice (at least to non-technical users), considering that the vast majority of users of shogi software are Japanese.

The justification for the use of 7-bit ASCII is to make the work easier for the engine programmer. Most shogi engines are written in low-level programming languages like C, where reading and writing Unicode is difficult, especially while trying to maintain portability. Translation of the move output from the engine into Japanese notation is assumed to be the responsibility of the GUI.

A USI engine may also have several engine parameters which can be configured by the user (e.g. style of play, piece values for the various pieces, different kinds of search parameters, and so on). Each parameter has an internal name in 7-bit ASCII which is used in all communication between the engine and the GUI. An USI engine should, in addition to the executable file, be delivered with a Unicode text file containing Japanese translations (and optionally translations into other languages) of all option names. The GUI should use the translations in this file when displaying the options to the user.

The format of the translations file is not yet decided, and will be described in a future version of this document.

3. Forsyth-Edwards notation for shogi

 

 

 

The side to move. This field contains of a single letter, "b" (for "black") or "w" (for "white"), depending on the current side to move.

Move count. An integer representing the number of the current move in the game. We are using the shogi convention for move counting, which means that we count what international players would call "plies" or "half moves". For instance, after the moves 1. P7g-7f 2. P8c-8d, the move counter is 3. The "move count" data field is optional; a program should be able to read and understand an SFEN string even if this field is missing.

 

A more complicated example is the following position, taken from the 3rd game of the 19th Ryu-O match between Sato and Watanabe:

 

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

+----+----+----+----+----+----+----+----+----+

 

The SFEN notation described above differs from the FEN notation for chess positions in a few ways. The castling and en passant fields have been removed, for the obvious reason that castling and en passant captures do not exist in shogi. The halfmove clock has been removed because shogi has no 50-move draw rule. Finally, because captured pieces can be dropped back on the board in shogi, the "pieces in hand" data field has been added.

4. Differences between the UCI and USI protocols

 

 

Spaces are not allowed in option names. This fixes a small defect in the UCI protocol: In a UCI chess engine, there are certain words (most notably "type") which cannot be used in option names because it would cause ambiguity. The only advantage of allowing spaces in option names is that it makes the names look cosmetically nicer in the GUI, and this advantage disappears in USI because the GUI will not display the option name, but the translation found for this option name in the translation file. For instance, if the engine has an option named "NULL_MOVE_R", the translation file can contain an English translation like "Null move reduction factor", and it is this translation that will be displayed in the GUI (assuming that the user has set English as her preferred language).

Instead of FEN strings, SFEN strings (as described in section 3) are used. Where UCI uses position fen <fen>, USI uses position sfen <sfen>.

Mate scores are always sent using the shogi convention for move counting: We count plies, not full moves. Where you would send info score mate 3 in a UCI engine, you should send info score mate 5 in a USI engine.

5. Description of the universal shogi interface

The specification is independent of the operating system. For Windows, the engine is a normal exe file, either a console or "real" windows application.

The engine should boot and wait for input from the GUI, the engine should wait for the isready or setoption command to set up its internal parameters as the boot process should be as quick as possible.

All command strings the engine receives will end with '\n', also all commands the GUI receives should end with '\n'. Note: '\n' can be 0x0d or 0x0a0d or any combination depending on your OS. If you use the engine and GUI in the same OS this should be no problem if you communicate in text mode, but be aware of this when for example running a Linux engine in a Windows GUI.

The engine will always be in forced mode which means it should never start calculating or pondering without receiving a go command first.

By default all the opening book handling is done by the GUI, but there is an option for the engine to use its own book (USI_OwnBook option, see below).

if the engine receives a command which is not supposed to come, for example stop when the engine is not calculating, it should also just ignore it.

Normal (i.e. non-promoting, non-dropping moves) are written in English coordinate notation, using only the source and destination squares, without any piece letters or other characters (for instance 7g7f).

Drops are written with the English piece letter in upper case followed by a star (*) and the destination square (for instance P*3d).

These are all the command the engine gets from the interface.

usi

 

Switch the debug mode of the engine on and off. In debug mode the engine should send additional infos to the GUI, e.g. with the info string command, to help debugging, e.g. the commands that the engine has received etc. This mode should be switched off by default and this command can be sent any time, also when the engine is thinking.

isready

 

This is sent to the engine when the user wants to change the internal parameters of the engine. For the button type no value is needed. One string will be sent for each parameter and this will only be sent when the engine is waiting. The name and value of the option in <id> should not be case sensitive and can not include spaces.

register

 

 

The user doesn't want to register the engine now.

The engine should be registered with the name <x>

The engine should be registered with the code <y>

 

"register later"

This is sent to the engine when the next search (started with position and go) will be from a different game. This can be a new game the engine should play or a new game it should analyse but also the next position from a testsuite with positions only. As the engine's reaction to usinewgame can take some time the GUI should always send isready after usinewgame to wait for the engine to finish its operation.

position [sfen <sfenstring> | startpos ] moves <move1> ... <movei>

 

 

Start calculating on the current position set up with the position command. There are a number of commands that can follow this command, all will be sent in the same string.

If one command is not sent its value should be interpreted as if it would not influence the search.

searchmoves <move1> ... <movei>

 

 

Start searching in pondering mode. Do not exit the search in ponder mode, even if it's mate! This means that the last move sent in in the position string is the ponder move. The engine can do what it wants to do, but after a ponderhit command it should execute the suggested move to ponder on. This means that the ponder move sent by the GUI can be interpreted as a recommendation about which move to ponder. However, if the engine decides to ponder on a different move, it should not display any mainlines as they are likely to be misinterpreted by the GUI because the GUI expects the engine to ponder on the suggested move.

btime <x>

wtime <x>

binc <x>

winc <x>

byoyomi <x>

movestogo <x>

depth <x>

nodes <x>

mate <x>

The command also seems largely redundant, as even engines that do have a special tsume search mode could activate this whenever they get to search on a position where one side lacks a King, and there already are plenty options on the go command to control thinking time. The solution could then be reported through the usual info pv commands, and failure through a bestmove resign command.

Search exactly x milliseconds.

Search until the stop command is received. Do not exit the search without being told so in this mode!

Stop calculating as soon as possible. Don't forget the bestmove and possibly the ponder token when finishing the search.

ponderhit

 

(Shogidogoro) Informs the engine that the game has ended with the specified result, from the engine's own point or view.

quit

 

id

This must be sent after receiving the usi command to identify the engine, e.g. id name Shredder X.Y\n

This must be sent after receiving the usi command to identify the engine, e.g. id author Stefan MK\n

Must be sent after the id and optional options to tell the GUI that the engine has sent all infos and is ready in usi mode.

readyok

 

bestmove [resign | win]

 

 

(Shogidogoro) Sent when a "go mate" search terminates, instead of a bestmove command, to convey the main line of the solution rather than just a single move. If it could be proven no solution exists, the word nomate will be sent instead of a main line, while timeout here would indicate the search was inconclusive. Finally, engines that do not implement the "go mate" function should reply to it with checkmate notimplemented.

copyprotection

 

 

 

TellGUI("copyprotection checking\n");

if(ok)

else

This is needed for engines that need a username and/or a code to function with all features. Analogously to the copyprotection command the engine can send registration checking after the usiok command followed by either registration ok or registration error. Also after every attempt to register the engine it should answer with registration checking and then either registration ok or registration error.

In contrast to the copyprotection command, the GUI can use the engine after the engine has reported an error, but should inform the user that the engine is not properly registered and might not use all its features.

In addition the GUI should offer to open a dialog to enable registration of the engine. To try to register an engine the GUI can send the register command. The GUI has to always answer with the register command if the engine sends registration error at engine startup (this can also be done with register later) and tell the user somehow that the engine is not registered. This way the engine knows that the GUI can deal with the registration procedure and the user will be informed that the engine is not properly registered.

info

 

 

 

info depth 2 score cp 214 time 1242 nodes 2124 nps 34928 pv 2g2f 8c8d 2f2e

I suggest to start sending currmove, currmovenumber, currline and refutation only after one second in order to avoid too much traffic.

Additional info:

depth <x>

seldepth <x>

time <x>

nodes <x>

pv <move1> ... <movei>

multipv <num>

score

The score from the engine's point of view, in centipawns.

Mate in y plies. If the engine is getting mated, use negative values for y.

The score is just a lower bound.

The score is just an upper bound.

Currently searching this move.

Currently searching move number x, for the first move x should be 1, not 0.

The hash is x permill full. The engine should send this info regularly.

x nodes per second searched. the engine should send this info regularly.

The cpu usage of the engine is x permill.

Any string str which will be displayed be the engine. if there is a string command the rest of the line will be interpreted as <str>.

Move <move1> is refuted by the line <move2> ... <movei>, where i can be any number >= 1. Example: after move 8h2b+ is searched, the engine can send info refutation 8h2b+ 1c2b if 1c2b is the best answer after 8h2b+ or if 1c2b refutes the move 8h2b+. If there is no refutation for 8h2b+ found, the engine should just send info refutation 8h2b+. The engine should only send this if the option USI_ShowRefutations is set to true.

This is the current line the engine is calculating. <cpunr> is the number of the cpu if the engine is running on more than one cpu. <cpunr> = 1,2,3.... If the engine is just using one cpu, <cpunr> can be omitted. If <cpunr> is greater than 1, always send all k lines in k strings together. The engine should only send this if the option USI_ShowCurrLine is set to true.

This command tells the GUI which parameters can be changed in the engine. This should be sent once at engine startup after the usi and the id commands if any parameter can be changed in the engine. The GUI should parse this and build a dialog for the user to change the settings. Note that not every option should appear in this dialog, as some options like USI_Ponder, USI_AnalyseMode, etc. are better handled elsewhere or are set automatically.

If the user wants to change some settings, the GUI will send a setoption command to the engine.

Note that the GUI need not send the setoption command when starting the engine for every option if it doesn't want to change the default value. For all allowed combinations see the examples below, as some combinations of this tokens don't make sense.

One string will be sent for each parameter.

name <id>

 

 

 

The value in MB for memory for hash tables can be changed, this should be answered with the first setoptions command at program boot if the engine has sent the appropriate option name Hash command, which should be supported by all engines! So the engine should use a very small hash first as default.

This means that the engine is able to ponder (i.e. think during the opponent's time). The GUI will send this whenever pondering is possible or not. Note: The engine should not start pondering on its own if this is enabled, this option is only needed because the engine might change its time management algorithm when pondering is allowed.

This means that the engine has its own opening book which is accessed by the engine itself. If this is set, the engine takes care of the opening book and the GUI will never execute a move out of its book for the engine. If this is set to false by the GUI, the engine should not access its own book.

The engine supports multi best line or k-best mode. The default value is 1.

The engine can show the current line it is calculating. See info currline above. This option should be false by default.

The engine can show a move and its refutation in a line. See info refutations above. This option should be false by default.

The engine is able to limit its strength to a specific dan/kyu number. This should always be implemented together with USI_Strength. This option should be false by default.

The engine can limit its strength within the given interval. Negative numbers are kyu levels, while positive numbers are amateur dan levels. If USI_LimitStrength is set to false, this value should be ignored. If USI_LimitStrength is set to true, the engine should play with this specific strength. This option should always be implemented together with USI_LimitStrength.

The engine wants to behave differently when analysing or playing a game. For example when playing it can use some kind of learning, or an asymetric evaluation function. The GUI should set this option to false if the engine is playing a game, and to true if the engine is analysing.

The option has type t. There are 5 different types of options the engine can send:

check

spin

combo

button

string

filename

default <x>

 

The minimum value of this parameter is x.

max <x>

 

 

"option name Nullmove type check default true\n"

"option name Style type combo default Normal var Solid var Normal var Risky\n"

"option name ResetLearning type button\n"

5.4. Examples

 

 

// tell the engine to switch to USI mode

 

 

id author Tord Romstad

// engine sends the options it can change

 

 

 

option name Style type combo default Normal var Solid var Normal var Risky

 

 

// wants to find out details about the engine, so the engine should

 

 

 

 

 

 

// waiting for the engine to finish initializing

// this command and the answer is required here!

isready

// engine has finished setting up the internal values

readyok

// now we are ready to go

// if the GUI is supporting it, tell the engine that is is

 

 

// search is supposed to be an analysis, the GUI should set

// engine.

setoption name USI_AnalyseMode value true

// tell the engine to search infinite from the start position after

 

go infinite

// the engine starts sending infos about the search to the GUI

// (only some examples are given)

info depth 1

info depth 1

info depth 2

info score cp 5 depth 2 nodes 255 time 90 pv 2g2f 4c4d

info nps 26437

...

// here the user has seen enough and asks to stop the searching

stop

// the engine has finished searching and is sending the bestmove command

// that the engine is ready again

bestmove 2g2f ponder 4c4d