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