Table of Contents
Abstract
This article documents the CXBoard protocol, version 1, designed for communication between Chinese Chess engines and interfaces or converters.
The XBoard (WinBoard for MS lackeys) has been very successful in the computer Chess community. Separating the interface from the engine has allowed developers to take differing directions in development goals yet still have interoperatable components. Users may interact with engines through a variety of interfaces in order to play against them, use them to analyze games, or pit them against each other. Interface authors can devote themselves to designing a pleasant and complete interface without having to worry about AI issues, and engine authors can write their engines knowing that they will be useful to users in the manner they wish to use them.
Recently a competitor to XBoard was designed called the Universal Chess Interface (UCI). This new protocol took a very different direction than XBoard yet still stayed relatively similar. In UCI the interface is in charge of everything and the engine's only job is to think about positions. The UCI protocol also adds some very useful commands sets, such as its option set, that XBoard is not yet capable of. One of the major strengths of UCI over XBoard is that UCI was designed as a communication protocol while XBoard is an ad-hoc protocol created origionally to communicate with a single engine (GNUChess).
Neither of these protocols is capable of communicating all of the needs for Chinese Chess as they where designed for Western Chess and it's variants only. A new protocol is necissary to adiquately replicate the XBoard/Engine system created by XBoard/GNUChess and then later by UCI. This document describes just such a protocol.
There are weaknesses and strengths in both XBoard and UCI, and since we are creating something totally new we have decided to use the best parts of each. In CXBoard you may run the engine in forced mode only like UCI, or you may choose to let the engine be in more control like XBoard. We have adopted the UCI option command set as well as synchronization and a few other things, added commands necissary for the engine to have control from XBoard, and added a small set of extra commands that seemed useful and/or necissary.
Feel free to use this protocol in your own engines or interface. I only ask that if you call your engine or interface cxboard compliant that you be sure that it is. Contact the authors though the sourceforge website at http://xiangqi-engine.sourceforge.net to request additions or alterations to the protocol before altering it yourself. If you need alterations that are not being included in the protocol you may create derivative works but you must call them by a different name.
Please keep in mind that this protocol is a copyrighted work. We are asking very little from users; only what is needed to be sure compatability is retained. It is a sad world indeed if these requirements cannot be met.
All interfaces and engines must meet the following requirements:
All command strings end in '\n'.
Processing will be done through standard input and output handles and components must always be able to process input.
The interface is in control of the opening book unless the "OwnBook" option is turned on.
The engine must never exit if it recieves a version higher than what it knows. Future versions of this protocol will be backwards compatable.
All moves are sent and processed in "long algebraic notation". The board is labeled from left to right with a-i and from bottom to top with 0-9 from red's perspective. Moves are sent with the origin followed by destination as one 4 character word.
Examples: h0g2, e0e1, h2e2
Positions are described in a modified version of Forsyth-Edwards Notation dubbed CFEN. This new format simply removes the fields "castling availability", "en-passant square", and "half-move clock". The position description segment contains one extra file and rank.
The following characters are used to represent pieces:
Pp - Pawn or Soldier
Cc - Canon
Rr - Rook or Cart
Hh - Horse or Knight
Ee - Elephant
Aa - Advisor or Guard
Kk - King or General
Example: rheakaehr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RHEAKAEHR r 1
This command is sent immediately upon starting the engine and opening a communication port. The version is the highest version number of the protocol that the GUI understands.
Enter forced mode.
In forced mode the engine will not make any moves without being told to, will check all moves for legality, will not ponder until told to, will stop and ignore its own internal clocks, will begin responding to the "go" command.
Only valid in force mode. Start calculating on the current position.
There are a number of commands that can follow this command, all will be sent on the same string. If a command is not sent its value should be assumed as to not influence the search.
Restrict the search to only these moves.
Begin searching in ponder mode. Switch to standard search mode upon recieving the next move command.
Red has X msec left on the clock.
Black has X msec left on the clock.
Moves must be limited to X msec in time.
The is X msec on the overtime clock.
There are X moves left until the next time control. If you don't get this then clocks are game clocks.
Limit the search to X ply not including quescence.
Limit the search to X nodes.
Search for a mate in X moves
Search for exactly X mseconds
Search until the "stop" command. Do not exit the search without being told to in this mode.
Leave force mode if in it, set the engine to play the color that is on move, associate the engine's clock with the color that is on move, associate the opponent's clock with the color not on move, start the engine's clock, start thinking and eventually make a move.
Leave force mode if in it, set the engine to play the color not on move, associate the engine's clock with the color not on move, associate the oppenent's clock with the clock on move, start the opponent's clock, if pondering is available begin pondering, when a move is recieved begin thinking and eventually make a move.
Check the supplied move for legality and make the move on the internal board if legal to do so. Stop the clock on move, begin the clock not on move, switch color to move. If new color to move in the engine's color, and not in force mode, begin thinking and eventually make a move. If new color is opponent's color and not in force mode then take move back and reply with error (you can check this before making the move).
Stop thinking and make a move immediately.
Only valid in force mode. Stop calculating as soon as possible, reply with a bestmove command.
This is used to synchronize the engine and GUI. When the GUI has sent a series of commands that may take some time to complete this command can be used to wait for the engine to be ready again or to ping the engine to see if it is still living. This command must always be answered with "readyok".
This command is sent to the engine when the user wishes to change its internal parameters. 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 of the option in <id> must not be case sensitive.
Set up the position described and make the moves on the internal chess board. If the game was played from the starting position the string "startpos" will be sent.
Switch the debug mode on/off in the engine. In debug mode the engine should send additional infos to the GUI. This mode should be switched off by default and this command can be sent at any time.
The engine's opponent offers the engine a draw. To accept the draw, send "offer draw". To decline, ignore the offer (that is, send nothing). Continue playing until the interface tells you the game is over. See also "offer draw" below.
After the end of each game, the interface must send the engine this command. RESULT is either 1-0, 0-1, 1/2-1/2, or * to indicate if the game was won by red, by black, a draw, or not finished.
request a hint from the engine, the engine should respond with "info hint xxxx" where xxxx is the recommended move, or it should ignore the command if there is no hint to make or if the command is not implemented.
back up one move. The interface must always put the engine in force mode before sending this command. It is recommended that this command be denied if not in force mode.
retract the last move made by the color on move. In other words undo the last 2 moves, one for each player. This command can be used in any mode.
Tell engine it's opponent's name.
Tells the engine that it is playing another engine and not a human. Engines will often drop expensive strategic evaluation in favor of speed and depth when playing another engine.
in pause mode the engine must not think, ponder, or otherwise consume significant CPU time. The current thinking or pondering is is suspended and both player's clocks are stopped. The only command that can be sent in this state is the resume command; the engine resumes in the same state it was in when it entered pause mode.
The engine should reply with an info command representing it's score of the current position.
Set the clocks of both players. GAMECLOCK is the total time available for the game for each side, MOVECLOCK is the maximum amount of time that can be used for a single move, and OVERTIME is the amount of time available to make each move after the GAMECLOCK has run out. Times are in minutes or minutes and seconds.
Examples: "clock 60 1 :30" - 5 minutes to play, 1 minute to move, 30 second overtime
This must be sent after recieving the "cxboard" command to identify the engine. Example: "id name tsito 2.0.0"
This must be sent after recieving the "cxboard". Example: "id author Noah Roberts"
Must be sent after the it and optional option to tell the GUI that the engine has sent all info and is ready in cxboard mode.
This must be sent in reply to isready when it has finished processing all input and is ready to accept new commands.
Used in force mode when finished with a go command. The engine has not made the move and will not enter ponder mode until requested.
Used to tell the interface that copyprotection is being checked. After the cxboardok command the engine can say "copyprotection checking". When it has finished checking the engin must send "copyprotection ok" or "copyprotection error". If there is an error the engine should respond to every command but quit with an Error reply and not quit until requested.
Send info to interface. This command should be sent any time something changes or in responce to a request for information (ie. hint).
search depth in plies.
selective search depth in plies; must be accompanied by a depth in same string.
time speant searching in miliseconds. should be sent with pv.
the best line found
for multi pv mode. send with pv to represent the order of pvs. best line is multipv 1.
score from the engine's perspective in centipawns
mate in x moves
score is a lowerbound
score is an upperbound
currently searching move.
currently searching move number x. The first move is 1 not 0.
The hash is x permill full, the engine should send this regularly.
x nodes per second searched, the engine should send this regularly.
x positions where found in the endgame tablebases.
the cpu usage of the engine is x permill.
any string to be displayed. all following characters on the line will be considered part of the string.
the engine recommends move as the next best. Sent in responce to hint command.
This command tells the GUI about parameters that can be set by the user. These should be sent after the id command sequence and before cxboardok. The GUI should use this information to build a settings dialog. The GUI will use the setoption command to alter these options on the user's behalf. One string will be sent for each parameter.
The option has the name id. This can be sent in any language. Certain options have fixed value for id, which means that the semantics for the option are fixed:
Amount of memory in MB used for trasposition table.
the engine is able to ponder.
The engine is in charge of its own opening book.
the engine supports multiple best line mode. default is 1
The engine supports the listed variants. Default is XiangQi.
A checkbox that can be either true or false.
a spin wheel that can be an integer in a certain range
a combo box that can have different predefined strings as a value
a button that can be pressed to send the engine a command.
a text field that has a string as a value. an empty string has the value "<empty>"
The default value of this parameter
the minimum of this parameter
the maximum of this parameter
a predefined value of this parameter
Examples:
option name OwnBook type check default true
option name Hash type spin default 32 min 0 max 1024
option name Search type combo default AlphaBeta var MTD var AlphaBeta var NegaScout
option name OpeningBookPath type string default /usr/share/tsito/book.dat
option name Clear Hash type button
The attempted move is illegal given the current position. The engine may optionally specify a reason. Examples: "Illegal move: e2e3", ""Illegal move (in check): e2f2"
The given command has generated the errortype error.
The engine is making the move m.
The engine has detected an end to the game and is claiming a win, loss, or draw. As far as the engine is concerned the game has finished and will process no more moves until a new position is provided.
The engine is resigning. As far as the engine is concerned the game is finished and will process no more moves until a new position is provided. The engine may use the result command instead of this one.
The engine wants to claim a draw. The offer is considered valid until two moves are made. The game is still on until the engine recieves a result command.
Relay MESSAGE to user.
Ask user a question. Interface responds with RESPTAG ANSWER.
Relay MESSAGE to teh opponent only
Relay MESSAGE to everyone but the opponent.
Relay MESSAGE to everyone.
// GUI start engine cxboard 1 // Engine identifies itself id name tsito 2.0 id author Noah Roberts // Engine tells GUI about some options option name Null Move type check default true option name Hash type spin default 32 min 0 max 256 option name Search type combo default MTD var MTD var NegaScout var AlphaBeta // Engine is done cxboardok // Gui sets some options setoption name Null Move value false setoption name Hash value 128 setoption name Search value NegaScout // Wait for engine to do the above isready // engine finishes readyok // itialize board... position startpos // User moves.. move h2e2 // Engine thinks... info depth 1 info score cp 45 depth 1 nodes 24 time 9 pv b7b0 info depth 2 info score cp 0 depth 2 nodes 130 time 23 pv h9g7 h0g2 // and so on... // engine replies move h9g7 // User quits quit
// GUI start engine cxboard 1 // Engine identifies itself id name tsito 2.0 id author Noah Roberts // Engine tells GUI about some options option name Null Move type check default true option name Hash type spin default 32 min 0 max 256 option name Search type combo default MTD var MTD var NegaScout var AlphaBeta // Engine is done cxboardok // Gui sets some options setoption name Null Move value false setoption name Hash value 128 setoption name Search value NegaScout // Wait for engine to do the above isready // engine finishes readyok // itialize board... position startpos // enter force mode... force // User moves.. move h2e2 go infinite // Engine thinks... info depth 1 info score cp 45 depth 1 nodes 24 time 9 pv b7b0 info depth 2 info score cp 0 depth 2 nodes 130 time 23 pv h9g7 h0g2 // and so on... // user requests an end... stop // engine replies bestmove h9g7 // Gui decides on something else move h7h0 // User quits quit