-<html>
-<head>
-<title>Chess Engine Communication Protocol</title>
-</head>
-
-<body>
-<hr noshade size="2">
-<h1>Chess Engine Communication Protocol</h1>
-<h2><a href="http://www.tim-mann.org/">Tim Mann</a></h2>
-<p>
-$Id$<br>
-Version 2; implemented in xboard/WinBoard 4.2.1 and later.<br>
-Changes since version 1 are indicated in <font color=red>red</font>.
-<hr noshade size="2">
-
-<ul>
-<li><a href="#1">1. Introduction</a>
-<li><a href="#2">2. Connection</a>
-<li><a href="#3">3. Debugging</a>
-<li><a href="#4">4. How it got this way</a>
-<li><a href="#5">5. WinBoard requires Win32 engines</a>
-<li><a href="#6">6. Hints on input/output</a>
-<li><a href="#7">7. Signals</a>
-<li><a href="#8">8. Commands from xboard to the engine</a>
-<li><a href="#9">9. Commands from the engine to xboard</a>
-<li><a href="#10">10. Thinking Output</a>
-<li><a href="#11">11. Time control</a>
-<li><a href="#12">12. Analyze Mode</a>
-<li><a href="#13">13. Idioms and backward compatibility features</a>
-</ul>
-
-<hr noshade size="2">
-
-<h2><a name="1">1. Introduction</a></h2>
-
-<p>
-This document is a set of rough notes on the protocol that xboard and
-WinBoard use to communicate with gnuchessx and other chess engines.
-These notes may be useful if you want to connect a different chess
-engine to xboard. Throughout the notes, "xboard" means both xboard
-and WinBoard except where they are specifically contrasted.
-</p>
-
-<p>
-There are two reasons I can imagine someone wanting to do this:
-</p>
-<ol>
-<li>You have, or are developing, a chess engine but you don't want to
-write your own graphical interface.
-<li>You have, or are developing,a chess engine, and you want to
-interface it to the Internet Chess Server.
-</ol>
-
-<p>
-In case (2), if you are using xboard, you will need to configure the
-"Zippy" code into it, but WinBoard includes this code already. See
-the file <a
-href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
-in the xboard or WinBoard distribution for more information.
-
-</p>
-
-<p>
-These notes are unpolished, but I've attempted to make them complete
-in this release. If you notice any errors, omissions, or misleading
-statements, let me know.
-</p>
-
-<p>
-I'd like to hear from everyone who is trying to interface their own
-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 <a href="http://groups.yahoo.com/group/chess-engines"
->http://groups.yahoo.com/group/chess-engines</a>, or you can read the
-list there without joining. The list is filtered to prevent spam.
-</p>
-
-<h2><a name="2">2. Connection</a></h2>
-
-<p>
-An xboard chess engine runs as a separate process from xboard itself,
-connected to xboard through a pair of anonymous pipes. The engine
-does not have to do anything special to set up these pipes. xboard
-sets up the pipes itself and starts the engine with one pipe as its
-standard input and the other as its standard output. The engine then
-reads commands from its standard input and writes responses to its
-standard output. This is, unfortunately, a little more complicated to
-do right than it sounds; see <a href="#6">section 6</a> below.
-</p>
-
-<p>
-And yes, contrary to some people's expectations, exactly the same
-thing is true for WinBoard. Pipes and standard input/output are
-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
-<a href="#5">5</a> and <a href="#6">6</a> below for additional details.
-</p>
-
-<h2><a name="3">3. Debugging</a></h2>
-
-<p>
-To diagnose problems in your engine's interaction with xboard, use the
--debug flag on xboard's command line to see the messages that are
-being exchanged. In WinBoard, these messages are written to the file
-WinBoard.debug instead of going to the screen.
-</p>
-
-<p>
-You can turn debug mode on or off while WinBoard is running by
-pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard
-is running by binding DebugProc to a shortcut key (and pressing the
-key!); see the instructions on shortcut keys in the xboard man page.
-</p>
-
-<p>
-While your engine is running under xboard/WinBoard, you can send a
-command directly to the engine by pressing Shift+1 (xboard) or Alt+1
-(WinBoard 4.0.3 and later). This brings up a dialog that you can type
-your command into. Press Shift+2 (Alt+2) instead to send to the
-second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier,
-Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict
-with typing the @-sign on some European keyboards.
-</p>
-
-<h2><a name="4">4. How it got this way</a></h2>
-
-<p>
-Originally, xboard was just trying to talk to the existing
-command-line interface of GNU Chess 3.1+ and 4, which was designed
-for people to type commands to. So the communication protocol is very
-ad-hoc. It might have been good to redesign it early on, but because
-xboard and GNU Chess are separate programs, I didn't want to force
-people to upgrade them together to versions that matched. I
-particularly wanted to keep new versions of xboard working with old
-versions of GNU Chess, to make it easier to compare the play of old
-and new gnuchess versions. I didn't foresee the need for a clean
-protocol to be used with other chess engines in the future.
-</p>
-
-<p>
-Circumstances have changed over the years, and now there are many more
-engines that work with xboard. I've had to make the protocol
-description more precise, I've added some features that GNU Chess
-does not support, and I've specified the standard semantics of a few
-features to be slightly different from what GNU Chess 4 does.
-</p>
-
-<p>
-<font color=red>
-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
-releases of xboard and WinBoard. The version number "1" applies
-generally to all those older versions of the protocol.
-</font>
-
-<font color=red>
-<p>Protocol version 2 remains compatible with older engines but has
-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
-enabled unless the engine specifically requests them using the feature
-command. If an engine does not send the feature command at all, the
-protocol behavior is nearly identical to version 1. Several new
-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.
-</p>
-</font>
-
-<h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
-
-<p>
-Due to some Microsoft brain damage that I don't understand, WinBoard
-does not work with chess engines that were compiled to use a DOS
-extender for 32-bit addressing. (Probably not with 16-bit DOS or
-Windows programs either.) WinBoard works only with engines that are
-compiled for the Win32 API. You can get a free compiler that targets
-the Win32 API from <a href="http://sources.redhat.com/cygwin/"
->http://sources.redhat.com/cygwin/</a>. I think DJGPP 2.x should also
-work if you use the RSXNTDJ extension, but I haven't tried it. Of
-course, Microsoft Visual C++ will work. Most likely the other
-commercial products that support Win32 will work too (Borland, etc.),
-but I have not tried them. Delphi has been successfully used to write
-engines for WinBoard; if you want to do this, Tony Werten has donated
-some <a href="http://www.tim-mann.org/winboard/delphi.txt" >sample
-code</a> that should help you get started.
-</p>
-
-<h2><a name="6">6. Hints on input/output</a></h2>
-
-<p>
-Beware of using buffered I/O in your chess engine. The C stdio
-library, C++ streams, and the I/O packages in most other languages use
-buffering both on input and output. That means two things. First,
-when your engine tries to write some characters to xboard, the library
-stashes them in an internal buffer and does not actually write them to
-the pipe connected to xboard until either the buffer fills up or you
-call a special library routine asking for it to be flushed. (In C
-stdio, this routine is named <tt>fflush</tt>.) Second, when your engine tries
-to read some characters from xboard, the library does not read just
-the characters you asked for -- it reads all the characters that are
-currently available (up to some limit) and stashes any characters you
-are not yet ready for in an internal buffer. The next time you ask to
-read, you get the characters from the buffer (if any) before the
-library tries to read more data from the actual pipe.
-</p>
-
-<p>
-Why does this cause problems? First, on the output side, remember
-that your engine produces output in small quantities (say, a few
-characters for a move, or a line or two giving the current analysis),
-and that data always needs to be delivered to xboard/WinBoard for
-display immediately. If you use buffered output, the data you print
-will sit in a buffer in your own address space instead of being
-delivered.
-</p>
-
-<p>
-You can usually fix the output buffering problem by asking for the
-buffering to be turned off. In C stdio, you do this by calling
-<tt>setbuf(stdout, NULL)</tt>. A more laborious and error-prone
-method is to carefully call <tt>fflush(stdout)</tt> after every line
-you output; I don't recommend this. In C++, you can try
-<tt>cout.setf(ios::unitbuf)</tt>, which is documented in current
-editions of "The C++ Programming Language," but not older ones.
-Another C++ method that might work is
-<tt>cout.rdbuf()->setbuf(NULL, 0)</tt>. Alternatively, you can
-carefully call <tt>cout.flush()</tt> after every line you output;
-again, I don't recommend this.
-</p>
-
-<p>
-Another way to fix the problem is to use unbuffered operating system
-calls to write directly to the file descriptor for standard output.
-On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).
-On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32
-native routines like <tt>WriteFile</tt>.
-</p>
-
-<p>
-Second, on the input side, you are likely to want to poll during your
-search and stop it if new input has come in. If you implement
-pondering, you'll need this so that pondering stops when the user
-makes a move. You should also poll during normal thinking on your
-move, so that you can implement the "?" (move now) command, and so
-that you can respond promptly to a "result", "force", or "quit"
-command if xboard wants to end the game or terminate your engine.
-Buffered input makes polling more complicated -- when you poll, you
-must stop your search if there are <em>either</em> characters in the buffer
-<em>or</em> characters available from the underlying file descriptor.
-</p>
-
-<p>
-The most direct way to fix this problem is to use unbuffered operating
-system calls to read (and poll) the underlying file descriptor
-directly. On Unix, use <tt>read(0, ...)</tt> to read from standard input, and
-use <tt>select()</tt> to poll it. See the man pages read(2) and select(2).
-(Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to
-poll for input. It is not very portable; that is, it does not exist
-on all versions of Unix, and is broken on some that do have it.) On
-Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native
-Win32 <tt>ReadFile()</tt> to read. Unfortunately, under Win32, the function to
-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 <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).
-For consoles,
-you can use <tt>GetNumberOfConsoleInputEvents</tt>. For sockets only, you can
-use <tt>select()</tt>. It might be possible to use
-<tt>WaitForSingleObject</tt> 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.
-</p>
-
-<p>
-A second way to fix the problem might be to ask your I/O library not
-to buffer on input. It should then be safe to poll the underlying
-file descriptor as described above. With C, you can try calling
-<tt>setbuf(stdin, NULL)</tt>. However, I have never tried this. Also, there
-could be problems if you use <tt>scanf()</tt>, at least with certain patterns,
-because <tt>scanf()</tt> sometimes needs to read one extra character and "push
-it back" into the buffer; hence, there is a one-character pushback
-buffer even if you asked for stdio to be unbuffered. With C++, you
-can try <tt>cin.rdbuf()->setbuf(NULL, 0)</tt>, but again, I have never tried
-this.
-</p>
-
-<p>
-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
-<tt>cin.rdbuf()->in_avail()</tt>. This method has been reported to
-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.
-</p>
-
-<p>
-A fourth way to fix the problem is to use a separate thread to read
-from stdin. This way works well if you are familiar with thread
-programming. This thread can be blocked waiting for input to come in
-at all times, while the main thread of your engine does its thinking.
-When input arrives, you have the thread put the input into a buffer
-and set a flag in a global variable. Your search routine then
-periodically tests the global variable to see if there is input to
-process, and stops if there is. WinBoard and my Win32 ports of ICC
-timestamp and FICS timeseal use threads to handle multiple input
-sources.
-</p>
-
-<h2><a name="7">7. Signals</a></h2>
-
-<p>Engines that run on Unix need to be concerned with two Unix
-signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>. This applies both to
-engines that run under xboard and (the unusual case of) engines that
-WinBoard remotely runs on a Unix host using the -firstHost or
--secondHost feature. It does not apply to engines that run on
-Windows, because Windows does not have Unix-style signals.
-<font color=red>
-Beginning with version 2, you can now turn off the use of
-either or both
-signals. See the "feature" command in <a href="#6">section 9</a> below.
-</font>
-</p>
-
-<p>First, when an engine is sent the "quit" command, it is also given
-a <tt>SIGTERM</tt> signal shortly afterward to make sure it goes away.
-If your engine reliably responds to "quit", and the signal causes
-problems for you, you should either ignore it by calling
-<tt>signal(SIGTERM, SIG_IGN)</tt> at the start of your program,
-or disable it with the "feature" command.</p>
-
-<p>Second, xboard will send an interrupt signal (<tt>SIGINT</tt>) at
-certain times when it believes the engine may not be listening to user
-input (thinking or pondering). WinBoard currently does this only when
-the engine is running remotely using the -firstHost or -secondHost
-feature, not when it is running locally. You probably need to know
-only enough about this grungy feature to keep it from getting in your
-way.
-</p>
-
-<p>
-The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess 4
-on systems where its input polling code is broken or disabled.
-Because they work in a rather peculiar way, it is recommended that you
-either ignore <tt>SIGINT</tt> by having your engine call
-<tt>signal(SIGINT, SIG_IGN)</tt>, or disable it with the "feature"
-command.</p>
-
-<p>
-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),
-it sends a <tt>SIGINT</tt> 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
-file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.
-Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard
-issues more commands. This behavior is necessary for GNU Chess 4. The
-first <tt>SIGINT</tt> stops it from pondering until the next move, but on some
-systems, GNU Chess 4 will die if it receives a <tt>SIGINT</tt> when not
-actually thinking or pondering.
-</p>
-
-<p>
-There are two reasons why WinBoard does not send the Win32 equivalent
-of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local
-engines. First, the Win32 GNU Chess 4 port does not need it. Second, I
-could not find a way to get it to work. Win32 seems to be designed
-under the assumption that only console applications, not windowed
-applications, would ever want to send a <tt>CTRL_C_EVENT</tt>.
-</p>
-
-<h2><a name="8">8. Commands from xboard to the engine</a></h2>
-
-<p>
-All commands from xboard to the engine end with a newline (\n), even
-where that is not explicitly stated. All your output to xboard must
-be in complete lines; any form of prompt or partial line will cause
-problems.
-</p>
-
-<p>
-At the beginning of each game, xboard sends an initialization string.
-This is currently "new\nrandom\n" unless the user changes it with the
-initString or secondInitString option.
-</p>
-
-<p>
-xboard normally reuses the same chess engine process for multiple
-games. At the end of a game, xboard will send the "force" command
-(see below) to make sure your engine stops thinking about the current
-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
-<font color=red>
-either with the "feature" command (beginning in protocol version
-2; see below) or
-</font>
-with xboard's -xreuse (or -xreuse2) command line
-option. xboard will then ask the process to quit after each game and
-start a new process for the next game.
-</p>
-
-<dl>
-<dt><strong>xboard</strong>
-<dd>This command will be sent once immediately after your engine
-process is started. You can use it to put your engine into "xboard
-mode" if that is needed. If your engine prints a prompt to ask for
-user input, you must turn off the prompt and output a newline when the
-"xboard" command comes in.
-<p>
-
-<dt><font color=blue><strong>gui GUI_NAME VERSION.SUBVERSION</strong></font>
-<dd><font color=blue>
-This is a new feature. The GUI sending after the "xboard" command and before
-"protover N" string the command "gui <GUI_NAME> <VERSION>.<SUBVERSION>"
-to the engine. The GUI_NAME is a string. VERSION and SUBVERSION is <i><strong>one</strong></i>
-character.<br>
-This command will be send always. You don't need to answer because its only
-a information for the engine. I recommend that the engine not response.
-The idea behind this command is that the engine now know which special feature
-support the named GUI.<br>
-To make the GUI string clear the known GUIs will be predefined:<br>
-<br>
-gui arena = send by Arena<br>
-gui chessassistant = send by Chess Assistant<br>
-gui chessbase = send by ChessBase<br>
-gui chessmaster = send by ChessMaster<br>
-gui chesspartner = send by ChessPartner GUI<br>
-gui wb2uci = send by wb2uci adapter<br>
-gui xboard = send by Winboard/Xboard<br>
-<br>
-This list is not completely and will be extend in the future.<br>
-<br>
-Example:<br>
-Winboard / Xboard send:<br>
-xboard\n<br>
-gui xboard 4.2\n<br>
-protover 2\n<br>
-</font>
-<p>
-
-
-
-<dt><font color=red><strong>protover N</strong></font>
-<dd><font color=red>
-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
-the only new command that xboard always sends in version 2. All other
-new commands to the engine are sent only if the engine first enables
-them with the "feature" command. Protocol versions will always be
-simple integers so that they can easily be compared.
-
-<p>Your engine should reply to the protover command by sending the
-"feature" command (see below) with the list of non-default feature
-settings that you require, if any.
-
-<p>Your engine should never refuse to run due to receiving a higher
-protocol version number than it is expecting! New protocol versions
-will always be compatible with older ones by default; the larger
-version number is simply a hint that additional "feature" command
-options added in later protocol versions may be accepted.
-</font>
-<p>
-
-<dt><font color=red><strong>accepted</strong></font>
-<dt><font color=red><strong>rejected</strong></font>
-<dd><font color=red>
-These commands may be sent to your engine in reply to the "feature"
-command; see its documentation below.
-</font>
-<p>
-
-<dt><strong>new</strong>
-<dd>Reset the board to the standard chess starting position. Set
-White on move. Leave force mode and set the engine to play Black.
-Associate the engine's clock with Black and the opponent's clock with
-White. Reset clocks and time controls to the start of a new game.
-Stop clocks. Do not ponder on this move, even if pondering is on.
-Remove any search depth limit previously set by the sd command.
-<p>
-
-<dt><strong>variant VARNAME</strong>
-<dd>If the game is not standard chess, but a variant, this command is
-sent after "new" and before the first move or "edit" command. Currently
-defined variant names are:
-
-<table>
-<tr align="left"><th>wildcastle<td>Shuffle chess where king can castle from d file
-<tr align="left"><th>nocastle<td>Shuffle chess with no castling at all
-<tr align="left"><th>fischerandom<td>Fischer Random (not supported yet)
-<tr align="left"><th>bughouse<td>Bughouse, ICC/FICS rules
-<tr align="left"><th>crazyhouse<td>Crazyhouse, ICC/FICS rules
-<tr align="left"><th>losers<td>Win by losing all pieces or getting mated (ICC)
-<tr align="left"><th>suicide<td>Win by losing all pieces including king,
-or by having fewer pieces when one player has no legal moves (FICS)
-<tr align="left"><th><font color=red>giveaway</font>
-<td><font color=red>Win by losing all pieces including king,
-or by having no legal moves (ICC)</font>
-<tr align="left"><th>twokings<td>Weird ICC wild 9
-<tr align="left"><th>kriegspiel<td>Kriegspiel (engines not supported)
-<tr align="left"><th>atomic<td>Atomic
-<tr align="left"><th>3check<td>Win by giving check 3 times
-<tr align="left"><th>unknown<td>Unknown variant (not supported)
-</table>
-<p>
-
-<dt><strong>quit</strong>
-<dd>The chess engine should immediately exit. This command is used
-when xboard is itself exiting, and also between games if the -xreuse
-command line option is given (or -xreuse2 for the second engine).
-See also <a href="#7">Signals</a> above.
-<p>
-
-<dt><strong>random</strong>
-<dd>This command is specific to GNU Chess 4. You can either ignore it
-completely (that is, treat it as a no-op) or implement it as GNU Chess
-does. The command toggles "random" mode (that is, it sets random =
-!random). In random mode, the engine adds a small random value to its
-evaluation function to vary its play. The "new" command sets random
-mode off.
-<p>
-
-<dt><strong>force</strong>
-<dd>Set the engine to play neither color ("force mode"). Stop clocks.
-The engine should check that moves received in force mode are legal
-and made in the proper turn, but should not think, ponder, or make
-moves of its own.
-<p>
-
-<dt><strong>go</strong>
-<dd>Leave force mode and set the engine to play the color that is on
-move. Associate the engine's clock with the color that is on move,
-the opponent's clock with the color that is not on move. Start the engine's
-clock. Start thinking and eventually make a move.
-<p>
-
-<dt><font color=red><strong>playother</strong></font>
-<dd>
-<font color=red>
-(This command is new in protocol version 2. It is not
-sent unless you enable it with the feature command.)
-Leave force mode and set the engine to play the color that is <i>not</i> on
-move. Associate the opponent's clock with the color that is on move,
-the engine's clock with the color that is not on move. Start the opponent's
-clock. If pondering is enabled, the engine should begin pondering.
-If the engine later receives a move, it should start thinking and eventually
-reply.
-</font>
-<p>
-
-<dt><strong>white</strong>
-<dd>
-<font color=red>
-(This command is obsolete as of protocol version 2, but is still
-sent in some situations to accommodate older engines unless you disable it
-with the feature command.)
-</font>
-Set White on move. Set the engine to play Black. Stop clocks.
-<p>
-
-<dt><strong>black</strong>
-<dd>
-<font color=red>
-(This command is obsolete as of protocol version 2, but is still
-sent in some situations to accommodate older engines unless you disable it
-with the feature command.)
-</font>
-Set Black on move. Set the engine to play White. Stop clocks.
-<p>
-
-<dt><strong>level MPS BASE INC</strong>
-<dd>Set time controls. See the <a href="#11">Time Control</a> section below.
-<p>
-
-<dt><strong>st TIME</strong>
-<dd>Set time controls. See the <a href="#11">Time Control</a> section
-below. The commands "level" and "st" are not used together.
-<p>
-
-<dt><strong>sd DEPTH</strong>
-<dd>The engine should limit its thinking to DEPTH ply.
-<p>
-
-<dt><strong>time N</strong>
-<dd>Set a clock that always belongs to the engine. N is a number in
- centiseconds (units of 1/100 second). Even if the engine changes to
- playing the opposite color, this clock remains with the engine.
-<p>
-
-<dt><strong>otim N</strong>
-
-<dd>Set a clock that always belongs to the opponent. N is a number in
-centiseconds (units of 1/100 second). Even if the opponent changes to
-playing the opposite color, this clock remains with the opponent.
-<p>
-If needed for purposes of board display in force mode (where the
-engine is not participating in the game) the time clock should be
-associated with the last color that the engine was set to play, the
-otim clock with the opposite color.
-</p>
-
-<p>
-<font color=red>
-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.
-</font>
-The following techniques from older protocol versions also
-work: You can ignore the time and otim commands (that is, treat them
-as no-ops), or send back "Error (unknown command): time" the first
-time you see "time".
-</p>
-
-<dt><strong>MOVE</strong>
-<dd>See below for the syntax of moves. If the move is illegal, print
-an error message; see the section "<a href="#9">Commands from the engine to
-xboard</a>". If the move is legal and in turn, make it. If not in force
-mode, stop the opponent's clock, start the engine's clock, start
-thinking, and eventually make a move.
-<p>
-When xboard sends your engine a move, it normally sends coordinate
-algebraic notation. Examples:
-<p>
-<table>
-<tr align="left"><td>Normal moves:<td>e2e4
-<tr align="left"><td>Pawn promotion:<td>e7e8q
-<tr align="left"><td>Castling:<td>e1g1, e1c1, e8g8, e8c8
-<tr align="left"><td>Bughouse/crazyhouse drop:<td>P@h3
-<tr align="left"><td>ICS Wild 0/1 castling:<td>d1f1, d1b1, d8f8, d8b8
-<tr align="left"><td>FischerRandom castling:<td>O-O, O-O-O (oh, not zero)
-</table>
-
-<p>
-<font color=red>
-Beginning in protocol version 2, you can use the feature command
-to select SAN (standard algebraic notation) instead; for example, e4,
-Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form,
-P@h3, is a extension to the PGN standard's definition of SAN, which does
-not support bughouse or crazyhouse.
-</font>
-</p>
-
-<p>
-xboard doesn't reliably detect illegal moves, because it does not keep
-track of castling unavailability due to king or rook moves, or en
-passant availability. If xboard sends an illegal move, send back an
-error message so that xboard can retract it and inform the user; see
-the section "<a href="#9">Commands from the engine to xboard</a>".
-</p>
-
-<dt><font color=red><strong>usermove MOVE</strong></font>
-<dd><font color=red>
-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.
-Example: "usermove e2e4".
-</font>
-</p>
-
-<dt><strong>?</strong>
-<dd>Move now. If your engine is thinking, it should move immediately;
- otherwise, the command should be ignored (treated as a no-op). It
- is permissible for your engine to always ignore the ? command. The
- only bad consequence is that xboard's Move Now menu command will do
- nothing.
-<p>
-It is also permissible for your engine to move immediately if it gets
-any command while thinking, as long as it processes the command right
-after moving, but it's preferable if you don't do this. For example,
-xboard may send post, nopost, easy, hard, force, quit,
-<font color=red>
-or other commands
-</font>
-while the engine is on move.
-</p>
-
-<dt><font color=red><strong>ping N</strong></font>
-<dd>
-<font color=red>
-In this command, N is a decimal number. When you receive the command,
-reply by sending the string <strong>pong N</strong>, where N is the
-same number you received. Important: You must not reply to a "ping"
-command until you have finished executing all commands that you
-received before it. Pondering does not count; if you receive a ping
-while pondering, you should reply immediately and continue pondering.
-Because of the way xboard uses the ping command, if you implement the
-other commands in this protocol, you should never see a "ping" command
-when it is your move; however, if you do, you must not send the "pong"
-reply to xboard until after you send your move. For example, xboard
-may send "?" immediately followed by "ping". If you implement the "?"
-command, you will have moved by the time you see the subsequent ping
-command. Similarly, xboard may send a sequence like "force", "new",
-"ping". You must not send the pong response until after you have
-finished executing the "new" command and are ready for the new game to
-start.
-
-<p>
-The ping command is new in protocol version 2 and will not be sent
-unless you enable it with the "feature" command. Its purpose is to
-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.
-</p>
-</font>
-
-<dt><strong>draw</strong>
-<dd>The engine's opponent offers the engine a draw. To accept the
-draw, send "offer draw". To decline, ignore the offer (that is, send
-nothing). If you're playing on ICS, it's possible for the draw offer
-to have been withdrawn by the time you accept it, so don't assume the
-game is over because you accept a draw offer. Continue playing until
-xboard tells you the game is over. See also "offer draw" below.
-<p>
-
-<dt><strong>result RESULT {COMMENT}</strong>
-<dd>After the end of each game, xboard will send you a result command.
-You can use this command to trigger learning. RESULT is either 1-0,
-0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
-was a draw, or the game was unfinished. The COMMENT string is purely
-a human-readable comment; its content is unspecified and subject to
-change. In ICS mode, it is passed through from ICS uninterpreted.
-Example: <pre>result 1-0 {White mates}</pre>
-<p>
-Here are some notes on interpreting the "result" command. Some apply
-only to playing on ICS ("Zippy" mode).
-</p>
-
-<p>
-If you won but did not just play a mate, your opponent must have
-resigned or forfeited. If you lost but were not just mated, you
-probably forfeited on time, or perhaps the operator resigned manually.
-If there was a draw for some nonobvious reason, perhaps your opponent
-called your flag when he had insufficient mating material (or vice
-versa), or perhaps the operator agreed to a draw manually.
-</p>
-
-<p>
-You will get a result command even if you already know the game ended
--- for example, after you just checkmated your opponent. In fact, if
-you send the "RESULT {COMMENT}" command (discussed below), you will
-simply get the same thing fed back to you with "result" tacked in
-front. You might not always get a "result *" command, however. In
-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.
-</p>
-
-<dt><font color=red><strong>setboard FEN</strong></font>
-<dd><font color=red>
-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.
-
-<p><i>Illegal positions:</i> Note that either setboard or edit can
-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,
-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.</p>
-</font>
-<p>
-
-<dt><strong>edit</strong>
-<dd>
-<font color=red>
-The edit command is the old way to set up positions. For compatibility
-with old engines, it is still used by default, but new engines may prefer
-to use the feature command (see below) to cause xboard to use setboard instead.
-</font>
-The edit command puts the chess engine into a special mode, where
-it accepts the following subcommands:
-<table>
-<tr align="left"><th>c<td>change current piece color, initially white
-<tr align="left"><th>Pa4 (for example)<td>place pawn of current color on a4
-<tr align="left"><th>xa4 (for example)<td>empty the square a4 (not used by xboard)
-<tr align="left"><th>#<td>clear board
-<tr align="left"><th>.<td>leave edit mode
-</table>
-<font color=red>
-See the Idioms section below for additional subcommands used in
-ChessBase's implementation of the protocol.
-</font>
-
-<p>The edit command does not change the side to move. To set up a
-black-on-move position, xboard uses the following command sequence:
-</p>
-<pre>
- new
- force
- a2a3
- edit
- <edit commands>
- .
-</pre>
-
-<p>
-This sequence is used to avoid the "black" command, which is now
-considered obsolete and which many engines never did implement as
-specified in this document.
-</p>
-
-<p>
-After an edit command is complete, if a king and a rook are on their
-home squares, castling is assumed to be available to them. En passant
-capture is assumed to be illegal on the current move regardless of the
-positions of the pawns. The clock for the 50 move rule starts at
-zero, and for purposes of the draw by repetition rule, no prior
-positions are deemed to have occurred.
-</p>
-
-<dt><strong>hint</strong>
-<dd>If the user asks for a hint, xboard sends your engine the command
-"hint". Your engine should respond with "Hint: xxx", where xxx is a
-suggested move. If there is no move to suggest, you can ignore the
-hint command (that is, treat it as a no-op).
-<p>
-
-<dt><strong>bk</strong>
-<dd>If the user selects "Book" from the xboard menu, xboard will send
-your engine the command "bk". You can send any text you like as the
-response, as long as each line begins with a blank space or tab (\t)
-character, and you send an empty line at the end. The text pops up in
-a modal information dialog.
-<p>
-
-<dt><strong>undo</strong>
-<dd>If the user asks to back up one move, xboard will send you the
-"undo" command. xboard will not send this command without putting you
-in "force" mode first, so you don't have to worry about what should
-happen if the user asks to undo a move your engine made. (GNU Chess 4
-actually switches to playing the opposite color in this case.)
-<p>
-
-<dt><strong>remove</strong>
-<dd>If the user asks to retract a move, xboard will send you the
-"remove" command. It sends this command only when the user is on
-move. Your engine should undo the last two moves (one for each
-player) and continue playing the same color.
-<p>
-
-<dt><strong>hard</strong>
-<dd>Turn on pondering (thinking on the opponent's time, also known as
-"permanent brain"). xboard will not make any assumption about what
-your default is for pondering or whether "new" affects this setting.
-<p>
-
-<dt><strong>easy</strong>
-<dd>Turn off pondering.
-<p>
-
-<dt><strong>post</strong>
-<dd>Turn on thinking/pondering output.
-See <a href="#10">Thinking Output</a> section.
-<p>
-
-<dt><strong>nopost</strong>
-<dd>Turn off thinking/pondering output.
-<p>
-
-<dt><strong>analyze</strong>
-<dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.
-<p>
-
-<dt><strong>name X</strong> <dd>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.
-<font color=red>
-When the engine is
-playing locally against a human user, xboard obtains the user's login
-name from the local operating system. When the engine is playing
-locally against another engine, xboard uses either the other engine's
-filename or the name that the other engine supplied in the myname
-option to the feature command. By default, xboard uses the name
-command only when the engine is playing on a chess server. Beginning
-in protocol version 2, you can change this with the name option to the
-feature command; see below.
-</font>
-<p>
-
-<dt><strong>rating</strong>
-<dd>In ICS mode, xboard obtains the ICS opponent's rating from the
-"Creating:" message that appears before each game. (This message may
-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.
-<font color=red>
-In the future this command may also be used in other modes, if ratings
-are known.
-</font>
-Example: <pre>rating 2600 1500</pre>
-<p>
-
-<dt><font color=red><strong>ics HOSTNAME</strong></font>
-<dd><font color=red>
-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
-the "feature" command. Example: "ics freechess.org"
-</font>
-<p>
-
-<dt><strong>computer</strong>
-<dd>The opponent is also a computer chess engine. Some engines alter
-their playing style when they receive this command.
-<p>
-
-<dt><font color=red><strong>pause</strong></font>
-<dt><font color=red><strong>resume</strong></font>
-<dd><font color=red>(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.)
-The "pause" command puts the engine into a special state where it
-does not think, ponder, or otherwise consume significant CPU time.
-The current thinking or pondering (if any) is suspended and both
-player's clocks are stopped. The only command that the interface may
-send to the engine while it is in the paused state is "resume". The
-paused thinking or pondering (if any) resumes from exactly where it
-left off, and the clock of the player on move resumes running from
-where it stopped.
-</font>
-</dl>
-
-<h3>Bughouse commands:</h3>
-
-<p>
-xboard now supports bughouse engines when in Zippy mode. See
-<a href="http://www.tim-mann.org/xboard/zippy.README"
->zippy.README</a> 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.
-Commands to inform your engine of the partner's game state may
-be added in the future.
-</p>
-
-<dl>
-<dt><strong>partner <player></strong>
-<dd><player> is now your partner for future games. Example: <pre>partner mann</pre>
-<p>
-
-<dt><strong>partner</strong>
-<dd>Meaning: You no longer have a partner.
-<p>
-
-<dt><strong>ptell <text></strong>
-<dd>Your partner told you <text>, either with a ptell or an ordinary tell.
-<p>
-
-<dt><strong>holding [<white>] [<black>]</strong>
-<dd>White currently holds <white>; black currently holds <black>.
- Example: <pre>holding [PPPRQ] []</pre>
-
-<dt><strong>holding [<white>] [<black>] <color><piece></strong>
-<dd>White currently holds <white>; black currently holds <black>, after
- <color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre>
-</dl>
-
-<h2><a name="9">9. Commands from the engine to xboard</a></h2>
-
-<p>
-<font color=red>
-In general, an engine should not send any output to xboard that is not
-described in this document. As the protocol is extended, newer
-versions of xboard may recognize additional strings as commands that
-were previously not assigned a meaning.
-</font>
-</p>
-
-<dl>
-<dt><font color=red>
-<strong>feature FEATURE1=VALUE1 FEATURE2=VALUE2 ...</strong>
-</font>
-
-<dd><font color=red>
-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
-assigned. Features can take string, integer, or boolean values; the
-type of value is listed for each feature. String values are written
-in double quotes (for example, <tt>feature myname="Miracle Chess
-0.9"</tt>), integers are written in decimal, and boolean values are
-written as 0 for false, 1 for true. Any number of features can be set
-in one feature command, or multiple feature commands can be given.
-
-<p>
-Your engine should send one or more feature commands immediately after
-receiving the "protover" command, since xboard needs to know the
-values of some features before sending further commands to the engine.
-Because engines that predate protocol version 2 do not send "feature",
-xboard uses a timeout mechanism: when it first starts your engine, it
-sends "xboard" and "protover N", then listens for feature commands for
-two seconds before sending any other commands. To end this timeout
-and avoid the wait, set the feature "done=1" at the end of your last
-feature command. To increase the timeout, if needed, set the feature
-"done=0" before your first feature command and "done=1" at the end.
-If needed, it is okay for your engine to set done=0 soon as it starts,
-even before it receives the xboard and protover commands. This can be
-useful if your engine takes a long time to initialize itself. It
-should be harmless even if you are talking to a (version 1) user
-interface that does not understand the "feature" command, since such
-interfaces generally ignore commands from the engine that they do not
-understand.
-</p>
-
-<p>
-The feature command is designed to let the protocol change without
-breaking engines that were written for older protocol versions. When
-a new feature is added to the protocol, its default value is always
-chosen to be compatible with older versions of the protocol that did
-not have the feature. Any feature that your engine does not set in a
-"feature" command retains its default value, so as the protocol
-changes, you do not have to change your engine to keep up with it
-unless you want to take advantage of a new feature. Because some
-features are improvements to the protocol, while others are meant to
-cater to engines that do not implement all the protocol features, the
-recommended setting for a feature is not always the same as the
-default setting. The listing below gives both default and recommended
-settings for most features.
-</p>
-
-<p>
-You may want to code your engine so as to be able to work with
-multiple versions of the engine protocol. Protocol version 1 does not
-send the protover command and does not implement the feature command;
-if you send a feature command in protocol version 1, it will have no
-effect and there will be no response. In protocol version 2 or later,
-each feature F that you set generates the response "accepted F" if the
-feature is implemented, or "rejected F" if it is not. Thus an engine
-author can request any feature without having to keep track of which
-protocol version it was introduced in; you need only check whether the
-feature is accepted or rejected. This mechanism also makes it
-possible for a user interface author to implement a subset of a
-protocol version by rejecting some features that are defined in that
-version; however, you should realize that engine authors are likely to
-code for xboard and may not be prepared to have a feature that they
-depend on be rejected.
-</p>
-
-<p>
-Here are the features that are currently defined.
-</p>
-</font>
-
-<dl>
-<dt><font color=red>
-<strong>ping</strong> (boolean, default 0, recommended 1)
-</font>
-<dd><font color=red>
-If ping=1, xboard may use the protocol's new "ping" command;
-if ping=0, xboard will not use the command.
-</font>
-
-<dt><font color=red>
-<strong>setboard</strong> (boolean, default 0, recommended 1)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>playother</strong> (boolean, default 0, recommended 1)
-</font>
-<dd><font color=red>
-If playother=1, xboard will use the protocol's new "playother" command
-when appropriate; if playother=0, it will not use the command.
-</font>
-
-<dt><font color=red>
-<strong>san</strong> (boolean, default 0)
-</font>
-<dd><font color=red>
-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
-<a href="#8">section 8</a> above for more details of both kinds of notation.
-</font>
-
-<dt><font color=red>
-<strong>usermove</strong> (boolean, default 0)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>time</strong> (boolean, default 1, recommended 1)
-</font>
-<dd><font color=red>
-If time=1, xboard will send the "time" and "otim" commands to
-update the engine's clocks; if time=0, it will not.
-</font>
-
-<dt><font color=red>
-<strong>draw</strong> (boolean, default 1, recommended 1)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>sigint</strong> (boolean, default 1)
-</font>
-<dd><font color=red>
-If sigint=1, xboard may send SIGINT (the interrupt signal) to
-the engine as <a href="#7">section 7</a> above; if sigint=0, it will
-not.
-</font>
-
-<dt><font color=red>
-<strong>sigterm</strong> (boolean, default 1)
-</font>
-<dd><font color=red>
-If sigterm=1, xboard may send SIGTERM (the termination signal) to
-the engine as <a href="#7">section 7</a> above; if sigterm=0, it will
-not.
-</font>
-
-<dt><font color=red>
-<strong>reuse</strong> (boolean, default 1, recommended 1)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>analyze</strong> (boolean, default 1, recommended 1)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>myname</strong> (string, default determined from engine filename)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>variants</strong> (string, see text below)
-</font>
-<dd><font color=red>
-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 <a href="#8">section 8</a> above. If
-you do not set this feature, xboard will assume by default that your
-engine supports all variants. (However, the -zippyVariants
-command-line option still limits which variants will be accepted in
-Zippy mode.) It is recommended that you set this feature to the
-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.
-</font>
-
-<dt><font color=red>
-<strong>colors</strong> (boolean, default 1, recommended 0)
-</font>
-<dd><font color=red>
-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 "<a href="#13">Idioms</a>" section
-below for details. If colors=0, xboard does not use the "white" and
-"black" commands at all.
-</font>
-
-<dt><font color=red>
-<strong>ics</strong> (boolean, default 0)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>name</strong> (boolean, see text below)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>pause</strong> (boolean, default 0)
-</font>
-<dd><font color=red>
-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.
-</font>
-
-<dt><font color=red>
-<strong>done</strong> (integer, no default)
-</font>
-<dd><font color=red>
-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.
-</font>
-</dl>
-<p>
-
-<dt><strong>Illegal move: MOVE</strong>
-<dt><strong>Illegal move (REASON): MOVE</strong>
-<dd>If your engine receives a MOVE command that is recognizably a move
-but is not legal in the current position, your engine must print an
-error message in one of the above formats so that xboard can pass the
-error on to the user and retract the move. The (REASON) is entirely
-optional. Examples:
-
-<pre>
- Illegal move: e2e4
- Illegal move (in check): Nf3
- Illegal move (moving into check): e1g1
-</pre>
-<p>
-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.
-</p>
-
-<dt><strong>Error (ERRORTYPE): COMMAND</strong>
-<dd>If your engine receives a command it does not understand or does
-not implement, it should print an error message in the above format so
-that xboard can parse it. Examples:
-<pre>
- Error (ambiguous move): Nf3
- Error (unknown command): analyze
- Error (command not legal now): undo
- Error (too many parameters): level 1 2 3 4 5 6 7
-</pre>
-
-<dt><strong>move MOVE</strong>
-<dd>Your engine is making the move MOVE. Do not echo moves from
-xboard with this command; send only new moves made by the engine.
-
-<font color=red>
-<p>For the actual move text from your chess engine (in place of MOVE
-above), your move should be either
-<ul>
-<li>in coordinate notation (e.g.,
-e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,
-e1g1), or
-<li>in Standard Algebraic Notation (SAN) as defined in the
-Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),
-with the extension piece@square (e.g., P@f7) to handle piece placement
-in bughouse and crazyhouse.
-</ul>
-xboard itself also accepts some variants of SAN, but for compatibility
-with non-xboard interfaces, it is best not to rely on this behavior.
-</p>
-
-<p>Warning: Even though all versions of this protocol specification
-have indicated that xboard accepts SAN moves, some non-xboard
-interfaces are known to accept only coordinate notation. See the
-Idioms section for more information on the known limitations of some
-non-xboard interfaces. It should be safe to send SAN moves if you
-receive a "protover 2" (or later) command from the interface, but
-otherwise it is best to stick to coordinate notation for maximum
-compatibility. An even more conservative approach would be for your
-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
-"accepted san" in reply.
-</p>
-</font>
-
-<dt><strong>RESULT {COMMENT}</strong> <dd>When your engine detects
-that the game has ended by rule, your engine must output a line of the
-form "RESULT {comment}" (without the quotes), where RESULT is a PGN
-result code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Here
-"by rule" means that the game is definitely over because of what
-happened on the board. In normal chess, this includes checkmate,
-stalemate, triple repetition, the 50 move rule, or insufficient
-material; it does not include loss on time or the like.
-Examples:
-<pre>
- 0-1 {Black mates}
- 1-0 {White mates}
- 1/2-1/2 {Draw by repetition}
- 1/2-1/2 {Stalemate}
-</pre>
-
-<p>
-xboard relays the result to the user, the ICS, the other engine in Two
-Machines mode, and the PGN save file as required.
-</p>
-
-<dt><strong>resign</strong>
-<dd>If your engine wants to resign, it can send the command "resign".
-Alternatively, it can use the "RESULT {comment}" command if the string
-"resign" is included in the comment; for example "0-1 {White
-resigns}". xboard relays the resignation to the user, the ICS, the
-other engine in Two Machines mode, and the PGN save file as required.
-<p>
-
-<dt><strong>offer draw</strong>
-<dd>If your engine wants to offer a draw by agreement (as opposed to
-claiming a draw by rule), it can send the command "offer draw".
-xboard relays the offer to the user, the ICS, the other engine in Two
-Machines mode, and the PGN save file as required. In Machine White,
-Machine Black, or Two Machines mode, the offer is considered valid
-until your engine has made two more moves.
-<p>
-
-<dt><font color=red><strong>tellopponent MESSAGE</strong></font>
-<dd><font color=red>
-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
-playing against a user on the local machine, xboard pops up an
-information dialog containing the message. When the engine is playing
-against an opponent on the ICS (Zippy mode), xboard sends "say
-MESSAGE\n" to the ICS.
-<p>
-
-<dt><strong>tellothers MESSAGE</strong>
-<dd>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
-engine is playing against a user on the local machine, this command
-does nothing. When the engine is playing against an opponent on the
-ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
-<p>
-
-<dt><strong>tellall MESSAGE</strong>
-<dd>This command lets the engine give a message to its opponent and
-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
-playing against a user on the local machine, xboard pops up an
-information dialog containing the message. When the engine is playing
-against an opponent on the ICS (Zippy mode), xboard sends "kibitz
-MESSAGE\n" to the ICS.
-</font>
-<p>
-
-<dt><strong>telluser MESSAGE</strong>
-<dd>xboard pops up an information dialog containing the message.
-MESSAGE consists of any characters, including whitespace, to the end
-of the line.
-<p>
-
-<dt><strong>tellusererror MESSAGE</strong>
-<dd>xboard pops up an error dialog containing the message.
-MESSAGE consists of any characters, including whitespace, to the end
-of the line.
-<p>
-
-<dt><strong>askuser REPTAG MESSAGE</strong>
-<dd>Here REPTAG is a string containing no whitespace, and MESSAGE
-consists of any characters, including whitespace, to the end of the
-line. xboard pops up a question dialog that says MESSAGE and
-has a typein box. If the user types in "bar", xboard sends "REPTAG
-bar" to the engine. The user can cancel the dialog and send nothing.
-<p>
-
-<dt><strong>tellics MESSAGE</strong>
-<dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists
-of any characters, including whitespace, to the end of the line.
-<p>
-
-<dt><font color=red><strong>tellicsnoalias MESSAGE</strong></font>
-<dd><font color=red>
-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
-characters, including whitespace, to the end of the line.
-</font>
-</dl>
-<p>
-
-<h2><a name="10">10. Thinking Output</a></h2>
-
-<p>
-If the user asks your engine to "show thinking", xboard sends your
-engine the "post" command. It sends "nopost" to turn thinking off.
-In post mode, your engine sends output lines to show the progress of
-its thinking. The engine can send as many or few of these lines as it
-wants to, whenever it wants to. Typically they would be sent when the
-PV (principal variation) changes or the depth changes. The thinking
-output should be in the following format:
-</p>
-
-<pre>ply score time nodes pv</pre>
-
-Where:
-<table>
-<tr align="left"><th>ply<td>Integer giving current search depth.
-<tr align="left"><th>score<td>Integer giving current evaluation in centipawns.
-<tr align="left"><th>time<td>Current search time in centiseconds (ex:
-1028 = 10.28 seconds).
-
-<tr align="left"><th>nodes<td>Nodes searched.
-<tr align="left"><th>pv<td>Freeform text giving current "best" line.
-You can continue the pv onto another line if you start each
-continuation line with at least four space characters.
-</table>
-
-<p>
-Example:
-</p>
-
-<pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
-
-<p>
-Meaning:
-</p>
-
-9 ply, score=1.56, time = 10.84 seconds, nodes=48000,
-PV = "Nf3 Nc6 Nc3 Nf6"
-
-<p>
-Longer example from actual Crafty output:
-</p>
-<pre>
- 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
- 4 116 23 2252 1. Nf3 Nc6 2. e4 e6
- 4 116 27 2589 1. Nf3 Nc6 2. e4 e6
- 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4
- 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4
-</pre>
-
-<p>
-You can use the PV to show other things; for instance, while in book,
-Crafty shows the observed frequency of different reply moves in its
-book. In situations like this where your engine is not really
-searching, start the PV with a '(' character:
-</p>
-
-<pre>
- 0 0 0 0 (e4 64%, d4 24%)
-</pre>
-
-<p>
-GNU Chess output is very slightly different. The ply number is
-followed by an extra nonblank character, and the time is in seconds,
-not hundredths of seconds. For compatibility, xboard accepts the
-extra character and takes it as a flag indicating the different time
-units. Example:
-</p>
-
-<pre>
- 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
-</pre>
-
-<p>If your engine is pondering (thinking on its opponent's time) in post
-mode, it can show its thinking then too. In this case your engine may
-omit the hint move (the move it is assuming its opponent will make)
-from the thinking lines <em>if and only if</em> it sends xboard the move in
-the usual "Hint: xxx" format before sending the first line.
-</p>
-
-<h2><a name="11">11. Time control</a></h2>
-
-<p>
-xboard supports three styles of time control: conventional chess clocks,
-the ICS-style incremental clock, and an exact number of seconds per move.
-</p>
-
-<p>In conventional clock mode, every time control period is the same.
-That is, if the time control is 40 moves in 5 minutes, then after each
-side has made 40 moves, they each get an additional 5 minutes, and so
-on, ad infinitum. At some future time it would be nice to support a
-series of distinct time controls. This is very low on my personal
-priority list, but code donations to the xboard project are accepted,
-so feel free to take a swing at it. I suggest you talk to me first,
-though.
-</p>
-
-<p>
-The command to set a conventional time control looks like this:
-</p>
-
-<pre>
- level 40 5 0
- level 40 0:30 0
-</pre>
-
-<p>
-The 40 means that there are 40 moves per time control. The 5 means
-there are 5 minutes in the control. In the second example, the 0:30
-means there are 30 seconds. The final 0 means that we are in
-conventional clock mode.
-</p>
-
-<p>
-The command to set an incremental time control looks like this:
-</p>
-
-<pre>
- level 0 2 12
-</pre>
-
-<p>
-Here the 0 means "play the whole game in this time control period",
-the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As
-in conventional clock mode, the second argument to level can be in
-minutes and seconds.
-</p>
-
-<p>
-At the start of the game, each player's clock is set to base minutes.
-Immediately after a player makes a move, inc seconds are added to his
-clock. A player's clock counts down while it is his turn. Your flag
-can be called whenever your clock is zero or negative. (Your clock
-can go negative and then become positive again because of the
-increment.)
-</p>
-
-<p>
-A special rule on some ICS implementations: if you ask for a game with
-base=0, the clocks really start at 10 seconds instead of 0. xboard
-itself does not know about this rule, so it passes the 0 on to the
-engine instead of changing it to 0:10.
-</p>
-
-<p>
-ICS also has time odds games. With time odds, each player has his own
-(base, inc) pair, but otherwise things work the same as in normal
-games. The Zippy xboard accepts time odds games but ignores the fact
-that the opponent's parameters are different; this is perhaps not
-quite the right thing to do, but gnuchess doesn't understand time
-odds. Time odds games are always unrated.
-</p>
-
-<p>
-The command to set an exact number of seconds per move looks like this:
-</p>
-
-<pre>
- st 30
-</pre>
-
-<p>
-This means that each move must be made in at most 30 seconds. Time not used
-on one move does not accumulate for use on later moves.
-</p>
-
-<h2><a name="12">12. Analyze Mode</a></h2>
-
-<p>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.
-<font color=red>
-Beginning in protocol version 2,
-if your engine does not support analyze mode, it should use
-the feature command to set analyze=0.
-</font>
-The older method of
-printing the error message "Error (unknown command): analyze" in
-response to the "analyze" command will also work, however.
-</p>
-
-<p>
-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
-following commands while in analyze mode:
-</p>
-
-<ul>
-<li>Any legal move, as in force mode
-<li><strong>undo</strong> Back up one move and analyze previous position.
-<li><strong>new</strong> Reset position to start of game but stay in analyze mode.
-<li><font color=red><strong>setboard</strong> if you have set feature setboard=1; otherwise <strong>edit</strong>. Exiting edit mode returns to analyze mode.
-</font>
-<li><strong>exit</strong> Leave analyze mode.
-<li><strong>.</strong> Send a search status update (optional); see below.
-<li><font color=red>
-<strong>bk</strong> Show book moves from this position,
-if any; see above.</font>
-<li><font color=red>
-<strong>hint</strong> Show the predicted move from this
-position, if any; see above.</font>
-</ul>
-
-<p>
-If the user selects "Periodic Updates", xboard will send the string
-".\n" to the chess engine periodically during analyze mode, unless the
-last PV received began with a '(' character.
-</p>
-
-<p>
-The chess engine should respond to ".\n" with a line like this:
-</p>
-
-<pre>
-stat01: time nodes ply mvleft mvtot <font color=red>mvname</font>
-</pre>
-
-Where:
-<table>
-<tr align="left"><th>time<td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).
-<tr align="left"><th>nodes<td>Nodes searched so far.
-<tr align="left"><th>ply<td>Search depth so far.
-<tr align="left"><th>mvleft<td>Number of moves left to consider at this depth.
-<tr align="left"><th>mvtot<td>Total number of moves to consider.
-<tr align="left"><th><font color=red>mvname</font><td><font color=red>
-Move currently being considered (SAN or coordinate notation). Optional;
-added in protocol version 2.</font>
-</table>
-
-<p>
-Examples:
-</p>
-<pre>
- stat01: 1234 30000 7 5 30
- stat01: 1234 30000 7 5 30 Nf3
-</pre>
-
-<p>
-Meaning:
-</p>
-
-<p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
- total of 30 legal moves, and I have 5 more moves to search
- before going to depth 8. In the second example, of the 30 legal
- moves, the one I am currently searching is Nf3.</p>
-
-<p>
-Implementation of the "." command is optional. If the engine does not
-respond to the "." command with a "stat01..." line, xboard will stop
-sending "." commands. If the engine does not implement this command,
-the analysis window will use a shortened format to display the engine
-info.
-</p>
-
-<p>
-To give the user some extra information, the chess engine can output
-the strings "++\n" and "--\n", to indicate that the current search is
-failing high or low, respectively. You don't have to send anything
-else to say "Okay, I'm not failing high/low anymore." xboard will
-figure this out itself.
-</p>
-
-<h2><a name="13">13. Idioms and backward compatibility features</a></h2>
-
-<p>
-Some engines have variant interpretations of the force/go/white/black,
-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
-have historically been particularly troublesome, and it is recommended
-that new engines set the feature colors=0 and/or ignore the commands.
-</p>
-
-<dl>
-
-<dt><strong>time N</strong>
-<dt><strong>otim N</strong>
-<dt><strong>MOVE</strong>
-<dd>Sent when the opponent makes a move and the engine is already
-playing the opposite color.
-<p>
-
-<dt><strong>white</strong>
-<dt><strong>go</strong>
-<dd>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.
-<font color=red>
-If you set the feature colors=0, "white" is not sent.
-</font>
-<p>
-
-<dt><strong>black</strong>
-<dt><strong>go</strong>
-<dd>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.
-<font color=red>
-If you set the feature colors=0, "black" is not sent.
-</font>
-<p>
-
-<dt><strong>white</strong>
-<dt><strong>time N</strong>
-<dt><strong>otim N</strong>
-<dt><strong>black</strong>
-<dt><strong>go</strong>
-<dd>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.
-The initial "white" is a kludge to accommodate GNU Chess
-4's variant interpretation of these commands.
-<font color=red>
-If you set the feature colors=0, "white" and "black" are not sent.
-</font>
-<p>
-
-<dt><strong>black</strong>
-<dt><strong>time N</strong>
-<dt><strong>otim N</strong>
-<dt><strong>white</strong>
-<dt><strong>go</strong>
-<dd>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.
-The initial "black" is a kludge to accommodate GNU Chess
-4's variant interpretation of these commands.
-<font color=red>
-If you set the feature colors=0, "black" and "white" are not sent.
-</font>
-<p>
-
-<dt><strong>hard</strong>
-<dt><strong>easy</strong>
-<dd>Sent in sequence to turn off pondering if xboard is not sure
-whether it is on. When xboard is sure, it will send "hard" or "easy"
-alone. xboard does this because "easy" is a toggle in GNU Chess 4 but
-"hard" is an absolute on.
-
-</dl>
-
-<p>
-To support older engines, certain additional commands from the engine
-to xboard are also recognized. (These are commands by themselves, not
-values to be placed in the comment field of the PGN result code.)
-These forms are not recommended for new engines; use the PGN result
-code commands or the resign command instead.
-</p>
-
-<table>
-<tr align="left"><th>Command <th>Interpreted as
-<tr align="left"><td>White resigns <td>0-1 {White resigns}
-<tr align="left"><td>Black resigns <td>1-0 {Black resigns}
-<tr align="left"><td>White <td>1-0 {White mates}
-<tr align="left"><td>Black <td>0-1 {Black mates}
-<tr align="left"><td>Draw <td>1/2-1/2 {Draw}
-<tr align="left"><td>computer mates <td>1-0 {White mates} or 0-1 {Black mates}
-<tr align="left"><td>opponent mates <td>1-0 {White mates} or 0-1 {Black mates}
-<tr align="left"><td>computer resigns <td>0-1 {White resigns} or 1-0 {Black resigns}
-<tr align="left"><td>game is a draw <td>1/2-1/2 {Draw}
-<tr align="left"><td>checkmate <td>1-0 {White mates} or 0-1 {Black mates}
-</table>
-
-<p>
-Commands in the above table are recognized if they begin a line and
-arbitrary characters follow, so (for example) "White mates" will be
-recognized as "White", and "game is a draw by the 50 move rule" will
-be recognized as "game is a draw". All the commands are
-case-sensitive.
-</p>
-
-<p>
-An alternative move syntax is also recognized:
-</p>
-
-<table>
-<tr align="left"><th>Command <th>Interpreted as
-<tr align="left"><td>NUMBER ... MOVE <td>move MOVE
-</table>
-
-<p>
-Here NUMBER means any string of decimal digits, optionally ending in a
-period. MOVE is any string containing no whitespace. In this command
-format, xboard requires the "..." even if your engine is playing
-White. A command of the form NUMBER MOVE will be ignored. This odd
-treatment of the commands is needed for compatibility with gnuchessx.
-The original reasons for it are lost in the mists of time, but I
-suspect it was originally a bug in the earliest versions of xboard,
-before I started working on it, which someone "fixed" in the wrong
-way, by creating a special version of gnuchess (gnuchessx) instead of
-changing xboard.
-</p>
-
-<p>
-Any line that contains the words "offer" and "draw" is recognized as
-"offer draw".
-</p>
-
-<p>
-The "Illegal move" message is recognized even if spelled "illegal
-move" and even if the colon (":") is omitted. This accommodates GNU
-Chess 4, which prints messages like "Illegal move (no matching
-move)e2e4", and old versions of Crafty, which print just "illegal move".
-</p>
-
-<p>
-In Zippy mode, for compatibility with older versions of Crafty,
-xboard passes through to ICS any line that begins "kibitz", "whisper",
-"tell", or "draw". Do not use this feature in new code. Instead, use the
-commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),
-"1/2-1/2 {COMMENT}", or "offer draw", as appropriate.
-</p>
-
-<p>
-<font color=red>
-If the engine responds to the "sd DEPTH" command with an error message
-indicating the command is not supported (such as "Illegal move: sd"),
-xboard sets an internal flag and subsequently uses the command
-"depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the
-newline in the middle of this command! New engines should not rely on
-this feature.
-</font>
-</p>
-
-<p>
-<font color=red>
-If the engine responds to the "st TIME" command with an error message
-indicating the command is not supported (such as "Illegal move: st"),
-xboard sets an internal flag and subsequently uses the command "level
-1 TIME" instead, for the benefit of GNU Chess 4. Note that this is
-not a standard use of the level command, as TIME seconds are not added
-after each player makes 1 move; rather, each move is made in at most
-TIME seconds. New engines should not implement or rely on this
-feature.
-</font>
-</p>
-
-<font color=red>
-<p>
-In support of the -firstHost/-secondHost features, which allow a chess
-engine to be run on another machine using the rsh protocol, xboard recognizes
-error messages that are likely to come from rsh as fatal errors. The following
-messages are currently recognized:
-</p>
-
-<blockquote>
-unknown host<br>
-No remote directory<br>
-not found<br>
-No such file<br>
-can't alloc<br>
-Permission denied<br>
-</blockquote>
-</font>
-
-<p>
-<font color=red>
-ChessBase/Fritz now implements the xboard/winboard protocol and can use
-WinBoard-compatible engines in its GUI. ChessBase's version of the
-protocol is generally the same as version 1, except that they have
-added the commands <strong>fritz</strong>, <strong>reset</strong>, and
-<strong>ponder</strong>, and the edit subcommands
-<strong>castle</strong> and <strong>ep</strong>. If you want your
-engine to work well with the ChessBase/Fritz GUI, you may need to
-implement these additional commands, and you should also be aware of
-the peculiar way that ChessBase uses the protocol. See their <a
-href="http://www.chessbase.com/Products/engines/winboard/tech.htm"
->web page</a> for documentation.
-</font>
-</p>
-
-<p>
-<font color=red>
-ChessMaster 8000 also implements version 1 of the xboard/winboard
-protocol and can use WinBoard-compatible engines. The original
-release of CM8000 also has one additional restriction: only pure
-coordinate notation (e.g., e2e4) is accepted in the move command. A
-patch to correct this should be available from The Learning Company
-(makers of CM8000) in February 2001.
-</font>
-</p>
-
-<hr noshade size="2">
-<address>converted to HTML by <a href="http://www.jakob.at/steffen/">Steffen A. Jakob</a></address>
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"\r
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">\r
+<head>\r
+<title>Chess Engine Communication Protocol</title>\r
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />\r
+<style type="text/css">\r
+ .header { \r
+ border-top:2px solid black;\r
+ border-bottom:2px solid black;\r
+ }\r
+ .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
+ dt { font-weight:bold;}\r
+\r
+ </style>\r
+\r
+</head>\r
+\r
+<body>\r
+<div class="header">\r
+<h1>Chess Engine Communication Protocol</h1>\r
+<h2><a href="http://www.tim-mann.org/">Tim Mann</a> & <a href="http://home.hccnet.nl/h.g.muller/winboardF.html">H.G.Muller</a></h2>\r
+<p>\r
+Version 2; implemented in xboard/WinBoard 4.2.1 and later. (Sept 3, 2009)<br />\r
+Changes since version 1 are indicated in <span class="version1">red</span>.<br />\r
+Changes for WinBoard 4.3.xx are indicated in <span class="version43">green</span>.<br />\r
+Changes for WinBoard 4.4.xx are indicated in <span class="version44">blue</span>.\r
+</p>\r
+</div>\r
+\r
+<ul>\r
+<li><a href="#1">1. Introduction</a></li>\r
+<li><a href="#2">2. Connection</a></li>\r
+<li><a href="#3">3. Debugging</a></li>\r
+<li><a href="#4">4. How it got this way</a></li>\r
+<li><a href="#5">5. WinBoard requires Win32 engines</a></li>\r
+<li><a href="#6">6. Hints on input/output</a></li>\r
+<li><a href="#7">7. Signals</a></li>\r
+<li><a href="#8">8. Commands from xboard to the engine</a></li>\r
+<li><a href="#9">9. Commands from the engine to xboard</a></li>\r
+<li><a href="#10">10. Thinking Output</a></li>\r
+<li><a href="#11">11. Time control</a></li>\r
+<li><a href="#12">12. Analyze Mode</a></li>\r
+<li><a href="#13">13. Idioms and backward compatibility features</a></li>\r
+</ul>\r
+\r
+<hr />\r
+\r
+<h2><a name="1">1. Introduction</a></h2>\r
+\r
+<p>\r
+This document is a set of rough notes on the protocol that xboard and\r
+WinBoard use to communicate with gnuchessx and other chess engines.\r
+These notes may be useful if you want to connect a different chess\r
+engine to xboard. Throughout the notes, "xboard" means both xboard\r
+and WinBoard except where they are specifically contrasted.\r
+</p>\r
+\r
+<p>\r
+There are two reasons I can imagine someone wanting to do this: \r
+</p>\r
+\r
+<ol>\r
+<li>You have, or are developing, a chess engine but you don't want to\r
+write your own graphical interface. </li>\r
+<li>You have, or are developing,a chess engine, and you want to\r
+interface it to the Internet Chess Server.</li>\r
+</ol>\r
+\r
+<p>\r
+In case (2), if you are using xboard, you will need to configure the\r
+"Zippy" code into it, but WinBoard includes this code already. See\r
+the file <a\r
+href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>\r
+in the xboard or WinBoard distribution for more information.\r
+</p>\r
+\r
+<p>\r
+These notes are unpolished, but I've attempted to make them complete\r
+in this release. If you notice any errors, omissions, or misleading\r
+statements, let me know.\r
+</p>\r
+\r
+<p>\r
+I'd like to hear from everyone who is trying to interface their own\r
+chess engine to xboard/WinBoard. Please join the mailing list for \r
+authors of xboard/WinBoard compatible chess engines and post a message \r
+about what you're doing. The list is now hosted by Yahoo Groups; you \r
+can join at <a href="http://groups.yahoo.com/group/chess-engines" \r
+>http://groups.yahoo.com/group/chess-engines</a>, or you can read the\r
+list there without joining. The list is filtered to prevent spam.\r
+</p>\r
+\r
+<p class="version43">\r
+Note that the WinBoard 4.3.xx line was developed independently of the\r
+original GNU project, by H.G.Muller.\r
+If you have questions about WinBoard 4.3.xx, or want to report bugs in it,\r
+report them in the appropriate section of the \r
+<a href="http://www.open-aurec.com/wbforum/">WinBoard forum</a>.\r
+</p>\r
+\r
+<h2><a name="2">2. Connection</a></h2>\r
+\r
+<p>\r
+An xboard chess engine runs as a separate process from xboard itself,\r
+connected to xboard through a pair of anonymous pipes. The engine\r
+does not have to do anything special to set up these pipes. xboard\r
+sets up the pipes itself and starts the engine with one pipe as its\r
+standard input and the other as its standard output. The engine then\r
+reads commands from its standard input and writes responses to its\r
+standard output. This is, unfortunately, a little more complicated to\r
+do right than it sounds; see <a href="#6">section 6</a> below.\r
+</p>\r
+\r
+<p>\r
+And yes, contrary to some people's expectations, exactly the same\r
+thing is true for WinBoard. Pipes and standard input/output are\r
+implemented in Win32 and work fine. You don't have to use DDE, COM,\r
+DLLs, BSOD, or any of the other infinite complexity that\r
+Microsoft has created just to talk between two programs. A WinBoard\r
+chess engine is a Win32 console program that simply reads from its\r
+standard input and writes to its standard output. See sections \r
+<a href="#5">5</a> and <a href="#6">6</a> below for additional details.\r
+</p>\r
+\r
+<h2><a name="3">3. Debugging</a></h2>\r
+\r
+<p>\r
+To diagnose problems in your engine's interaction with xboard, use the\r
+-debug flag on xboard's command line to see the messages that are\r
+being exchanged. In WinBoard, these messages are written to the file\r
+WinBoard.debug instead of going to the screen.\r
+</p>\r
+\r
+<p>\r
+You can turn debug mode on or off while WinBoard is running by\r
+pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard\r
+is running by binding DebugProc to a shortcut key (and pressing the\r
+key!); see the instructions on shortcut keys in the xboard man page.\r
+</p>\r
+\r
+<p>\r
+While your engine is running under xboard/WinBoard, you can send a\r
+command directly to the engine by pressing Shift+1 (xboard) or Alt+1\r
+(WinBoard 4.0.3 and later). This brings up a dialog that you can type\r
+your command into. Press Shift+2 (Alt+2) instead to send to the\r
+second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier,\r
+Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict\r
+with typing the @-sign on some European keyboards.\r
+</p>\r
+\r
+<h2><a name="4">4. How it got this way</a></h2>\r
+\r
+<p>\r
+Originally, xboard was just trying to talk to the existing\r
+command-line interface of GNU Chess 3.1+ and 4, which was designed\r
+for people to type commands to. So the communication protocol is very\r
+ad-hoc. It might have been good to redesign it early on, but because\r
+xboard and GNU Chess are separate programs, I didn't want to force\r
+people to upgrade them together to versions that matched. I\r
+particularly wanted to keep new versions of xboard working with old\r
+versions of GNU Chess, to make it easier to compare the play of old\r
+and new gnuchess versions. I didn't foresee the need for a clean\r
+protocol to be used with other chess engines in the future.\r
+</p>\r
+\r
+<p>\r
+Circumstances have changed over the years, and now there are many more\r
+engines that work with xboard. I've had to make the protocol\r
+description more precise, I've added some features that GNU Chess\r
+does not support, and I've specified the standard semantics of a few\r
+features to be slightly different from what GNU Chess 4 does.\r
+</p>\r
+\r
+<p class="version1">\r
+This release of the protocol specification is the first to carry a\r
+version number of its own -- version 2. Previous releases simply\r
+carried a last-modified date and were loosely tied to specific \r
+releases of xboard and WinBoard. The version number "1" applies\r
+generally to all those older versions of the protocol.\r
+</p>\r
+\r
+<p class="version1">\r
+Protocol version 2 remains compatible with older engines but has\r
+several new capabilities. In particular, it adds the \r
+"feature" command, a new mechanism for making backward-compatible\r
+changes and extensions to the protocol. Engines that do not support a\r
+particular new feature do not have to use it; new features are not\r
+enabled unless the engine specifically requests them using the feature\r
+command. If an engine does not send the feature command at all, the\r
+protocol behavior is nearly identical to version 1. Several new\r
+features can be selected by the feature command in version 2,\r
+including the "ping" command (recommended for all engines), the\r
+"setboard" command, and many optional parameters. Additional features\r
+will probably be added in future versions.\r
+</p>\r
+\r
+<p class="version43">\r
+If it is necessary to have a separate name, \r
+it would be best to refer to the protocol including the green additions as version 2f.\r
+I really don't think it is a different protocol from version 2, though.\r
+I just tried to clarify some ambiguities in the original definition,\r
+now that the WinBoard 4.3.xx line has implemented them in a specific way.\r
+The hand-shaking protocol for features as defined in protocol 2 perfectly\r
+allows addition of an occasional new features without any need for stepping up the protocol version number,\r
+and I think refraining from the latter would enormously lower the barrier for actual\r
+implementation of these features in engines.\r
+<br />\r
+The two really new things are the engine debug comments, and the "nps" command.\r
+The former merely tries to regulate an extremely common existing pactice \r
+of having engines dump debug messages on WinBoard in an unprotected way, \r
+as usually you get away with that.\r
+</p>\r
+\r
+<h2><a name="5">5. WinBoard requires Win32 engines</a></h2>\r
+\r
+<p>\r
+Due to some Microsoft brain damage that I don't understand, WinBoard\r
+does not work with chess engines that were compiled to use a DOS\r
+extender for 32-bit addressing. (Probably not with 16-bit DOS or\r
+Windows programs either.) WinBoard works only with engines that are\r
+compiled for the Win32 API. You can get a free compiler that targets\r
+the Win32 API from <a href="http://sources.redhat.com/cygwin/"\r
+>http://sources.redhat.com/cygwin/</a>. I think DJGPP 2.x should also\r
+work if you use the RSXNTDJ extension, but I haven't tried it. Of\r
+course, Microsoft Visual C++ will work. Most likely the other\r
+commercial products that support Win32 will work too (Borland, etc.),\r
+but I have not tried them. Delphi has been successfully used to write\r
+engines for WinBoard; if you want to do this, Tony Werten has donated\r
+some <a href="http://www.tim-mann.org/winboard/delphi.txt" >sample\r
+code</a> that should help you get started.\r
+</p>\r
+\r
+<h2><a name="6">6. Hints on input/output</a></h2>\r
+\r
+<p>\r
+Beware of using buffered I/O in your chess engine. The C stdio\r
+library, C++ streams, and the I/O packages in most other languages use\r
+buffering both on input and output. That means two things. First,\r
+when your engine tries to write some characters to xboard, the library\r
+stashes them in an internal buffer and does not actually write them to\r
+the pipe connected to xboard until either the buffer fills up or you\r
+call a special library routine asking for it to be flushed. (In C\r
+stdio, this routine is named <tt>fflush</tt>.) Second, when your engine tries\r
+to read some characters from xboard, the library does not read just\r
+the characters you asked for -- it reads all the characters that are\r
+currently available (up to some limit) and stashes any characters you\r
+are not yet ready for in an internal buffer. The next time you ask to\r
+read, you get the characters from the buffer (if any) before the\r
+library tries to read more data from the actual pipe.\r
+</p>\r
+\r
+<p>\r
+Why does this cause problems? First, on the output side, remember\r
+that your engine produces output in small quantities (say, a few\r
+characters for a move, or a line or two giving the current analysis),\r
+and that data always needs to be delivered to xboard/WinBoard for\r
+display immediately. If you use buffered output, the data you print\r
+will sit in a buffer in your own address space instead of being\r
+delivered.\r
+</p>\r
+\r
+<p>\r
+You can usually fix the output buffering problem by asking for the\r
+buffering to be turned off. In C stdio, you do this by calling\r
+<tt>setbuf(stdout, NULL)</tt>. A more laborious and error-prone\r
+method is to carefully call <tt>fflush(stdout)</tt> after every line\r
+you output; I don't recommend this. In C++, you can try\r
+<tt>cout.setf(ios::unitbuf)</tt>, which is documented in current\r
+editions of "The C++ Programming Language," but not older ones.\r
+Another C++ method that might work is\r
+<tt>cout.rdbuf()->setbuf(NULL, 0)</tt>. Alternatively, you can\r
+carefully call <tt>cout.flush()</tt> after every line you output;\r
+again, I don't recommend this.\r
+</p>\r
+\r
+<p>\r
+Another way to fix the problem is to use unbuffered operating system\r
+calls to write directly to the file descriptor for standard output.\r
+On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).\r
+On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32\r
+native routines like <tt>WriteFile</tt>.\r
+</p>\r
+\r
+<p>\r
+Second, on the input side, you are likely to want to poll during your\r
+search and stop it if new input has come in. If you implement\r
+pondering, you'll need this so that pondering stops when the user\r
+makes a move. You should also poll during normal thinking on your\r
+move, so that you can implement the "?" (move now) command, and so\r
+that you can respond promptly to a "result", "force", or "quit"\r
+command if xboard wants to end the game or terminate your engine.\r
+Buffered input makes polling more complicated -- when you poll, you\r
+must stop your search if there are <em>either</em> characters in the buffer\r
+<em>or</em> characters available from the underlying file descriptor.\r
+</p>\r
+\r
+<p>\r
+The most direct way to fix this problem is to use unbuffered operating\r
+system calls to read (and poll) the underlying file descriptor\r
+directly. On Unix, use <tt>read(0, ...)</tt> to read from standard input, and\r
+use <tt>select()</tt> to poll it. See the man pages read(2) and select(2).\r
+(Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to\r
+poll for input. It is not very portable; that is, it does not exist\r
+on all versions of Unix, and is broken on some that do have it.) On\r
+Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native\r
+Win32 <tt>ReadFile()</tt> to read. Unfortunately, under Win32, the function to\r
+use for polling is different depending on whether the input device is\r
+a pipe, a console, or something else. (More Microsoft brain damage\r
+here -- did they never hear of device independence?) For pipes, you\r
+can use <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).\r
+For consoles, \r
+you can use <tt>GetNumberOfConsoleInputEvents</tt>. For sockets only, you can\r
+use <tt>select()</tt>. It might be possible to use\r
+<tt>WaitForSingleObject</tt> more \r
+generally, but I have not tried it. Some code to do these things can\r
+be found in Crafty's utility.c, but I don't guarantee that it's all\r
+correct or optimal.\r
+</p>\r
+\r
+<p>\r
+A second way to fix the problem might be to ask your I/O library not\r
+to buffer on input. It should then be safe to poll the underlying\r
+file descriptor as described above. With C, you can try calling\r
+<tt>setbuf(stdin, NULL)</tt>. However, I have never tried this. Also, there\r
+could be problems if you use <tt>scanf()</tt>, at least with certain patterns,\r
+because <tt>scanf()</tt> sometimes needs to read one extra character and "push\r
+it back" into the buffer; hence, there is a one-character pushback\r
+buffer even if you asked for stdio to be unbuffered. With C++, you\r
+can try <tt>cin.rdbuf()->setbuf(NULL, 0)</tt>, but again, I have never tried\r
+this.\r
+</p>\r
+\r
+<p>\r
+A third way to fix the problem is to check whether there are\r
+characters in the buffer whenever you poll. C I/O libraries generally\r
+do not provide any portable way to do this. Under C++, you can use\r
+<tt>cin.rdbuf()->in_avail()</tt>. This method has been reported to\r
+work with \r
+EXchess. Remember that if there are no characters in the buffer, you\r
+still have to poll the underlying file descriptor too, using the\r
+method described above.\r
+</p>\r
+\r
+<p>\r
+A fourth way to fix the problem is to use a separate thread to read\r
+from stdin. This way works well if you are familiar with thread\r
+programming. This thread can be blocked waiting for input to come in\r
+at all times, while the main thread of your engine does its thinking.\r
+When input arrives, you have the thread put the input into a buffer\r
+and set a flag in a global variable. Your search routine then\r
+periodically tests the global variable to see if there is input to\r
+process, and stops if there is. WinBoard and my Win32 ports of ICC\r
+timestamp and FICS timeseal use threads to handle multiple input\r
+sources.\r
+</p>\r
+\r
+<h2><a name="7">7. Signals</a></h2>\r
+\r
+<p>Engines that run on Unix need to be concerned with two Unix\r
+signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>. This applies both to\r
+engines that run under xboard and (the unusual case of) engines that\r
+WinBoard remotely runs on a Unix host using the -firstHost or\r
+-secondHost feature. It does not apply to engines that run on\r
+Windows, because Windows does not have Unix-style signals.\r
+<span class="version1">\r
+Beginning with version 2, you can now turn off the use of\r
+either or both\r
+signals. See the "feature" command in <a href="#6">section 9</a> below.\r
+</span>\r
+</p>\r
+\r
+<p>First, when an engine is sent the "quit" command, it is also given\r
+a <tt>SIGTERM</tt> signal shortly afterward to make sure it goes away.\r
+If your engine reliably responds to "quit", and the signal causes\r
+problems for you, you should either ignore it by calling\r
+<tt>signal(SIGTERM, SIG_IGN)</tt> at the start of your program,\r
+or disable it with the "feature" command.</p>\r
+\r
+<p>Second, xboard will send an interrupt signal (<tt>SIGINT</tt>) at\r
+certain times when it believes the engine may not be listening to user\r
+input (thinking or pondering). WinBoard currently does this only when\r
+the engine is running remotely using the -firstHost or -secondHost\r
+feature, not when it is running locally. You probably need to know\r
+only enough about this grungy feature to keep it from getting in your\r
+way.\r
+</p>\r
+\r
+<p>\r
+The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess 4\r
+on systems where its input polling code is broken or disabled.\r
+Because they work in a rather peculiar way, it is recommended that you\r
+either ignore <tt>SIGINT</tt> by having your engine call\r
+<tt>signal(SIGINT, SIG_IGN)</tt>, or disable it with the "feature"\r
+command.</p>\r
+\r
+<p>\r
+Here are details for the curious. If xboard needs to send a command\r
+when it is the chess engine's move (such as before the "?" command), \r
+it sends a <tt>SIGINT</tt> first. If xboard needs to send commands when it is\r
+not the chess engine's move, but the chess engine may be pondering\r
+(thinking on its opponent's time) or analyzing (analysis or analyze\r
+file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.\r
+Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard\r
+issues more commands. This behavior is necessary for GNU Chess 4. The\r
+first <tt>SIGINT</tt> stops it from pondering until the next move, but on some\r
+systems, GNU Chess 4 will die if it receives a <tt>SIGINT</tt> when not \r
+actually thinking or pondering.\r
+</p>\r
+\r
+<p>\r
+There are two reasons why WinBoard does not send the Win32 equivalent\r
+of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local\r
+engines. First, the Win32 GNU Chess 4 port does not need it. Second, I\r
+could not find a way to get it to work. Win32 seems to be designed\r
+under the assumption that only console applications, not windowed\r
+applications, would ever want to send a <tt>CTRL_C_EVENT</tt>.\r
+</p>\r
+\r
+<h2><a name="8">8. Commands from xboard to the engine</a></h2>\r
+\r
+<p>\r
+All commands from xboard to the engine end with a newline (\n), even\r
+where that is not explicitly stated. All your output to xboard must\r
+be in complete lines; any form of prompt or partial line will cause\r
+problems.\r
+</p>\r
+\r
+<p>\r
+At the beginning of each game, xboard sends an initialization string.\r
+This is currently "new\nrandom\n" unless the user changes it with the\r
+initString or secondInitString option.\r
+</p>\r
+\r
+<p>\r
+xboard normally reuses the same chess engine process for multiple\r
+games. At the end of a game, xboard will send the "force" command\r
+(see below) to make sure your engine stops thinking about the current\r
+position. It will later send the initString again to start a new\r
+game. If your engine can't play multiple games, you can disable reuse\r
+<span class="version1">\r
+either with the "feature" command (beginning in protocol version\r
+2; see below) or \r
+</span>\r
+with xboard's -xreuse (or -xreuse2) command line\r
+option. xboard will then ask the process to quit after each game and\r
+start a new process for the next game.\r
+</p>\r
+\r
+<dl>\r
+<dt>xboard</dt>\r
+<dd>This command will be sent once immediately after your engine\r
+process is started. You can use it to put your engine into "xboard\r
+mode" if that is needed. If your engine prints a prompt to ask for\r
+user input, you must turn off the prompt and output a newline when the\r
+"xboard" command comes in.\r
+</dd>\r
+\r
+<dt class="version1">protover N</dt>\r
+<dd class="version1">\r
+<p>Beginning in protocol version 2 (in which N=2), this command will\r
+be sent immediately after the "xboard" command. If you receive some\r
+other command immediately after "xboard" (such as "new"), you can\r
+assume that protocol version 1 is in use. The "protover" command is\r
+the only new command that xboard always sends in version 2. All other\r
+new commands to the engine are sent only if the engine first enables\r
+them with the "feature" command. Protocol versions will always be\r
+simple integers so that they can easily be compared.\r
+</p>\r
+\r
+<p>Your engine should reply to the protover command by sending the\r
+"feature" command (see below) with the list of non-default feature\r
+settings that you require, if any.</p>\r
+\r
+<p>Your engine should never refuse to run due to receiving a higher\r
+protocol version number than it is expecting! New protocol versions\r
+will always be compatible with older ones by default; the larger\r
+version number is simply a hint that additional "feature" command\r
+options added in later protocol versions may be accepted.\r
+</p>\r
+</dd>\r
+\r
+<dt class="version1">accepted</dt>\r
+<dt class="version1">rejected</dt>\r
+<dd class="version1">\r
+These commands may be sent to your engine in reply to the "feature"\r
+command; see its documentation below.\r
+</dd>\r
+\r
+<dt>new</dt>\r
+<dd>Reset the board to the standard chess starting position. Set\r
+White on move. Leave force mode and set the engine to play Black.\r
+Associate the engine's clock with Black and the opponent's clock with\r
+White. Reset clocks and time controls to the start of a new game.\r
+Use wall clock for time measurement.\r
+Stop clocks. Do not ponder on this move, even if pondering is on.\r
+Remove any search depth limit previously set by the sd command.\r
+</dd>\r
+\r
+<dt>variant VARNAME</dt>\r
+<dd>If the game is not standard chess, but a variant, this command is\r
+sent after "new" and before the first move or "edit" command. Currently\r
+defined variant names are:\r
+\r
+<table>\r
+<tr><td>wildcastle</td><td>Shuffle chess where king can castle from d file</td></tr>\r
+<tr><td>nocastle</td><td>Shuffle chess with no castling at all</td></tr>\r
+<tr><td>fischerandom</td><td>Fischer Random</td></tr>\r
+<tr><td>bughouse</td><td>Bughouse, ICC/FICS rules</td></tr>\r
+<tr><td>crazyhouse</td><td>Crazyhouse, ICC/FICS rules</td></tr>\r
+<tr><td>losers</td><td>Win by losing all pieces or getting mated (ICC)</td></tr>\r
+<tr><td>suicide</td><td>Win by losing all pieces including king,\r
+ or by having fewer pieces when one player has no legal moves (FICS)</td></tr>\r
+<tr class="version1"><td>giveaway</td><td>Win by losing all pieces including king,\r
+ or by having no legal moves (ICC)</td></tr>\r
+<tr><td>twokings</td><td>Weird ICC wild 9</td></tr>\r
+<tr><td>kriegspiel</td><td>Kriegspiel (engines not supported)</td></tr>\r
+<tr><td>atomic</td><td>Atomic</td></tr>\r
+<tr><td>3check</td><td>Win by giving check 3 times</td></tr>\r
+<tr class="version43"><td>xiangqi </td><td>Chinese Chess (9x10 board)</td></tr>\r
+<tr class="version43"><td>shogi </td><td>Japanese Chess (9x9 bord)</td></tr>\r
+<tr class="version43"><td>capablanca</td><td>Capablanca Chess (10x8 board, with Archbishop and Chancellor)</td></tr>\r
+<tr class="version43"><td>gothic </td><td>Gothic Chess (10x8 board, same with better opening setup)</td></tr>\r
+<tr class="version43"><td>falcon </td><td>Falcon Chess (10x8 board, with two Falcon pieces)</td></tr>\r
+<tr class="version43"><td>shatranj </td><td>ancient Arabic Chess, with Elephants and General in stead of B and Q</td></tr>\r
+<tr class="version43"><td>courier </td><td>Courier Chess (12x8 board, a medieval precursor of modern Chess</td></tr>\r
+<tr class="version43"><td>knightmate </td><td>King moves as Knight and vice versa</td></tr>\r
+<tr class="version43"><td>berolina</td><td> Pawns capture straight ahead, and move diagonally</td></tr>\r
+<tr class="version43"><td>janus</td><td> Janus Chess (10x8, with two Archbishops)</td></tr>\r
+<tr class="version43"><td>caparandom </td><td>shuffle variant like FRC (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
+<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>The chess engine should immediately exit. This command is used\r
+when xboard is itself exiting, and also between games if the -xreuse\r
+command line option is given (or -xreuse2 for the second engine).\r
+See also <a href="#7">Signals</a> above.\r
+</dd>\r
+\r
+<dt>random</dt>\r
+<dd>This command is specific to GNU Chess 4. You can either ignore it\r
+completely (that is, treat it as a no-op) or implement it as GNU Chess\r
+does. The command toggles "random" mode (that is, it sets random =\r
+!random). In random mode, the engine adds a small random value to its\r
+evaluation function to vary its play. The "new" command sets random\r
+mode off.\r
+</dd>\r
+\r
+<dt>force</dt>\r
+<dd>Set the engine to play neither color ("force mode"). Stop clocks.\r
+The engine should check that moves received in force mode are legal\r
+and made in the proper turn, but should not think, ponder, or make\r
+moves of its own.\r
+</dd>\r
+\r
+<dt>go</dt>\r
+<dd>Leave force mode and set the engine to play the color that is on\r
+move. Associate the engine's clock with the color that is on move,\r
+the opponent's clock with the color that is not on move. Start the engine's\r
+clock. Start thinking and eventually make a move.\r
+</dd>\r
+\r
+<dt class="version1">playother</dt>\r
+<dd class="version1">\r
+(This command is new in protocol version 2. It is not\r
+sent unless you enable it with the feature command.)\r
+Leave force mode and set the engine to play the color that is <i>not</i> on\r
+move. Associate the opponent's clock with the color that is on move,\r
+the engine's clock with the color that is not on move. Start the opponent's\r
+clock. If pondering is enabled, the engine should begin pondering.\r
+If the engine later receives a move, it should start thinking and eventually\r
+reply.\r
+</dd>\r
+\r
+<dt>white</dt>\r
+<dd>\r
+<p><span class="version1">\r
+(This command is obsolete as of protocol version 2, but is still\r
+sent in some situations to accommodate older engines unless you disable it \r
+with the feature command.)\r
+</span>\r
+Set White on move. Set the engine to play Black. Stop clocks.\r
+</p>\r
+</dd>\r
+ \r
+<dt>black </dt>\r
+<dd>\r
+<span class="version1">\r
+(This command is obsolete as of protocol version 2, but is still\r
+sent in some situations to accommodate older engines unless you disable it \r
+with the feature command.)\r
+</span>\r
+Set Black on move. Set the engine to play White. Stop clocks.\r
+</dd>\r
+\r
+<dt>level MPS BASE INC</dt>\r
+<dd>Set time controls. See the <a href="#11">Time Control</a> section below.\r
+</dd>\r
+ \r
+<dt>st TIME</dt>\r
+<dd>Set time controls. See the <a href="#11">Time Control</a> section\r
+below. \r
+</dd>\r
+\r
+<dt>sd DEPTH</dt>\r
+<dd>\r
+<p>The engine should limit its thinking to DEPTH ply.\r
+<span class="version43">The commands "level" or "st" and "sd" can be used together in an orthogonal way.\r
+If both are issued, the engine should observe both limitations:</span>\r
+In the protocol, the "sd" command isn't a time control. It doesn't\r
+say that your engine has unlimited time but must search to exactly the\r
+given depth. It says that you should pay attention to the time\r
+control as normal, but cut off the search at the specified depth even\r
+if you have time to search deeper. If you don't have time to search\r
+to the specified depth, given your normal time management algorithm,\r
+then you will want to stop sooner than the given depth.\r
+</p><p>\r
+The "new" command should set the search depth back to unlimited. This\r
+is already stated in the spec. The "level" command should not affect\r
+the search depth. As it happens, xboard/WinBoard currently always\r
+sends sd (if needed) right after level, but that isn't part of the\r
+spec.</p>\r
+</dd>\r
+\r
+<dt><span class="version43">nps NODE_RATE</span></dt>\r
+<dd><span class="version43">The engine should not use wall-clock time to make its timing decisions,\r
+but an own internal time measure based on the number of nodes it has searched\r
+(and will report as "thinking output", see <a href="#10">section 10</a>),\r
+converted to seconds through dividing by the given NODE_RATE.\r
+Example: after receiving the commands "st 8" and "nps 10000",\r
+the engine should never use more that 80,000 nodes in the search for any move.\r
+In this mode, the engine should report user CPU time used (in its thinking output), \r
+rather than wall-clock time.\r
+This even holds if NODE_RATE is given as 0,\r
+but in that case it should also use the user CPU time for its timing decisions.\r
+The effect of an "nps" command should persist until the next "new" command.\r
+</span>\r
+</dd>\r
+\r
+<dt>time N</dt>\r
+<dd>Set a clock that always belongs to the engine. N is a number in\r
+ centiseconds (units of 1/100 second). Even if the engine changes to\r
+ playing the opposite color, this clock remains with the engine.\r
+</dd>\r
+\r
+<dt>otim N</dt>\r
+\r
+<dd><p>Set a clock that always belongs to the opponent. N is a number in\r
+centiseconds (units of 1/100 second). Even if the opponent changes to\r
+playing the opposite color, this clock remains with the opponent.\r
+</p><p>\r
+If needed for purposes of board display in force mode (where the\r
+engine is not participating in the game) the time clock should be\r
+associated with the last color that the engine was set to play, the\r
+otim clock with the opposite color.\r
+</p>\r
+<p>\r
+<span class="version43">This business of "clocks remaining with the engine" is apparently so ambiguous\r
+that many engines implement it wrong.\r
+The clocks in fact always remain with the color.\r
+Which clock reading is relayed with "time", and which by "otim", is determined by which side the engine plays.\r
+Note that the way the clocks operate and receive extra time (in accordance with the selected time control)\r
+is not affected in any way by which moves are made by the engine, which by the opponent, and which were forced.\r
+</span>\r
+</p>\r
+<p>\r
+<span class="version1">\r
+Beginning in protocol version 2, if you can't handle the time and\r
+otim commands, you can use the "feature" command to disable them; see\r
+below. \r
+</span>\r
+The following techniques from older protocol versions also\r
+work: You can ignore the time and otim commands (that is, treat them\r
+as no-ops), or send back "Error (unknown command): time" the first\r
+time you see "time".\r
+</p></dd>\r
+\r
+<dt>MOVE</dt>\r
+<dd>\r
+<p>See below for the syntax of moves. If the move is illegal, print\r
+an error message; see the section "<a href="#9">Commands from the engine to\r
+xboard</a>". If the move is legal and in turn, make it. If not in force\r
+mode, stop the opponent's clock, start the engine's clock, start\r
+thinking, and eventually make a move.\r
+</p><p>\r
+When xboard sends your engine a move, it normally sends coordinate\r
+algebraic notation. Examples:\r
+</p>\r
+<table>\r
+<tr><td>Normal moves:</td><td>e2e4</td></tr>\r
+<tr><td>Pawn promotion:</td><td>e7e8q</td></tr>\r
+<tr><td>Castling:</td><td>e1g1, e1c1, e8g8, e8c8</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
+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
+to select SAN (standard algebraic notation) instead; for example, e4,\r
+Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form,\r
+P@h3, is a extension to the PGN standard's definition of SAN, which does\r
+not support bughouse or crazyhouse.\r
+</p>\r
+\r
+<p>\r
+xboard doesn't reliably detect illegal moves, because it does not keep\r
+track of castling unavailability due to king or rook moves, or en\r
+passant availability. If xboard sends an illegal move, send back an\r
+error message so that xboard can retract it and inform the user; see\r
+the section "<a href="#9">Commands from the engine to xboard</a>".\r
+</p>\r
+</dd>\r
+<dt class="version1">usermove MOVE</dt>\r
+<dd class="version1">\r
+By default, moves are sent to the engine without a command name;\r
+the notation is just sent as a line by itself.\r
+Beginning in protocol version 2, you can use the feature command\r
+to cause the command name "usermove" to be sent before the move.\r
+Example: "usermove e2e4".\r
+</dd>\r
+\r
+<dt>?</dt>\r
+<dd><p>Move now. If your engine is thinking, it should move immediately;\r
+ otherwise, the command should be ignored (treated as a no-op). It\r
+ is permissible for your engine to always ignore the ? command. The\r
+ only bad consequence is that xboard's Move Now menu command will do\r
+ nothing.\r
+</p><p>\r
+It is also permissible for your engine to move immediately if it gets\r
+any command while thinking, as long as it processes the command right\r
+after moving, but it's preferable if you don't do this. For example,\r
+xboard may send post, nopost, easy, hard, force, quit,\r
+<span class="version1">\r
+or other commands\r
+</span>\r
+while the engine is on move.\r
+</p>\r
+</dd>\r
+\r
+<dt class="version1">ping N</dt>\r
+<dd class="version1">\r
+<p>In this command, N is a decimal number. When you receive the command,\r
+reply by sending the string <strong>pong N</strong>, where N is the\r
+same number you received. Important: You must not reply to a "ping"\r
+command until you have finished executing all commands that you\r
+received before it. Pondering does not count; if you receive a ping\r
+while pondering, you should reply immediately and continue pondering.\r
+Because of the way xboard uses the ping command, if you implement the\r
+other commands in this protocol, you should never see a "ping" command\r
+when it is your move; however, if you do, you must not send the "pong"\r
+reply to xboard until after you send your move. For example, xboard\r
+may send "?" immediately followed by "ping". If you implement the "?"\r
+command, you will have moved by the time you see the subsequent ping\r
+command. Similarly, xboard may send a sequence like "force", "new",\r
+"ping". You must not send the pong response until after you have\r
+finished executing the "new" command and are ready for the new game to\r
+start.\r
+</p>\r
+<p>\r
+The ping command is new in protocol version 2 and will not be sent\r
+unless you enable it with the "feature" command. Its purpose is to\r
+allow several race conditions that could occur in previous versions of\r
+the protocol to be fixed, so it is highly recommended that you\r
+implement it. It is especially important in simple engines that do\r
+not ponder and do not poll for input while thinking, but it is needed in all\r
+engines. \r
+</p>\r
+</dd>\r
+\r
+<dt>draw</dt>\r
+<dd>The engine's opponent offers the engine a draw. To accept the\r
+draw, send "offer draw". To decline, ignore the offer (that is, send\r
+nothing). If you're playing on ICS, it's possible for the draw offer\r
+to have been withdrawn by the time you accept it, so don't assume the\r
+game is over because you accept a draw offer. Continue playing until\r
+xboard tells you the game is over. See also "offer draw" below.\r
+</dd>\r
+\r
+<dt>result RESULT {COMMENT}</dt>\r
+<dd>After the end of each game, xboard will send you a result command.\r
+You can use this command to trigger learning. RESULT is either 1-0,\r
+0-1, 1/2-1/2, or *, indicating whether white won, black won, the game\r
+was a draw, or the game was unfinished. The COMMENT string is purely\r
+a human-readable comment; its content is unspecified and subject to\r
+change. In ICS mode, it is passed through from ICS uninterpreted.\r
+Example: <pre>result 1-0 {White mates}</pre>\r
+<p>\r
+Here are some notes on interpreting the "result" command. Some apply\r
+only to playing on ICS ("Zippy" mode).\r
+</p>\r
+\r
+<p>\r
+If you won but did not just play a mate, your opponent must have\r
+resigned or forfeited. If you lost but were not just mated, you\r
+probably forfeited on time, or perhaps the operator resigned manually.\r
+If there was a draw for some nonobvious reason, perhaps your opponent\r
+called your flag when he had insufficient mating material (or vice\r
+versa), or perhaps the operator agreed to a draw manually.\r
+</p>\r
+\r
+<p>\r
+You will get a result command even if you already know the game ended\r
+-- for example, after you just checkmated your opponent. In fact, if\r
+you send the "RESULT {COMMENT}" command (discussed below), you will\r
+simply get the same thing fed back to you with "result" tacked in\r
+front. You might not always get a "result *" command, however. In\r
+particular, you won't get one in local chess engine mode when the user\r
+stops playing by selecting Reset, Edit Game, Exit or the like.\r
+</p>\r
+</dd>\r
+\r
+<dt><span class="version1">setboard FEN</span></dt>\r
+<dd>\r
+<p><span class="version1">\r
+The setboard command is the new way to set up positions, beginning\r
+in protocol version 2. It is not used unless it has been selected\r
+with the feature command. Here FEN is a position in Forsythe-Edwards\r
+Notation, as defined in the PGN standard.</span>\r
+<span class="version43">Note that this PGN standard referred to here\r
+only applies to normal Chess;\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 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
+to the outermost rook on the given side.</span>\r
+</p>\r
+\r
+<p class="version1">\r
+<em>Illegal positions:</em> Note that either setboard or edit can\r
+be used to send an illegal position to the engine. The user can\r
+create any position with xboard's Edit Position command (even, say,\r
+an empty board, or a board with 64 white kings and no black ones).\r
+If your engine receives a position that it considers illegal, \r
+I suggest that you send the response "tellusererror Illegal position",\r
+and then respond to any attempted move with "Illegal move" until\r
+the next new, edit, or setboard command.\r
+</p>\r
+</dd>\r
+\r
+<dt>edit</dt>\r
+<dd>\r
+<p><span class="version1">\r
+The edit command is the old way to set up positions. For compatibility\r
+with old engines, it is still used by default, but new engines may prefer\r
+to use the feature command (see below) to cause xboard to use setboard instead.\r
+</span>\r
+The edit command puts the chess engine into a special mode, where\r
+it accepts the following subcommands:</p>\r
+<table>\r
+<tr><td>c</td><td>change current piece color, initially white</td></tr>\r
+<tr><td>Pa4 (for example)</td><td>place pawn of current color on a4</td></tr>\r
+<tr><td>xa4 (for example)</td><td>empty the square a4 (not used by xboard)</td></tr>\r
+<tr><td>#</td><td>clear board</td></tr>\r
+<tr><td>.</td><td>leave edit mode</td></tr>\r
+</table>\r
+<p class="version1">\r
+See the Idioms section below for additional subcommands used in\r
+ChessBase's implementation of the protocol.\r
+</p>\r
+\r
+<p>The edit command does not change the side to move. To set up a\r
+black-on-move position, xboard uses the following command sequence:\r
+</p>\r
+<pre>\r
+ new\r
+ force\r
+ a2a3\r
+ edit\r
+ <edit commands>\r
+ .\r
+</pre>\r
+\r
+<p>\r
+This sequence is used to avoid the "black" command, which is now\r
+considered obsolete and which many engines never did implement as \r
+specified in this document.\r
+</p>\r
+\r
+<p>\r
+After an edit command is complete, if a king and a rook are on their\r
+home squares, castling is assumed to be available to them. En passant\r
+capture is assumed to be illegal on the current move regardless of the\r
+positions of the pawns. The clock for the 50 move rule starts at\r
+zero, and for purposes of the draw by repetition rule, no prior\r
+positions are deemed to have occurred.\r
+<span class="version43">\r
+In FRC or CRC, any rook and king put on the back rank should be considered to\r
+have castling rights, even if it later becomes apparent that they cannot be both in the\r
+initial position, because the position just set up is asymmetric.\r
+It is upto WinBoard to find work-around in cases where this is not desired,\r
+similar to the "black kludge" shown above, by setting up an earlier position,\r
+and then do a move to destroy castling rights or create e.p. rights.\r
+(Don't bet your life on it...)\r
+</span>\r
+</p>\r
+</dd>\r
+\r
+<dt>hint</dt>\r
+<dd>If the user asks for a hint, xboard sends your engine the command\r
+"hint". Your engine should respond with "Hint: xxx", where xxx is a\r
+suggested move. If there is no move to suggest, you can ignore the\r
+hint command (that is, treat it as a no-op).\r
+</dd>\r
+\r
+<dt>bk</dt>\r
+<dd>If the user selects "Book" from the xboard menu, xboard will send\r
+your engine the command "bk". You can send any text you like as the\r
+response, as long as each line begins with a blank space or tab (\t)\r
+character, and you send an empty line at the end. The text pops up in\r
+a modal information dialog.\r
+</dd>\r
+\r
+<dt>undo</dt>\r
+<dd>If the user asks to back up one move, xboard will send you the\r
+"undo" command. xboard will not send this command without putting you\r
+in "force" mode first, so you don't have to worry about what should\r
+happen if the user asks to undo a move your engine made. (GNU Chess 4\r
+actually switches to playing the opposite color in this case.)\r
+</dd>\r
+\r
+<dt>remove</dt>\r
+<dd>If the user asks to retract a move, xboard will send you the\r
+"remove" command. It sends this command only when the user is on\r
+move. Your engine should undo the last two moves (one for each\r
+player) and continue playing the same color.\r
+</dd>\r
+\r
+<dt>hard</dt>\r
+<dd>Turn on pondering (thinking on the opponent's time, also known as\r
+"permanent brain"). xboard will not make any assumption about what\r
+your default is for pondering or whether "new" affects this setting.\r
+</dd>\r
+\r
+<dt>easy</dt>\r
+<dd>Turn off pondering.</dd>\r
+ \r
+<dt>post</dt>\r
+<dd>Turn on thinking/pondering output. \r
+See <a href="#10">Thinking Output</a> section.</dd>\r
+\r
+<dt>nopost</dt>\r
+<dd>Turn off thinking/pondering output.</dd>\r
+ \r
+<dt>analyze</dt>\r
+<dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.</dd>\r
+\r
+<dt>name X </dt>\r
+<dd>This command informs the engine of its\r
+opponent's name. When the engine is playing on a chess server, xboard\r
+obtains the opponent's name from the server. \r
+<span class="version1">\r
+When the engine is\r
+playing locally against a human user, xboard obtains the user's login\r
+name from the local operating system. When the engine is playing\r
+locally against another engine, xboard uses either the other engine's\r
+filename or the name that the other engine supplied in the myname\r
+option to the feature command. By default, xboard uses the name\r
+command only when the engine is playing on a chess server. Beginning\r
+in protocol version 2, you can change this with the name option to the\r
+feature command; see below.\r
+</span>\r
+</dd>\r
+\r
+<dt>rating</dt>\r
+<dd>In ICS mode, xboard obtains the ICS opponent's rating from the\r
+"Creating:" message that appears before each game. (This message may\r
+not appear on servers using outdated versions of the FICS code.) In\r
+Zippy mode, it sends these ratings on to the chess engine using the\r
+"rating" command. The chess engine's own rating comes first, and if\r
+either opponent is not rated, his rating is given as 0. \r
+<span class="version1">\r
+In the future this command may also be used in other modes, if ratings\r
+are known.\r
+</span>\r
+Example: <pre>rating 2600 1500</pre>\r
+</dd>\r
+\r
+<dt><span class="version1">ics HOSTNAME</span></dt>\r
+<dd class="version1">\r
+If HOSTNAME is "-", the engine is playing against a local\r
+opponent; otherwise, the engine is playing on an Internet Chess Server\r
+(ICS) with the given hostname. This command is new in protocol\r
+version 2 and is not sent unless the engine has enabled it with\r
+the "feature" command. Example: "ics freechess.org"\r
+</dd>\r
+\r
+<dt>computer</dt>\r
+<dd>The opponent is also a computer chess engine. Some engines alter\r
+their playing style when they receive this command.\r
+</dd>\r
+\r
+<dt class="version1">pause</dt>\r
+<dt class="version1">resume</dt>\r
+<dd class="version1">(These commands are new in protocol\r
+version 2 and will not be sent unless feature pause=1 is set. At\r
+this writing, xboard actually does not use the commands at all, but it\r
+or other interfaces may use them in the future.)\r
+The "pause" command puts the engine into a special state where it\r
+does not think, ponder, or otherwise consume significant CPU time.\r
+The current thinking or pondering (if any) is suspended and both\r
+player's clocks are stopped. The only command that the interface may\r
+send to the engine while it is in the paused state is "resume". The\r
+paused thinking or pondering (if any) resumes from exactly where it\r
+left off, and the clock of the player on move resumes running from\r
+where it stopped.\r
+</dd>\r
+\r
+<dt class="version44">memory N</dt>\r
+<dd class="version44">\r
+This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes.\r
+On receipt of this command, the engine should adapt the size of its hash tables accordingly.\r
+This command does only fix the total memory use,\r
+the engine has to decide for itself \r
+(or be configured by the user by other means) \r
+how to divide up the available memory between the various tables it wants to use \r
+(e.g. main hash, pawn hash, tablebase cache, bitbases).\r
+This command will only be sent to engines that have requested it through the memory feature,\r
+and only at the start of a game,\r
+as the first of the commands to relay engine option settings just before each "new" command.\r
+</dd>\r
+\r
+<dt class="version44">cores N</dt>\r
+<dd class="version44">\r
+This command informs the engine on how many CPU cores it is allowed to use maximally.\r
+This could be interpreted as the number of search threads for SMP engines. \r
+(Threads that do not consume significant amounts of CPU time, like I/O threads, need not be included in the count.)\r
+This command will only be sent to engines that have requested it through the smp feature.\r
+The engine should be able to respond to the "cores" command any time during a game,\r
+but it is allowed to finish a search in progress before procesing the command.\r
+(Obeying the command should take priority over finishing a ponder search, though.)\r
+In any case it will be sent at the start of every game\r
+as the last command to relay engine option settings before the "new" command.\r
+</dd>\r
+\r
+<dt class="version44">egtpath TYPE PATH</dt>\r
+<dd class="version44">\r
+This command informs the engine in which directory (given by the PATH argument)\r
+it can find end-game tables of the specified TYPE.\r
+The TYPE argument can be any character string which does not contain spaces.\r
+Currently <strong>nalimov</strong> and <strong>scorpio</strong> are defined types, \r
+for Nalimov tablebases and Scorpio bitbases, respectively,\r
+but future developers of other formats are free to define their own format names.\r
+The GUI simply matches the TYPE names the engine says it supports \r
+with those that the user supplied when configuring xboard.\r
+For every match, it sends a separate "y" command.\r
+The PATH argument would normally (for Nalimov) be the pathname of the directory the EGT files are in,\r
+but could also be the name of a file, or in fact anything the particular EGT type requires.\r
+It is upto the developer of the EGT format to specify the syntax of this parameter.\r
+This command will only be sent to engines that have told the GUI they support EGTs of the given TYPE\r
+through the egt feature.\r
+It will be sent at the start of each game, before the "new" command.\r
+</dd>\r
+\r
+<dt class="version44">option NAME[=VALUE]</dt>\r
+<dd class="version44">\r
+This command changes the setting of the option NAME defined by the engine \r
+(through an earlier feature command)\r
+to the given VALUE.\r
+XBoard will in general have no idea what the option means,\r
+and will send the command only when a user changes the value of this option through a menu,\r
+or at startup of the engine \r
+(before the first 'cores' command or, if that is not sent, the first 'new' command)\r
+in reaction to command-line options.\r
+The NAME echoes back to the engine the string that was identified as an option NAME\r
+in the feature command defining the option.\r
+The VALUE is of the type (numeric or text or absent) that was implied by the option type\r
+specified in this feature command,\r
+i.e. with 'spin' and 'check' options VALUE will be a decimal integer (in the latter case 0 or 1),\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
+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
+(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
+\r
+<p>\r
+xboard now supports bughouse engines when in Zippy mode. See\r
+<a href="http://www.tim-mann.org/xboard/zippy.README"\r
+>zippy.README</a> for information on Zippy mode and how to turn on the\r
+bughouse support. The bughouse move format is given above. xboard\r
+sends the following additional commands to the engine when in bughouse\r
+mode. \r
+Commands to inform your engine of the partner's game state may\r
+be added in the future.\r
+</p>\r
+\r
+<dl>\r
+<dt>partner <player></dt>\r
+<dd><player> is now your partner for future games. Example: <pre>partner mann</pre>\r
+</dd>\r
+\r
+<dt>partner</dt>\r
+<dd>Meaning: You no longer have a partner.\r
+</dd>\r
+\r
+<dt>ptell <text></dt>\r
+<dd>Your partner told you <text>, either with a ptell or an ordinary tell. \r
+</dd>\r
+\r
+<dt>holding [<white>] [<black>]</dt>\r
+<dd>White currently holds <white>; black currently holds <black>.\r
+ Example: <pre>holding [PPPRQ] []</pre></dd>\r
+\r
+<dt>holding [<white>] [<black>] <color><piece></dt>\r
+<dd>White currently holds <white>; black currently holds <black>, after\r
+ <color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre></dd>\r
+</dl>\r
+\r
+<h2><a name="9">9. Commands from the engine to xboard</a></h2>\r
+\r
+<p class="version1">\r
+In general, an engine should not send any output to xboard that is not\r
+described in this document. As the protocol is extended, newer\r
+versions of xboard may recognize additional strings as commands that\r
+were previously not assigned a meaning.\r
+</p>\r
+\r
+<dl>\r
+\r
+<dt class="version1"> feature FEATURE1=VALUE1 FEATURE2=VALUE2 ... </dt>\r
+<dd class="version1">\r
+<p>Beginning with version 2, the protocol includes the "feature"\r
+command, which lets your engine control certain optional protocol\r
+features. Feature settings are written as FEATURE=VALUE, where\r
+FEATURE is a name from the list below and VALUE is the value to be\r
+assigned. Features can take string, integer, or boolean values; the\r
+type of value is listed for each feature. String values are written\r
+in double quotes (for example, <tt>feature myname="Miracle Chess\r
+0.9"</tt>), integers are written in decimal, and boolean values are\r
+written as 0 for false, 1 for true. Any number of features can be set\r
+in one feature command, or multiple feature commands can be given.</p>\r
+\r
+<p>\r
+Your engine should send one or more feature commands immediately after\r
+receiving the "protover" command, since xboard needs to know the\r
+values of some features before sending further commands to the engine.\r
+Because engines that predate protocol version 2 do not send "feature",\r
+xboard uses a timeout mechanism: when it first starts your engine, it\r
+sends "xboard" and "protover N", then listens for feature commands for\r
+two seconds before sending any other commands. To end this timeout\r
+and avoid the wait, set the feature "done=1" at the end of your last\r
+feature command. To increase the timeout, if needed, set the feature\r
+"done=0" before your first feature command and "done=1" at the end.\r
+If needed, it is okay for your engine to set done=0 soon as it starts,\r
+even before it receives the xboard and protover commands. This can be\r
+useful if your engine takes a long time to initialize itself. It\r
+should be harmless even if you are talking to a (version 1) user\r
+interface that does not understand the "feature" command, since such\r
+interfaces generally ignore commands from the engine that they do not\r
+understand.\r
+</p>\r
+\r
+<p>\r
+The feature command is designed to let the protocol change without\r
+breaking engines that were written for older protocol versions. When\r
+a new feature is added to the protocol, its default value is always\r
+chosen to be compatible with older versions of the protocol that did\r
+not have the feature. Any feature that your engine does not set in a\r
+"feature" command retains its default value, so as the protocol\r
+changes, you do not have to change your engine to keep up with it\r
+unless you want to take advantage of a new feature. Because some\r
+features are improvements to the protocol, while others are meant to\r
+cater to engines that do not implement all the protocol features, the\r
+recommended setting for a feature is not always the same as the\r
+default setting. The listing below gives both default and recommended\r
+settings for most features.\r
+</p>\r
+\r
+<p>\r
+You may want to code your engine so as to be able to work with\r
+multiple versions of the engine protocol. Protocol version 1 does not\r
+send the protover command and does not implement the feature command;\r
+if you send a feature command in protocol version 1, it will have no\r
+effect and there will be no response. In protocol version 2 or later,\r
+each feature F that you set generates the response "accepted F" if the\r
+feature is implemented, or "rejected F" if it is not. Thus an engine\r
+author can request any feature without having to keep track of which\r
+protocol version it was introduced in; you need only check whether the\r
+feature is accepted or rejected. This mechanism also makes it\r
+possible for a user interface author to implement a subset of a\r
+protocol version by rejecting some features that are defined in that\r
+version; however, you should realize that engine authors are likely to\r
+code for xboard and may not be prepared to have a feature that they\r
+depend on be rejected.\r
+<span class="version44">If the GUI rejects an option feature because of the\r
+syntax of the value, it should print the value string with the\r
+"rejected" command, e.g. "rejected option nonsense" in response\r
+to receiving feature option="nonsense".</span>\r
+</p>\r
+\r
+<p>\r
+Here are the features that are currently defined.\r
+</p>\r
+\r
+<dl>\r
+<dt class="version1">ping (boolean, default 0, recommended 1)</dt>\r
+<dd class="version1">\r
+If ping=1, xboard may use the protocol's new "ping" command;\r
+if ping=0, xboard will not use the command.\r
+</dd>\r
+\r
+<dt class="version1">setboard (boolean, default 0, recommended 1)</dt>\r
+<dd class="version1">\r
+If setboard=1, xboard will use the protocol's new "setboard" command\r
+to set up positions; if setboard=0, it will use the older "edit" command.\r
+</dd>\r
+\r
+<dt class="version1">playother (boolean, default 0, recommended 1)</dt>\r
+<dd class="version1">\r
+If playother=1, xboard will use the protocol's new "playother" command\r
+when appropriate; if playother=0, it will not use the command.\r
+</dd>\r
+\r
+<dt class="version1">san (boolean, default 0)</dt>\r
+<dd class="version1">\r
+If san=1, xboard will send moves to the engine in standard algebraic\r
+notation (SAN); for example, Nf3. If san=0, xboard will send moves in\r
+coordinate notation; for example, g1f3. See MOVE in \r
+<a href="#8">section 8</a> above for more details of both kinds of notation.\r
+</dd>\r
+\r
+<dt class="version1">usermove (boolean, default 0)</dt>\r
+<dd class="version1">\r
+If usermove=1, xboard will send moves to the engine with the\r
+command "usermove MOVE"; if usermove=0, xboard will send just the move,\r
+with no command name.\r
+</dd>\r
+\r
+<dt class="version1">time (boolean, default 1, recommended 1)</dt>\r
+<dd class="version1">\r
+If time=1, xboard will send the "time" and "otim" commands to\r
+update the engine's clocks; if time=0, it will not.\r
+</dd>\r
+\r
+<dt class="version1">draw (boolean, default 1, recommended 1)</dt>\r
+<dd class="version1">\r
+If draw=1, xboard will send the "draw" command if the engine's opponent\r
+offers a draw; if draw=0, xboard will not inform the engine about\r
+draw offers. Note that if draw=1, you may receive a draw offer while you\r
+are on move; if this will cause you to move immediately, you should set\r
+draw=0.\r
+</dd>\r
+\r
+<dt class="version1">sigint (boolean, default 1)</dt>\r
+<dd class="version1">\r
+If sigint=1, xboard may send SIGINT (the interrupt signal) to\r
+the engine as <a href="#7">section 7</a> above; if sigint=0, it will\r
+not.\r
+</dd>\r
+\r
+<dt class="version1">sigterm (boolean, default 1)</dt>\r
+<dd class="version1">\r
+If sigterm=1, xboard may send SIGTERM (the termination signal) to\r
+the engine as <a href="#7">section 7</a> above; if sigterm=0, it will\r
+not.\r
+</dd>\r
+\r
+<dt class="version1">reuse (boolean, default 1, recommended 1) </dt>\r
+<dd class="version1">\r
+If reuse=1, xboard may reuse your engine for multiple games. If\r
+reuse=0 (or if the user has set the -xreuse option on xboard's command\r
+line), xboard will kill the engine process after every game and start\r
+a fresh process for the next game.\r
+</dd>\r
+\r
+<dt class="version1">analyze (boolean, default 1, recommended 1)</dt>\r
+<dd class="version1">\r
+If analyze=0, xboard will not try to use the "analyze" command; it\r
+will pop up an error message if the user asks for analysis mode. If\r
+analyze=1, xboard will try to use the command if the user asks for\r
+analysis mode.\r
+</dd>\r
+\r
+<dt class="version1">myname (string, default determined from engine filename)</dt>\r
+<dd class="version1">\r
+This feature lets you set the name that xboard will use for your\r
+engine in window banners, in the PGN tags of saved game files, and when\r
+sending the "name" command to another engine.\r
+</dd>\r
+\r
+<dt class="version1">variants (string, see text below)</dt>\r
+<dd><span class="version1">\r
+This feature indicates which chess variants your engine accepts.\r
+It should be a comma-separated list of variant names. See the table\r
+under the "variant" command in <a href="#8">section 8</a> above. If\r
+you do not set this feature, xboard will assume by default that your\r
+engine supports all variants. (However, the -zippyVariants\r
+command-line option still limits which variants will be accepted in\r
+Zippy mode.) It is recommended that you set this feature to the\r
+correct value for your engine (just "normal" in most cases) rather\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 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
+If there is a maximum to the board size, this can be prefixed,\r
+e.g. "12x10+0_boardsize".\r
+</span>\r
+</dd>\r
+\r
+<dt class="version1">colors (boolean, default 1, recommended 0) </dt>\r
+<dd><span class="version1">\r
+If colors=1, xboard uses the obsolete "white" and "black"\r
+commands in a stylized way that works with most older chess engines\r
+that require the commands. See the "<a href="#13">Idioms</a>" section\r
+below for details. If colors=0, xboard does not use the "white" and\r
+"black" commands at all.\r
+</span>\r
+</dd>\r
+\r
+<dt class="version1">ics (boolean, default 0)</dt>\r
+<dd class="version1">\r
+If ics=1, xboard will use the protocol's new "ics" command\r
+to inform the engine of whether or not it is playing on a chess server;\r
+if ics=0, it will not.\r
+</dd>\r
+\r
+<dt class="version1">name (boolean, see text below)</dt>\r
+<dd class="version1">\r
+If name=1, xboard will use the protocol's "name" command\r
+to inform the engine of the opponent's name; if name=0, it will not.\r
+By default, name=1 if the engine is playing on a chess server; name=0 if not.\r
+</dd>\r
+\r
+<dt class="version1">pause (boolean, default 0)</dt>\r
+<dd class="version1">\r
+If pause=1, xboard may use the protocol's new "pause" command;\r
+if pause=0, xboard assumes that the engine does not support this command.\r
+</dd>\r
+\r
+<dt class="version43">nps (boolean, default ?)</dt>\r
+<dd class="version43">\r
+If nps=1, it means the engine supports the nps command.\r
+If nps=0, it means the engine does not support it, and WinBoard should refrain from sending it.\r
+Default is that WinBoard sends it, in an attempt to try out if the engine understand it.\r
+The engine should properly respond with "Error (unkown command): nps" if it does not implement it,\r
+(as any protocol version pre-scribes),\r
+or WinBoard might assume that the engine did understand the command. \r
+In that case the use of different time standards that ensues could lead to time forfeits for the engine.\r
+</dd>\r
+\r
+<dt class="version43">debug (boolean, default 0)</dt>\r
+<dd class="version43">\r
+If debug=1, it means the engine wants to send debug output prefixed by '#',\r
+which WinBoard should ignore, except for including it in the winboard.debug file.\r
+As this feature is added to protocol 2 ony late,\r
+so that not all protocol-2 supporting versions of WinBoard might implement it,\r
+it is important that engines check if WinBoard accepts the feature.\r
+If the feature is rejected,\r
+engines must refrain from sending the debug output,\r
+or do so at their own risk.\r
+</dd>\r
+\r
+<dt class="version44">memory (boolean, default 0)</dt>\r
+<dd class="version44">\r
+If memory=1, the size of the total amount of memory available for the memory-consuming tables of the engine \r
+(e.g. hash, EGTB cache)\r
+will be set by the GUI through the "memory" command.\r
+</dd>\r
+\r
+<dt class="version44">smp (boolean, default 0)</dt>\r
+<dd class="version44">\r
+If smp=1, the GUI will send the "cores" command to the engine to inform it how many CPU cores it can use.\r
+Note that sending smp=1 does not imply the engine can use more than one CPU;\r
+just that it wants to receive the "cores" command.\r
+</dd>\r
+\r
+<dt class="version44">egt (string, see text below)</dt>\r
+<dd class="version44">\r
+This feature indicates which end-game table formats the engine supports.\r
+It should be a comma-separated list of format names.\r
+See under the "egtpath" command in <a href="#8">section 8</a> above.\r
+If you do not set this feature, xboard will assume the engine does not support end-game tables,\r
+and will not send any "egtpath" commands to inform the engine about their whereabouts.\r
+</dd>\r
+\r
+<dt class="version44">option (string, see text below)</dt>\r
+<dd><span class="version44">\r
+This feature is used by the engine to define an option command to appear in a GUI menu,\r
+so that the user can change the corresponding setting of the engine through the GUI interactively.\r
+The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range.\r
+Unlike other features, option features are accumulated by the GUI, \r
+and the GUI must be able to add a new option to the list at any time,\r
+even after having received feature done=1.\r
+There are ten different options types, each requiring a slighly different syntax of the defining string:\r
+<br />\r
+feature option="NAME -button"\r
+<br />\r
+feature option="NAME -save"\r
+<br />\r
+feature option="NAME -reset"\r
+<br />\r
+feature option="NAME -check VALUE"\r
+<br />\r
+feature option="NAME -string VALUE"\r
+<br />\r
+feature option="NAME -spin VALUE MIN MAX"\r
+<br />\r
+feature option="NAME -combo CHOICE1 /// CHOICE2 ..."\r
+<br />\r
+feature option="NAME -slider VALUE MIN MAX"\r
+<br />\r
+feature option="NAME -file VALUE"\r
+<br />\r
+feature option="NAME -path VALUE"\r
+<br />\r
+NAME is an arbitrary alphanumeric string which can contain spaces; \r
+the other words in capitals would be replaced by the current (default) setting of the option,\r
+(a character string for -string options, a decimal number for -spin and -check options,\r
+were the latter uses 1=checked, 0=unchecked),\r
+the minimum or maximum value of numeric (-spin) options, \r
+or arbitrary text labels (for -combo option).\r
+In the latter case, the current value will be preceded by an asterisk.\r
+The -file and -path options are similar to -string, but can be used to inform the GUI that\r
+the text represents a file name or folder name respectively, \r
+so the GUI dialog could add the appropriate browse button to the text-edit field.\r
+Similarly, a -slider option is like a -spin, but the GUI might make a different\r
+graphical representation for it.\r
+A -save option is like a -button, and defines an immediate command to be sent by the engine.\r
+With -save the GUI will make sure all current option settings are flushed to the engine\r
+before it sends this command.\r
+A -reset option is like a -button, but use of it purges the list of options before sending \r
+the corresponding option command to the engine.\r
+This enables the engine to completely redefine its options or their current settings,\r
+by sending a new set of option feature commands to the GUI, \r
+terminated by feature done=1.\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">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
+xboard sends you the "xboard" command, the\r
+timeout will end and xboard will not look for any more feature\r
+commands before starting normal operation.\r
+If you set done=0, the initial timeout is increased to one hour;\r
+in this case, you must set done=1 before xboard will enter normal operation.\r
+</span>\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
+<dd>If your engine receives a MOVE command that is recognizably a move\r
+but is not legal in the current position, your engine must print an\r
+error message in one of the above formats so that xboard can pass the\r
+error on to the user and retract the move. The (REASON) is entirely\r
+optional. Examples:\r
+\r
+<pre>\r
+ Illegal move: e2e4\r
+ Illegal move (in check): Nf3\r
+ Illegal move (moving into check): e1g1\r
+</pre>\r
+<p>\r
+Generally, xboard will never send an ambiguous move, so it does not \r
+matter whether you respond to such a move with an Illegal move message \r
+or an Error message.\r
+</p>\r
+</dd>\r
+\r
+<dt>Error (ERRORTYPE): COMMAND</dt>\r
+<dd>If your engine receives a command it does not understand or does\r
+not implement, it should print an error message in the above format so\r
+that xboard can parse it. Examples:\r
+<pre>\r
+ Error (ambiguous move): Nf3\r
+ Error (unknown command): analyze\r
+ Error (command not legal now): undo\r
+ Error (too many parameters): level 1 2 3 4 5 6 7\r
+</pre>\r
+</dd>\r
+\r
+<dt>move MOVE</dt>\r
+<dd>Your engine is making the move MOVE. Do not echo moves from\r
+xboard with this command; send only new moves made by the engine.\r
+\r
+<div class="version1">\r
+<p>For the actual move text from your chess engine (in place of MOVE\r
+above), your move should be either</p>\r
+<ul>\r
+<li>in coordinate notation (e.g.,\r
+e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,\r
+e1g1), or</li>\r
+<li>in Standard Algebraic Notation (SAN) as defined in the\r
+Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),\r
+with the extension piece@square (e.g., P@f7) to handle piece placement\r
+in bughouse and crazyhouse.</li>\r
+</ul>\r
+<p>\r
+xboard itself also accepts some variants of SAN, but for compatibility\r
+with non-xboard interfaces, it is best not to rely on this behavior.\r
+</p>\r
+\r
+<p>Warning: Even though all versions of this protocol specification\r
+have indicated that xboard accepts SAN moves, some non-xboard\r
+interfaces are known to accept only coordinate notation. See the\r
+Idioms section for more information on the known limitations of some\r
+non-xboard interfaces. It should be safe to send SAN moves if you\r
+receive a "protover 2" (or later) command from the interface, but\r
+otherwise it is best to stick to coordinate notation for maximum\r
+compatibility. An even more conservative approach would be for your\r
+engine to send SAN to the interface only if you have set feature san=1\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
+<dt>RESULT {COMMENT}</dt>\r
+<dd>When your engine detects\r
+that the game has ended by rule, your engine must output a line of the\r
+form "RESULT {comment}" (without the quotes), where RESULT is a PGN\r
+result code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Here\r
+"by rule" means that the game is definitely over because of what\r
+happened on the board. In normal chess, this includes checkmate,\r
+stalemate, triple repetition, the 50 move rule, or insufficient\r
+material; it does not include loss on time or the like.\r
+Examples:\r
+<pre>\r
+ 0-1 {Black mates}\r
+ 1-0 {White mates}\r
+ 1/2-1/2 {Draw by repetition}\r
+ 1/2-1/2 {Stalemate}\r
+</pre>\r
+\r
+<p>\r
+xboard relays the result to the user, the ICS, the other engine in Two\r
+Machines mode, and the PGN save file as required.\r
+<span class="version43">Note that "definitey over" above means that sending this command \r
+will be taken by WinBoard as an unconditional refusal of the engine to play on,\r
+which might cause you to forfeit if the game was in fact not over.\r
+This command should thus not be used to offer draws, accept draws,\r
+or make draw-by-rule claims that are not yet valid in the current position\r
+(but will be after you move).\r
+For offering and claiming such draws, "offer draw" should be used.</span>\r
+</p>\r
+\r
+<p class="version44">\r
+Note that (in accordance with FIDE rules) only KK, KNK, KBK and KBKB with all bishops on the\r
+same color can be claimed as draws on the basis of insufficient mating material.\r
+The end-games KNNK, KBKN, KNKN and KBKB with unlike bishops do have mate positions,\r
+and cannot be claimed.\r
+Complex draws based on locked Pawn chains will not be recognized as draws by most interfaces,\r
+so do not claim in such positions, but just offer a draw or play on.\r
+</p>\r
+\r
+<p class="version44">\r
+Note to GUI programmers: RESULT commands that the engine sends immediately after its move\r
+might be detected by the GUI only after the opponent has moved, because of communication\r
+and scheduling delays, no matter how fast the engine sent it.\r
+Any judgement of the validity of RESULT claims based on te "current" board position\r
+will have to account for this uncertainty.\r
+</p>\r
+</dd>\r
+\r
+<dt>resign</dt>\r
+<dd>If your engine wants to resign, it can send the command "resign".\r
+Alternatively, it can use the "RESULT {comment}" command if the string\r
+"resign" is included in the comment; for example "0-1 {White\r
+resigns}". xboard relays the resignation to the user, the ICS, the\r
+other engine in Two Machines mode, and the PGN save file as required.\r
+<span class="version44">Note that many interfaces work more smoothly if you resign <em>before</em>\r
+you move.</span>\r
+</dd>\r
+\r
+<dt>offer draw</dt>\r
+<dd>If your engine wants to offer a draw by agreement (as opposed to\r
+claiming a draw by rule), it can send the command "offer draw".\r
+xboard relays the offer to the user, the ICS, the other engine in Two\r
+Machines mode, and the PGN save file as required. In Machine White,\r
+Machine Black, or Two Machines mode, the offer is considered valid\r
+until your engine has made two more moves.\r
+<span class="version43">This command must also be used to accept a draw offer.\r
+Do not use the 1/2-1/2 command for that, as the offer might be no longer valid,\r
+in which case a refusal to play on implied by the RESULT command might make you forfeit the game.\r
+"offer draw" should also be used to claim 50-move and 3-fold-repetition draws\r
+that will occur <em>after</em> your move, by sending it <em>before</em> making the move.\r
+WinBoard will grant draw offers without the opponent having any say in\r
+it in situations where draws can be claimed.\r
+Only if the draw cannot be claimed, the offer will be passed to your opponent after you make your next move,\r
+just before WinBoard relays this move to the opponent.\r
+</span>\r
+</dd>\r
+\r
+<dt class="version1">tellopponent MESSAGE</dt>\r
+<dd class="version1">\r
+This command lets the engine give a message to its opponent,\r
+independent of whether the opponent is a user on the local machine or\r
+a remote ICS user (Zippy mode). MESSAGE consists of any characters,\r
+including whitespace, to the end of the line. When the engine is\r
+playing against a user on the local machine, xboard pops up an\r
+information dialog containing the message. When the engine is playing\r
+against an opponent on the ICS (Zippy mode), xboard sends "say\r
+MESSAGE\n" to the ICS.\r
+</dd>\r
+\r
+<dt class="version1">tellothers MESSAGE </dt>\r
+<dd class="version1">This command lets the engine give a message to people watching the\r
+game other than the engine's opponent. MESSAGE consists of any\r
+characters, including whitespace, to the end of the line. When the\r
+engine is playing against a user on the local machine, this command\r
+does nothing. When the engine is playing against an opponent on the\r
+ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.\r
+</dd>\r
+\r
+<dt class="version1">tellall MESSAGE</dt>\r
+<dd class="version1">This command lets the engine give a message to its opponent and\r
+other people watching the game, \r
+independent of whether the opponent is a user on the local machine or\r
+a remote ICS user (Zippy mode). MESSAGE consists of any characters,\r
+including whitespace, to the end of the line. When the engine is\r
+playing against a user on the local machine, xboard pops up an\r
+information dialog containing the message. When the engine is playing\r
+against an opponent on the ICS (Zippy mode), xboard sends "kibitz\r
+MESSAGE\n" to the ICS.\r
+</dd>\r
+\r
+<dt>telluser MESSAGE</dt>\r
+<dd>xboard pops up an information dialog containing the message.\r
+MESSAGE consists of any characters, including whitespace, to the end\r
+of the line.\r
+</dd>\r
+\r
+<dt>tellusererror MESSAGE</dt>\r
+<dd>xboard pops up an error dialog containing the message.\r
+MESSAGE consists of any characters, including whitespace, to the end\r
+of the line.\r
+</dd>\r
+\r
+<dt>askuser REPTAG MESSAGE</dt>\r
+<dd>Here REPTAG is a string containing no whitespace, and MESSAGE\r
+consists of any characters, including whitespace, to the end of the\r
+line. xboard pops up a question dialog that says MESSAGE and\r
+has a typein box. If the user types in "bar", xboard sends "REPTAG\r
+bar" to the engine. The user can cancel the dialog and send nothing.\r
+</dd>\r
+\r
+<dt>tellics MESSAGE</dt>\r
+<dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists\r
+of any characters, including whitespace, to the end of the line.\r
+</dd>\r
+\r
+<dt class="version1">tellicsnoalias MESSAGE</dt>\r
+<dd class="version1">\r
+In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a\r
+character that prevents the ICS from expanding command aliases, if\r
+xboard knows of such a character. (On chessclub.com and chess.net,\r
+"/" is used; on freechess.org, "$" is used.) MESSAGE consists of any\r
+characters, including whitespace, to the end of the line.\r
+</dd>\r
+\r
+<dt class="version43"># COMMENT</dt>\r
+<dd class="version43">\r
+The engine can send any string of printable characters, terminated by a newline,\r
+for inclusion in the winboard.debug file, provided the line starts with a '#' character.\r
+If the engine has set feature debug=1,\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">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
+</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
+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
+\r
+<p>\r
+If the user asks your engine to "show thinking", xboard sends your\r
+engine the "post" command. It sends "nopost" to turn thinking off.\r
+In post mode, your engine sends output lines to show the progress of\r
+its thinking. The engine can send as many or few of these lines as it\r
+wants to, whenever it wants to. Typically they would be sent when the\r
+PV (principal variation) changes or the depth changes. The thinking\r
+output should be in the following format:\r
+</p>\r
+\r
+<pre>ply score time nodes pv</pre>\r
+\r
+<p>Where:</p>\r
+<table>\r
+<tr><td>ply</td><td>Integer giving current search depth.</td></tr>\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
+\r
+<pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>\r
+\r
+<p>\r
+Meaning:\r
+</p>\r
+\r
+<pre>\r
+9 ply, score=1.56, time = 10.84 seconds, nodes=48000, PV = "Nf3 Nc6 Nc3 Nf6"\r
+</pre>\r
+\r
+<p>\r
+Longer example from actual Crafty output:\r
+</p>\r
+\r
+<pre>\r
+ 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6\r
+ 4 116 23 2252 1. Nf3 Nc6 2. e4 e6\r
+ 4 116 27 2589 1. Nf3 Nc6 2. e4 e6\r
+ 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4\r
+ 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4\r
+</pre>\r
+\r
+<p>\r
+You can use the PV to show other things; for instance, while in book,\r
+Crafty shows the observed frequency of different reply moves in its\r
+book. In situations like this where your engine is not really\r
+searching, start the PV with a '(' character:\r
+</p>\r
+\r
+<pre>\r
+ 0 0 0 0 (e4 64%, d4 24%)\r
+</pre>\r
+\r
+<p>\r
+GNU Chess output is very slightly different. The ply number is\r
+followed by an extra nonblank character, and the time is in seconds,\r
+not hundredths of seconds. For compatibility, xboard accepts the\r
+extra character and takes it as a flag indicating the different time\r
+units. Example:\r
+</p>\r
+\r
+<pre>\r
+ 2. 14 0 38 d1d2 e8e7 \r
+ 3+ 78 0 65 d1d2 e8e7 d2d3 \r
+ 3& 14 0 89 d1d2 e8e7 d2d3 \r
+ 3& 76 0 191 d1e2 e8e7 e2e3 \r
+ 3. 76 0 215 d1e2 e8e7 e2e3 \r
+ 4& 15 0 366 d1e2 e8e7 e2e3 e7e6 \r
+ 4. 15 0 515 d1e2 e8e7 e2e3 e7e6 \r
+ 5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4 \r
+ 5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4 \r
+ 5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4 \r
+ 6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 \r
+ 6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 \r
+ 7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 \r
+ 7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 \r
+ 8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5 \r
+ 8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5 \r
+ 9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4 \r
+ d4e4 \r
+ 9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4 \r
+ d4e4 \r
+10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4 \r
+ d4e4 f7f5 e4f4 \r
+10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4 \r
+ d4e4 f7f5 e4f4 \r
+</pre>\r
+\r
+<p>If your engine is pondering (thinking on its opponent's time) in post\r
+mode, it can show its thinking then too. In this case your engine may\r
+omit the hint move (the move it is assuming its opponent will make)\r
+from the thinking lines <em>if and only if</em> it sends xboard the move in\r
+the usual "Hint: xxx" format before sending the first line.\r
+</p>\r
+\r
+<h2><a name="11">11. Time control</a></h2>\r
+\r
+<p>\r
+xboard supports three styles of time control: conventional chess clocks,\r
+the ICS-style incremental clock, and an exact number of seconds per move.\r
+</p>\r
+\r
+<p>In conventional clock mode, every time control period is the same.\r
+That is, if the time control is 40 moves in 5 minutes, then after each\r
+side has made 40 moves, they each get an additional 5 minutes, and so\r
+on, ad infinitum. At some future time it would be nice to support a\r
+series of distinct time controls. This is very low on my personal\r
+priority list, but code donations to the xboard project are accepted,\r
+so feel free to take a swing at it. I suggest you talk to me first,\r
+though.\r
+</p>\r
+\r
+<p>\r
+The command to set a conventional time control looks like this:\r
+</p>\r
+\r
+<pre>\r
+ level 40 5 0\r
+ level 40 0:30 0\r
+</pre>\r
+\r
+<p>\r
+The 40 means that there are 40 moves per time control. The 5 means\r
+there are 5 minutes in the control. In the second example, the 0:30\r
+means there are 30 seconds. The final 0 means that we are in\r
+conventional clock mode.\r
+</p>\r
+\r
+<p class="version43">\r
+Note that the time parameter in this command is not a pure numeric argument,\r
+but in general is a character string, in order to pass the number of seconds.\r
+Engines are encouraged to ignore any unexpected characters at the end of this string,\r
+i.e. following the MIN or MIN:SEC specification.\r
+Future protocol versions might (under control of an appropriate feature)\r
+append such extra characters to this argument,\r
+in order to inform the engine in advance of the time control it can expect after the current session completes.\r
+E.g. "level 40 25+5 0" could mean that the engine has to play 40 moves in 25 minutes,\r
+but should expect to get only 5 minutes for the entire remainder of the game after that,\r
+rather than another 25 minutes for the next 40 moves.\r
+When the time comes, (i.e. after the 40 moves), \r
+it will be informed of the time-control change by receiving a new "level 0 5 0" command,\r
+but engines with advanced time management might want to plan for this in advance.\r
+</p>\r
+\r
+<p>\r
+The command to set an incremental time control looks like this:\r
+</p>\r
+\r
+<pre>\r
+ level 0 2 12\r
+</pre>\r
+\r
+<p>\r
+Here the 0 means "play the whole game in this time control period",\r
+the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As\r
+in conventional clock mode, the second argument to level can be in\r
+minutes and seconds.\r
+</p>\r
+\r
+<p>\r
+At the start of the game, each player's clock is set to base minutes.\r
+Immediately after a player makes a move, inc seconds are added to his\r
+clock. A player's clock counts down while it is his turn. Your flag\r
+can be called whenever your clock is zero or negative. (Your clock\r
+can go negative and then become positive again because of the\r
+increment.)\r
+</p>\r
+\r
+<p class="version44">\r
+The number of moves given in the level command (when non-zero) should \r
+be taken as the number of moves still to do before the specified time\r
+will be added to the clock, if the "level" command is received after\r
+some moves have already been played.\r
+The time given should be interpreted as the time left on its clock\r
+(including any time left over from the previous sessions),\r
+and not necessarily the time that will be added to the clock\r
+after the specified number of moves has been played.\r
+This is only relevant in WinBoard 4.3.xx, which might send the engine\r
+"level" commands during a game,\r
+just before the engine has to start thinking about the first move of \r
+a new time-control session.\r
+Example: if at the start of the game "level 40 60 0" was given \r
+(40 moves per hour),\r
+and the engine receives "level 20 22 0" just before move 41,\r
+it should understand that it should do the next 20 moves in 22 minutes\r
+(pehaps because the secondary session was 20 moves per 15 minutes,\r
+and it had 7 minutes left on its clock after the first 40 moves).\r
+</p>\r
+\r
+<p>\r
+A special rule on some ICS implementations: if you ask for a game with\r
+base=0, the clocks really start at 10 seconds instead of 0. xboard\r
+itself does not know about this rule, so it passes the 0 on to the\r
+engine instead of changing it to 0:10.\r
+</p>\r
+\r
+<p>\r
+ICS also has time odds games. With time odds, each player has his own\r
+(base, inc) pair, but otherwise things work the same as in normal\r
+games. The Zippy xboard accepts time odds games but ignores the fact\r
+that the opponent's parameters are different; this is perhaps not\r
+quite the right thing to do, but gnuchess doesn't understand time\r
+odds. Time odds games are always unrated.\r
+</p>\r
+\r
+<p>\r
+The command to set an exact number of seconds per move looks like this:\r
+</p>\r
+\r
+<pre>\r
+ st 30\r
+</pre>\r
+\r
+<p>\r
+This means that each move must be made in at most 30 seconds. Time not used\r
+on one move does not accumulate for use on later moves.\r
+</p>\r
+\r
+<h2><a name="12">12. Analyze Mode</a></h2>\r
+\r
+<p>xboard supports analyzing fresh games, edited positions, and games\r
+from files. However, all of these look the same from the chess\r
+engine's perspective. Basically, the engine just has to respond to the\r
+"analyze" command. \r
+<span class="version1">\r
+Beginning in protocol version 2,\r
+if your engine does not support analyze mode, it should use\r
+the feature command to set analyze=0. \r
+</span>\r
+The older method of\r
+printing the error message "Error (unknown command): analyze" in\r
+response to the "analyze" command will also work, however.\r
+</p>\r
+\r
+<p>\r
+To enter analyze mode, xboard sends the command sequence "post", "analyze". \r
+Analyze mode in your engine should be\r
+similar to force mode, except that your engine thinks about what move\r
+it would make next if it were on move. Your engine should accept the\r
+following commands while in analyze mode:\r
+</p>\r
+\r
+<ul>\r
+<li>Any legal move, as in force mode</li>\r
+<li><strong>undo</strong> Back up one move and analyze previous position.</li>\r
+<li><strong>new</strong> Reset position to start of game but stay in analyze mode.</li>\r
+<li><span class="version1"><strong>setboard</strong> if you have set feature setboard=1; otherwise <strong>edit</strong>. Exiting edit mode returns to analyze mode.</span></li>\r
+<li><strong>exit</strong> Leave analyze mode.</li>\r
+<li><strong>.</strong> Send a search status update (optional); see below.</li>\r
+<li><span class="version1">\r
+<strong>bk</strong> Show book moves from this position,\r
+if any; see above.</span></li>\r
+<li><span class="version1">\r
+<strong>hint</strong> Show the predicted move from this\r
+position, if any; see above.</span></li>\r
+</ul>\r
+ \r
+<p>\r
+If the user selects "Periodic Updates", xboard will send the string\r
+".\n" to the chess engine periodically during analyze mode, unless the\r
+last PV received began with a '(' character.\r
+</p>\r
+\r
+<p>\r
+The chess engine should respond to ".\n" with a line like this:\r
+</p>\r
+\r
+<pre>\r
+stat01: time nodes ply mvleft mvtot <span class="version1">mvname</span>\r
+</pre>\r
+\r
+<p>Where:</p>\r
+<table>\r
+<tr><td>time</td><td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).</td></tr>\r
+<tr><td>nodes</td><td>Nodes searched so far.</td></tr>\r
+<tr><td>ply</td><td>Search depth so far.</td></tr>\r
+<tr><td>mvleft</td><td>Number of moves left to consider at this depth.</td></tr>\r
+<tr><td>mvtot</td><td>Total number of moves to consider.</td></tr>\r
+<tr class="version1"><td>mvname</td><td>Move currently being considered (SAN or coordinate notation). Optional;\r
+added in protocol version 2.</td></tr>\r
+</table>\r
+\r
+<p>\r
+Examples:\r
+</p>\r
+<pre>\r
+ stat01: 1234 30000 7 5 30\r
+ stat01: 1234 30000 7 5 30 Nf3\r
+</pre>\r
+\r
+<p>\r
+Meaning:\r
+</p>\r
+\r
+<p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a\r
+ total of 30 legal moves, and I have 5 more moves to search\r
+ before going to depth 8. In the second example, of the 30 legal\r
+ moves, the one I am currently searching is Nf3.</p>\r
+\r
+<p>\r
+Implementation of the "." command is optional. If the engine does not\r
+respond to the "." command with a "stat01..." line, xboard will stop\r
+sending "." commands. If the engine does not implement this command,\r
+the analysis window will use a shortened format to display the engine\r
+info.\r
+</p>\r
+\r
+<p>\r
+To give the user some extra information, the chess engine can output\r
+the strings "++\n" and "--\n", to indicate that the current search is\r
+failing high or low, respectively. You don't have to send anything\r
+else to say "Okay, I'm not failing high/low anymore." xboard will\r
+figure this out itself.\r
+</p>\r
+\r
+<h2><a name="13">13. Idioms and backward compatibility features</a></h2>\r
+\r
+<p>\r
+Some engines have variant interpretations of the force/go/white/black,\r
+time/otim, and hard/easy command sets. \r
+In order to accommodate these older engines, xboard uses these commands\r
+only according to the stylized patterns ("idioms") given in this section.\r
+The obsolete white and black commands\r
+have historically been particularly troublesome, and it is recommended\r
+that new engines set the feature colors=0 and/or ignore the commands.\r
+</p>\r
+\r
+<dl>\r
+\r
+<dt>time N</dt>\r
+<dt>otim N</dt>\r
+<dt>MOVE</dt>\r
+<dd>Sent when the opponent makes a move and the engine is already\r
+playing the opposite color.\r
+</dd>\r
+<dt>white</dt>\r
+<dt>go</dt>\r
+<dd>Sent when the engine is in force mode or playing Black but should\r
+switch to playing White. This sequence is sent only when White is\r
+already on move. \r
+<span class="version1">\r
+If you set the feature colors=0, "white" is not sent.\r
+</span>\r
+</dd>\r
+\r
+<dt>black</dt>\r
+<dt>go</dt>\r
+<dd>Sent when the engine is in force mode or playing White but should\r
+switch to playing Black. This sequence is sent only when Black is\r
+already on move. \r
+<span class="version1">\r
+If you set the feature colors=0, "black" is not sent.\r
+</span>\r
+</dd>\r
+\r
+<dt>white</dt>\r
+<dt>time N</dt>\r
+<dt>otim N</dt>\r
+<dt>black</dt>\r
+<dt>go</dt>\r
+<dd>Sent when Black is on move, the engine is in force mode or playing\r
+White, and the engine's clock needs to be updated before it starts\r
+playing. \r
+The initial "white" is a kludge to accommodate GNU Chess\r
+4's variant interpretation of these commands. \r
+<span class="version1">\r
+If you set the feature colors=0, "white" and "black" are not sent.\r
+</span>\r
+</dd>\r
+\r
+<dt>black</dt>\r
+<dt>time N</dt>\r
+<dt>otim N</dt>\r
+<dt>white</dt>\r
+<dt>go</dt>\r
+<dd>Sent when White is on move, the engine is in force mode or playing\r
+Black, and the engine's clock needs to be updated before it starts\r
+playing. See previous idiom. \r
+The initial "black" is a kludge to accommodate GNU Chess\r
+4's variant interpretation of these commands. \r
+<span class="version1">\r
+If you set the feature colors=0, "black" and "white" are not sent.\r
+</span>\r
+</dd>\r
+\r
+<dt>hard</dt>\r
+<dt>easy</dt>\r
+<dd>Sent in sequence to turn off pondering if xboard is not sure\r
+whether it is on. When xboard is sure, it will send "hard" or "easy"\r
+alone. xboard does this because "easy" is a toggle in GNU Chess 4 but\r
+"hard" is an absolute on.\r
+</dd>\r
+</dl>\r
+\r
+<p>\r
+To support older engines, certain additional commands from the engine\r
+to xboard are also recognized. (These are commands by themselves, not\r
+values to be placed in the comment field of the PGN result code.)\r
+These forms are not recommended for new engines; use the PGN result\r
+code commands or the resign command instead.\r
+</p>\r
+\r
+<table>\r
+<tr><th>Command</th> <th>Interpreted as</th></tr>\r
+<tr><td>White resigns </td><td>0-1 {White resigns}</td></tr>\r
+<tr><td>Black resigns </td><td>1-0 {Black resigns}</td></tr>\r
+<tr><td>White </td><td>1-0 {White mates}</td></tr>\r
+<tr><td>Black </td><td>0-1 {Black mates}</td></tr>\r
+<tr><td>Draw </td><td>1/2-1/2 {Draw}</td></tr>\r
+<tr><td>computer mates </td><td>1-0 {White mates} or 0-1 {Black mates}</td></tr>\r
+<tr><td>opponent mates </td><td>1-0 {White mates} or 0-1 {Black mates}</td></tr>\r
+<tr><td>computer resigns </td><td>0-1 {White resigns} or 1-0 {Black resigns}</td></tr>\r
+<tr><td>game is a draw </td><td>1/2-1/2 {Draw}</td></tr>\r
+<tr><td>checkmate </td><td>1-0 {White mates} or 0-1 {Black mates}</td></tr>\r
+</table>\r
+\r
+<p>\r
+Commands in the above table are recognized if they begin a line and\r
+arbitrary characters follow, so (for example) "White mates" will be\r
+recognized as "White", and "game is a draw by the 50 move rule" will\r
+be recognized as "game is a draw". All the commands are\r
+case-sensitive.\r
+</p>\r
+\r
+<p>\r
+An alternative move syntax is also recognized:\r
+</p>\r
+\r
+<table>\r
+<tr><th>Command </th><th>Interpreted as</th></tr>\r
+<tr><td>NUMBER ... MOVE </td><td>move MOVE</td></tr>\r
+</table>\r
+\r
+<p>\r
+Here NUMBER means any string of decimal digits, optionally ending in a\r
+period. MOVE is any string containing no whitespace. In this command\r
+format, xboard requires the "..." even if your engine is playing\r
+White. A command of the form NUMBER MOVE will be ignored. This odd\r
+treatment of the commands is needed for compatibility with gnuchessx.\r
+The original reasons for it are lost in the mists of time, but I\r
+suspect it was originally a bug in the earliest versions of xboard,\r
+before I started working on it, which someone "fixed" in the wrong\r
+way, by creating a special version of gnuchess (gnuchessx) instead of\r
+changing xboard.\r
+</p>\r
+\r
+<p>\r
+Any line that contains the words "offer" and "draw" is recognized as\r
+"offer draw".\r
+</p>\r
+\r
+<p>\r
+The "Illegal move" message is recognized even if spelled "illegal\r
+move" and even if the colon (":") is omitted. This accommodates GNU\r
+Chess 4, which prints messages like "Illegal move (no matching\r
+move)e2e4", and old versions of Crafty, which print just "illegal move".\r
+</p>\r
+\r
+<p>\r
+In Zippy mode, for compatibility with older versions of Crafty,\r
+xboard passes through to ICS any line that begins "kibitz", "whisper",\r
+"tell", or "draw". Do not use this feature in new code. Instead, use the\r
+commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),\r
+"1/2-1/2 {COMMENT}", or "offer draw", as appropriate.\r
+</p>\r
+\r
+<p class="version1">\r
+If the engine responds to the "sd DEPTH" command with an error message\r
+indicating the command is not supported (such as "Illegal move: sd"),\r
+xboard sets an internal flag and subsequently uses the command\r
+"depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the\r
+newline in the middle of this command! New engines should not rely on\r
+this feature.\r
+</p>\r
+\r
+<p class="version1">\r
+If the engine responds to the "st TIME" command with an error message\r
+indicating the command is not supported (such as "Illegal move: st"),\r
+xboard sets an internal flag and subsequently uses the command "level\r
+1 TIME" instead, for the benefit of GNU Chess 4. Note that this is\r
+not a standard use of the level command, as TIME seconds are not added\r
+after each player makes 1 move; rather, each move is made in at most\r
+TIME seconds. New engines should not implement or rely on this\r
+feature.\r
+</p>\r
+\r
+<div class="version1">\r
+<p>\r
+In support of the -firstHost/-secondHost features, which allow a chess\r
+engine to be run on another machine using the rsh protocol, xboard recognizes\r
+error messages that are likely to come from rsh as fatal errors. The following\r
+messages are currently recognized:\r
+</p>\r
+\r
+<ul>\r
+<li>unknown host</li>\r
+<li>No remote directory</li>\r
+<li>not found</li>\r
+<li>No such file</li>\r
+<li>can't alloc</li>\r
+<li>Permission denied</li>\r
+</ul>\r
+</div>\r
+\r
+<p class="version1">\r
+ChessBase/Fritz now implements the xboard/winboard protocol and can use\r
+WinBoard-compatible engines in its GUI. ChessBase's version of the\r
+protocol is generally the same as version 1, except that they have\r
+added the commands <strong>fritz</strong>, <strong>reset</strong>, and\r
+<strong>ponder</strong>, and the edit subcommands\r
+<strong>castle</strong> and <strong>ep</strong>. If you want your\r
+engine to work well with the ChessBase/Fritz GUI, you may need to\r
+implement these additional commands, and you should also be aware of\r
+the peculiar way that ChessBase uses the protocol. See their <a\r
+href="http://www.chessbase.com/Products/engines/winboard/tech.htm"\r
+>web page</a> for documentation.\r
+</p>\r
+\r
+<p class="version1">\r
+ChessMaster 8000 also implements version 1 of the xboard/winboard\r
+protocol and can use WinBoard-compatible engines. The original\r
+release of CM8000 also has one additional restriction: only pure\r
+coordinate notation (e.g., e2e4) is accepted in the move command. A\r
+patch to correct this should be available from The Learning Company\r
+(makers of CM8000) in February 2001.\r
+</p>\r
+\r
+</body>\r
+</html>\r
projects / xboard.git / blobdiff