.version1 { color: red;}\r
.version43 { color: green;}\r
.version44 { color: blue; }\r
+ .version47 { color: purple; }\r
+ .version48 { color: brown; }\r
\r
table tr { text-align: left}\r
tr > td:first-child { font-weight:bold;}\r
<tr class="version43"><td>cylinder </td><td>Pieces wrap around between side edges, like board is a cylinder</td></tr>\r
<tr class="version44"><td>super </td><td>Superchess: a shuffle variant with 4 fairy pieces on 8x8 board</td></tr>\r
<tr class="version44"><td>great </td><td>Great Shatranj: sliders are replaced by corresponding short-range pieces on a 10x8 board</td></tr>\r
+<tr class="version48"><td>lion </td><td>Mighty-Lion Chess, with a super-knight, more powerful than a Queen</td></tr>\r
+<tr class="version48"><td>elven </td><td>Elven Chess: hybrid between Chess and Chu Shogi on 10x10 board</td></tr>\r
+<tr class="version48"><td>chu </td><td>Chu Shogi: Edo-period Japanese Chess on a 12x12 board</td></tr>\r
<tr><td>unknown</td><td>Unknown variant (not supported)</td></tr>\r
</table>\r
\r
+<span class="version48">As of XBoard 4.8, engines can define arbitrary variant names; see the "feature" and "setup" commands in <a href="#9">section 9</a>.</span>\r
</dd>\r
\r
<dt>quit</dt>\r
<tr><td>Bughouse/crazyhouse drop:</td><td>P@h3</td></tr>\r
<tr><td>ICS Wild 0/1 castling:</td><td>d1f1, d1b1, d8f8, d8b8</td></tr>\r
<tr><td>FischerRandom castling:</td><td>O-O, O-O-O (oh, not zero)</td></tr>\r
+<tr class="version48"><td>Multi-leg move:</td><td>c4d5,d5e4 (legs separated by comma)</td></tr>\r
+<tr class="version48"><td>Null move:</td><td>@@@@</td></tr>\r
</table>\r
\r
<p class="version43">\r
-Note that on boards with more than 9 ranks, counting of the ranks starts at 0.\r
+Note that on boards with <span class="version48">exactly 10</span> ranks, counting of the ranks starts at 0.\r
</p>\r
<p class="version1">\r
Beginning in protocol version 2, you can use the feature command\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
+\r
+<dt class="version48">lift SQUARE</dt>\r
+<dt class="version48">put SQUARE</dt>\r
+<dt class="version48">hover SQUARE</dt>\r
+<dd class="version48">\r
+These commands are only important for variants the GUI does not know the rules of,\r
+and keep the engine aware of how the user is manipulating pieces in the GUI,\r
+so that it can supply relevant rule information.\r
+The "lift" command is sent by the GUI when the user 'picks up' (or selects) a piece from the mentioned SQUARE,\r
+so that the engine can reply with a "highlight" command to mark the squares where that piece can move to.\r
+The "put" command similarly indicates where the user releases that piece;\r
+as the GUI clears the highlights on that event by itself, usually no engine response would be required.\r
+The "hover" command is sent whenever the mouse pointer enters a square that is currently marked in red,\r
+(reserved for captures)\r
+so that the engine can (optionally) reply with a "highlight" command to mark victims of non-standard capture\r
+(such as e.p. capture in Chess, or jump capture in Checkers) when the user would move the currently selected piece there.\r
+These commands will only be sent to engines that have requested such through the highlight 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="version48">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
</span>\r
</dd>\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
+\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
+\r
+<dt class="version48">highlight (boolean, default 0)</dt>\r
+<dd class="version48">\r
+If highlight=1 the GUI will send "lift", "put" and "hover" commands to the engine,\r
+to keep the latter aware of the user's piece manipulation before the move entry is completed,\r
+so it can respond with the proper "highlight" and "click" commands.\r
+</dd>\r
+\r
<dt class="version1">done (integer, no default)</dt>\r
<dd><span class="version1">\r
If you set done=1 during the initial two-second timeout after\r
</dd>\r
</dl>\r
</dd>\r
+</p>\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
+<p>\r
+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
+</p>\r
+</dd>\r
+\r
+<dt><span class="version48">piece ID PIECEDESC</span></dt>\r
+<dd><span class="version48">The engine can send one or more piece commands\r
+in response to a variant command, in order to specify that the piece\r
+indicated by ID moves in a non-standard way in this variant.\r
+(This to enable the GUI to reliably perform mate detection, and produce good SAN.)\r
+Like in FEN the ID is a case-sensitive letter, specifying the color.\r
+When it is a capital suffixed by &, the description is valid for both colors.\r
+PIECEDESC describes the moves in 'Betza notation',\r
+basically a concatenation of one-letter (upper-case) codes for all of its moves.\r
+These codes can be prefixed with lower-case 'modifiers' to indicate directional sub-sets\r
+(combinations of fblrvs, if the piece is not totally symmetric),\r
+move modality (non-capture, capture, e.p. capture; mce),\r
+and whether the move can jump directly to its destination,\r
+or can be blocked (n).\r
+Moves only valid for a virgin piece are prefixed by 'i'.\r
+An optional numeric suffix on the move indicates the maximum number of times\r
+the move can be repeated in the same direction,\r
+to indicate sliders / riders (with the convention 0 = infinite).\r
+</span>\r
+</dd>\r
+</p>\r
\r
<dt>Illegal move: MOVE</dt>\r
<dt>Illegal move (REASON): MOVE</dt>\r
(which causes the interface to send SAN to you) and have received\r
"accepted san" in reply.\r
</p>\r
+\r
+<p class="version48">\r
+For a multi-leg move, each leg will have to be sent in a separate "move" command,\r
+a comma at the end of all non-final legs indicating there is more to follow.\r
+</p>\r
</div>\r
</dd>\r
\r
it is guaranteed that WinBoard (and any future version of it) will completely ignore\r
these lines in any other respect.\r
</dd>\r
+\r
+<dt class="version48">highlight COLORFEN</dt>\r
+<dd class="version48">\r
+Through this command the engine can apply markers to the board squares,\r
+of the same type as the GUI uses for indicating where the user could put down a piece he grabs.\r
+The COLORFEN is a construct similar to the board part of a FEN,\r
+in which the letters indicate colors rather than piece types.\r
+Eight colors are available, through the single-letter codes: RYGCBMWD,\r
+for red, yellow, green, cyan, blue, magenta, white, black ('dark'), respectively.\r
+For example, "highlight 8/8/8/8/4y3/4yr2/8/8" would mark e3 and e4 yellow, and f3 red.\r
+Some colors have special meaning to the GUI:\r
+<table>\r
+<tr><th>color</th><th>used for</th><th>effect</th><tr>\r
+<tr><td>red</td><td>capture</td><td>hovering over the square makes the GUI send a "hover" command</td><tr>\r
+<tr><td>magenta</td><td>promotion</td><td>moving to the square will be treated by the GUI as a promotion</td><tr>\r
+<tr><td>cyan</td><td>multi-move</td><td>moving to the square will not complete the move entry</td><tr>\r
+<tr><td>green</td><td>victims</td><td>no real effect, but used by convention to indicate capture victims on "hover"</td><tr>\r
+</table>\r
+The GUI will use the markers for legality checking,\r
+and will consider moves to squares left non-marked in a highlight command as illegal even when legality checking is off.\r
+This way the GUI can be made aware of the rules of unknown variants,\r
+popping up promotion dialogs where it would otherwise not,\r
+and knowing where to wait for more input on multi-leg moves.\r
+When it would be necessary to mark squares where no legal moves go to\r
+(e.g. to indicate side effects),\r
+the corresponding lower-case character can be used for the color.\r
+For indicating a legal destination square without visibly marking it, T (transparent) can be used.\r
+</dd>\r
+\r
+<dt class="version48">click SQUARE</dt>\r
+<dd class="version48">\r
+The GUI will treat this command as if the user had clicked the mentioned SQUARE.\r
+This can be used to implement one-click moving in variants the GUI does not know the rules of\r
+(having the engine send the clicks needed to complete the move).\r
+It can also be used to implement side effects of the move the GUI would not know about\r
+(e.g. moving the Rook in a non-standard castling).\r
+</dd>\r
</dl>\r
\r
<h2><a name="10">10. Thinking Output</a></h2>\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="version48">\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="version48">\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="version48">\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