X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=engine-intf.html;h=02166eac3156192f31dc75b77504fc6472c67040;hb=912ff451e7a648f6aa3ba7d2a10df2a1dc2cace5;hp=3fac3643087a46296fb010aee81f9506af577da5;hpb=05bc30b15e31c427ce208495a889e9ff36e6642b;p=xboard.git diff --git a/engine-intf.html b/engine-intf.html index 3fac364..02166ea 100644 --- a/engine-intf.html +++ b/engine-intf.html @@ -1,4 +1,3 @@ - Chess Engine Communication Protocol @@ -9,7 +8,7 @@

Chess Engine Communication Protocol

Tim Mann

-Last modified on Mon Feb 5 23:23:16 PST 2001 by mann
+$Id$
Version 2; implemented in xboard/WinBoard 4.2.1 and later.
Changes since version 1 are indicated in red.


@@ -21,7 +20,7 @@ Changes since version 1 are indicated in red.
  • 4. How it got this way
  • 5. WinBoard requires Win32 engines
  • 6. Hints on input/output -
  • 7. Interrupts +
  • 7. Signals
  • 8. Commands from xboard to the engine
  • 9. Commands from the engine to xboard
  • 10. Thinking Output @@ -43,11 +42,11 @@ and WinBoard except where they are specifically contrasted.

    -There are two reasons I can imagine someone wanting to do this: +There are two reasons I can imagine someone wanting to do this:

    1. You have, or are developing, a chess engine but you don't want to -write your own graphical interface. +write your own graphical interface.
    2. You have, or are developing,a chess engine, and you want to interface it to the Internet Chess Server.
    @@ -69,12 +68,11 @@ statements, let me know.

    I'd like to hear from everyone who is trying to interface their own -chess engine to xboard/WinBoard. Please email me, tim.mann@compaq.com. Also, please join -the mailing list for authors of xboard/WinBoard compatible chess -engines. The list is now hosted by egroups.com; you can join at http://www.egroups.com/group/chess-engines, or you can read the +chess engine to xboard/WinBoard. Please join the mailing list for +authors of xboard/WinBoard compatible chess engines and post a message +about what you're doing. The list is now hosted by Yahoo Groups; you +can join at http://groups.yahoo.com/group/chess-engines, or you can read the list there without joining. The list is filtered to prevent spam.

    @@ -98,7 +96,7 @@ implemented in Win32 and work fine. You don't have to use DDE, COM, DLLs, BSOD, or any of the other infinite complexity that Microsoft has created just to talk between two programs. A WinBoard chess engine is a Win32 console program that simply reads from its -standard input and writes to its standard output. See sections +standard input and writes to its standard output. See sections 5 and 6 below for additional details.

    @@ -155,14 +153,14 @@ features to be slightly different from what GNU Chess 4 does. This release of the protocol specification is the first to carry a version number of its own -- version 2. Previous releases simply -carried a last-modified date and were loosely tied to specific +carried a last-modified date and were loosely tied to specific releases of xboard and WinBoard. The version number "1" applies generally to all those older versions of the protocol.

    Protocol version 2 remains compatible with older engines but has -several new capabilities. In particular, it adds the +several new capabilities. In particular, it adds the "feature" command, a new mechanism for making backward-compatible changes and extensions to the protocol. Engines that do not support a particular new feature do not have to use it; new features are not @@ -173,8 +171,8 @@ features can be selected by the feature command in version 2, including the "ping" command (recommended for all engines), the "setboard" command, and many optional parameters. Additional features will probably be added in future versions. -

    +

    5. WinBoard requires Win32 engines

    @@ -273,10 +271,10 @@ use for polling is different depending on whether the input device is a pipe, a console, or something else. (More Microsoft brain damage here -- did they never hear of device independence?) For pipes, you can use PeekNamedPipe to poll (even when the pipe is unnamed). -For consoles, +For consoles, you can use GetNumberOfConsoleInputEvents. For sockets only, you can use select(). It might be possible to use -WaitForSingleObject more +WaitForSingleObject more generally, but I have not tried it. Some code to do these things can be found in Crafty's utility.c, but I don't guarantee that it's all correct or optimal. @@ -300,7 +298,7 @@ A third way to fix the problem is to check whether there are characters in the buffer whenever you poll. C I/O libraries generally do not provide any portable way to do this. Under C++, you can use cin.rdbuf()->in_avail(). This method has been reported to -work with +work with EXchess. Remember that if there are no characters in the buffer, you still have to poll the underlying file descriptor too, using the method described above. @@ -360,7 +358,7 @@ command.

    Here are details for the curious. If xboard needs to send a command -when it is the chess engine's move (such as before the "?" command), +when it is the chess engine's move (such as before the "?" command), it sends a SIGINT first. If xboard needs to send commands when it is not the chess engine's move, but the chess engine may be pondering (thinking on its opponent's time) or analyzing (analysis or analyze @@ -368,7 +366,7 @@ file mode), xboard sends a SIGINT before the first such command only. Another SIGINT is not sent until another move is made, even if xboard issues more commands. This behavior is necessary for GNU Chess 4. The first SIGINT stops it from pondering until the next move, but on some -systems, GNU Chess 4 will die if it receives a SIGINT when not +systems, GNU Chess 4 will die if it receives a SIGINT when not actually thinking or pondering.

    @@ -404,7 +402,7 @@ position. It will later send the initString again to start a new game. If your engine can't play multiple games, you can disable reuse either with the "feature" command (beginning in protocol version -2; see below) or +2; see below) or with xboard's -xreuse (or -xreuse2) command line option. xboard will then ask the process to quit after each game and @@ -420,9 +418,9 @@ user input, you must turn off the prompt and output a newline when the "xboard" command comes in.

    - -

    protover N -
    Beginning in protocol version 2 (in which N=2), this command will +
    protover N +
    +Beginning in protocol version 2 (in which N=2), this command will be sent immediately after the "xboard" command. If you receive some other command immediately after "xboard" (such as "new"), you can assume that protocol version 1 is in use. The "protover" command is @@ -443,10 +441,10 @@ options added in later protocol versions may be accepted.

    - -

    accepted -
    rejected -
    These commands may be sent to your engine in reply to the "feature" +
    accepted +
    rejected +
    +These commands may be sent to your engine in reply to the "feature" command; see its documentation below.

    @@ -533,17 +531,17 @@ reply.

    (This command is obsolete as of protocol version 2, but is still -sent in some situations to accommodate older engines unless you disable it +sent in some situations to accommodate older engines unless you disable it with the feature command.) Set White on move. Set the engine to play Black. Stop clocks.

    - +

    black
    (This command is obsolete as of protocol version 2, but is still -sent in some situations to accommodate older engines unless you disable it +sent in some situations to accommodate older engines unless you disable it with the feature command.) Set Black on move. Set the engine to play White. Stop clocks. @@ -552,7 +550,7 @@ Set Black on move. Set the engine to play White. Stop clocks.
    level MPS BASE INC
    Set time controls. See the Time Control section below.

    - +

    st TIME
    Set time controls. See the Time Control section below. The commands "level" and "st" are not used together. @@ -584,7 +582,7 @@ otim clock with the opposite color. Beginning in protocol version 2, if you can't handle the time and otim commands, you can use the "feature" command to disable them; see -below. +below. The following techniques from older protocol versions also work: You can ignore the time and otim commands (that is, treat them @@ -629,9 +627,9 @@ error message so that xboard can retract it and inform the user; see the section "Commands from the engine to xboard".

    - -
    usermove MOVE -
    By default, moves are sent to the engine without a command name; +
    usermove MOVE +
    +By default, moves are sent to the engine without a command name; the notation is just sent as a line by itself. Beginning in protocol version 2, you can use the feature command to cause the command name "usermove" to be sent before the move. @@ -656,9 +654,9 @@ or other commands while the engine is on move.

    - -
    ping N +
    ping N
    + In this command, N is a decimal number. When you receive the command, reply by sending the string pong N, where N is the same number you received. Important: You must not reply to a "ping" @@ -683,7 +681,7 @@ allow several race conditions that could occur in previous versions of the protocol to be fixed, so it is highly recommended that you implement it. It is especially important in simple engines that do not ponder and do not poll for input while thinking, but it is needed in all -engines. +engines.

    @@ -728,9 +726,9 @@ particular, you won't get one in local chess engine mode when the user stops playing by selecting Reset, Edit Game, Exit or the like.

    - -
    setboard FEN -
    The setboard command is the new way to set up positions, beginning +
    setboard FEN +
    +The setboard command is the new way to set up positions, beginning in protocol version 2. It is not used unless it has been selected with the feature command. Here FEN is a position in Forsythe-Edwards Notation, as defined in the PGN standard. @@ -739,7 +737,7 @@ Notation, as defined in the PGN standard. be used to send an illegal position to the engine. The user can create any position with xboard's Edit Position command (even, say, an empty board, or a board with 64 white kings and no black ones). -If your engine receives a position that it considers illegal, +If your engine receives a position that it considers illegal, I suggest that you send the response "tellusererror Illegal position", and then respond to any attempted move with "Illegal move" until the next new, edit, or setboard command.

    @@ -781,7 +779,7 @@ black-on-move position, xboard uses the following command sequence:

    This sequence is used to avoid the "black" command, which is now -considered obsolete and which many engines never did implement as +considered obsolete and which many engines never did implement as specified in this document.

    @@ -833,23 +831,23 @@ your default is for pondering or whether "new" affects this setting.
    easy
    Turn off pondering.

    - +

    post -
    Turn on thinking/pondering output. +
    Turn on thinking/pondering output. See Thinking Output section.

    nopost
    Turn off thinking/pondering output.

    - +

    analyze
    Enter analyze mode. See Analyze Mode section.

    name X
    This command informs the engine of its opponent's name. When the engine is playing on a chess server, xboard -obtains the opponent's name from the server. +obtains the opponent's name from the server. When the engine is playing locally against a human user, xboard obtains the user's login @@ -869,7 +867,7 @@ feature command; see below. not appear on servers using outdated versions of the FICS code.) In Zippy mode, it sends these ratings on to the chess engine using the "rating" command. The chess engine's own rating comes first, and if -either opponent is not rated, his rating is given as 0. +either opponent is not rated, his rating is given as 0. In the future this command may also be used in other modes, if ratings are known. @@ -877,9 +875,9 @@ are known. Example:
    rating 2600 1500

    - -

    ics HOSTNAME -
    If HOSTNAME is "-", the engine is playing against a local +
    ics HOSTNAME +
    +If HOSTNAME is "-", the engine is playing against a local opponent; otherwise, the engine is playing on an Internet Chess Server (ICS) with the given hostname. This command is new in protocol version 2 and is not sent unless the engine has enabled it with @@ -892,10 +890,9 @@ the "feature" command. Example: "ics freechess.org" their playing style when they receive this command.

    - -

    pause -
    resume -
    (These commands are new in protocol +
    pause +
    resume +
    (These commands are new in protocol version 2 and will not be sent unless feature pause=1 is set. At this writing, xboard actually does not use the commands at all, but it or other interfaces may use them in the future.) @@ -918,7 +915,7 @@ xboard now supports bughouse engines when in Zippy mode. See >zippy.README for information on Zippy mode and how to turn on the bughouse support. The bughouse move format is given above. xboard sends the following additional commands to the engine when in bughouse -mode. +mode. Commands to inform your engine of the partner's game state may be added in the future.

    @@ -933,7 +930,7 @@ be added in the future.

    ptell <text> -
    Your partner told you <text>, either with a ptell or an ordinary tell. +
    Your partner told you <text>, either with a ptell or an ordinary tell.

    holding [<white>] [<black>] @@ -957,10 +954,12 @@ were previously not assigned a meaning.

    - -
    feature FEATURE1=VALUE1 FEATURE2=VALUE2 ... +
    +feature FEATURE1=VALUE1 FEATURE2=VALUE2 ... + -
    Beginning with version 2, the protocol includes the "feature" +
    +Beginning with version 2, the protocol includes the "feature" command, which lets your engine control certain optional protocol features. Feature settings are written as FEATURE=VALUE, where FEATURE is a name from the list below and VALUE is the value to be @@ -1028,71 +1027,123 @@ depend on be rejected.

    Here are the features that are currently defined.

    +
    -
    ping (boolean, default 0, recommended 1) -
    If ping=1, xboard may use the protocol's new "ping" command; +
    +ping (boolean, default 0, recommended 1) + +
    +If ping=1, xboard may use the protocol's new "ping" command; if ping=0, xboard will not use the command. + -
    setboard (boolean, default 0, recommended 1) -
    If setboard=1, xboard will use the protocol's new "setboard" command +
    +setboard (boolean, default 0, recommended 1) + +
    +If setboard=1, xboard will use the protocol's new "setboard" command to set up positions; if setboard=0, it will use the older "edit" command. + -
    playother (boolean, default 0, recommended 1) -
    If playother=1, xboard will use the protocol's new "playother" command +
    +playother (boolean, default 0, recommended 1) + +
    +If playother=1, xboard will use the protocol's new "playother" command when appropriate; if playother=0, it will not use the command. + -
    san (boolean, default 0) -
    If san=1, xboard will send moves to the engine in standard algebraic +
    +san (boolean, default 0) + +
    +If san=1, xboard will send moves to the engine in standard algebraic notation (SAN); for example, Nf3. If san=0, xboard will send moves in -coordinate notation; for example, g1f3. See MOVE in +coordinate notation; for example, g1f3. See MOVE in section 8 above for more details of both kinds of notation. + -
    usermove (boolean, default 0) -
    If usermove=1, xboard will send moves to the engine with the +
    +usermove (boolean, default 0) + +
    +If usermove=1, xboard will send moves to the engine with the command "usermove MOVE"; if usermove=0, xboard will send just the move, with no command name. + -
    time (boolean, default 1, recommended 1) -
    If time=1, xboard will send the "time" and "otim" commands to +
    +time (boolean, default 1, recommended 1) + +
    +If time=1, xboard will send the "time" and "otim" commands to update the engine's clocks; if time=0, it will not. + -
    draw (boolean, default 1, recommended 1) -
    If draw=1, xboard will send the "draw" command if the engine's opponent +
    +draw (boolean, default 1, recommended 1) + +
    +If draw=1, xboard will send the "draw" command if the engine's opponent offers a draw; if draw=0, xboard will not inform the engine about draw offers. Note that if draw=1, you may receive a draw offer while you are on move; if this will cause you to move immediately, you should set draw=0. + -
    sigint (boolean, default 1) -
    If sigint=1, xboard may send SIGINT (the interrupt signal) to +
    +sigint (boolean, default 1) + +
    +If sigint=1, xboard may send SIGINT (the interrupt signal) to the engine as section 7 above; if sigint=0, it will not. + -
    sigterm (boolean, default 1) -
    If sigterm=1, xboard may send SIGTERM (the termination signal) to +
    +sigterm (boolean, default 1) + +
    +If sigterm=1, xboard may send SIGTERM (the termination signal) to the engine as section 7 above; if sigterm=0, it will not. + -
    reuse (boolean, default 1, recommended 1) -
    If reuse=1, xboard may reuse your engine for multiple games. If +
    +reuse (boolean, default 1, recommended 1) + +
    +If reuse=1, xboard may reuse your engine for multiple games. If reuse=0 (or if the user has set the -xreuse option on xboard's command line), xboard will kill the engine process after every game and start a fresh process for the next game. + -
    analyze (boolean, default 1, recommended 1) -
    If analyze=0, xboard will not try to use the "analyze" command; it +
    +analyze (boolean, default 1, recommended 1) + +
    +If analyze=0, xboard will not try to use the "analyze" command; it will pop up an error message if the user asks for analysis mode. If analyze=1, xboard will try to use the command if the user asks for analysis mode. + -
    myname (string, default determined from engine filename) -
    This feature lets you set the name that xboard will use for your +
    +myname (string, default determined from engine filename) + +
    +This feature lets you set the name that xboard will use for your engine in window banners, in the PGN tags of saved game files, and when sending the "name" command to another engine. + -
    variants (string, see text below) -
    This feature indicates which chess variants your engine accepts. +
    +variants (string, see text below) + +
    +This feature indicates which chess variants your engine accepts. It should be a comma-separated list of variant names. See the table under the "variant" command in section 8 above. If you do not set this feature, xboard will assume by default that your @@ -1103,37 +1154,57 @@ correct value for your engine (just "normal" in most cases) rather than leaving the default in place, so that the user will get an appropriate error message if he tries to play a variant that your engine does not support. + -
    colors (boolean, default 1, recommended 0) -
    If colors=1, xboard uses the obsolete "white" and "black" +
    +colors (boolean, default 1, recommended 0) + +
    +If colors=1, xboard uses the obsolete "white" and "black" commands in a stylized way that works with most older chess engines that require the commands. See the "Idioms" section below for details. If colors=0, xboard does not use the "white" and "black" commands at all. + -
    ics (boolean, default 0) -
    If ics=1, xboard will use the protocol's new "ics" command +
    +ics (boolean, default 0) + +
    +If ics=1, xboard will use the protocol's new "ics" command to inform the engine of whether or not it is playing on a chess server; if ics=0, it will not. + -
    name (boolean, see text below) -
    If name=1, xboard will use the protocol's "name" command +
    +name (boolean, see text below) + +
    +If name=1, xboard will use the protocol's "name" command to inform the engine of the opponent's name; if name=0, it will not. By default, name=1 if the engine is playing on a chess server; name=0 if not. + -
    pause (boolean, default 0) -
    If pause=1, xboard may use the protocol's new "pause" command; +
    +pause (boolean, default 0) + +
    +If pause=1, xboard may use the protocol's new "pause" command; if pause=0, xboard assumes that the engine does not support this command. + -
    done (integer, no default) -
    If you set done=1 during the initial two-second timeout after +
    +done (integer, no default) + +
    +If you set done=1 during the initial two-second timeout after xboard sends you the "xboard" command, the timeout will end and xboard will not look for any more feature commands before starting normal operation. If you set done=0, the initial timeout is increased to one hour; in this case, you must set done=1 before xboard will enter normal operation. -
    +

    Illegal move: MOVE @@ -1150,8 +1221,8 @@ optional. Examples: Illegal move (moving into check): e1g1

    -Generally, xboard will never send an ambiguous move, so it does not -matter whether you respond to such a move with an Illegal move message +Generally, xboard will never send an ambiguous move, so it does not +matter whether you respond to such a move with an Illegal move message or an Error message.

    @@ -1238,9 +1309,9 @@ Machine Black, or Two Machines mode, the offer is considered valid until your engine has made two more moves.

    - -

    tellopponent MESSAGE -
    This command lets the engine give a message to its opponent, +
    tellopponent MESSAGE +
    +This command lets the engine give a message to its opponent, independent of whether the opponent is a user on the local machine or a remote ICS user (Zippy mode). MESSAGE consists of any characters, including whitespace, to the end of the line. When the engine is @@ -1250,7 +1321,7 @@ against an opponent on the ICS (Zippy mode), xboard sends "say MESSAGE\n" to the ICS.

    -

    tellothers MESSAGE +
    tellothers MESSAGE
    This command lets the engine give a message to people watching the game other than the engine's opponent. MESSAGE consists of any characters, including whitespace, to the end of the line. When the @@ -1261,7 +1332,7 @@ ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
    tellall MESSAGE
    This command lets the engine give a message to its opponent and -other people watching the game, +other people watching the game, independent of whether the opponent is a user on the local machine or a remote ICS user (Zippy mode). MESSAGE consists of any characters, including whitespace, to the end of the line. When the engine is @@ -1297,9 +1368,9 @@ bar" to the engine. The user can cancel the dialog and send nothing. of any characters, including whitespace, to the end of the line.

    - -

    tellicsnoalias MESSAGE -
    In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a +
    tellicsnoalias MESSAGE +
    +In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a character that prevents the ICS from expanding command aliases, if xboard knows of such a character. (On chessclub.com and chess.net, "/" is used; on freechess.org, "$" is used.) MESSAGE consists of any @@ -1345,7 +1416,7 @@ Example: Meaning:

    -9 ply, score=1.56, time = 10.84 seconds, nodes=48000, +9 ply, score=1.56, time = 10.84 seconds, nodes=48000, PV = "Nf3 Nc6 Nc3 Nf6"

    @@ -1379,30 +1450,30 @@ units. Example:

    - 2.     14    0       38   d1d2  e8e7 
    - 3+     78    0       65   d1d2  e8e7  d2d3 
    - 3&     14    0       89   d1d2  e8e7  d2d3 
    - 3&     76    0      191   d1e2  e8e7  e2e3 
    - 3.     76    0      215   d1e2  e8e7  e2e3 
    - 4&     15    0      366   d1e2  e8e7  e2e3  e7e6 
    - 4.     15    0      515   d1e2  e8e7  e2e3  e7e6 
    - 5+     74    0      702   d1e2  f7f5  e2e3  e8e7  e3f4 
    - 5&     71    0     1085   d1e2  e8e7  e2e3  e7e6  e3f4 
    - 5.     71    0     1669   d1e2  e8e7  e2e3  e7e6  e3f4 
    - 6&     48    0     3035   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4 
    - 6.     48    0     3720   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4 
    - 7&     48    0     6381   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4 
    - 7.     48    0    10056   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4 
    - 8&     66    1    20536   d1e2  e8e7  e2e3  e7e6  e3d4  g7g5  a2a4  f7f5 
    - 8.     66    1    24387   d1e2  e8e7  e2e3  e7e6  e3d4  g7g5  a2a4  f7f5 
    - 9&     62    2    38886   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  a2a4  h5h4 
    -                           d4e4 
    - 9.     62    4    72578   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  a2a4  h5h4 
    -                           d4e4 
    -10&     34    7   135944   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  c2c4  h5h4 
    -                           d4e4  f7f5  e4f4 
    -10.     34    9   173474   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  c2c4  h5h4 
    -                           d4e4  f7f5  e4f4 
    + 2.     14    0       38   d1d2  e8e7
    + 3+     78    0       65   d1d2  e8e7  d2d3
    + 3&     14    0       89   d1d2  e8e7  d2d3
    + 3&     76    0      191   d1e2  e8e7  e2e3
    + 3.     76    0      215   d1e2  e8e7  e2e3
    + 4&     15    0      366   d1e2  e8e7  e2e3  e7e6
    + 4.     15    0      515   d1e2  e8e7  e2e3  e7e6
    + 5+     74    0      702   d1e2  f7f5  e2e3  e8e7  e3f4
    + 5&     71    0     1085   d1e2  e8e7  e2e3  e7e6  e3f4
    + 5.     71    0     1669   d1e2  e8e7  e2e3  e7e6  e3f4
    + 6&     48    0     3035   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
    + 6.     48    0     3720   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
    + 7&     48    0     6381   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
    + 7.     48    0    10056   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
    + 8&     66    1    20536   d1e2  e8e7  e2e3  e7e6  e3d4  g7g5  a2a4  f7f5
    + 8.     66    1    24387   d1e2  e8e7  e2e3  e7e6  e3d4  g7g5  a2a4  f7f5
    + 9&     62    2    38886   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  a2a4  h5h4
    +                           d4e4
    + 9.     62    4    72578   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  a2a4  h5h4
    +                           d4e4
    +10&     34    7   135944   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  c2c4  h5h4
    +                           d4e4  f7f5  e4f4
    +10.     34    9   173474   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  c2c4  h5h4
    +                           d4e4  f7f5  e4f4
     

    If your engine is pondering (thinking on its opponent's time) in post @@ -1503,11 +1574,11 @@ on one move does not accumulate for use on later moves.

    xboard supports analyzing fresh games, edited positions, and games from files. However, all of these look the same from the chess engine's perspective. Basically, the engine just has to respond to the -"analyze" command. +"analyze" command. Beginning in protocol version 2, if your engine does not support analyze mode, it should use -the feature command to set analyze=0. +the feature command to set analyze=0. The older method of printing the error message "Error (unknown command): analyze" in @@ -1515,7 +1586,7 @@ response to the "analyze" command will also work, however.

    -To enter analyze mode, xboard sends the command sequence "post", "analyze". +To enter analyze mode, xboard sends the command sequence "post", "analyze". Analyze mode in your engine should be similar to force mode, except that your engine thinks about what move it would make next if it were on move. Your engine should accept the @@ -1526,19 +1597,18 @@ following commands while in analyze mode:

  • Any legal move, as in force mode
  • undo   Back up one move and analyze previous position.
  • new   Reset position to start of game but stay in analyze mode. - -
  • setboard if you have set feature setboard=1; otherwise edit. Exiting edit mode returns to analyze mode. +
  • setboard if you have set feature setboard=1; otherwise edit. Exiting edit mode returns to analyze mode.
  • exit   Leave analyze mode.
  • .   Send a search status update (optional); see below. -
  • +
  • bk   Show book moves from this position, if any; see above. -
  • +
  • hint   Show the predicted move from this position, if any; see above. - +

    If the user selects "Periodic Updates", xboard will send the string ".\n" to the chess engine periodically during analyze mode, unless the @@ -1602,7 +1672,7 @@ figure this out itself.

    Some engines have variant interpretations of the force/go/white/black, -time/otim, and hard/easy command sets. +time/otim, and hard/easy command sets. In order to accommodate these older engines, xboard uses these commands only according to the stylized patterns ("idioms") given in this section. The obsolete white and black commands @@ -1623,7 +1693,7 @@ playing the opposite color.

    go
    Sent when the engine is in force mode or playing Black but should switch to playing White. This sequence is sent only when White is -already on move. +already on move. If you set the feature colors=0, "white" is not sent. @@ -1633,7 +1703,7 @@ If you set the feature colors=0, "white" is not sent.
    go
    Sent when the engine is in force mode or playing White but should switch to playing Black. This sequence is sent only when Black is -already on move. +already on move. If you set the feature colors=0, "black" is not sent. @@ -1646,9 +1716,9 @@ If you set the feature colors=0, "black" is not sent.
    go
    Sent when Black is on move, the engine is in force mode or playing White, and the engine's clock needs to be updated before it starts -playing. +playing. The initial "white" is a kludge to accommodate GNU Chess -4's variant interpretation of these commands. +4's variant interpretation of these commands. If you set the feature colors=0, "white" and "black" are not sent. @@ -1661,9 +1731,9 @@ If you set the feature colors=0, "white" and "black" are not sent.
    go
    Sent when White is on move, the engine is in force mode or playing Black, and the engine's clock needs to be updated before it starts -playing. See previous idiom. +playing. See previous idiom. The initial "black" is a kludge to accommodate GNU Chess -4's variant interpretation of these commands. +4's variant interpretation of these commands. If you set the feature colors=0, "black" and "white" are not sent.