<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
-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>.<br>\r
-Proposed changes, implemented only in alpha versions are indicated in <font color=blue>blue</font>.\r
+Changes for WinBoard 4.4.xx are indicated in <font color=blue>blue</font>.\r
<hr noshade size="2">\r
\r
<ul>\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
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
</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.\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
-There are six different options types, each requiring a slighly different syntax of the defining string:\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 -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 oter words in capitals would be replaced by the current (default) setting of the option,\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 cae, the current value will be preceded by an asterisk.\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
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
projects / xboard.git / blobdiff