.version1 { color: red;}\r
.version43 { color: green;}\r
.version44 { color: blue; }\r
+ .version47 { color: purple; }\r
\r
table tr { text-align: left}\r
tr > td:first-child { font-weight:bold;}\r
<tr><td>unknown</td><td>Unknown variant (not supported)</td></tr>\r
</table>\r
\r
+As of XBoard 4.8, engines can define arbitrary variant names; see the "feature" and "setup" commands in <a href="#9">section 9</a>.\r
</dd>\r
\r
<dt>quit</dt>\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
+xboard will use a FEN format that is standard or suitable for that variant.\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
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
</dd>\r
+\r
+<dt class="version47">exclude MOVE</dt>\r
+<dt class="version47">include MOVE</dt>\r
+<dt class="version47">exclude all</dt>\r
+<dt class="version47">include all</dt>\r
+<dd class="version47">\r
+These commands change the set of moves that the engine should consider in the root node of its search,\r
+by removing or adding the mentioned MOVE from this set.\r
+After reaching a new position, (e.g. through a usermove, undo, new or setboard command),\r
+or after receiving "include all",\r
+this set should always be reset to all legal moves from that position.\r
+If the set of moves changes during a search, \r
+the engine could start a new search from scratch, or it can try to be smart, \r
+and continue the current search with the new set of moves\r
+(e.g. after exclusion of a move that has not been searched yet in the current iteration).\r
+After "exclude all", the engine would have no legal moves in the root,\r
+which logically should make it behave as if it is (stale)mated,\r
+but it is allowed to defer any effects of this command on a search in progress\r
+to when the set gets non-empty again through addition of a move.\r
+These commands will only be sent to engines that have requested such through the exclude feature.\r
+</dd>\r
+\r
+<dt class="version47">setscore SCORE DEPTH</dt>\r
+<dd class="version47">\r
+This command instructs the engine to treat future search requests on the current position\r
+(also when it is encountered inside a larger search tree)\r
+upto the given DEPTH as if these result is SCORE centi-Pawn in favor of the side that has the move in this position.\r
+It is entirely up to the engine to decide when the effect of this option should expire.\r
+(E.g. it could last upto the next "new" or "quit" command,\r
+or even into future sessions until the user explicitly clears it through an engine-defined option.)\r
+This command will only be sent to engines that have requested it through the setscore feature.\r
+</dd>\r
</dl>\r
\r
<h3>Bughouse commands:</h3>\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.</span>\r
+<span class="version47">As of XBoard 4.8 a variant name not known to the GUI will be\r
+considered an engine-defined variant.\r
+The user will be given the opportunity to select such variants,\r
+but when this happens, the engine should define its meaning\r
+in detail with the aid of a "setup" command defined below,\r
+in order to avoid an error.</span>\r
<br />\r
<span class="version43">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
+it can list them amongst the variants with a prefix specifying board size plus\r
holdings size, like 8x8+0_capablanca or 10x8+7_capablanca.\r
If it is capable of playing any variant with an arbitrary board size,\r
it should list "boardsize" as one of the variants.\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
</span>\r
+\r
+<dt class="version47">exclude (boolean, default 0)</dt>\r
+<dd class="version47">\r
+If exclude=1 the GUI can send "exclude" and "include" commands to control which moves\r
+from the root position should be searched.\r
+</dd>\r
+</dd>\r
+\r
+<dt class="version47">setscore (boolean, default 0)</dt>\r
+<dd class="version47">\r
+If setscore=1 the GUI can send "setscore" commands to define the score of the current position.\r
+</dd>\r
</dd>\r
\r
<dt class="version1">done (integer, no default)</dt>\r
</dl>\r
</dd>\r
\r
+<dt>setup FEN</dt>\r
+<dt>setup (PIECETOCHAR) FEN</dt>\r
+<dt>setup (PIECETOCHAR) WxH+S_PARENTVARIANT FEN</dt>\r
+<dd>The engine can optionally send a setup command to the GUI in reply\r
+to the variant command.\r
+In the simplest form this sends the FEN of the initial position.\r
+This can be used to implement engines for non-standard variants\r
+that only differ from standard variants through the initial position.\r
+(E.g. many of the 'wild' boards you can play on an ICS.)\r
+Whether the GUI should obey or ignore this command depends on the situation.\r
+Normally it would ignore it in variants where it knows the standard initial position\r
+and legality testing is on, or when the user specified an initial position.\r
+In other cases it will use the FEN sent by the first engine\r
+for setting up the initial position, as if it was an externally supplied position.\r
+Such a position will always be sent to a second engine that might be involved,\r
+and any setup commands received from the latter will always be ignored.\r
+(This to allow for shuffle games, where the two engines might pick different setups.)\r
+When no initial position is known, such as for 'catch-all' variants like fairy,\r
+or whenever the board width is overruled to a non-standard value,\r
+the FEN will be used as default initial position even when legality testing is on.\r
+</dd>\r
+<dd>Optionally the meaning of the piece ID letters in the FEN can be defined\r
+between parentheses; this will be interpreted as if it was the value of a\r
+-pieceToCharTable command-line option, mapping letters to GUI piece types.\r
+Also optionally behind that, the setup command can specify board width W,\r
+board height H and holdings size S, as well as a 'parent variant'.\r
+This is typically done in response to a variant command with a non-standard name,\r
+about which the GUI is not supposed to know anything at all.\r
+The engine can then specify board size, participating pieces, initial setup,\r
+and other rule details (inherited from the parent variant),\r
+saving the user the trouble to configure the GUI for this non-standard variant.\r
+Example:\r
+<pre>\r
+ setup (PN.RQKpn.rqk) 6x6+0_fairy rnqknr/pppppp/6/6/PPPPPP/RNQKNR w - - 0 1\r
+</pre>\r
+could be used by an engine for Los-Alamos Chess in response to 'variant losalamos',\r
+and would automatically switch the GUI to this variant as soon as the user\r
+selected it from the GUI menu.\r
+The PIECETOCHAR element would ensure a Bishop would not be accepted as promotion choice. \r
+</dd>\r
\r
<dt>Illegal move: MOVE</dt>\r
<dt>Illegal move (REASON): MOVE</dt>\r
<tr><td>score</td><td>Integer giving current evaluation in centipawns.</td></tr>\r
<tr><td>time</td><td>Current search time in centiseconds (ex:1028 = 10.28 seconds).</td></tr>\r
<tr><td>nodes</td><td>Nodes searched.</td></tr>\r
+<tr><td>*selective depth</td><td>Maximium length of any branch in the current search.</td></tr>\r
+<tr><td>*speed</td><td>Nodes per second in last measured time interval.</td></tr>\r
+<tr><td>*</td><td>Reserved for future extensions.</td></tr>\r
+<tr><td>*tbhits</td><td>Number of tablebase probes made in the current search.</td></tr>\r
<tr><td>pv</td><td>Freeform text giving current "best" line.\r
You can continue the pv onto another line if you start each\r
continuation line with at least four space characters.</td></tr>\r
</table>\r
\r
+<p class="version47">\r
+The items marked with * are optional.\r
+If any of these items is present, the <b>pv</b> field must be preceeded directly by a tab character;\r
+if no tab character preceeds the first non-integer token,\r
+the <b>pv</b> field will start at the first non-blank character after <b>nodes</b>.\r
+Otherwise it will start after the last tab that is not behind any non-integer token.\r
+Of all integers between <b>nodes</b> and <b>pv</b> the last one is intepreted as <b>tbhits</b>.\r
+Of any remaining ones the first is interpreted as <b>selective depth</b>,\r
+and a second as <b>speed</b>.\r
+More infos could be added to this in the future.\r
+Note that older interfaces might consider the optional infos to be part of the <b>pv</b> field,\r
+and display them exactly as sent.\r
+It is therefore encouraged that engines use tabs or spaces to format this optional info\r
+so that it will display nicely in (not too wide) columns.\r
+</p>\r
+\r
+<p class="version47">\r
+A question mark as the last character in the <b>pv</b> field should be used to indicate\r
+the reported score is from a fail low, and thus represents an upper bound only.\r
+Similarly, an exclamation point should be used to indicate a fail high / lower bound.\r
+</p>\r
+\r
+<p class="version47">\r
+Mate scores should be indicated as 100000 + N for "mate in N moves",\r
+and -100000 - N for "mated in N moves".\r
+</p>\r
+\r
<p>\r
Example:\r
</p>\r
projects / xboard.git / blobdiff