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
+For promotion moves you can get a double "put" command, the first one sent when the piece lands on the square,\r
+without being decided yet what it promotes to, so the engine can send a "choice" command to\r
+specify the promotion choice the GUI should offer when promotion wasn't already implied by the "lift" location.\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
(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
</dd>\r
</dl>\r
</dd>\r
+</p>\r
\r
<dt>setup FEN</dt>\r
<dt>setup (PIECETOCHAR) FEN</dt>\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
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
<dd>If your engine receives a MOVE command that is recognizably a move\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>magenta</td><td>promotion choice</td><td>moving to the square will be treated by the GUI as a promotion</td><tr>\r
+<tr><td>blue</td><td>forced promotion</td><td>moving to the square will automatically promote the piece as specified in a 'choice' command</td><tr>\r
+<tr><td>cyan</td><td>multi-leg moving</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
For indicating a legal destination square without visibly marking it, T (transparent) can be used.\r
</dd>\r
\r
+<dt class="version48">choice PIECESTRING</dt>\r
+<dd class="version48">\r
+This command can be sent to the GUI in response to a 'lift' or 'put' command that implies a promotion move,\r
+to alter the choice offered to the user for the promotion piece from what the GUI would naturally assume,\r
+to the piece IDs mentioned in the PIECESTRING.\r
+The IDs in that string should be given as capitals irrespective of color.\r
+The first piece mentioned will be the default choice.\r
+An engine <i>must</i> send this command on receiving a 'put' on a square that it highlighted in blue,\r
+or the move will not be completed;\r
+the GUI must wait for the 'choice' command in this case,\r
+to complete the move with the specified promotion suffix,\r
+which will then always be the first piece mentioned in the PIECESTRING.\r
+</dd>\r
+</dl>\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
projects / xboard.git / blobdiff