Silence warning

[xboard.git] / engine-intf.html

diff --git a/engine-intf.html b/engine-intf.html
index 969495b..058f147 100644 (file)
--- a/engine-intf.html
+++ b/engine-intf.html
@@ -13,6 +13,7 @@
   .version43 { color: green;}\r
   .version44 { color: blue; }\r
   .version47 { color: purple; }\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
 \r
   table tr { text-align: left}\r
   tr > td:first-child { font-weight:bold;}\r


@@ -537,10 +538,13 @@ defined variant names are:
 <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="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
 <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
+<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
 </dd>\r
 \r
 <dt>quit</dt>\r


@@ -706,10 +710,12 @@ algebraic notation.  Examples:
 <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><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
 </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
 </p>\r
 <p class="version1">\r
 Beginning in protocol version 2, you can use the feature command\r


@@ -1121,6 +1127,24 @@ It is entirely up to the engine to decide when the effect of this option should
 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
 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
 </dl>\r
 \r
 <h3>Bughouse commands:</h3>\r


@@ -1343,7 +1367,7 @@ correct value for your engine (just "normal" in most cases) rather
 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
 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
+<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
 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


@@ -1490,18 +1514,24 @@ terminated by feature done=1.
 (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
 (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

+</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">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
 \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>\r
 \r
 <dt class="version1">done (integer, no default)</dt>\r


@@ -1516,6 +1546,7 @@ in this case, you must set done=1 before xboard will enter normal operation.
 </dd>\r
 </dl>\r
 </dd>\r
 </dd>\r
 </dl>\r
 </dd>\r

+</p>\r

 \r
 <dt>setup FEN</dt>\r
 <dt>setup (PIECETOCHAR) FEN</dt>\r
 \r
 <dt>setup FEN</dt>\r
 <dt>setup (PIECETOCHAR) FEN</dt>\r


@@ -1537,8 +1568,8 @@ and any setup commands received from the latter will always be ignored.
 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
 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
+<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
 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


@@ -1556,8 +1587,31 @@ could be used by an engine for Los-Alamos Chess in response to 'variant losalamo
 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
 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
 </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
 <dd>If your engine receives a MOVE command that is recognizably a move\r
 <dt>Illegal move: MOVE</dt>\r
 <dt>Illegal move (REASON): MOVE</dt>\r
 <dd>If your engine receives a MOVE command that is recognizably a move\r


@@ -1623,6 +1677,11 @@ engine to send SAN to the interface only if you have set feature san=1
 (which causes the interface to send SAN to you) and have received\r
 "accepted san" in reply.\r
 </p>\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
 </div>\r
 </dd>\r
 \r


@@ -1777,6 +1836,43 @@ If the engine has set feature debug=1,
 it is guaranteed that WinBoard (and any future version of it) will completely ignore\r
 these lines in any other respect.\r
 </dd>\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
 </dl>\r
 \r
 <h2><a name="10">10. Thinking Output</a></h2>\r


@@ -1808,7 +1904,7 @@ You can continue the pv onto another line if you start each
 continuation line with at least four space characters.</td></tr>\r
 </table>\r
 \r
 continuation line with at least four space characters.</td></tr>\r
 </table>\r
 \r

-<p class="version47">\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 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


@@ -1824,12 +1920,17 @@ It is therefore encouraged that engines use tabs or spaces to format this option
 so that it will display nicely in (not too wide) columns.\r
 </p>\r
 \r
 so that it will display nicely in (not too wide) columns.\r
 </p>\r
 \r

-<p class="version47">\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
 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
 <p>\r
 Example:\r
 </p>\r