engine-intf.html

   1 <html>
   2 <head>
   3 <title>Chess Engine Communication Protocol</title>
   4 </head>
   5
   6 <body>
   7 <hr noshade size="2">
   8 <h1>Chess Engine Communication Protocol</h1>
   9 <h2><a href="http://www.tim-mann.org/">Tim Mann</a></h2>
  10 <p>
  11 $Id$<br>
  12 Version 2; implemented in xboard/WinBoard 4.2.1 and later.<br>
  13 Changes since version 1 are indicated in <font color=red>red</font>.
  14 <hr noshade size="2">
  15
  16 <ul>
  17 <li><a href="#1">1. Introduction</a>
  18 <li><a href="#2">2. Connection</a>
  19 <li><a href="#3">3. Debugging</a>
  20 <li><a href="#4">4. How it got this way</a>
  21 <li><a href="#5">5. WinBoard requires Win32 engines</a>
  22 <li><a href="#6">6. Hints on input/output</a>
  23 <li><a href="#7">7. Signals</a>
  24 <li><a href="#8">8. Commands from xboard to the engine</a>
  25 <li><a href="#9">9. Commands from the engine to xboard</a>
  26 <li><a href="#10">10. Thinking Output</a>
  27 <li><a href="#11">11. Time control</a>
  28 <li><a href="#12">12. Analyze Mode</a>
  29 <li><a href="#13">13. Idioms and backward compatibility features</a>
  30 </ul>
  31
  32 <hr noshade size="2">
  33
  34 <h2><a name="1">1. Introduction</a></h2>
  35
  36 <p>
  37 This document is a set of rough notes on the protocol that xboard and
  38 WinBoard use to communicate with gnuchessx and other chess engines.
  39 These notes may be useful if you want to connect a different chess
  40 engine to xboard.  Throughout the notes, "xboard" means both xboard
  41 and WinBoard except where they are specifically contrasted.
  42 </p>
  43
  44 <p>
  45 There are two reasons I can imagine someone wanting to do this:
  46 </p>
  47 <ol>
  48 <li>You have, or are developing, a chess engine but you don't want to
  49 write your own graphical interface.
  50 <li>You have, or are developing,a chess engine, and you want to
  51 interface it to the Internet Chess Server.
  52 </ol>
  53
  54 <p>
  55 In case (2), if you are using xboard, you will need to configure the
  56 "Zippy" code into it, but WinBoard includes this code already.  See
  57 the file <a
  58 href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
  59 in the xboard or WinBoard distribution for more information.
  60
  61 </p>
  62
  63 <p>
  64 These notes are unpolished, but I've attempted to make them complete
  65 in this release.  If you notice any errors, omissions, or misleading
  66 statements, let me know.
  67 </p>
  68
  69 <p>
  70 I'd like to hear from everyone who is trying to interface their own
  71 chess engine to xboard/WinBoard.  Please email me,
  72 tim<a name="nospam">@</a>tim-mann.org.  Also, please join
  73 the mailing list for authors of xboard/WinBoard compatible chess
  74 engines.  The list is now hosted by Yahoo Groups; you can join at <a
  75 href="http://www.egroups.com/group/chess-engines"
  76 >http://www.egroups.com/group/chess-engines</a>, or you can read the
  77 list there without joining.  The list is filtered to prevent spam.
  78 </p>
  79
  80 <h2><a name="2">2. Connection</a></h2>
  81
  82 <p>
  83 An xboard chess engine runs as a separate process from xboard itself,
  84 connected to xboard through a pair of anonymous pipes.  The engine
  85 does not have to do anything special to set up these pipes.  xboard
  86 sets up the pipes itself and starts the engine with one pipe as its
  87 standard input and the other as its standard output.  The engine then
  88 reads commands from its standard input and writes responses to its
  89 standard output.  This is, unfortunately, a little more complicated to
  90 do right than it sounds; see <a href="#6">section 6</a> below.
  91 </p>
  92
  93 <p>
  94 And yes, contrary to some people's expectations, exactly the same
  95 thing is true for WinBoard.  Pipes and standard input/output are
  96 implemented in Win32 and work fine.  You don't have to use DDE, COM,
  97 DLLs, BSOD, or any of the other infinite complexity that
  98 Microsoft has created just to talk between two programs.  A WinBoard
  99 chess engine is a Win32 console program that simply reads from its
 100 standard input and writes to its standard output.  See sections
 101 <a href="#5">5</a> and <a href="#6">6</a> below for additional details.
 102 </p>
 103
 104 <h2><a name="3">3. Debugging</a></h2>
 105
 106 <p>
 107 To diagnose problems in your engine's interaction with xboard, use the
 108 -debug flag on xboard's command line to see the messages that are
 109 being exchanged.  In WinBoard, these messages are written to the file
 110 WinBoard.debug instead of going to the screen.
 111 </p>
 112
 113 <p>
 114 You can turn debug mode on or off while WinBoard is running by
 115 pressing Ctrl+Alt+F12.  You can turn debug mode on or off while xboard
 116 is running by binding DebugProc to a shortcut key (and pressing the
 117 key!); see the instructions on shortcut keys in the xboard man page.
 118 </p>
 119
 120 <p>
 121 While your engine is running under xboard/WinBoard, you can send a
 122 command directly to the engine by pressing Shift+1 (xboard) or Alt+1
 123 (WinBoard 4.0.3 and later).  This brings up a dialog that you can type
 124 your command into.  Press Shift+2 (Alt+2) instead to send to the
 125 second chess engine in Two Machines mode.  On WinBoard 4.0.2 and earlier,
 126 Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict
 127 with typing the @-sign on some European keyboards.
 128 </p>
 129
 130 <h2><a name="4">4. How it got this way</a></h2>
 131
 132 <p>
 133 Originally, xboard was just trying to talk to the existing
 134 command-line interface of GNU Chess 3.1+ and 4, which was designed
 135 for people to type commands to.  So the communication protocol is very
 136 ad-hoc.  It might have been good to redesign it early on, but because
 137 xboard and GNU Chess are separate programs, I didn't want to force
 138 people to upgrade them together to versions that matched.  I
 139 particularly wanted to keep new versions of xboard working with old
 140 versions of GNU Chess, to make it easier to compare the play of old
 141 and new gnuchess versions.  I didn't foresee the need for a clean
 142 protocol to be used with other chess engines in the future.
 143 </p>
 144
 145 <p>
 146 Circumstances have changed over the years, and now there are many more
 147 engines that work with xboard.  I've had to make the protocol
 148 description more precise, I've added some features that GNU Chess
 149 does not support, and I've specified the standard semantics of a few
 150 features to be slightly different from what GNU Chess 4 does.
 151 </p>
 152
 153 <p>
 154 <font color=red>
 155 This release of the protocol specification is the first to carry a
 156 version number of its own -- version 2.  Previous releases simply
 157 carried a last-modified date and were loosely tied to specific
 158 releases of xboard and WinBoard.  The version number "1" applies
 159 generally to all those older versions of the protocol.
 160 </font>
 161
 162 <font color=red>
 163 <p>Protocol version 2 remains compatible with older engines but has
 164 several new capabilities.  In particular, it adds the
 165 "feature" command, a new mechanism for making backward-compatible
 166 changes and extensions to the protocol.  Engines that do not support a
 167 particular new feature do not have to use it; new features are not
 168 enabled unless the engine specifically requests them using the feature
 169 command.  If an engine does not send the feature command at all, the
 170 protocol behavior is nearly identical to version 1.  Several new
 171 features can be selected by the feature command in version 2,
 172 including the "ping" command (recommended for all engines), the
 173 "setboard" command, and many optional parameters.  Additional features
 174 will probably be added in future versions.
 175 </p>
 176 </font>
 177
 178 <h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
 179
 180 <p>
 181 Due to some Microsoft brain damage that I don't understand, WinBoard
 182 does not work with chess engines that were compiled to use a DOS
 183 extender for 32-bit addressing.  (Probably not with 16-bit DOS or
 184 Windows programs either.)  WinBoard works only with engines that are
 185 compiled for the Win32 API.  You can get a free compiler that targets
 186 the Win32 API from <a href="http://sources.redhat.com/cygwin/"
 187 >http://sources.redhat.com/cygwin/</a>.  I think DJGPP 2.x should also
 188 work if you use the RSXNTDJ extension, but I haven't tried it.  Of
 189 course, Microsoft Visual C++ will work.  Most likely the other
 190 commercial products that support Win32 will work too (Borland, etc.),
 191 but I have not tried them.  Delphi has been successfully used to write
 192 engines for WinBoard; if you want to do this, Tony Werten has donated
 193 some <a href="http://www.tim-mann.org/winboard/delphi.txt" >sample
 194 code</a> that should help you get started.
 195 </p>
 196
 197 <h2><a name="6">6. Hints on input/output</a></h2>
 198
 199 <p>
 200 Beware of using buffered I/O in your chess engine.  The C stdio
 201 library, C++ streams, and the I/O packages in most other languages use
 202 buffering both on input and output.  That means two things.  First,
 203 when your engine tries to write some characters to xboard, the library
 204 stashes them in an internal buffer and does not actually write them to
 205 the pipe connected to xboard until either the buffer fills up or you
 206 call a special library routine asking for it to be flushed.  (In C
 207 stdio, this routine is named <tt>fflush</tt>.)  Second, when your engine tries
 208 to read some characters from xboard, the library does not read just
 209 the characters you asked for -- it reads all the characters that are
 210 currently available (up to some limit) and stashes any characters you
 211 are not yet ready for in an internal buffer.  The next time you ask to
 212 read, you get the characters from the buffer (if any) before the
 213 library tries to read more data from the actual pipe.
 214 </p>
 215
 216 <p>
 217 Why does this cause problems?  First, on the output side, remember
 218 that your engine produces output in small quantities (say, a few
 219 characters for a move, or a line or two giving the current analysis),
 220 and that data always needs to be delivered to xboard/WinBoard for
 221 display immediately.  If you use buffered output, the data you print
 222 will sit in a buffer in your own address space instead of being
 223 delivered.
 224 </p>
 225
 226 <p>
 227 You can usually fix the output buffering problem by asking for the
 228 buffering to be turned off.  In C stdio, you do this by calling
 229 <tt>setbuf(stdout, NULL)</tt>.  A more laborious and error-prone
 230 method is to carefully call <tt>fflush(stdout)</tt> after every line
 231 you output; I don't recommend this.  In C++, you can try
 232 <tt>cout.setf(ios::unitbuf)</tt>, which is documented in current
 233 editions of "The C++ Programming Language," but not older ones.
 234 Another C++ method that might work is
 235 <tt>cout.rdbuf()-&gt;setbuf(NULL, 0)</tt>.  Alternatively, you can
 236 carefully call <tt>cout.flush()</tt> after every line you output;
 237 again, I don't recommend this.
 238 </p>
 239
 240 <p>
 241 Another way to fix the problem is to use unbuffered operating system
 242 calls to write directly to the file descriptor for standard output.
 243 On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).
 244 On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32
 245 native routines like <tt>WriteFile</tt>.
 246 </p>
 247
 248 <p>
 249 Second, on the input side, you are likely to want to poll during your
 250 search and stop it if new input has come in.  If you implement
 251 pondering, you'll need this so that pondering stops when the user
 252 makes a move.  You should also poll during normal thinking on your
 253 move, so that you can implement the "?" (move now) command, and so
 254 that you can respond promptly to a "result", "force", or "quit"
 255 command if xboard wants to end the game or terminate your engine.
 256 Buffered input makes polling more complicated -- when you poll, you
 257 must stop your search if there are <em>either</em> characters in the buffer
 258 <em>or</em> characters available from the underlying file descriptor.
 259 </p>
 260
 261 <p>
 262 The most direct way to fix this problem is to use unbuffered operating
 263 system calls to read (and poll) the underlying file descriptor
 264 directly.  On Unix, use <tt>read(0, ...)</tt> to read from standard input, and
 265 use <tt>select()</tt> to poll it.  See the man pages read(2) and select(2).
 266 (Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to
 267 poll for input.  It is not very portable; that is, it does not exist
 268 on all versions of Unix, and is broken on some that do have it.)  On
 269 Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native
 270 Win32 <tt>ReadFile()</tt> to read.  Unfortunately, under Win32, the function to
 271 use for polling is different depending on whether the input device is
 272 a pipe, a console, or something else.  (More Microsoft brain damage
 273 here -- did they never hear of device independence?)  For pipes, you
 274 can use <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).
 275 For consoles,
 276 you can use <tt>GetNumberOfConsoleInputEvents</tt>.  For sockets only, you can
 277 use <tt>select()</tt>.  It might be possible to use
 278 <tt>WaitForSingleObject</tt> more
 279 generally, but I have not tried it.  Some code to do these things can
 280 be found in Crafty's utility.c, but I don't guarantee that it's all
 281 correct or optimal.
 282 </p>
 283
 284 <p>
 285 A second way to fix the problem might be to ask your I/O library not
 286 to buffer on input.  It should then be safe to poll the underlying
 287 file descriptor as described above.  With C, you can try calling
 288 <tt>setbuf(stdin, NULL)</tt>.  However, I have never tried this.  Also, there
 289 could be problems if you use <tt>scanf()</tt>, at least with certain patterns,
 290 because <tt>scanf()</tt> sometimes needs to read one extra character and "push
 291 it back" into the buffer; hence, there is a one-character pushback
 292 buffer even if you asked for stdio to be unbuffered.  With C++, you
 293 can try <tt>cin.rdbuf()-&gt;setbuf(NULL, 0)</tt>, but again, I have never tried
 294 this.
 295 </p>
 296
 297 <p>
 298 A third way to fix the problem is to check whether there are
 299 characters in the buffer whenever you poll.  C I/O libraries generally
 300 do not provide any portable way to do this.  Under C++, you can use
 301 <tt>cin.rdbuf()-&gt;in_avail()</tt>.  This method has been reported to
 302 work with
 303 EXchess.  Remember that if there are no characters in the buffer, you
 304 still have to poll the underlying file descriptor too, using the
 305 method described above.
 306 </p>
 307
 308 <p>
 309 A fourth way to fix the problem is to use a separate thread to read
 310 from stdin.  This way works well if you are familiar with thread
 311 programming.  This thread can be blocked waiting for input to come in
 312 at all times, while the main thread of your engine does its thinking.
 313 When input arrives, you have the thread put the input into a buffer
 314 and set a flag in a global variable.  Your search routine then
 315 periodically tests the global variable to see if there is input to
 316 process, and stops if there is.  WinBoard and my Win32 ports of ICC
 317 timestamp and FICS timeseal use threads to handle multiple input
 318 sources.
 319 </p>
 320
 321 <h2><a name="7">7. Signals</a></h2>
 322
 323 <p>Engines that run on Unix need to be concerned with two Unix
 324 signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>.  This applies both to
 325 engines that run under xboard and (the unusual case of) engines that
 326 WinBoard remotely runs on a Unix host using the -firstHost or
 327 -secondHost feature.  It does not apply to engines that run on
 328 Windows, because Windows does not have Unix-style signals.
 329 <font color=red>
 330 Beginning with version 2, you can now turn off the use of
 331 either or both
 332 signals.  See the "feature" command in <a href="#6">section 9</a> below.
 333 </font>
 334 </p>
 335
 336 <p>First, when an engine is sent the "quit" command, it is also given
 337 a <tt>SIGTERM</tt> signal shortly afterward to make sure it goes away.
 338 If your engine reliably responds to "quit", and the signal causes
 339 problems for you, you should either ignore it by calling
 340 <tt>signal(SIGTERM, SIG_IGN)</tt> at the start of your program,
 341 or disable it with the "feature" command.</p>
 342
 343 <p>Second, xboard will send an interrupt signal (<tt>SIGINT</tt>) at
 344 certain times when it believes the engine may not be listening to user
 345 input (thinking or pondering).  WinBoard currently does this only when
 346 the engine is running remotely using the -firstHost or -secondHost
 347 feature, not when it is running locally.  You probably need to know
 348 only enough about this grungy feature to keep it from getting in your
 349 way.
 350 </p>
 351
 352 <p>
 353 The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess 4
 354 on systems where its input polling code is broken or disabled.
 355 Because they work in a rather peculiar way, it is recommended that you
 356 either ignore <tt>SIGINT</tt> by having your engine call
 357 <tt>signal(SIGINT, SIG_IGN)</tt>, or disable it with the "feature"
 358 command.</p>
 359
 360 <p>
 361 Here are details for the curious.  If xboard needs to send a command
 362 when it is the chess engine's move (such as before the "?" command),
 363 it sends a <tt>SIGINT</tt> first.  If xboard needs to send commands when it is
 364 not the chess engine's move, but the chess engine may be pondering
 365 (thinking on its opponent's time) or analyzing (analysis or analyze
 366 file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.
 367 Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard
 368 issues more commands.  This behavior is necessary for GNU Chess 4.  The
 369 first <tt>SIGINT</tt> stops it from pondering until the next move, but on some
 370 systems, GNU Chess 4 will die if it receives a <tt>SIGINT</tt> when not
 371 actually thinking or pondering.
 372 </p>
 373
 374 <p>
 375 There are two reasons why WinBoard does not send the Win32 equivalent
 376 of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local
 377 engines.  First, the Win32 GNU Chess 4 port does not need it.  Second, I
 378 could not find a way to get it to work.  Win32 seems to be designed
 379 under the assumption that only console applications, not windowed
 380 applications, would ever want to send a <tt>CTRL_C_EVENT</tt>.
 381 </p>
 382
 383 <h2><a name="8">8. Commands from xboard to the engine</a></h2>
 384
 385 <p>
 386 All commands from xboard to the engine end with a newline (\n), even
 387 where that is not explicitly stated.  All your output to xboard must
 388 be in complete lines; any form of prompt or partial line will cause
 389 problems.
 390 </p>
 391
 392 <p>
 393 At the beginning of each game, xboard sends an initialization string.
 394 This is currently "new\nrandom\n" unless the user changes it with the
 395 initString or secondInitString option.
 396 </p>
 397
 398 <p>
 399 xboard normally reuses the same chess engine process for multiple
 400 games.  At the end of a game, xboard will send the "force" command
 401 (see below) to make sure your engine stops thinking about the current
 402 position.  It will later send the initString again to start a new
 403 game.  If your engine can't play multiple games, you can disable reuse
 404 <font color=red>
 405 either with the "feature" command (beginning in protocol version
 406 2; see below) or
 407 </font>
 408 with xboard's -xreuse (or -xreuse2) command line
 409 option.  xboard will then ask the process to quit after each game and
 410 start a new process for the next game.
 411 </p>
 412
 413 <dl>
 414 <dt><strong>xboard</strong>
 415 <dd>This command will be sent once immediately after your engine
 416 process is started.  You can use it to put your engine into "xboard
 417 mode" if that is needed.  If your engine prints a prompt to ask for
 418 user input, you must turn off the prompt and output a newline when the
 419 "xboard" command comes in.
 420 <p>
 421
 422 <dt><font color=red><strong>protover N</strong></font>
 423 <dd><font color=red>
 424 Beginning in protocol version 2 (in which N=2), this command will
 425 be sent immediately after the "xboard" command.  If you receive some
 426 other command immediately after "xboard" (such as "new"), you can
 427 assume that protocol version 1 is in use.  The "protover" command is
 428 the only new command that xboard always sends in version 2.  All other
 429 new commands to the engine are sent only if the engine first enables
 430 them with the "feature" command.  Protocol versions will always be
 431 simple integers so that they can easily be compared.
 432
 433 <p>Your engine should reply to the protover command by sending the
 434 "feature" command (see below) with the list of non-default feature
 435 settings that you require, if any.
 436
 437 <p>Your engine should never refuse to run due to receiving a higher
 438 protocol version number than it is expecting!  New protocol versions
 439 will always be compatible with older ones by default; the larger
 440 version number is simply a hint that additional "feature" command
 441 options added in later protocol versions may be accepted.
 442 </font>
 443 <p>
 444
 445 <dt><font color=red><strong>accepted</strong></font>
 446 <dt><font color=red><strong>rejected</strong></font>
 447 <dd><font color=red>
 448 These commands may be sent to your engine in reply to the "feature"
 449 command; see its documentation below.
 450 </font>
 451 <p>
 452
 453 <dt><strong>new</strong>
 454 <dd>Reset the board to the standard chess starting position.  Set
 455 White on move.  Leave force mode and set the engine to play Black.
 456 Associate the engine's clock with Black and the opponent's clock with
 457 White.  Reset clocks and time controls to the start of a new game.
 458 Stop clocks.  Do not ponder on this move, even if pondering is on.
 459 Remove any search depth limit previously set by the sd command.
 460 <p>
 461
 462 <dt><strong>variant VARNAME</strong>
 463 <dd>If the game is not standard chess, but a variant, this command is
 464 sent after "new" and before the first move or "edit" command.  Currently
 465 defined variant names are:
 466
 467 <table>
 468 <tr align="left"><th>wildcastle<td>Shuffle chess where king can castle from d file
 469 <tr align="left"><th>nocastle<td>Shuffle chess with no castling at all
 470 <tr align="left"><th>fischerandom<td>Fischer Random (not supported yet)
 471 <tr align="left"><th>bughouse<td>Bughouse, ICC/FICS rules
 472 <tr align="left"><th>crazyhouse<td>Crazyhouse, ICC/FICS rules
 473 <tr align="left"><th>losers<td>Win by losing all pieces or getting mated (ICC)
 474 <tr align="left"><th>suicide<td>Win by losing all pieces including king,
 475 or by having fewer pieces when one player has no legal moves (FICS)
 476 <tr align="left"><th><font color=red>giveaway</font>
 477 <td><font color=red>Win by losing all pieces including king,
 478 or by having no legal moves (ICC)</font>
 479 <tr align="left"><th>twokings<td>Weird ICC wild 9
 480 <tr align="left"><th>kriegspiel<td>Kriegspiel (engines not supported)
 481 <tr align="left"><th>atomic<td>Atomic
 482 <tr align="left"><th>3check<td>Win by giving check 3 times
 483 <tr align="left"><th>unknown<td>Unknown variant (not supported)
 484 </table>
 485 <p>
 486
 487 <dt><strong>quit</strong>
 488 <dd>The chess engine should immediately exit.  This command is used
 489 when xboard is itself exiting, and also between games if the -xreuse
 490 command line option is given (or -xreuse2 for the second engine).
 491 See also <a href="#7">Signals</a> above.
 492 <p>
 493
 494 <dt><strong>random</strong>
 495 <dd>This command is specific to GNU Chess 4.  You can either ignore it
 496 completely (that is, treat it as a no-op) or implement it as GNU Chess
 497 does.  The command toggles "random" mode (that is, it sets random =
 498 !random).  In random mode, the engine adds a small random value to its
 499 evaluation function to vary its play.  The "new" command sets random
 500 mode off.
 501 <p>
 502
 503 <dt><strong>force</strong>
 504 <dd>Set the engine to play neither color ("force mode").  Stop clocks.
 505 The engine should check that moves received in force mode are legal
 506 and made in the proper turn, but should not think, ponder, or make
 507 moves of its own.
 508 <p>
 509
 510 <dt><strong>go</strong>
 511 <dd>Leave force mode and set the engine to play the color that is on
 512 move.  Associate the engine's clock with the color that is on move,
 513 the opponent's clock with the color that is not on move.  Start the engine's
 514 clock.  Start thinking and eventually make a move.
 515 <p>
 516
 517 <dt><font color=red><strong>playother</strong></font>
 518 <dd>
 519 <font color=red>
 520 (This command is new in protocol version 2.  It is not
 521 sent unless you enable it with the feature command.)
 522 Leave force mode and set the engine to play the color that is <i>not</i> on
 523 move.  Associate the opponent's clock with the color that is on move,
 524 the engine's clock with the color that is not on move.  Start the opponent's
 525 clock.  If pondering is enabled, the engine should begin pondering.
 526 If the engine later receives a move, it should start thinking and eventually
 527 reply.
 528 </font>
 529 <p>
 530
 531 <dt><strong>white</strong>
 532 <dd>
 533 <font color=red>
 534 (This command is obsolete as of protocol version 2, but is still
 535 sent in some situations to accommodate older engines unless you disable it
 536 with the feature command.)
 537 </font>
 538 Set White on move.  Set the engine to play Black.  Stop clocks.
 539 <p>
 540
 541 <dt><strong>black</strong>
 542 <dd>
 543 <font color=red>
 544 (This command is obsolete as of protocol version 2, but is still
 545 sent in some situations to accommodate older engines unless you disable it
 546 with the feature command.)
 547 </font>
 548 Set Black on move.  Set the engine to play White.  Stop clocks.
 549 <p>
 550
 551 <dt><strong>level MPS BASE INC</strong>
 552 <dd>Set time controls.  See the <a href="#11">Time Control</a> section below.
 553 <p>
 554
 555 <dt><strong>st TIME</strong>
 556 <dd>Set time controls.  See the <a href="#11">Time Control</a> section
 557 below. The commands "level" and "st" are not used together.
 558 <p>
 559
 560 <dt><strong>sd DEPTH</strong>
 561 <dd>The engine should limit its thinking to DEPTH ply.
 562 <p>
 563
 564 <dt><strong>time N</strong>
 565 <dd>Set a clock that always belongs to the engine.  N is a number in
 566   centiseconds (units of 1/100 second).  Even if the engine changes to
 567   playing the opposite color, this clock remains with the engine.
 568 <p>
 569
 570 <dt><strong>otim N</strong>
 571
 572 <dd>Set a clock that always belongs to the opponent.  N is a number in
 573 centiseconds (units of 1/100 second).  Even if the opponent changes to
 574 playing the opposite color, this clock remains with the opponent.
 575 <p>
 576 If needed for purposes of board display in force mode (where the
 577 engine is not participating in the game) the time clock should be
 578 associated with the last color that the engine was set to play, the
 579 otim clock with the opposite color.
 580 </p>
 581
 582 <p>
 583 <font color=red>
 584 Beginning in protocol version 2, if you can't handle the time and
 585 otim commands, you can use the "feature" command to disable them; see
 586 below.
 587 </font>
 588 The following techniques from older protocol versions also
 589 work: You can ignore the time and otim commands (that is, treat them
 590 as no-ops), or send back "Error (unknown command): time" the first
 591 time you see "time".
 592 </p>
 593
 594 <dt><strong>MOVE</strong>
 595 <dd>See below for the syntax of moves.  If the move is illegal, print
 596 an error message; see the section "<a href="#9">Commands from the engine to
 597 xboard</a>".  If the move is legal and in turn, make it.  If not in force
 598 mode, stop the opponent's clock, start the engine's clock, start
 599 thinking, and eventually make a move.
 600 <p>
 601 When xboard sends your engine a move, it normally sends coordinate
 602 algebraic notation.  Examples:
 603 <p>
 604 <table>
 605 <tr align="left"><td>Normal moves:<td>e2e4
 606 <tr align="left"><td>Pawn promotion:<td>e7e8q
 607 <tr align="left"><td>Castling:<td>e1g1, e1c1, e8g8, e8c8
 608 <tr align="left"><td>Bughouse/crazyhouse drop:<td>P@h3
 609 <tr align="left"><td>ICS Wild 0/1 castling:<td>d1f1, d1b1, d8f8, d8b8
 610 <tr align="left"><td>FischerRandom castling:<td>O-O, O-O-O (oh, not zero)
 611 </table>
 612
 613 <p>
 614 <font color=red>
 615 Beginning in protocol version 2, you can use the feature command
 616 to select SAN (standard algebraic notation) instead; for example, e4,
 617 Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3.  Note that the last form,
 618 P@h3, is a extension to the PGN standard's definition of SAN, which does
 619 not support bughouse or crazyhouse.
 620 </font>
 621 </p>
 622
 623 <p>
 624 xboard doesn't reliably detect illegal moves, because it does not keep
 625 track of castling unavailability due to king or rook moves, or en
 626 passant availability.  If xboard sends an illegal move, send back an
 627 error message so that xboard can retract it and inform the user; see
 628 the section "<a href="#9">Commands from the engine to xboard</a>".
 629 </p>
 630
 631 <dt><font color=red><strong>usermove MOVE</strong></font>
 632 <dd><font color=red>
 633 By default, moves are sent to the engine without a command name;
 634 the notation is just sent as a line by itself.
 635 Beginning in protocol version 2, you can use the feature command
 636 to cause the command name "usermove" to be sent before the move.
 637 Example: "usermove e2e4".
 638 </font>
 639 </p>
 640
 641 <dt><strong>?</strong>
 642 <dd>Move now.  If your engine is thinking, it should move immediately;
 643   otherwise, the command should be ignored (treated as a no-op).  It
 644   is permissible for your engine to always ignore the ? command.  The
 645   only bad consequence is that xboard's Move Now menu command will do
 646   nothing.
 647 <p>
 648 It is also permissible for your engine to move immediately if it gets
 649 any command while thinking, as long as it processes the command right
 650 after moving, but it's preferable if you don't do this.  For example,
 651 xboard may send post, nopost, easy, hard, force, quit,
 652 <font color=red>
 653 or other commands
 654 </font>
 655 while the engine is on move.
 656 </p>
 657
 658 <dt><font color=red><strong>ping N</strong></font>
 659 <dd>
 660 <font color=red>
 661 In this command, N is a decimal number.  When you receive the command,
 662 reply by sending the string <strong>pong N</strong>, where N is the
 663 same number you received.  Important: You must not reply to a "ping"
 664 command until you have finished executing all commands that you
 665 received before it.  Pondering does not count; if you receive a ping
 666 while pondering, you should reply immediately and continue pondering.
 667 Because of the way xboard uses the ping command, if you implement the
 668 other commands in this protocol, you should never see a "ping" command
 669 when it is your move; however, if you do, you must not send the "pong"
 670 reply to xboard until after you send your move.  For example, xboard
 671 may send "?" immediately followed by "ping".  If you implement the "?"
 672 command, you will have moved by the time you see the subsequent ping
 673 command.  Similarly, xboard may send a sequence like "force", "new",
 674 "ping".  You must not send the pong response until after you have
 675 finished executing the "new" command and are ready for the new game to
 676 start.
 677
 678 <p>
 679 The ping command is new in protocol version 2 and will not be sent
 680 unless you enable it with the "feature" command.  Its purpose is to
 681 allow several race conditions that could occur in previous versions of
 682 the protocol to be fixed, so it is highly recommended that you
 683 implement it.  It is especially important in simple engines that do
 684 not ponder and do not poll for input while thinking, but it is needed in all
 685 engines.
 686 </p>
 687 </font>
 688
 689 <dt><strong>draw</strong>
 690 <dd>The engine's opponent offers the engine a draw.  To accept the
 691 draw, send "offer draw".  To decline, ignore the offer (that is, send
 692 nothing).  If you're playing on ICS, it's possible for the draw offer
 693 to have been withdrawn by the time you accept it, so don't assume the
 694 game is over because you accept a draw offer.  Continue playing until
 695 xboard tells you the game is over.  See also "offer draw" below.
 696 <p>
 697
 698 <dt><strong>result RESULT {COMMENT}</strong>
 699 <dd>After the end of each game, xboard will send you a result command.
 700 You can use this command to trigger learning.  RESULT is either 1-0,
 701 0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
 702 was a draw, or the game was unfinished.  The COMMENT string is purely
 703 a human-readable comment; its content is unspecified and subject to
 704 change.  In ICS mode, it is passed through from ICS uninterpreted.
 705 Example: <pre>result 1-0 {White mates}</pre>
 706 <p>
 707 Here are some notes on interpreting the "result" command.  Some apply
 708 only to playing on ICS ("Zippy" mode).
 709 </p>
 710
 711 <p>
 712 If you won but did not just play a mate, your opponent must have
 713 resigned or forfeited.  If you lost but were not just mated, you
 714 probably forfeited on time, or perhaps the operator resigned manually.
 715 If there was a draw for some nonobvious reason, perhaps your opponent
 716 called your flag when he had insufficient mating material (or vice
 717 versa), or perhaps the operator agreed to a draw manually.
 718 </p>
 719
 720 <p>
 721 You will get a result command even if you already know the game ended
 722 -- for example, after you just checkmated your opponent.  In fact, if
 723 you send the "RESULT {COMMENT}" command (discussed below), you will
 724 simply get the same thing fed back to you with "result" tacked in
 725 front.  You might not always get a "result *" command, however.  In
 726 particular, you won't get one in local chess engine mode when the user
 727 stops playing by selecting Reset, Edit Game, Exit or the like.
 728 </p>
 729
 730 <dt><font color=red><strong>setboard FEN</strong></font>
 731 <dd><font color=red>
 732 The setboard command is the new way to set up positions, beginning
 733 in protocol version 2.  It is not used unless it has been selected
 734 with the feature command.  Here FEN is a position in Forsythe-Edwards
 735 Notation, as defined in the PGN standard.
 736
 737 <p><i>Illegal positions:</i> Note that either setboard or edit can
 738 be used to send an illegal position to the engine.  The user can
 739 create any position with xboard's Edit Position command (even, say,
 740 an empty board, or a board with 64 white kings and no black ones).
 741 If your engine receives a position that it considers illegal,
 742 I suggest that you send the response "tellusererror Illegal position",
 743 and then respond to any attempted move with "Illegal move" until
 744 the next new, edit, or setboard command.</p>
 745 </font>
 746 <p>
 747
 748 <dt><strong>edit</strong>
 749 <dd>
 750 <font color=red>
 751 The edit command is the old way to set up positions.  For compatibility
 752 with old engines, it is still used by default, but new engines may prefer
 753 to use the feature command (see below) to cause xboard to use setboard instead.
 754 </font>
 755 The edit command puts the chess engine into a special mode, where
 756 it accepts the following subcommands:
 757 <table>
 758 <tr align="left"><th>c<td>change current piece color, initially white
 759 <tr align="left"><th>Pa4 (for example)<td>place pawn of current color on a4
 760 <tr align="left"><th>xa4 (for example)<td>empty the square a4 (not used by xboard)
 761 <tr align="left"><th>#<td>clear board
 762 <tr align="left"><th>.<td>leave edit mode
 763 </table>
 764 <font color=red>
 765 See the Idioms section below for additional subcommands used in
 766 ChessBase's implementation of the protocol.
 767 </font>
 768
 769 <p>The edit command does not change the side to move.  To set up a
 770 black-on-move position, xboard uses the following command sequence:
 771 </p>
 772 <pre>
 773     new
 774     force
 775     a2a3
 776     edit
 777     &lt;edit commands&gt;
 778     .
 779 </pre>
 780
 781 <p>
 782 This sequence is used to avoid the "black" command, which is now
 783 considered obsolete and which many engines never did implement as
 784 specified in this document.
 785 </p>
 786
 787 <p>
 788 After an edit command is complete, if a king and a rook are on their
 789 home squares, castling is assumed to be available to them.  En passant
 790 capture is assumed to be illegal on the current move regardless of the
 791 positions of the pawns.  The clock for the 50 move rule starts at
 792 zero, and for purposes of the draw by repetition rule, no prior
 793 positions are deemed to have occurred.
 794 </p>
 795
 796 <dt><strong>hint</strong>
 797 <dd>If the user asks for a hint, xboard sends your engine the command
 798 "hint".  Your engine should respond with "Hint: xxx", where xxx is a
 799 suggested move.  If there is no move to suggest, you can ignore the
 800 hint command (that is, treat it as a no-op).
 801 <p>
 802
 803 <dt><strong>bk</strong>
 804 <dd>If the user selects "Book" from the xboard menu, xboard will send
 805 your engine the command "bk".  You can send any text you like as the
 806 response, as long as each line begins with a blank space or tab (\t)
 807 character, and you send an empty line at the end.  The text pops up in
 808 a modal information dialog.
 809 <p>
 810
 811 <dt><strong>undo</strong>
 812 <dd>If the user asks to back up one move, xboard will send you the
 813 "undo" command.  xboard will not send this command without putting you
 814 in "force" mode first, so you don't have to worry about what should
 815 happen if the user asks to undo a move your engine made.  (GNU Chess 4
 816 actually switches to playing the opposite color in this case.)
 817 <p>
 818
 819 <dt><strong>remove</strong>
 820 <dd>If the user asks to retract a move, xboard will send you the
 821 "remove" command.  It sends this command only when the user is on
 822 move.  Your engine should undo the last two moves (one for each
 823 player) and continue playing the same color.
 824 <p>
 825
 826 <dt><strong>hard</strong>
 827 <dd>Turn on pondering (thinking on the opponent's time, also known as
 828 "permanent brain").  xboard will not make any assumption about what
 829 your default is for pondering or whether "new" affects this setting.
 830 <p>
 831
 832 <dt><strong>easy</strong>
 833 <dd>Turn off pondering.
 834 <p>
 835
 836 <dt><strong>post</strong>
 837 <dd>Turn on thinking/pondering output.
 838 See <a href="#10">Thinking Output</a> section.
 839 <p>
 840
 841 <dt><strong>nopost</strong>
 842 <dd>Turn off thinking/pondering output.
 843 <p>
 844
 845 <dt><strong>analyze</strong>
 846 <dd>Enter analyze mode.  See <a href="#12">Analyze Mode</a> section.
 847 <p>
 848
 849 <dt><strong>name X</strong> <dd>This command informs the engine of its
 850 opponent's name.  When the engine is playing on a chess server, xboard
 851 obtains the opponent's name from the server.
 852 <font color=red>
 853 When the engine is
 854 playing locally against a human user, xboard obtains the user's login
 855 name from the local operating system.  When the engine is playing
 856 locally against another engine, xboard uses either the other engine's
 857 filename or the name that the other engine supplied in the myname
 858 option to the feature command.  By default, xboard uses the name
 859 command only when the engine is playing on a chess server.  Beginning
 860 in protocol version 2, you can change this with the name option to the
 861 feature command; see below.
 862 </font>
 863 <p>
 864
 865 <dt><strong>rating</strong>
 866 <dd>In ICS mode, xboard obtains the ICS opponent's rating from the
 867 "Creating:" message that appears before each game.  (This message may
 868 not appear on servers using outdated versions of the FICS code.)  In
 869 Zippy mode, it sends these ratings on to the chess engine using the
 870 "rating" command.  The chess engine's own rating comes first, and if
 871 either opponent is not rated, his rating is given as 0.
 872 <font color=red>
 873 In the future this command may also be used in other modes, if ratings
 874 are known.
 875 </font>
 876 Example: <pre>rating 2600 1500</pre>
 877 <p>
 878
 879 <dt><font color=red><strong>ics HOSTNAME</strong></font>
 880 <dd><font color=red>
 881 If HOSTNAME is "-", the engine is playing against a local
 882 opponent; otherwise, the engine is playing on an Internet Chess Server
 883 (ICS) with the given hostname.  This command is new in protocol
 884 version 2 and is not sent unless the engine has enabled it with
 885 the "feature" command.  Example: "ics freechess.org"
 886 </font>
 887 <p>
 888
 889 <dt><strong>computer</strong>
 890 <dd>The opponent is also a computer chess engine.  Some engines alter
 891 their playing style when they receive this command.
 892 <p>
 893
 894 <dt><font color=red><strong>pause</strong></font>
 895 <dt><font color=red><strong>resume</strong></font>
 896 <dd><font color=red>(These commands are new in protocol
 897 version 2 and will not be sent unless feature pause=1 is set.  At
 898 this writing, xboard actually does not use the commands at all, but it
 899 or other interfaces may use them in the future.)
 900 The "pause" command puts the engine into a special state where it
 901 does not think, ponder, or otherwise consume significant CPU time.
 902 The current thinking or pondering (if any) is suspended and both
 903 player's clocks are stopped.  The only command that the interface may
 904 send to the engine while it is in the paused state is "resume".  The
 905 paused thinking or pondering (if any) resumes from exactly where it
 906 left off, and the clock of the player on move resumes running from
 907 where it stopped.
 908 </font>
 909 </dl>
 910
 911 <h3>Bughouse commands:</h3>
 912
 913 <p>
 914 xboard now supports bughouse engines when in Zippy mode.  See
 915 <a href="http://www.tim-mann.org/xboard/zippy.README"
 916 >zippy.README</a> for information on Zippy mode and how to turn on the
 917 bughouse support.  The bughouse move format is given above.  xboard
 918 sends the following additional commands to the engine when in bughouse
 919 mode.
 920 Commands to inform your engine of the partner's game state may
 921 be added in the future.
 922 </p>
 923
 924 <dl>
 925 <dt><strong>partner &lt;player&gt;</strong>
 926 <dd>&lt;player&gt; is now your partner for future games.  Example: <pre>partner mann</pre>
 927 <p>
 928
 929 <dt><strong>partner</strong>
 930 <dd>Meaning: You no longer have a partner.
 931 <p>
 932
 933 <dt><strong>ptell &lt;text&gt;</strong>
 934 <dd>Your partner told you &lt;text&gt;, either with a ptell or an ordinary tell.
 935 <p>
 936
 937 <dt><strong>holding [&lt;white&gt;] [&lt;black&gt;]</strong>
 938 <dd>White currently holds &lt;white&gt;; black currently holds &lt;black&gt;.
 939   Example: <pre>holding [PPPRQ] []</pre>
 940
 941 <dt><strong>holding [&lt;white&gt;] [&lt;black&gt;] &lt;color&gt;&lt;piece&gt;</strong>
 942 <dd>White currently holds &lt;white&gt;; black currently holds &lt;black&gt;, after
 943   &lt;color&gt; acquired &lt;piece&gt;.   Example: <pre>holding [PPPRQ] [R] BR</pre>
 944 </dl>
 945
 946 <h2><a name="9">9. Commands from the engine to xboard</a></h2>
 947
 948 <p>
 949 <font color=red>
 950 In general, an engine should not send any output to xboard that is not
 951 described in this document.  As the protocol is extended, newer
 952 versions of xboard may recognize additional strings as commands that
 953 were previously not assigned a meaning.
 954 </font>
 955 </p>
 956
 957 <dl>
 958 <dt><font color=red>
 959 <strong>feature FEATURE1=VALUE1 FEATURE2=VALUE2 ...</strong>
 960 </font>
 961
 962 <dd><font color=red>
 963 Beginning with version 2, the protocol includes the "feature"
 964 command, which lets your engine control certain optional protocol
 965 features.  Feature settings are written as FEATURE=VALUE, where
 966 FEATURE is a name from the list below and VALUE is the value to be
 967 assigned.  Features can take string, integer, or boolean values; the
 968 type of value is listed for each feature.  String values are written
 969 in double quotes (for example, <tt>feature myname="Miracle Chess
 970 0.9"</tt>), integers are written in decimal, and boolean values are
 971 written as 0 for false, 1 for true.  Any number of features can be set
 972 in one feature command, or multiple feature commands can be given.
 973
 974 <p>
 975 Your engine should send one or more feature commands immediately after
 976 receiving the "protover" command, since xboard needs to know the
 977 values of some features before sending further commands to the engine.
 978 Because engines that predate protocol version 2 do not send "feature",
 979 xboard uses a timeout mechanism: when it first starts your engine, it
 980 sends "xboard" and "protover N", then listens for feature commands for
 981 two seconds before sending any other commands.  To end this timeout
 982 and avoid the wait, set the feature "done=1" at the end of your last
 983 feature command.  To increase the timeout, if needed, set the feature
 984 "done=0" before your first feature command and "done=1" at the end.
 985 If needed, it is okay for your engine to set done=0 soon as it starts,
 986 even before it receives the xboard and protover commands.  This can be
 987 useful if your engine takes a long time to initialize itself.  It
 988 should be harmless even if you are talking to a (version 1) user
 989 interface that does not understand the "feature" command, since such
 990 interfaces generally ignore commands from the engine that they do not
 991 understand.
 992 </p>
 993
 994 <p>
 995 The feature command is designed to let the protocol change without
 996 breaking engines that were written for older protocol versions.  When
 997 a new feature is added to the protocol, its default value is always
 998 chosen to be compatible with older versions of the protocol that did
 999 not have the feature.  Any feature that your engine does not set in a
1000 "feature" command retains its default value, so as the protocol
1001 changes, you do not have to change your engine to keep up with it
1002 unless you want to take advantage of a new feature.  Because some
1003 features are improvements to the protocol, while others are meant to
1004 cater to engines that do not implement all the protocol features, the
1005 recommended setting for a feature is not always the same as the
1006 default setting.  The listing below gives both default and recommended
1007 settings for most features.
1008 </p>
1009
1010 <p>
1011 You may want to code your engine so as to be able to work with
1012 multiple versions of the engine protocol.  Protocol version 1 does not
1013 send the protover command and does not implement the feature command;
1014 if you send a feature command in protocol version 1, it will have no
1015 effect and there will be no response.  In protocol version 2 or later,
1016 each feature F that you set generates the response "accepted F" if the
1017 feature is implemented, or "rejected F" if it is not.  Thus an engine
1018 author can request any feature without having to keep track of which
1019 protocol version it was introduced in; you need only check whether the
1020 feature is accepted or rejected.  This mechanism also makes it
1021 possible for a user interface author to implement a subset of a
1022 protocol version by rejecting some features that are defined in that
1023 version; however, you should realize that engine authors are likely to
1024 code for xboard and may not be prepared to have a feature that they
1025 depend on be rejected.
1026 </p>
1027
1028 <p>
1029 Here are the features that are currently defined.
1030 </p>
1031 </font>
1032
1033 <dl>
1034 <dt><font color=red>
1035 <strong>ping</strong> (boolean, default 0, recommended 1)
1036 </font>
1037 <dd><font color=red>
1038 If ping=1, xboard may use the protocol's new "ping" command;
1039 if ping=0, xboard will not use the command.
1040 </font>
1041
1042 <dt><font color=red>
1043 <strong>setboard</strong> (boolean, default 0, recommended 1)
1044 </font>
1045 <dd><font color=red>
1046 If setboard=1, xboard will use the protocol's new "setboard" command
1047 to set up positions; if setboard=0, it will use the older "edit" command.
1048 </font>
1049
1050 <dt><font color=red>
1051 <strong>playother</strong> (boolean, default 0, recommended 1)
1052 </font>
1053 <dd><font color=red>
1054 If playother=1, xboard will use the protocol's new "playother" command
1055 when appropriate; if playother=0, it will not use the command.
1056 </font>
1057
1058 <dt><font color=red>
1059 <strong>san</strong> (boolean, default 0)
1060 </font>
1061 <dd><font color=red>
1062 If san=1, xboard will send moves to the engine in standard algebraic
1063 notation (SAN); for example, Nf3.  If san=0, xboard will send moves in
1064 coordinate notation; for example, g1f3.  See MOVE in
1065 <a href="#8">section 8</a> above for more details of both kinds of notation.
1066 </font>
1067
1068 <dt><font color=red>
1069 <strong>usermove</strong> (boolean, default 0)
1070 </font>
1071 <dd><font color=red>
1072 If usermove=1, xboard will send moves to the engine with the
1073 command "usermove MOVE"; if usermove=0, xboard will send just the move,
1074 with no command name.
1075 </font>
1076
1077 <dt><font color=red>
1078 <strong>time</strong> (boolean, default 1, recommended 1)
1079 </font>
1080 <dd><font color=red>
1081 If time=1, xboard will send the "time" and "otim" commands to
1082 update the engine's clocks; if time=0, it will not.
1083 </font>
1084
1085 <dt><font color=red>
1086 <strong>draw</strong> (boolean, default 1, recommended 1)
1087 </font>
1088 <dd><font color=red>
1089 If draw=1, xboard will send the "draw" command if the engine's opponent
1090 offers a draw; if draw=0, xboard will not inform the engine about
1091 draw offers.  Note that if draw=1, you may receive a draw offer while you
1092 are on move; if this will cause you to move immediately, you should set
1093 draw=0.
1094 </font>
1095
1096 <dt><font color=red>
1097 <strong>sigint</strong> (boolean, default 1)
1098 </font>
1099 <dd><font color=red>
1100 If sigint=1, xboard may send SIGINT (the interrupt signal) to
1101 the engine as <a href="#7">section 7</a> above; if sigint=0, it will
1102 not.
1103 </font>
1104
1105 <dt><font color=red>
1106 <strong>sigterm</strong> (boolean, default 1)
1107 </font>
1108 <dd><font color=red>
1109 If sigterm=1, xboard may send SIGTERM (the termination signal) to
1110 the engine as <a href="#7">section 7</a> above; if sigterm=0, it will
1111 not.
1112 </font>
1113
1114 <dt><font color=red>
1115 <strong>reuse</strong> (boolean, default 1, recommended 1)
1116 </font>
1117 <dd><font color=red>
1118 If reuse=1, xboard may reuse your engine for multiple games.  If
1119 reuse=0 (or if the user has set the -xreuse option on xboard's command
1120 line), xboard will kill the engine process after every game and start
1121 a fresh process for the next game.
1122 </font>
1123
1124 <dt><font color=red>
1125 <strong>analyze</strong> (boolean, default 1, recommended 1)
1126 </font>
1127 <dd><font color=red>
1128 If analyze=0, xboard will not try to use the "analyze" command; it
1129 will pop up an error message if the user asks for analysis mode.  If
1130 analyze=1, xboard will try to use the command if the user asks for
1131 analysis mode.
1132 </font>
1133
1134 <dt><font color=red>
1135 <strong>myname</strong> (string, default determined from engine filename)
1136 </font>
1137 <dd><font color=red>
1138 This feature lets you set the name that xboard will use for your
1139 engine in window banners, in the PGN tags of saved game files, and when
1140 sending the "name" command to another engine.
1141 </font>
1142
1143 <dt><font color=red>
1144 <strong>variants</strong> (string, see text below)
1145 </font>
1146 <dd><font color=red>
1147 This feature indicates which chess variants your engine accepts.
1148 It should be a comma-separated list of variant names.  See the table
1149 under the "variant" command in <a href="#8">section 8</a> above.  If
1150 you do not set this feature, xboard will assume by default that your
1151 engine supports all variants.  (However, the -zippyVariants
1152 command-line option still limits which variants will be accepted in
1153 Zippy mode.)  It is recommended that you set this feature to the
1154 correct value for your engine (just "normal" in most cases) rather
1155 than leaving the default in place, so that the user will get an
1156 appropriate error message if he tries to play a variant that your
1157 engine does not support.
1158 </font>
1159
1160 <dt><font color=red>
1161 <strong>colors</strong> (boolean, default 1, recommended 0)
1162 </font>
1163 <dd><font color=red>
1164 If colors=1, xboard uses the obsolete "white" and "black"
1165 commands in a stylized way that works with most older chess engines
1166 that require the commands.  See the "<a href="#13">Idioms</a>" section
1167 below for details.  If colors=0, xboard does not use the "white" and
1168 "black" commands at all.
1169 </font>
1170
1171 <dt><font color=red>
1172 <strong>ics</strong> (boolean, default 0)
1173 </font>
1174 <dd><font color=red>
1175 If ics=1, xboard will use the protocol's new "ics" command
1176 to inform the engine of whether or not it is playing on a chess server;
1177 if ics=0, it will not.
1178 </font>
1179
1180 <dt><font color=red>
1181 <strong>name</strong> (boolean, see text below)
1182 </font>
1183 <dd><font color=red>
1184 If name=1, xboard will use the protocol's "name" command
1185 to inform the engine of the opponent's name; if name=0, it will not.
1186 By default, name=1 if the engine is playing on a chess server; name=0 if not.
1187 </font>
1188
1189 <dt><font color=red>
1190 <strong>pause</strong> (boolean, default 0)
1191 </font>
1192 <dd><font color=red>
1193 If pause=1, xboard may use the protocol's new "pause" command;
1194 if pause=0, xboard assumes that the engine does not support this command.
1195 </font>
1196
1197 <dt><font color=red>
1198 <strong>done</strong> (integer, no default)
1199 </font>
1200 <dd><font color=red>
1201 If you set done=1 during the initial two-second timeout after
1202 xboard sends you the "xboard" command, the
1203 timeout will end and xboard will not look for any more feature
1204 commands before starting normal operation.
1205 If you set done=0, the initial timeout is increased to one hour;
1206 in this case, you must set done=1 before xboard will enter normal operation.
1207 </font>
1208 </dl>
1209 <p>
1210
1211 <dt><strong>Illegal move: MOVE</strong>
1212 <dt><strong>Illegal move (REASON): MOVE</strong>
1213 <dd>If your engine receives a MOVE command that is recognizably a move
1214 but is not legal in the current position, your engine must print an
1215 error message in one of the above formats so that xboard can pass the
1216 error on to the user and retract the move.  The (REASON) is entirely
1217 optional.  Examples:
1218
1219 <pre>
1220   Illegal move: e2e4
1221   Illegal move (in check): Nf3
1222   Illegal move (moving into check): e1g1
1223 </pre>
1224 <p>
1225 Generally, xboard will never send an ambiguous move, so it does not
1226 matter whether you respond to such a move with an Illegal move message
1227 or an Error message.
1228 </p>
1229
1230 <dt><strong>Error (ERRORTYPE): COMMAND</strong>
1231 <dd>If your engine receives a command it does not understand or does
1232 not implement, it should print an error message in the above format so
1233 that xboard can parse it.  Examples:
1234 <pre>
1235   Error (ambiguous move): Nf3
1236   Error (unknown command): analyze
1237   Error (command not legal now): undo
1238   Error (too many parameters): level 1 2 3 4 5 6 7
1239 </pre>
1240
1241 <dt><strong>move MOVE</strong>
1242 <dd>Your engine is making the move MOVE.  Do not echo moves from
1243 xboard with this command; send only new moves made by the engine.
1244
1245 <font color=red>
1246 <p>For the actual move text from your chess engine (in place of MOVE
1247 above), your move should be either
1248 <ul>
1249 <li>in coordinate notation (e.g.,
1250 e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,
1251 e1g1), or
1252 <li>in Standard Algebraic Notation (SAN) as defined in the
1253 Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),
1254 with the extension piece@square (e.g., P@f7) to handle piece placement
1255 in bughouse and crazyhouse.
1256 </ul>
1257 xboard itself also accepts some variants of SAN, but for compatibility
1258 with non-xboard interfaces, it is best not to rely on this behavior.
1259 </p>
1260
1261 <p>Warning: Even though all versions of this protocol specification
1262 have indicated that xboard accepts SAN moves, some non-xboard
1263 interfaces are known to accept only coordinate notation.  See the
1264 Idioms section for more information on the known limitations of some
1265 non-xboard interfaces.  It should be safe to send SAN moves if you
1266 receive a "protover 2" (or later) command from the interface, but
1267 otherwise it is best to stick to coordinate notation for maximum
1268 compatibility.  An even more conservative approach would be for your
1269 engine to send SAN to the interface only if you have set feature san=1
1270 (which causes the interface to send SAN to you) and have received
1271 "accepted san" in reply.
1272 </p>
1273 </font>
1274
1275 <dt><strong>RESULT {COMMENT}</strong> <dd>When your engine detects
1276 that the game has ended by rule, your engine must output a line of the
1277 form "RESULT {comment}" (without the quotes), where RESULT is a PGN
1278 result code (1-0, 0-1, or 1/2-1/2), and comment is the reason.  Here
1279 "by rule" means that the game is definitely over because of what
1280 happened on the board.  In normal chess, this includes checkmate,
1281 stalemate, triple repetition, the 50 move rule, or insufficient
1282 material; it does not include loss on time or the like.
1283 Examples:
1284 <pre>
1285   0-1 {Black mates}
1286   1-0 {White mates}
1287   1/2-1/2 {Draw by repetition}
1288   1/2-1/2 {Stalemate}
1289 </pre>
1290
1291 <p>
1292 xboard relays the result to the user, the ICS, the other engine in Two
1293 Machines mode, and the PGN save file as required.
1294 </p>
1295
1296 <dt><strong>resign</strong>
1297 <dd>If your engine wants to resign, it can send the command "resign".
1298 Alternatively, it can use the "RESULT {comment}" command if the string
1299 "resign" is included in the comment; for example "0-1 {White
1300 resigns}".  xboard relays the resignation to the user, the ICS, the
1301 other engine in Two Machines mode, and the PGN save file as required.
1302 <p>
1303
1304 <dt><strong>offer draw</strong>
1305 <dd>If your engine wants to offer a draw by agreement (as opposed to
1306 claiming a draw by rule), it can send the command "offer draw".
1307 xboard relays the offer to the user, the ICS, the other engine in Two
1308 Machines mode, and the PGN save file as required.  In Machine White,
1309 Machine Black, or Two Machines mode, the offer is considered valid
1310 until your engine has made two more moves.
1311 <p>
1312
1313 <dt><font color=red><strong>tellopponent MESSAGE</strong></font>
1314 <dd><font color=red>
1315 This command lets the engine give a message to its opponent,
1316 independent of whether the opponent is a user on the local machine or
1317 a remote ICS user (Zippy mode).  MESSAGE consists of any characters,
1318 including whitespace, to the end of the line.  When the engine is
1319 playing against a user on the local machine, xboard pops up an
1320 information dialog containing the message.  When the engine is playing
1321 against an opponent on the ICS (Zippy mode), xboard sends "say
1322 MESSAGE\n" to the ICS.
1323 <p>
1324
1325 <dt><strong>tellothers MESSAGE</strong>
1326 <dd>This command lets the engine give a message to people watching the
1327 game other than the engine's opponent.  MESSAGE consists of any
1328 characters, including whitespace, to the end of the line.  When the
1329 engine is playing against a user on the local machine, this command
1330 does nothing.  When the engine is playing against an opponent on the
1331 ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
1332 <p>
1333
1334 <dt><strong>tellall MESSAGE</strong>
1335 <dd>This command lets the engine give a message to its opponent and
1336 other people watching the game,
1337 independent of whether the opponent is a user on the local machine or
1338 a remote ICS user (Zippy mode).  MESSAGE consists of any characters,
1339 including whitespace, to the end of the line.  When the engine is
1340 playing against a user on the local machine, xboard pops up an
1341 information dialog containing the message.  When the engine is playing
1342 against an opponent on the ICS (Zippy mode), xboard sends "kibitz
1343 MESSAGE\n" to the ICS.
1344 </font>
1345 <p>
1346
1347 <dt><strong>telluser MESSAGE</strong>
1348 <dd>xboard pops up an information dialog containing the message.
1349 MESSAGE consists of any characters, including whitespace, to the end
1350 of the line.
1351 <p>
1352
1353 <dt><strong>tellusererror MESSAGE</strong>
1354 <dd>xboard pops up an error dialog containing the message.
1355 MESSAGE consists of any characters, including whitespace, to the end
1356 of the line.
1357 <p>
1358
1359 <dt><strong>askuser REPTAG MESSAGE</strong>
1360 <dd>Here REPTAG is a string containing no whitespace, and MESSAGE
1361 consists of any characters, including whitespace, to the end of the
1362 line.  xboard pops up a question dialog that says MESSAGE and
1363 has a typein box.  If the user types in "bar", xboard sends "REPTAG
1364 bar" to the engine.  The user can cancel the dialog and send nothing.
1365 <p>
1366
1367 <dt><strong>tellics MESSAGE</strong>
1368 <dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS.  MESSAGE consists
1369 of any characters, including whitespace, to the end of the line.
1370 <p>
1371
1372 <dt><font color=red><strong>tellicsnoalias MESSAGE</strong></font>
1373 <dd><font color=red>
1374 In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a
1375 character that prevents the ICS from expanding command aliases, if
1376 xboard knows of such a character.  (On chessclub.com and chess.net,
1377 "/" is used; on freechess.org, "$" is used.)  MESSAGE consists of any
1378 characters, including whitespace, to the end of the line.
1379 </font>
1380 </dl>
1381 <p>
1382
1383 <h2><a name="10">10. Thinking Output</a></h2>
1384
1385 <p>
1386 If the user asks your engine to "show thinking", xboard sends your
1387 engine the "post" command.  It sends "nopost" to turn thinking off.
1388 In post mode, your engine sends output lines to show the progress of
1389 its thinking.  The engine can send as many or few of these lines as it
1390 wants to, whenever it wants to.  Typically they would be sent when the
1391 PV (principal variation) changes or the depth changes.  The thinking
1392 output should be in the following format:
1393 </p>
1394
1395 <pre>ply score time nodes pv</pre>
1396
1397 Where:
1398 <table>
1399 <tr align="left"><th>ply<td>Integer giving current search depth.
1400 <tr align="left"><th>score<td>Integer giving current evaluation in centipawns.
1401 <tr align="left"><th>time<td>Current search time in centiseconds (ex:
1402 1028 = 10.28 seconds).
1403
1404 <tr align="left"><th>nodes<td>Nodes searched.
1405 <tr align="left"><th>pv<td>Freeform text giving current "best" line.
1406 You can continue the pv onto another line if you start each
1407 continuation line with at least four space characters.
1408 </table>
1409
1410 <p>
1411 Example:
1412 </p>
1413
1414 <pre>  9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
1415
1416 <p>
1417 Meaning:
1418 </p>
1419
1420 9 ply, score=1.56, time = 10.84 seconds, nodes=48000,
1421 PV = "Nf3 Nc6 Nc3 Nf6"
1422
1423 <p>
1424 Longer example from actual Crafty output:
1425 </p>
1426 <pre>
1427   4    109      14   1435  1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
1428   4    116      23   2252  1. Nf3 Nc6 2. e4 e6
1429   4    116      27   2589  1. Nf3 Nc6 2. e4 e6
1430   5    141      44   4539  1. Nf3 Nc6 2. O-O e5 3. e4
1431   5    141      54   5568  1. Nf3 Nc6 2. O-O e5 3. e4
1432 </pre>
1433
1434 <p>
1435 You can use the PV to show other things; for instance, while in book,
1436 Crafty shows the observed frequency of different reply moves in its
1437 book.  In situations like this where your engine is not really
1438 searching, start the PV with a '(' character:
1439 </p>
1440
1441 <pre>
1442   0      0       0      0  (e4 64%, d4 24%)
1443 </pre>
1444
1445 <p>
1446 GNU Chess output is very slightly different.  The ply number is
1447 followed by an extra nonblank character, and the time is in seconds,
1448 not hundredths of seconds.  For compatibility, xboard accepts the
1449 extra character and takes it as a flag indicating the different time
1450 units.  Example:
1451 </p>
1452
1453 <pre>
1454  2.     14    0       38   d1d2  e8e7
1455  3+     78    0       65   d1d2  e8e7  d2d3
1456  3&     14    0       89   d1d2  e8e7  d2d3
1457  3&     76    0      191   d1e2  e8e7  e2e3
1458  3.     76    0      215   d1e2  e8e7  e2e3
1459  4&     15    0      366   d1e2  e8e7  e2e3  e7e6
1460  4.     15    0      515   d1e2  e8e7  e2e3  e7e6
1461  5+     74    0      702   d1e2  f7f5  e2e3  e8e7  e3f4
1462  5&     71    0     1085   d1e2  e8e7  e2e3  e7e6  e3f4
1463  5.     71    0     1669   d1e2  e8e7  e2e3  e7e6  e3f4
1464  6&     48    0     3035   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
1465  6.     48    0     3720   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
1466  7&     48    0     6381   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
1467  7.     48    0    10056   d1e2  e8e7  e2e3  e7e6  e3e4  f7f5  e4d4
1468  8&     66    1    20536   d1e2  e8e7  e2e3  e7e6  e3d4  g7g5  a2a4  f7f5
1469  8.     66    1    24387   d1e2  e8e7  e2e3  e7e6  e3d4  g7g5  a2a4  f7f5
1470  9&     62    2    38886   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  a2a4  h5h4
1471                            d4e4
1472  9.     62    4    72578   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  a2a4  h5h4
1473                            d4e4
1474 10&     34    7   135944   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  c2c4  h5h4
1475                            d4e4  f7f5  e4f4
1476 10.     34    9   173474   d1e2  e8e7  e2e3  e7e6  e3d4  h7h5  c2c4  h5h4
1477                            d4e4  f7f5  e4f4
1478 </pre>
1479
1480 <p>If your engine is pondering (thinking on its opponent's time) in post
1481 mode, it can show its thinking then too.  In this case your engine may
1482 omit the hint move (the move it is assuming its opponent will make)
1483 from the thinking lines <em>if and only if</em> it sends xboard the move in
1484 the usual "Hint: xxx" format before sending the first line.
1485 </p>
1486
1487 <h2><a name="11">11. Time control</a></h2>
1488
1489 <p>
1490 xboard supports three styles of time control: conventional chess clocks,
1491 the ICS-style incremental clock, and an exact number of seconds per move.
1492 </p>
1493
1494 <p>In conventional clock mode, every time control period is the same.
1495 That is, if the time control is 40 moves in 5 minutes, then after each
1496 side has made 40 moves, they each get an additional 5 minutes, and so
1497 on, ad infinitum.  At some future time it would be nice to support a
1498 series of distinct time controls.  This is very low on my personal
1499 priority list, but code donations to the xboard project are accepted,
1500 so feel free to take a swing at it.  I suggest you talk to me first,
1501 though.
1502 </p>
1503
1504 <p>
1505 The command to set a conventional time control looks like this:
1506 </p>
1507
1508 <pre>
1509   level 40 5 0
1510   level 40 0:30 0
1511 </pre>
1512
1513 <p>
1514 The 40 means that there are 40 moves per time control.  The 5 means
1515 there are 5 minutes in the control.  In the second example, the 0:30
1516 means there are 30 seconds.  The final 0 means that we are in
1517 conventional clock mode.
1518 </p>
1519
1520 <p>
1521 The command to set an incremental time control looks like this:
1522 </p>
1523
1524 <pre>
1525   level 0 2 12
1526 </pre>
1527
1528 <p>
1529 Here the 0 means "play the whole game in this time control period",
1530 the 2 means "base=2 minutes", and the 12 means "inc=12 seconds".  As
1531 in conventional clock mode, the second argument to level can be in
1532 minutes and seconds.
1533 </p>
1534
1535 <p>
1536 At the start of the game, each player's clock is set to base minutes.
1537 Immediately after a player makes a move, inc seconds are added to his
1538 clock.  A player's clock counts down while it is his turn.  Your flag
1539 can be called whenever your clock is zero or negative.  (Your clock
1540 can go negative and then become positive again because of the
1541 increment.)
1542 </p>
1543
1544 <p>
1545 A special rule on some ICS implementations: if you ask for a game with
1546 base=0, the clocks really start at 10 seconds instead of 0.  xboard
1547 itself does not know about this rule, so it passes the 0 on to the
1548 engine instead of changing it to 0:10.
1549 </p>
1550
1551 <p>
1552 ICS also has time odds games.  With time odds, each player has his own
1553 (base, inc) pair, but otherwise things work the same as in normal
1554 games.  The Zippy xboard accepts time odds games but ignores the fact
1555 that the opponent's parameters are different; this is perhaps not
1556 quite the right thing to do, but gnuchess doesn't understand time
1557 odds.  Time odds games are always unrated.
1558 </p>
1559
1560 <p>
1561 The command to set an exact number of seconds per move looks like this:
1562 </p>
1563
1564 <pre>
1565   st 30
1566 </pre>
1567
1568 <p>
1569 This means that each move must be made in at most 30 seconds.  Time not used
1570 on one move does not accumulate for use on later moves.
1571 </p>
1572
1573 <h2><a name="12">12. Analyze Mode</a></h2>
1574
1575 <p>xboard supports analyzing fresh games, edited positions, and games
1576 from files.  However, all of these look the same from the chess
1577 engine's perspective. Basically, the engine just has to respond to the
1578 "analyze" command.
1579 <font color=red>
1580 Beginning in protocol version 2,
1581 if your engine does not support analyze mode, it should use
1582 the feature command to set analyze=0.
1583 </font>
1584 The older method of
1585 printing the error message "Error (unknown command): analyze" in
1586 response to the "analyze" command will also work, however.
1587 </p>
1588
1589 <p>
1590 To enter analyze mode, xboard sends the command sequence "post", "analyze".
1591 Analyze mode in your engine should be
1592 similar to force mode, except that your engine thinks about what move
1593 it would make next if it were on move.  Your engine should accept the
1594 following commands while in analyze mode:
1595 </p>
1596
1597 <ul>
1598 <li>Any legal move, as in force mode
1599 <li><strong>undo</strong>&nbsp;&nbsp; Back up one move and analyze previous position.
1600 <li><strong>new</strong>&nbsp;&nbsp; Reset position to start of game but stay in analyze mode.
1601 <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.
1602 </font>
1603 <li><strong>exit</strong>&nbsp;&nbsp; Leave analyze mode.
1604 <li><strong>.</strong>&nbsp;&nbsp; Send a search status update (optional); see below.
1605 <li><font color=red>
1606 <strong>bk</strong>&nbsp;&nbsp; Show book moves from this position,
1607 if any; see above.</font>
1608 <li><font color=red>
1609 <strong>hint</strong>&nbsp;&nbsp; Show the predicted move from this
1610 position, if any; see above.</font>
1611 </ul>
1612
1613 <p>
1614 If the user selects "Periodic Updates", xboard will send the string
1615 ".\n" to the chess engine periodically during analyze mode, unless the
1616 last PV received began with a '(' character.
1617 </p>
1618
1619 <p>
1620 The chess engine should respond to ".\n" with a line like this:
1621 </p>
1622
1623 <pre>
1624 stat01: time nodes ply mvleft mvtot <font color=red>mvname</font>
1625 </pre>
1626
1627 Where:
1628 <table>
1629 <tr align="left"><th>time<td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).
1630 <tr align="left"><th>nodes<td>Nodes searched so far.
1631 <tr align="left"><th>ply<td>Search depth so far.
1632 <tr align="left"><th>mvleft<td>Number of moves left to consider at this depth.
1633 <tr align="left"><th>mvtot<td>Total number of moves to consider.
1634 <tr align="left"><th><font color=red>mvname</font><td><font color=red>
1635 Move currently being considered (SAN or coordinate notation).  Optional;
1636 added in protocol version 2.</font>
1637 </table>
1638
1639 <p>
1640 Examples:
1641 </p>
1642 <pre>
1643   stat01: 1234 30000 7 5 30
1644   stat01: 1234 30000 7 5 30 Nf3
1645 </pre>
1646
1647 <p>
1648 Meaning:
1649 </p>
1650
1651 <p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
1652   total of 30 legal moves, and I have 5 more moves to search
1653   before going to depth 8.  In the second example, of the 30 legal
1654   moves, the one I am currently searching is Nf3.</p>
1655
1656 <p>
1657 Implementation of the "." command is optional. If the engine does not
1658 respond to the "." command with a "stat01..." line, xboard will stop
1659 sending "."  commands.  If the engine does not implement this command,
1660 the analysis window will use a shortened format to display the engine
1661 info.
1662 </p>
1663
1664 <p>
1665 To give the user some extra information, the chess engine can output
1666 the strings "++\n" and "--\n", to indicate that the current search is
1667 failing high or low, respectively.  You don't have to send anything
1668 else to say "Okay, I'm not failing high/low anymore."  xboard will
1669 figure this out itself.
1670 </p>
1671
1672 <h2><a name="13">13. Idioms and backward compatibility features</a></h2>
1673
1674 <p>
1675 Some engines have variant interpretations of the force/go/white/black,
1676 time/otim, and hard/easy command sets.
1677 In order to accommodate these older engines, xboard uses these commands
1678 only according to the stylized patterns ("idioms") given in this section.
1679 The obsolete white and black commands
1680 have historically been particularly troublesome, and it is recommended
1681 that new engines set the feature colors=0 and/or ignore the commands.
1682 </p>
1683
1684 <dl>
1685
1686 <dt><strong>time N</strong>
1687 <dt><strong>otim N</strong>
1688 <dt><strong>MOVE</strong>
1689 <dd>Sent when the opponent makes a move and the engine is already
1690 playing the opposite color.
1691 <p>
1692
1693 <dt><strong>white</strong>
1694 <dt><strong>go</strong>
1695 <dd>Sent when the engine is in force mode or playing Black but should
1696 switch to playing White.  This sequence is sent only when White is
1697 already on move.
1698 <font color=red>
1699 If you set the feature colors=0, "white" is not sent.
1700 </font>
1701 <p>
1702
1703 <dt><strong>black</strong>
1704 <dt><strong>go</strong>
1705 <dd>Sent when the engine is in force mode or playing White but should
1706 switch to playing Black.  This sequence is sent only when Black is
1707 already on move.
1708 <font color=red>
1709 If you set the feature colors=0, "black" is not sent.
1710 </font>
1711 <p>
1712
1713 <dt><strong>white</strong>
1714 <dt><strong>time N</strong>
1715 <dt><strong>otim N</strong>
1716 <dt><strong>black</strong>
1717 <dt><strong>go</strong>
1718 <dd>Sent when Black is on move, the engine is in force mode or playing
1719 White, and the engine's clock needs to be updated before it starts
1720 playing.
1721 The initial "white" is a kludge to accommodate GNU Chess
1722 4's variant interpretation of these commands.
1723 <font color=red>
1724 If you set the feature colors=0, "white" and "black" are not sent.
1725 </font>
1726 <p>
1727
1728 <dt><strong>black</strong>
1729 <dt><strong>time N</strong>
1730 <dt><strong>otim N</strong>
1731 <dt><strong>white</strong>
1732 <dt><strong>go</strong>
1733 <dd>Sent when White is on move, the engine is in force mode or playing
1734 Black, and the engine's clock needs to be updated before it starts
1735 playing.  See previous idiom.
1736 The initial "black" is a kludge to accommodate GNU Chess
1737 4's variant interpretation of these commands.
1738 <font color=red>
1739 If you set the feature colors=0, "black" and "white" are not sent.
1740 </font>
1741 <p>
1742
1743 <dt><strong>hard</strong>
1744 <dt><strong>easy</strong>
1745 <dd>Sent in sequence to turn off pondering if xboard is not sure
1746 whether it is on.  When xboard is sure, it will send "hard" or "easy"
1747 alone.  xboard does this because "easy" is a toggle in GNU Chess 4 but
1748 "hard" is an absolute on.
1749
1750 </dl>
1751
1752 <p>
1753 To support older engines, certain additional commands from the engine
1754 to xboard are also recognized.  (These are commands by themselves, not
1755 values to be placed in the comment field of the PGN result code.)
1756 These forms are not recommended for new engines; use the PGN result
1757 code commands or the resign command instead.
1758 </p>
1759
1760 <table>
1761 <tr align="left"><th>Command              <th>Interpreted as
1762 <tr align="left"><td>White resigns        <td>0-1 {White resigns}
1763 <tr align="left"><td>Black resigns        <td>1-0 {Black resigns}
1764 <tr align="left"><td>White                <td>1-0 {White mates}
1765 <tr align="left"><td>Black                <td>0-1 {Black mates}
1766 <tr align="left"><td>Draw                 <td>1/2-1/2 {Draw}
1767 <tr align="left"><td>computer mates       <td>1-0 {White mates} or 0-1 {Black mates}
1768 <tr align="left"><td>opponent mates       <td>1-0 {White mates} or 0-1 {Black mates}
1769 <tr align="left"><td>computer resigns     <td>0-1 {White resigns} or 1-0 {Black resigns}
1770 <tr align="left"><td>game is a draw       <td>1/2-1/2 {Draw}
1771 <tr align="left"><td>checkmate            <td>1-0 {White mates} or 0-1 {Black mates}
1772 </table>
1773
1774 <p>
1775 Commands in the above table are recognized if they begin a line and
1776 arbitrary characters follow, so (for example) "White mates" will be
1777 recognized as "White", and "game is a draw by the 50 move rule" will
1778 be recognized as "game is a draw".  All the commands are
1779 case-sensitive.
1780 </p>
1781
1782 <p>
1783 An alternative move syntax is also recognized:
1784 </p>
1785
1786 <table>
1787 <tr align="left"><th>Command              <th>Interpreted as
1788 <tr align="left"><td>NUMBER ... MOVE      <td>move MOVE
1789 </table>
1790
1791 <p>
1792 Here NUMBER means any string of decimal digits, optionally ending in a
1793 period.  MOVE is any string containing no whitespace.  In this command
1794 format, xboard requires the "..." even if your engine is playing
1795 White.  A command of the form NUMBER MOVE will be ignored.  This odd
1796 treatment of the commands is needed for compatibility with gnuchessx.
1797 The original reasons for it are lost in the mists of time, but I
1798 suspect it was originally a bug in the earliest versions of xboard,
1799 before I started working on it, which someone "fixed" in the wrong
1800 way, by creating a special version of gnuchess (gnuchessx) instead of
1801 changing xboard.
1802 </p>
1803
1804 <p>
1805 Any line that contains the words "offer" and "draw" is recognized as
1806 "offer draw".
1807 </p>
1808
1809 <p>
1810 The "Illegal move" message is recognized even if spelled "illegal
1811 move" and even if the colon (":") is omitted.  This accommodates GNU
1812 Chess 4, which prints messages like "Illegal move (no matching
1813 move)e2e4", and old versions of Crafty, which print just "illegal move".
1814 </p>
1815
1816 <p>
1817 In Zippy mode, for compatibility with older versions of Crafty,
1818 xboard passes through to ICS any line that begins "kibitz", "whisper",
1819 "tell", or "draw".  Do not use this feature in new code.  Instead, use the
1820 commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),
1821 "1/2-1/2 {COMMENT}", or "offer draw", as appropriate.
1822 </p>
1823
1824 <p>
1825 <font color=red>
1826 If the engine responds to the "sd DEPTH" command with an error message
1827 indicating the command is not supported (such as "Illegal move: sd"),
1828 xboard sets an internal flag and subsequently uses the command
1829 "depth\nDEPTH" instead, for the benefit of GNU Chess 4.  Note the
1830 newline in the middle of this command!  New engines should not rely on
1831 this feature.
1832 </font>
1833 </p>
1834
1835 <p>
1836 <font color=red>
1837 If the engine responds to the "st TIME" command with an error message
1838 indicating the command is not supported (such as "Illegal move: st"),
1839 xboard sets an internal flag and subsequently uses the command "level
1840 1 TIME" instead, for the benefit of GNU Chess 4.  Note that this is
1841 not a standard use of the level command, as TIME seconds are not added
1842 after each player makes 1 move; rather, each move is made in at most
1843 TIME seconds.  New engines should not implement or rely on this
1844 feature.
1845 </font>
1846 </p>
1847
1848 <font color=red>
1849 <p>
1850 In support of the -firstHost/-secondHost features, which allow a chess
1851 engine to be run on another machine using the rsh protocol, xboard recognizes
1852 error messages that are likely to come from rsh as fatal errors.  The following
1853 messages are currently recognized:
1854 </p>
1855
1856 <blockquote>
1857 unknown host<br>
1858 No remote directory<br>
1859 not found<br>
1860 No such file<br>
1861 can't alloc<br>
1862 Permission denied<br>
1863 </blockquote>
1864 </font>
1865
1866 <p>
1867 <font color=red>
1868 ChessBase/Fritz now implements the xboard/winboard protocol and can use
1869 WinBoard-compatible engines in its GUI.  ChessBase's version of the
1870 protocol is generally the same as version 1, except that they have
1871 added the commands <strong>fritz</strong>, <strong>reset</strong>, and
1872 <strong>ponder</strong>, and the edit subcommands
1873 <strong>castle</strong> and <strong>ep</strong>.  If you want your
1874 engine to work well with the ChessBase/Fritz GUI, you may need to
1875 implement these additional commands, and you should also be aware of
1876 the peculiar way that ChessBase uses the protocol.  See their <a
1877 href="http://www.chessbase.com/Products/engines/winboard/tech.htm"
1878 >web page</a> for documentation.
1879 </font>
1880 </p>
1881
1882 <p>
1883 <font color=red>
1884 ChessMaster 8000 also implements version 1 of the xboard/winboard
1885 protocol and can use WinBoard-compatible engines.  The original
1886 release of CM8000 also has one additional restriction: only pure
1887 coordinate notation (e.g., e2e4) is accepted in the move command.  A
1888 patch to correct this should be available from The Learning Company
1889 (makers of CM8000) in February 2001.
1890 </font>
1891 </p>
1892
1893 <hr noshade size="2">
1894 <address>converted to HTML by <a href="http://www.jakob.at/steffen/">Steffen A. Jakob</a></address>
1895 </body>
1896 </html>