<body>\r
<hr noshade size="2">\r
<h1>Chess Engine Communication Protocol</h1>\r
-<h1><font color=green>Discussion Proposal</font></h1>\r
<h2><a href="http://www.tim-mann.org/">Tim Mann</a> & <a href="http://home.hccnet.nl/h.g.muller/winboardF.html">H.G.Muller</a></h2>\r
<p>\r
-$Id: engine-intf.html,v 2.1 2003/10/27 19:21:00 mann Exp $<br>\r
-Version 2; implemented in xboard/WinBoard 4.2.1 and later.<br>\r
+Version 2; implemented in xboard/WinBoard 4.2.1 and later. (Sept 3, 2009)<br>\r
Changes since version 1 are indicated in <font color=red>red</font>.<br>\r
-Changes for WinBoard 4.3.xx are indicated in <font color=green>green</font>.\r
+Changes for WinBoard 4.3.xx are indicated in <font color=green>green</font>.<br>\r
+Changes for WinBoard 4.4.xx are indicated in <font color=blue>blue</font>.\r
<hr noshade size="2">\r
\r
<ul>\r
\r
<p>\r
I'd like to hear from everyone who is trying to interface their own\r
-chess engine to xboard/WinBoard. Please email me,\r
-tim<a name="nospam">@</a>tim-mann.org. Also, please join\r
-the mailing list for authors of xboard/WinBoard compatible chess\r
-engines. The list is now hosted by Yahoo Groups; you can join at <a\r
-href="http://www.egroups.com/group/chess-engines"\r
->http://www.egroups.com/group/chess-engines</a>, or you can read the\r
+chess engine to xboard/WinBoard. Please join the mailing list for \r
+authors of xboard/WinBoard compatible chess engines and post a message \r
+about what you're doing. The list is now hosted by Yahoo Groups; you \r
+can join at <a href="http://groups.yahoo.com/group/chess-engines" \r
+>http://groups.yahoo.com/group/chess-engines</a>, or you can read the\r
list there without joining. The list is filtered to prevent spam.\r
</p>\r
<p>\r
<font color=green>\r
-Note that the WinBoard 4.3.xx line is developed independently of the\r
+Note that the WinBoard 4.3.xx line was developed independently of the\r
original GNU project, by H.G.Muller.\r
If you have questions about WinBoard 4.3.xx, or want to report bugs in it,\r
report them in the appropriate section of the \r
<td><font color=green>shuffle variant like FRC (10x8 board)</font>\r
<tr align="left"><th><font color=green>cylinder</font>\r
<td><font color=green>Pieces wrap around between side edges, like board is a cylinder</font>\r
+<tr align="left"><th><font color=blue>super</font>\r
+<td><font color=blue>Superchess: a shuffle variant with 4 fairy pieces on 8x8 board</font>\r
+<tr align="left"><th><font color=blue>great</font>\r
+<td><font color=blue>Great Shatranj: sliders are replaced by corresponding short-range pieces on a 10x8 board</font>\r
<tr align="left"><th>unknown<td>Unknown variant (not supported)\r
</table>\r
<p>\r
<dt><strong>sd DEPTH</strong>\r
<dd>The engine should limit its thinking to DEPTH ply.\r
<font color=green>The commands "level" or "st" and "sd" can be used together in an orthogonal way.\r
-If both are issued, the engine should observe both limitations.</font>\r
+If both are issued, the engine should observe both limitations:</font>\r
+In the protocol, the "sd" command isn't a time control. It doesn't\r
+say that your engine has unlimited time but must search to exactly the\r
+given depth. It says that you should pay attention to the time\r
+control as normal, but cut off the search at the specified depth even\r
+if you have time to search deeper. If you don't have time to search\r
+to the specified depth, given your normal time management algorithm,\r
+then you will want to stop sooner than the given depth.\r
+<p>\r
+The "new" command should set the search depth back to unlimited. This\r
+is already stated in the spec. The "level" command should not affect\r
+the search depth. As it happens, xboard/WinBoard currently always\r
+sends sd (if needed) right after level, but that isn't part of the\r
+spec.\r
<p>\r
\r
<dt><font color=green><strong>nps NODE_RATE</strong></font>\r
that many engines implement it wrong.\r
The clocks in fact always remain with the color.\r
Which clock reading is relayed with "time", and which by "otim", is determined by which side the engine plays.\r
-Not that the way the clocks operate and receive extra time (in accordance with the selected time control)\r
+Note that the way the clocks operate and receive extra time (in accordance with the selected time control)\r
is not affected in any way by which moves are made by the engine, which by the opponent, and which were forced.\r
</font>\r
</p>\r
in protocol version 2. It is not used unless it has been selected\r
with the feature command. Here FEN is a position in Forsythe-Edwards\r
Notation, as defined in the PGN standard.</font>\r
-<font color=green>In FRC or CRC, WinBoard will use Shredder-FEN or X-FEN standard,\r
-i.e. it can use the rook-file indicator letter to represent a castling right (like HAha)\r
-whenever it wants, but if it uses KQkq, this will always refer to the outermost rook on the given side</font>\r
+<font color=green>Note that this PGN standard referred to here\r
+only applies to normal Chess;\r
+Obviously in variants that cannot be described by a FEN for normal Chess,\r
+e.g. because the board is not 8x8, other pieces then PNBRQK participate, \r
+there are holdings that need to be specified, etc., \r
+xboard will use a FEN format that is standard or suitable for that varant.\r
+In particular, in FRC or CRC, WinBoard will use Shredder-FEN or X-FEN standard,\r
+i.e. it can use the rook-file indicator letter to represent a castling right \r
+(like HAha) whenever it wants, but if it uses KQkq, this will always refer \r
+to the outermost rook on the given side.</font>\r
<font color=red>\r
\r
<p><i>Illegal positions:</i> Note that either setboard or edit can\r
left off, and the clock of the player on move resumes running from\r
where it stopped.\r
</font>\r
+<p>\r
+\r
+<dt><font color=blue><strong>memory N</strong></font>\r
+<dd><font color=blue>\r
+This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes.\r
+On receipt of this command, the engine should adapt the size of its hash tables accordingly.\r
+This command does only fix the total memory use,\r
+the engine has to decide for itself \r
+(or be configured by the user by other means) \r
+how to divide up the available memory between the various tables it wants to use \r
+(e.g. main hash, pawn hash, tablebase cache, bitbases).\r
+This command will only be sent to engines that have requested it through the memory feature,\r
+and only at the start of a game,\r
+as the first of the commands to relay engine option settings just before each "new" command.\r
+</font>\r
+<p>\r
+\r
+<dt><font color=blue><strong>cores N</strong></font>\r
+<dd><font color=blue>\r
+This command informs the engine on how many CPU cores it is allowed to use maximally.\r
+This could be interpreted as the number of search threads for SMP engines. \r
+(Threads that do not consume significant amounts of CPU time, like I/O threads, need not be included in the count.)\r
+This command will only be sent to engines that have requested it through the smp feature.\r
+The engine should be able to respond to the "cores" command any time during a game,\r
+but it is allowed to finish a search in progress before procesing the command.\r
+(Obeying the command should take priority over finishing a ponder search, though.)\r
+In any case it will be sent at the start of every game\r
+as the last command to relay engine option settings before the "new" command.\r
+</font>\r
+<p>\r
+\r
+<dt><font color=blue><strong>egtpath TYPE PATH</strong></font>\r
+<dd><font color=blue>\r
+This command informs the engine in which directory (given by the PATH argument)\r
+it can find end-game tables of the specified TYPE.\r
+The TYPE argument can be any character string which does not contain spaces.\r
+Currently <strong>nalimov</strong> and <strong>scorpio</strong> are defined types, \r
+for Nalimov tablebases and Scorpio bitbases, respectively,\r
+but future developers of other formats are free to define their own format names.\r
+The GUI simply matches the TYPE names the engine says it supports \r
+with those that the user supplied when configuring xboard.\r
+For every match, it sends a separate "y" command.\r
+The PATH argument would normally (for Nalimov) be the pathname of the directory the EGT files are in,\r
+but could also be the name of a file, or in fact anything the particular EGT type requires.\r
+It is upto the developer of the EGT format to specify the syntax of this parameter.\r
+This command will only be sent to engines that have told the GUI they support EGTs of the given TYPE\r
+through the egt feature.\r
+It will be sent at the start of each game, before the "new" command.\r
+</font>\r
+<p>\r
+\r
+<dt><font color=blue><strong>option NAME[=VALUE]</strong></font>\r
+<dd><font color=blue>\r
+This command changes the setting of the option NAME defined by the engine \r
+(through an earlier feature command)\r
+to the given VALUE.\r
+XBoard will in general have no idea what the option means,\r
+and will send the command only when a user changes the value of this option through a menu,\r
+or at startup of the engine \r
+(before the first 'cores' command or, if that is not sent, the first 'new' command)\r
+in reaction to command-line options.\r
+The NAME echoes back to the engine the string that was identified as an option NAME\r
+in the feature command defining the option.\r
+The VALUE is of the type (numeric or text or absent) that was implied by the option type\r
+specified in this feature command,\r
+i.e. with 'spin' and 'check' options VALUE will be a decimal integer (in the latter case 0 or 1),\r
+with 'combo' and 'string' options VALUE will be a text string,\r
+and with 'button' and 'save' options no VALUE will be sent at all.\r
+</font>\r
</dl>\r
\r
<h3>Bughouse commands:</h3>\r
version; however, you should realize that engine authors are likely to\r
code for xboard and may not be prepared to have a feature that they\r
depend on be rejected.\r
+<font color=blue>If the GUI rejects an option feature because of the\r
+syntax of the value, it should print the value string with the\r
+"rejected" command, e.g. "rejected option nonsense" in response\r
+to receiving feature option="nonsense".</font>\r
</p>\r
\r
<p>\r
correct value for your engine (just "normal" in most cases) rather\r
than leaving the default in place, so that the user will get an\r
appropriate error message if he tries to play a variant that your\r
-engine does not support.\r
+engine does not support.</font>\r
<br>\r
-If your engine can play variants on a deviating board size,\r
+<font color=green>If your engine can play variants on a deviating board size,\r
like capablanca on an 8x8 board, or capablanca crazyhouse,\r
it can list them amongst the variants with a prefix spcifying board size plus\r
holdings size, like 8x8+0_capablanca or 10x8+7_capablanca.\r
or do so at their own risk.\r
</font>\r
\r
+<dt><font color=blue>\r
+<strong>memory</strong> (boolean, default 0)\r
+</font>\r
+<dd><font color=blue>\r
+If memory=1, the size of the total amount of memory available for the memory-consuming tables of the engine \r
+(e.g. hash, EGTB cache)\r
+will be set by the GUI through the "memory" command.\r
+</font>\r
+\r
+<dt><font color=blue>\r
+<strong>smp</strong> (boolean, default 0)\r
+</font>\r
+<dd><font color=blue>\r
+If smp=1, the GUI will send the "cores" command to the engine to inform it how many CPU cores it can use.\r
+Note that sending smp=1 does not imply the engine can use more than one CPU;\r
+just that it wants to receive the "cores" command.\r
+</font>\r
+\r
+<dt><font color=blue>\r
+<strong>egt</strong> (string, see text below)\r
+</font>\r
+<dd><font color=blue>\r
+This feature indicates which end-game table formats the engine supports.\r
+It should be a comma-separated list of format names.\r
+See under the "egtpath" command in <a href="#8">section 8</a> above.\r
+If you do not set this feature, xboard will assume the engine does not support end-game tables,\r
+and will not send any "egtpath" commands to inform the engine about their whereabouts.\r
+</font>\r
+\r
+<dt><font color=blue>\r
+<strong>option</strong> (string, see text below)\r
+</font>\r
+<dd><font color=blue>\r
+This feature is used by the engine to define an option command to appear in a GUI menu,\r
+so that the user can change the corresponding setting of the engine through the GUI interactively.\r
+The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range.\r
+Unlike other features, option features are accumulated by the GUI, \r
+and the GUI must be able to add a new option to the list at any time,\r
+even after having received feature done=1.\r
+There are ten different options types, each requiring a slighly different syntax of the defining string:\r
+<br>\r
+feature option="NAME -button"\r
+<br>\r
+feature option="NAME -save"\r
+<br>\r
+feature option="NAME -reset"\r
+<br>\r
+feature option="NAME -check VALUE"\r
+<br>\r
+feature option="NAME -string VALUE"\r
+<br>\r
+feature option="NAME -spin VALUE MIN MAX"\r
+<br>\r
+feature option="NAME -combo CHOICE1 /// CHOICE2 ..."\r
+<br>\r
+feature option="NAME -slider VALUE MIN MAX"\r
+<br>\r
+feature option="NAME -file VALUE"\r
+<br>\r
+feature option="NAME -path VALUE"\r
+<br>\r
+NAME is an arbitrary alphanumeric string which can contain spaces; \r
+the other words in capitals would be replaced by the current (default) setting of the option,\r
+(a character string for -string options, a decimal number for -spin and -check options,\r
+were the latter uses 1=checked, 0=unchecked),\r
+the minimum or maximum value of numeric (-spin) options, \r
+or arbitrary text labels (for -combo option).\r
+In the latter case, the current value will be preceded by an asterisk.\r
+The -file and -path options are similar to -string, but can be used to inform the GUI that\r
+the text represents a file name or folder name respectively, \r
+so the GUI dialog could add the appropriate browse button to the text-edit field.\r
+Similarly, a -slider option is like a -spin, but the GUI might make a different\r
+graphical representation for it.\r
+A -save option is like a -button, and defines an immediate command to be sent by the engine.\r
+With -save the GUI will make sure all current option settings are flushed to the engine\r
+before it sends this command.\r
+A -reset option is like a -button, but use of it purges the list of options before sending \r
+the corresponding option command to the engine.\r
+This enables the engine to completely redefine its options or their current settings,\r
+by sending a new set of option feature commands to the GUI, \r
+terminated by feature done=1.\r
+(The effect of sending an option feature for an option with the same name as was defined before, \r
+without first receiving a -reset option command, is undefined.)\r
+</font>\r
+\r
<dt><font color=red>\r
<strong>done</strong> (integer, no default)\r
</font>\r
will be taken by WinBoard as an unconditional refusal of the engine to play on,\r
which might cause you to forfeit if the game was in fact not over.\r
This command should thus not be used to offer draws, accept draws,\r
-or make draw-by-rule claims that might not be valid \r
-(because it is not your move, and the opponent already moved without you knowing it yet).\r
-For offering and claiming draws, "offer draw" should be used.</font>\r
+or make draw-by-rule claims that are not yet valid in the current position\r
+(but will be after you move).\r
+For offering and claiming such draws, "offer draw" should be used.</font>\r
+<p>\r
+<font color=blue>\r
+Note that (in accordance with FIDE rules) only KK, KNK, KBK and KBKB with all bishops on the\r
+same color can be claimed as draws on the basis of insufficient mating material.\r
+The end-games KNNK, KBKN, KNKN and KBKB with unlike bishops do have mate positions,\r
+and cannot be claimed.\r
+Complex draws based on locked Pawn chains will not be recognized as draws by most interfaces,\r
+so do not claim in such positions, but just offer a draw or play on.\r
+</font>\r
+<p>\r
+<font color=blue>\r
+Note to GUI programmers: RESULT commands that the engine sends immediately after its move\r
+might be detected by the GUI only after the opponent has moved, because of communication\r
+and scheduling delays, no matter how fast the engine sent it.\r
+Any judgement of the validity of RESULT claims based on te "current" board position\r
+will have to account for this uncertainty.\r
+</font>\r
</p>\r
\r
<dt><strong>resign</strong>\r
"resign" is included in the comment; for example "0-1 {White\r
resigns}". xboard relays the resignation to the user, the ICS, the\r
other engine in Two Machines mode, and the PGN save file as required.\r
+<font color=blue>Note that many interfaces work more smoothly if you resign <em>before</em>\r
+you move.</font>\r
<p>\r
\r
<dt><strong>offer draw</strong>\r
until your engine has made two more moves.\r
<font color=green>This command must also be used to accept a draw offer.\r
Do not use the 1/2-1/2 command for that, as the offer might be no longer valid,\r
-in which case a refusal to play on implied by the RESULT command would make you forfeit the game.\r
+in which case a refusal to play on implied by the RESULT command might make you forfeit the game.\r
"offer draw" should also be used to claim 50-move and 3-fold-repetition draws\r
that will occur <em>after</em> your move, by sending it <em>before</em> making the move.\r
WinBoard will grant draw offers without the opponent having any say in\r
increment.)\r
</p>\r
\r
-<p>\r
+<p><font color=blue>\r
The number of moves given in the level command (when non-zero) should \r
be taken as the number of moves still to do before the specified time\r
will be added to the clock, if the "level" command is received after\r
it should understand that it should do the next 20 moves in 22 minutes\r
(pehaps because the secondary session was 20 moves per 15 minutes,\r
and it had 7 minutes left on its clock after the first 40 moves).\r
-</p>\r
+</font></p>\r
\r
<p>\r
A special rule on some ICS implementations: if you ask for a game with\r
projects / xboard.git / blobdiff