X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=engine-intf.html;h=b8b09fb01f59fdcef7ad43e960080d68489f8b6d;hb=bfb5abb19b495e71372de64dc760ff5449216e15;hp=4f4af46779274c342d1450582bdde4abe6391f58;hpb=7b022c2db89d4b4454a4f74ca6e66d59f782e6f9;p=xboard.git
diff --git a/engine-intf.html b/engine-intf.html
index 4f4af46..b8b09fb 100644
--- a/engine-intf.html
+++ b/engine-intf.html
@@ -1139,6 +1139,9 @@ The "lift" command is sent by the GUI when the user 'picks up' (or selects) a pi
so that the engine can reply with a "highlight" command to mark the squares where that piece can move to.
The "put" command similarly indicates where the user releases that piece;
as the GUI clears the highlights on that event by itself, usually no engine response would be required.
+For promotion moves you can get a double "put" command, the first one sent when the piece lands on the square,
+without being decided yet what it promotes to, so the engine can send a "choice" command to
+specify the promotion choice the GUI should offer when promotion wasn't already implied by the "lift" location.
The "hover" command is sent whenever the mouse pointer enters a square that is currently marked in red,
(reserved for captures)
so that the engine can (optionally) reply with a "highlight" command to mark victims of non-standard capture
@@ -1591,11 +1594,23 @@ The PIECETOCHAR element would ensure a Bishop would not be accepted as promotion
piece ID PIECEDESC
-This command is already reserved for future protocol extension.
-The engine can send it in response to a variant command in order to specify that the piece
-indicated by its pieceToChar letter ID moves in a non-standard way in this variant.
-(This to enable the GUI to reliably perform made detection, and produce good SAN.)
-The format of PIECEDESC is subject to future specification.
+The engine can send one or more piece commands
+in response to a variant command, in order to specify that the piece
+indicated by ID moves in a non-standard way in this variant.
+(This to enable the GUI to reliably perform mate detection, and produce good SAN.)
+Like in FEN the ID is a case-sensitive letter, specifying the color.
+When it is a capital suffixed by &, the description is valid for both colors.
+PIECEDESC describes the moves in 'Betza notation',
+basically a concatenation of one-letter (upper-case) codes for all of its moves.
+These codes can be prefixed with lower-case 'modifiers' to indicate directional sub-sets
+(combinations of fblrvs, if the piece is not totally symmetric),
+move modality (non-capture, capture, e.p. capture; mce),
+and whether the move can jump directly to its destination,
+or can be blocked (n).
+Moves only valid for a virgin piece are prefixed by 'i'.
+An optional numeric suffix on the move indicates the maximum number of times
+the move can be repeated in the same direction,
+to indicate sliders / riders (with the convention 0 = infinite).
@@ -1838,8 +1853,9 @@ Some colors have special meaning to the GUI:
color | used for | effect |
---|
red | capture | hovering over the square makes the GUI send a "hover" command |
-
magenta | promotion | moving to the square will be treated by the GUI as a promotion |
-
cyan | multi-move | moving to the square will not complete the move entry |
+
magenta | promotion choice | moving to the square will be treated by the GUI as a promotion |
+
blue | forced promotion | moving to the square will automatically promote the piece as specified in a 'choice' command |
+
cyan | multi-leg moving | moving to the square will not complete the move entry |
green | victims | no real effect, but used by convention to indicate capture victims on "hover" |
The GUI will use the markers for legality checking,
@@ -1853,6 +1869,21 @@ the corresponding lower-case character can be used for the color.
For indicating a legal destination square without visibly marking it, T (transparent) can be used.
+choice PIECESTRING
+
+This command can be sent to the GUI in response to a 'lift' or 'put' command that implies a promotion move,
+to alter the choice offered to the user for the promotion piece from what the GUI would naturally assume,
+to the piece IDs mentioned in the PIECESTRING.
+The IDs in that string should be given as capitals irrespective of color.
+The first piece mentioned will be the default choice.
+An engine must send this command on receiving a 'put' on a square that it highlighted in blue,
+or the move will not be completed;
+the GUI must wait for the 'choice' command in this case,
+to complete the move with the specified promotion suffix,
+which will then always be the first piece mentioned in the PIECESTRING.
+
+
+
click SQUARE
The GUI will treat this command as if the user had clicked the mentioned SQUARE.