Merge commit 'v4.3.16'
[xboard.git] / engine-intf.html
index 13e1719..bad8e89 100644 (file)
@@ -71,17 +71,16 @@ statements, let me know.
 \r
 <p>\r
 I'd like to hear from everyone who is trying to interface their own\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
 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
 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
@@ -618,7 +617,20 @@ below.
 <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
 <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
 <p>\r
 \r
 <dt><font color=green><strong>nps NODE_RATE</strong></font>\r
@@ -821,9 +833,16 @@ The setboard command is the new way to set up positions, beginning
 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
 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
 <font color=red>\r
 \r
 <p><i>Illegal positions:</i> Note that either setboard or edit can\r
@@ -1056,6 +1075,26 @@ This command will only be sent to engines that have told the GUI they support EG
 through the egt feature.\r
 It will be sent at the start of each game, before the "new" command.\r
 </font>\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
 </dl>\r
 \r
 <h3>Bughouse commands:</h3>\r
@@ -1409,6 +1448,34 @@ If you do not set this feature, xboard will assume the engine does not support e
 and will not send any "egtpath" commands to inform the engine about their whereabouts.\r
 </font>\r
 \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.\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
+<br>\r
+feature option="NAME -button"\r
+<br>\r
+feature option="NAME -save"\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
+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 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
+</font>\r
+\r
 <dt><font color=red>\r
 <strong>done</strong> (integer, no default)\r
 </font>\r
 <dt><font color=red>\r
 <strong>done</strong> (integer, no default)\r
 </font>\r