3 <title>Chess Engine Communication Protocol</title>
8 <h1>Chess Engine Communication Protocol</h1>
9 <h2><a href="http://www.tim-mann.org/">Tim Mann</a></h2>
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>.
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>
34 <h2><a name="1">1. Introduction</a></h2>
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.
45 There are two reasons I can imagine someone wanting to do this:
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.
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
58 href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
59 in the xboard or WinBoard distribution for more information.
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.
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.
79 <h2><a name="2">2. Connection</a></h2>
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.
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.
103 <h2><a name="3">3. Debugging</a></h2>
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.
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.
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.
129 <h2><a name="4">4. How it got this way</a></h2>
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.
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.
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.
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.
177 <h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
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.
196 <h2><a name="6">6. Hints on input/output</a></h2>
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.
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
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()->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.
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>.
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.
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).
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
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()->setbuf(NULL, 0)</tt>, but again, I have never tried
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()->in_avail()</tt>. This method has been reported to
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.
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
320 <h2><a name="7">7. Signals</a></h2>
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.
329 Beginning with version 2, you can now turn off the use of
331 signals. See the "feature" command in <a href="#6">section 9</a> below.
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>
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
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"
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.
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>.
382 <h2><a name="8">8. Commands from xboard to the engine</a></h2>
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
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.
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
404 either with the "feature" command (beginning in protocol version
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.
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.
421 <dt><font color=blue><strong>gui GUI_NAME VERSION.SUBVERSION</strong></font>
422 <dd><font color=blue>
423 This is a new feature. The GUI sending after the "xboard" command and before
424 "protover N" string the command "gui <GUI_NAME> <VERSION>.<SUBVERSION>"
425 to the engine. The GUI_NAME is a string. VERSION and SUBVERSION is <i><strong>one</strong></i>
427 This command will be send always. You don't need to answer because its only
428 a information for the engine. I recommend that the engine not response.
429 The idea behind this command is that the engine now know which special feature
430 support the named GUI.<br>
431 To make the GUI string clear the known GUIs will be predefined:<br>
433 gui arena = send by Arena<br>
434 gui chessassistant = send by Chess Assistant<br>
435 gui chessbase = send by ChessBase<br>
436 gui chessmaster = send by ChessMaster<br>
437 gui chesspartner = send by ChessPartner GUI<br>
438 gui wb2uci = send by wb2uci adapter<br>
439 gui xboard = send by Winboard/Xboard<br>
441 This list is not completely and will be extend in the future.<br>
444 Winboard / Xboard send:<br>
453 <dt><font color=red><strong>protover N</strong></font>
455 Beginning in protocol version 2 (in which N=2), this command will
456 be sent immediately after the "xboard" command. If you receive some
457 other command immediately after "xboard" (such as "new"), you can
458 assume that protocol version 1 is in use. The "protover" command is
459 the only new command that xboard always sends in version 2. All other
460 new commands to the engine are sent only if the engine first enables
461 them with the "feature" command. Protocol versions will always be
462 simple integers so that they can easily be compared.
464 <p>Your engine should reply to the protover command by sending the
465 "feature" command (see below) with the list of non-default feature
466 settings that you require, if any.
468 <p>Your engine should never refuse to run due to receiving a higher
469 protocol version number than it is expecting! New protocol versions
470 will always be compatible with older ones by default; the larger
471 version number is simply a hint that additional "feature" command
472 options added in later protocol versions may be accepted.
476 <dt><font color=red><strong>accepted</strong></font>
477 <dt><font color=red><strong>rejected</strong></font>
479 These commands may be sent to your engine in reply to the "feature"
480 command; see its documentation below.
484 <dt><strong>new</strong>
485 <dd>Reset the board to the standard chess starting position. Set
486 White on move. Leave force mode and set the engine to play Black.
487 Associate the engine's clock with Black and the opponent's clock with
488 White. Reset clocks and time controls to the start of a new game.
489 Stop clocks. Do not ponder on this move, even if pondering is on.
490 Remove any search depth limit previously set by the sd command.
493 <dt><strong>variant VARNAME</strong>
494 <dd>If the game is not standard chess, but a variant, this command is
495 sent after "new" and before the first move or "edit" command. Currently
496 defined variant names are:
499 <tr align="left"><th>wildcastle<td>Shuffle chess where king can castle from d file
500 <tr align="left"><th>nocastle<td>Shuffle chess with no castling at all
501 <tr align="left"><th>fischerandom<td>Fischer Random (not supported yet)
502 <tr align="left"><th>bughouse<td>Bughouse, ICC/FICS rules
503 <tr align="left"><th>crazyhouse<td>Crazyhouse, ICC/FICS rules
504 <tr align="left"><th>losers<td>Win by losing all pieces or getting mated (ICC)
505 <tr align="left"><th>suicide<td>Win by losing all pieces including king,
506 or by having fewer pieces when one player has no legal moves (FICS)
507 <tr align="left"><th><font color=red>giveaway</font>
508 <td><font color=red>Win by losing all pieces including king,
509 or by having no legal moves (ICC)</font>
510 <tr align="left"><th>twokings<td>Weird ICC wild 9
511 <tr align="left"><th>kriegspiel<td>Kriegspiel (engines not supported)
512 <tr align="left"><th>atomic<td>Atomic
513 <tr align="left"><th>3check<td>Win by giving check 3 times
514 <tr align="left"><th>unknown<td>Unknown variant (not supported)
518 <dt><strong>quit</strong>
519 <dd>The chess engine should immediately exit. This command is used
520 when xboard is itself exiting, and also between games if the -xreuse
521 command line option is given (or -xreuse2 for the second engine).
522 See also <a href="#7">Signals</a> above.
525 <dt><strong>random</strong>
526 <dd>This command is specific to GNU Chess 4. You can either ignore it
527 completely (that is, treat it as a no-op) or implement it as GNU Chess
528 does. The command toggles "random" mode (that is, it sets random =
529 !random). In random mode, the engine adds a small random value to its
530 evaluation function to vary its play. The "new" command sets random
534 <dt><strong>force</strong>
535 <dd>Set the engine to play neither color ("force mode"). Stop clocks.
536 The engine should check that moves received in force mode are legal
537 and made in the proper turn, but should not think, ponder, or make
541 <dt><strong>go</strong>
542 <dd>Leave force mode and set the engine to play the color that is on
543 move. Associate the engine's clock with the color that is on move,
544 the opponent's clock with the color that is not on move. Start the engine's
545 clock. Start thinking and eventually make a move.
548 <dt><font color=red><strong>playother</strong></font>
551 (This command is new in protocol version 2. It is not
552 sent unless you enable it with the feature command.)
553 Leave force mode and set the engine to play the color that is <i>not</i> on
554 move. Associate the opponent's clock with the color that is on move,
555 the engine's clock with the color that is not on move. Start the opponent's
556 clock. If pondering is enabled, the engine should begin pondering.
557 If the engine later receives a move, it should start thinking and eventually
562 <dt><strong>white</strong>
565 (This command is obsolete as of protocol version 2, but is still
566 sent in some situations to accommodate older engines unless you disable it
567 with the feature command.)
569 Set White on move. Set the engine to play Black. Stop clocks.
572 <dt><strong>black</strong>
575 (This command is obsolete as of protocol version 2, but is still
576 sent in some situations to accommodate older engines unless you disable it
577 with the feature command.)
579 Set Black on move. Set the engine to play White. Stop clocks.
582 <dt><strong>level MPS BASE INC</strong>
583 <dd>Set time controls. See the <a href="#11">Time Control</a> section below.
586 <dt><strong>st TIME</strong>
587 <dd>Set time controls. See the <a href="#11">Time Control</a> section
588 below. The commands "level" and "st" are not used together.
591 <dt><strong>sd DEPTH</strong>
592 <dd>The engine should limit its thinking to DEPTH ply.
595 <dt><strong>time N</strong>
596 <dd>Set a clock that always belongs to the engine. N is a number in
597 centiseconds (units of 1/100 second). Even if the engine changes to
598 playing the opposite color, this clock remains with the engine.
601 <dt><strong>otim N</strong>
603 <dd>Set a clock that always belongs to the opponent. N is a number in
604 centiseconds (units of 1/100 second). Even if the opponent changes to
605 playing the opposite color, this clock remains with the opponent.
607 If needed for purposes of board display in force mode (where the
608 engine is not participating in the game) the time clock should be
609 associated with the last color that the engine was set to play, the
610 otim clock with the opposite color.
615 Beginning in protocol version 2, if you can't handle the time and
616 otim commands, you can use the "feature" command to disable them; see
619 The following techniques from older protocol versions also
620 work: You can ignore the time and otim commands (that is, treat them
621 as no-ops), or send back "Error (unknown command): time" the first
625 <dt><strong>MOVE</strong>
626 <dd>See below for the syntax of moves. If the move is illegal, print
627 an error message; see the section "<a href="#9">Commands from the engine to
628 xboard</a>". If the move is legal and in turn, make it. If not in force
629 mode, stop the opponent's clock, start the engine's clock, start
630 thinking, and eventually make a move.
632 When xboard sends your engine a move, it normally sends coordinate
633 algebraic notation. Examples:
636 <tr align="left"><td>Normal moves:<td>e2e4
637 <tr align="left"><td>Pawn promotion:<td>e7e8q
638 <tr align="left"><td>Castling:<td>e1g1, e1c1, e8g8, e8c8
639 <tr align="left"><td>Bughouse/crazyhouse drop:<td>P@h3
640 <tr align="left"><td>ICS Wild 0/1 castling:<td>d1f1, d1b1, d8f8, d8b8
641 <tr align="left"><td>FischerRandom castling:<td>O-O, O-O-O (oh, not zero)
646 Beginning in protocol version 2, you can use the feature command
647 to select SAN (standard algebraic notation) instead; for example, e4,
648 Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form,
649 P@h3, is a extension to the PGN standard's definition of SAN, which does
650 not support bughouse or crazyhouse.
655 xboard doesn't reliably detect illegal moves, because it does not keep
656 track of castling unavailability due to king or rook moves, or en
657 passant availability. If xboard sends an illegal move, send back an
658 error message so that xboard can retract it and inform the user; see
659 the section "<a href="#9">Commands from the engine to xboard</a>".
662 <dt><font color=red><strong>usermove MOVE</strong></font>
664 By default, moves are sent to the engine without a command name;
665 the notation is just sent as a line by itself.
666 Beginning in protocol version 2, you can use the feature command
667 to cause the command name "usermove" to be sent before the move.
668 Example: "usermove e2e4".
672 <dt><strong>?</strong>
673 <dd>Move now. If your engine is thinking, it should move immediately;
674 otherwise, the command should be ignored (treated as a no-op). It
675 is permissible for your engine to always ignore the ? command. The
676 only bad consequence is that xboard's Move Now menu command will do
679 It is also permissible for your engine to move immediately if it gets
680 any command while thinking, as long as it processes the command right
681 after moving, but it's preferable if you don't do this. For example,
682 xboard may send post, nopost, easy, hard, force, quit,
686 while the engine is on move.
689 <dt><font color=red><strong>ping N</strong></font>
692 In this command, N is a decimal number. When you receive the command,
693 reply by sending the string <strong>pong N</strong>, where N is the
694 same number you received. Important: You must not reply to a "ping"
695 command until you have finished executing all commands that you
696 received before it. Pondering does not count; if you receive a ping
697 while pondering, you should reply immediately and continue pondering.
698 Because of the way xboard uses the ping command, if you implement the
699 other commands in this protocol, you should never see a "ping" command
700 when it is your move; however, if you do, you must not send the "pong"
701 reply to xboard until after you send your move. For example, xboard
702 may send "?" immediately followed by "ping". If you implement the "?"
703 command, you will have moved by the time you see the subsequent ping
704 command. Similarly, xboard may send a sequence like "force", "new",
705 "ping". You must not send the pong response until after you have
706 finished executing the "new" command and are ready for the new game to
710 The ping command is new in protocol version 2 and will not be sent
711 unless you enable it with the "feature" command. Its purpose is to
712 allow several race conditions that could occur in previous versions of
713 the protocol to be fixed, so it is highly recommended that you
714 implement it. It is especially important in simple engines that do
715 not ponder and do not poll for input while thinking, but it is needed in all
720 <dt><strong>draw</strong>
721 <dd>The engine's opponent offers the engine a draw. To accept the
722 draw, send "offer draw". To decline, ignore the offer (that is, send
723 nothing). If you're playing on ICS, it's possible for the draw offer
724 to have been withdrawn by the time you accept it, so don't assume the
725 game is over because you accept a draw offer. Continue playing until
726 xboard tells you the game is over. See also "offer draw" below.
729 <dt><strong>result RESULT {COMMENT}</strong>
730 <dd>After the end of each game, xboard will send you a result command.
731 You can use this command to trigger learning. RESULT is either 1-0,
732 0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
733 was a draw, or the game was unfinished. The COMMENT string is purely
734 a human-readable comment; its content is unspecified and subject to
735 change. In ICS mode, it is passed through from ICS uninterpreted.
736 Example: <pre>result 1-0 {White mates}</pre>
738 Here are some notes on interpreting the "result" command. Some apply
739 only to playing on ICS ("Zippy" mode).
743 If you won but did not just play a mate, your opponent must have
744 resigned or forfeited. If you lost but were not just mated, you
745 probably forfeited on time, or perhaps the operator resigned manually.
746 If there was a draw for some nonobvious reason, perhaps your opponent
747 called your flag when he had insufficient mating material (or vice
748 versa), or perhaps the operator agreed to a draw manually.
752 You will get a result command even if you already know the game ended
753 -- for example, after you just checkmated your opponent. In fact, if
754 you send the "RESULT {COMMENT}" command (discussed below), you will
755 simply get the same thing fed back to you with "result" tacked in
756 front. You might not always get a "result *" command, however. In
757 particular, you won't get one in local chess engine mode when the user
758 stops playing by selecting Reset, Edit Game, Exit or the like.
761 <dt><font color=red><strong>setboard FEN</strong></font>
763 The setboard command is the new way to set up positions, beginning
764 in protocol version 2. It is not used unless it has been selected
765 with the feature command. Here FEN is a position in Forsythe-Edwards
766 Notation, as defined in the PGN standard.
768 <p><i>Illegal positions:</i> Note that either setboard or edit can
769 be used to send an illegal position to the engine. The user can
770 create any position with xboard's Edit Position command (even, say,
771 an empty board, or a board with 64 white kings and no black ones).
772 If your engine receives a position that it considers illegal,
773 I suggest that you send the response "tellusererror Illegal position",
774 and then respond to any attempted move with "Illegal move" until
775 the next new, edit, or setboard command.</p>
779 <dt><strong>edit</strong>
782 The edit command is the old way to set up positions. For compatibility
783 with old engines, it is still used by default, but new engines may prefer
784 to use the feature command (see below) to cause xboard to use setboard instead.
786 The edit command puts the chess engine into a special mode, where
787 it accepts the following subcommands:
789 <tr align="left"><th>c<td>change current piece color, initially white
790 <tr align="left"><th>Pa4 (for example)<td>place pawn of current color on a4
791 <tr align="left"><th>xa4 (for example)<td>empty the square a4 (not used by xboard)
792 <tr align="left"><th>#<td>clear board
793 <tr align="left"><th>.<td>leave edit mode
796 See the Idioms section below for additional subcommands used in
797 ChessBase's implementation of the protocol.
800 <p>The edit command does not change the side to move. To set up a
801 black-on-move position, xboard uses the following command sequence:
808 <edit commands>
813 This sequence is used to avoid the "black" command, which is now
814 considered obsolete and which many engines never did implement as
815 specified in this document.
819 After an edit command is complete, if a king and a rook are on their
820 home squares, castling is assumed to be available to them. En passant
821 capture is assumed to be illegal on the current move regardless of the
822 positions of the pawns. The clock for the 50 move rule starts at
823 zero, and for purposes of the draw by repetition rule, no prior
824 positions are deemed to have occurred.
827 <dt><strong>hint</strong>
828 <dd>If the user asks for a hint, xboard sends your engine the command
829 "hint". Your engine should respond with "Hint: xxx", where xxx is a
830 suggested move. If there is no move to suggest, you can ignore the
831 hint command (that is, treat it as a no-op).
834 <dt><strong>bk</strong>
835 <dd>If the user selects "Book" from the xboard menu, xboard will send
836 your engine the command "bk". You can send any text you like as the
837 response, as long as each line begins with a blank space or tab (\t)
838 character, and you send an empty line at the end. The text pops up in
839 a modal information dialog.
842 <dt><strong>undo</strong>
843 <dd>If the user asks to back up one move, xboard will send you the
844 "undo" command. xboard will not send this command without putting you
845 in "force" mode first, so you don't have to worry about what should
846 happen if the user asks to undo a move your engine made. (GNU Chess 4
847 actually switches to playing the opposite color in this case.)
850 <dt><strong>remove</strong>
851 <dd>If the user asks to retract a move, xboard will send you the
852 "remove" command. It sends this command only when the user is on
853 move. Your engine should undo the last two moves (one for each
854 player) and continue playing the same color.
857 <dt><strong>hard</strong>
858 <dd>Turn on pondering (thinking on the opponent's time, also known as
859 "permanent brain"). xboard will not make any assumption about what
860 your default is for pondering or whether "new" affects this setting.
863 <dt><strong>easy</strong>
864 <dd>Turn off pondering.
867 <dt><strong>post</strong>
868 <dd>Turn on thinking/pondering output.
869 See <a href="#10">Thinking Output</a> section.
872 <dt><strong>nopost</strong>
873 <dd>Turn off thinking/pondering output.
876 <dt><strong>analyze</strong>
877 <dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.
880 <dt><strong>name X</strong> <dd>This command informs the engine of its
881 opponent's name. When the engine is playing on a chess server, xboard
882 obtains the opponent's name from the server.
885 playing locally against a human user, xboard obtains the user's login
886 name from the local operating system. When the engine is playing
887 locally against another engine, xboard uses either the other engine's
888 filename or the name that the other engine supplied in the myname
889 option to the feature command. By default, xboard uses the name
890 command only when the engine is playing on a chess server. Beginning
891 in protocol version 2, you can change this with the name option to the
892 feature command; see below.
896 <dt><strong>rating</strong>
897 <dd>In ICS mode, xboard obtains the ICS opponent's rating from the
898 "Creating:" message that appears before each game. (This message may
899 not appear on servers using outdated versions of the FICS code.) In
900 Zippy mode, it sends these ratings on to the chess engine using the
901 "rating" command. The chess engine's own rating comes first, and if
902 either opponent is not rated, his rating is given as 0.
904 In the future this command may also be used in other modes, if ratings
907 Example: <pre>rating 2600 1500</pre>
910 <dt><font color=red><strong>ics HOSTNAME</strong></font>
912 If HOSTNAME is "-", the engine is playing against a local
913 opponent; otherwise, the engine is playing on an Internet Chess Server
914 (ICS) with the given hostname. This command is new in protocol
915 version 2 and is not sent unless the engine has enabled it with
916 the "feature" command. Example: "ics freechess.org"
920 <dt><strong>computer</strong>
921 <dd>The opponent is also a computer chess engine. Some engines alter
922 their playing style when they receive this command.
925 <dt><font color=red><strong>pause</strong></font>
926 <dt><font color=red><strong>resume</strong></font>
927 <dd><font color=red>(These commands are new in protocol
928 version 2 and will not be sent unless feature pause=1 is set. At
929 this writing, xboard actually does not use the commands at all, but it
930 or other interfaces may use them in the future.)
931 The "pause" command puts the engine into a special state where it
932 does not think, ponder, or otherwise consume significant CPU time.
933 The current thinking or pondering (if any) is suspended and both
934 player's clocks are stopped. The only command that the interface may
935 send to the engine while it is in the paused state is "resume". The
936 paused thinking or pondering (if any) resumes from exactly where it
937 left off, and the clock of the player on move resumes running from
942 <h3>Bughouse commands:</h3>
945 xboard now supports bughouse engines when in Zippy mode. See
946 <a href="http://www.tim-mann.org/xboard/zippy.README"
947 >zippy.README</a> for information on Zippy mode and how to turn on the
948 bughouse support. The bughouse move format is given above. xboard
949 sends the following additional commands to the engine when in bughouse
951 Commands to inform your engine of the partner's game state may
952 be added in the future.
956 <dt><strong>partner <player></strong>
957 <dd><player> is now your partner for future games. Example: <pre>partner mann</pre>
960 <dt><strong>partner</strong>
961 <dd>Meaning: You no longer have a partner.
964 <dt><strong>ptell <text></strong>
965 <dd>Your partner told you <text>, either with a ptell or an ordinary tell.
968 <dt><strong>holding [<white>] [<black>]</strong>
969 <dd>White currently holds <white>; black currently holds <black>.
970 Example: <pre>holding [PPPRQ] []</pre>
972 <dt><strong>holding [<white>] [<black>] <color><piece></strong>
973 <dd>White currently holds <white>; black currently holds <black>, after
974 <color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre>
977 <h2><a name="9">9. Commands from the engine to xboard</a></h2>
981 In general, an engine should not send any output to xboard that is not
982 described in this document. As the protocol is extended, newer
983 versions of xboard may recognize additional strings as commands that
984 were previously not assigned a meaning.
990 <strong>feature FEATURE1=VALUE1 FEATURE2=VALUE2 ...</strong>
994 Beginning with version 2, the protocol includes the "feature"
995 command, which lets your engine control certain optional protocol
996 features. Feature settings are written as FEATURE=VALUE, where
997 FEATURE is a name from the list below and VALUE is the value to be
998 assigned. Features can take string, integer, or boolean values; the
999 type of value is listed for each feature. String values are written
1000 in double quotes (for example, <tt>feature myname="Miracle Chess
1001 0.9"</tt>), integers are written in decimal, and boolean values are
1002 written as 0 for false, 1 for true. Any number of features can be set
1003 in one feature command, or multiple feature commands can be given.
1006 Your engine should send one or more feature commands immediately after
1007 receiving the "protover" command, since xboard needs to know the
1008 values of some features before sending further commands to the engine.
1009 Because engines that predate protocol version 2 do not send "feature",
1010 xboard uses a timeout mechanism: when it first starts your engine, it
1011 sends "xboard" and "protover N", then listens for feature commands for
1012 two seconds before sending any other commands. To end this timeout
1013 and avoid the wait, set the feature "done=1" at the end of your last
1014 feature command. To increase the timeout, if needed, set the feature
1015 "done=0" before your first feature command and "done=1" at the end.
1016 If needed, it is okay for your engine to set done=0 soon as it starts,
1017 even before it receives the xboard and protover commands. This can be
1018 useful if your engine takes a long time to initialize itself. It
1019 should be harmless even if you are talking to a (version 1) user
1020 interface that does not understand the "feature" command, since such
1021 interfaces generally ignore commands from the engine that they do not
1026 The feature command is designed to let the protocol change without
1027 breaking engines that were written for older protocol versions. When
1028 a new feature is added to the protocol, its default value is always
1029 chosen to be compatible with older versions of the protocol that did
1030 not have the feature. Any feature that your engine does not set in a
1031 "feature" command retains its default value, so as the protocol
1032 changes, you do not have to change your engine to keep up with it
1033 unless you want to take advantage of a new feature. Because some
1034 features are improvements to the protocol, while others are meant to
1035 cater to engines that do not implement all the protocol features, the
1036 recommended setting for a feature is not always the same as the
1037 default setting. The listing below gives both default and recommended
1038 settings for most features.
1042 You may want to code your engine so as to be able to work with
1043 multiple versions of the engine protocol. Protocol version 1 does not
1044 send the protover command and does not implement the feature command;
1045 if you send a feature command in protocol version 1, it will have no
1046 effect and there will be no response. In protocol version 2 or later,
1047 each feature F that you set generates the response "accepted F" if the
1048 feature is implemented, or "rejected F" if it is not. Thus an engine
1049 author can request any feature without having to keep track of which
1050 protocol version it was introduced in; you need only check whether the
1051 feature is accepted or rejected. This mechanism also makes it
1052 possible for a user interface author to implement a subset of a
1053 protocol version by rejecting some features that are defined in that
1054 version; however, you should realize that engine authors are likely to
1055 code for xboard and may not be prepared to have a feature that they
1056 depend on be rejected.
1060 Here are the features that are currently defined.
1065 <dt><font color=red>
1066 <strong>ping</strong> (boolean, default 0, recommended 1)
1068 <dd><font color=red>
1069 If ping=1, xboard may use the protocol's new "ping" command;
1070 if ping=0, xboard will not use the command.
1073 <dt><font color=red>
1074 <strong>setboard</strong> (boolean, default 0, recommended 1)
1076 <dd><font color=red>
1077 If setboard=1, xboard will use the protocol's new "setboard" command
1078 to set up positions; if setboard=0, it will use the older "edit" command.
1081 <dt><font color=red>
1082 <strong>playother</strong> (boolean, default 0, recommended 1)
1084 <dd><font color=red>
1085 If playother=1, xboard will use the protocol's new "playother" command
1086 when appropriate; if playother=0, it will not use the command.
1089 <dt><font color=red>
1090 <strong>san</strong> (boolean, default 0)
1092 <dd><font color=red>
1093 If san=1, xboard will send moves to the engine in standard algebraic
1094 notation (SAN); for example, Nf3. If san=0, xboard will send moves in
1095 coordinate notation; for example, g1f3. See MOVE in
1096 <a href="#8">section 8</a> above for more details of both kinds of notation.
1099 <dt><font color=red>
1100 <strong>usermove</strong> (boolean, default 0)
1102 <dd><font color=red>
1103 If usermove=1, xboard will send moves to the engine with the
1104 command "usermove MOVE"; if usermove=0, xboard will send just the move,
1105 with no command name.
1108 <dt><font color=red>
1109 <strong>time</strong> (boolean, default 1, recommended 1)
1111 <dd><font color=red>
1112 If time=1, xboard will send the "time" and "otim" commands to
1113 update the engine's clocks; if time=0, it will not.
1116 <dt><font color=red>
1117 <strong>draw</strong> (boolean, default 1, recommended 1)
1119 <dd><font color=red>
1120 If draw=1, xboard will send the "draw" command if the engine's opponent
1121 offers a draw; if draw=0, xboard will not inform the engine about
1122 draw offers. Note that if draw=1, you may receive a draw offer while you
1123 are on move; if this will cause you to move immediately, you should set
1127 <dt><font color=red>
1128 <strong>sigint</strong> (boolean, default 1)
1130 <dd><font color=red>
1131 If sigint=1, xboard may send SIGINT (the interrupt signal) to
1132 the engine as <a href="#7">section 7</a> above; if sigint=0, it will
1136 <dt><font color=red>
1137 <strong>sigterm</strong> (boolean, default 1)
1139 <dd><font color=red>
1140 If sigterm=1, xboard may send SIGTERM (the termination signal) to
1141 the engine as <a href="#7">section 7</a> above; if sigterm=0, it will
1145 <dt><font color=red>
1146 <strong>reuse</strong> (boolean, default 1, recommended 1)
1148 <dd><font color=red>
1149 If reuse=1, xboard may reuse your engine for multiple games. If
1150 reuse=0 (or if the user has set the -xreuse option on xboard's command
1151 line), xboard will kill the engine process after every game and start
1152 a fresh process for the next game.
1155 <dt><font color=red>
1156 <strong>analyze</strong> (boolean, default 1, recommended 1)
1158 <dd><font color=red>
1159 If analyze=0, xboard will not try to use the "analyze" command; it
1160 will pop up an error message if the user asks for analysis mode. If
1161 analyze=1, xboard will try to use the command if the user asks for
1165 <dt><font color=red>
1166 <strong>myname</strong> (string, default determined from engine filename)
1168 <dd><font color=red>
1169 This feature lets you set the name that xboard will use for your
1170 engine in window banners, in the PGN tags of saved game files, and when
1171 sending the "name" command to another engine.
1174 <dt><font color=red>
1175 <strong>variants</strong> (string, see text below)
1177 <dd><font color=red>
1178 This feature indicates which chess variants your engine accepts.
1179 It should be a comma-separated list of variant names. See the table
1180 under the "variant" command in <a href="#8">section 8</a> above. If
1181 you do not set this feature, xboard will assume by default that your
1182 engine supports all variants. (However, the -zippyVariants
1183 command-line option still limits which variants will be accepted in
1184 Zippy mode.) It is recommended that you set this feature to the
1185 correct value for your engine (just "normal" in most cases) rather
1186 than leaving the default in place, so that the user will get an
1187 appropriate error message if he tries to play a variant that your
1188 engine does not support.
1191 <dt><font color=red>
1192 <strong>colors</strong> (boolean, default 1, recommended 0)
1194 <dd><font color=red>
1195 If colors=1, xboard uses the obsolete "white" and "black"
1196 commands in a stylized way that works with most older chess engines
1197 that require the commands. See the "<a href="#13">Idioms</a>" section
1198 below for details. If colors=0, xboard does not use the "white" and
1199 "black" commands at all.
1202 <dt><font color=red>
1203 <strong>ics</strong> (boolean, default 0)
1205 <dd><font color=red>
1206 If ics=1, xboard will use the protocol's new "ics" command
1207 to inform the engine of whether or not it is playing on a chess server;
1208 if ics=0, it will not.
1211 <dt><font color=red>
1212 <strong>name</strong> (boolean, see text below)
1214 <dd><font color=red>
1215 If name=1, xboard will use the protocol's "name" command
1216 to inform the engine of the opponent's name; if name=0, it will not.
1217 By default, name=1 if the engine is playing on a chess server; name=0 if not.
1220 <dt><font color=red>
1221 <strong>pause</strong> (boolean, default 0)
1223 <dd><font color=red>
1224 If pause=1, xboard may use the protocol's new "pause" command;
1225 if pause=0, xboard assumes that the engine does not support this command.
1228 <dt><font color=red>
1229 <strong>done</strong> (integer, no default)
1231 <dd><font color=red>
1232 If you set done=1 during the initial two-second timeout after
1233 xboard sends you the "xboard" command, the
1234 timeout will end and xboard will not look for any more feature
1235 commands before starting normal operation.
1236 If you set done=0, the initial timeout is increased to one hour;
1237 in this case, you must set done=1 before xboard will enter normal operation.
1242 <dt><strong>Illegal move: MOVE</strong>
1243 <dt><strong>Illegal move (REASON): MOVE</strong>
1244 <dd>If your engine receives a MOVE command that is recognizably a move
1245 but is not legal in the current position, your engine must print an
1246 error message in one of the above formats so that xboard can pass the
1247 error on to the user and retract the move. The (REASON) is entirely
1252 Illegal move (in check): Nf3
1253 Illegal move (moving into check): e1g1
1256 Generally, xboard will never send an ambiguous move, so it does not
1257 matter whether you respond to such a move with an Illegal move message
1258 or an Error message.
1261 <dt><strong>Error (ERRORTYPE): COMMAND</strong>
1262 <dd>If your engine receives a command it does not understand or does
1263 not implement, it should print an error message in the above format so
1264 that xboard can parse it. Examples:
1266 Error (ambiguous move): Nf3
1267 Error (unknown command): analyze
1268 Error (command not legal now): undo
1269 Error (too many parameters): level 1 2 3 4 5 6 7
1272 <dt><strong>move MOVE</strong>
1273 <dd>Your engine is making the move MOVE. Do not echo moves from
1274 xboard with this command; send only new moves made by the engine.
1277 <p>For the actual move text from your chess engine (in place of MOVE
1278 above), your move should be either
1280 <li>in coordinate notation (e.g.,
1281 e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,
1283 <li>in Standard Algebraic Notation (SAN) as defined in the
1284 Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),
1285 with the extension piece@square (e.g., P@f7) to handle piece placement
1286 in bughouse and crazyhouse.
1288 xboard itself also accepts some variants of SAN, but for compatibility
1289 with non-xboard interfaces, it is best not to rely on this behavior.
1292 <p>Warning: Even though all versions of this protocol specification
1293 have indicated that xboard accepts SAN moves, some non-xboard
1294 interfaces are known to accept only coordinate notation. See the
1295 Idioms section for more information on the known limitations of some
1296 non-xboard interfaces. It should be safe to send SAN moves if you
1297 receive a "protover 2" (or later) command from the interface, but
1298 otherwise it is best to stick to coordinate notation for maximum
1299 compatibility. An even more conservative approach would be for your
1300 engine to send SAN to the interface only if you have set feature san=1
1301 (which causes the interface to send SAN to you) and have received
1302 "accepted san" in reply.
1306 <dt><strong>RESULT {COMMENT}</strong> <dd>When your engine detects
1307 that the game has ended by rule, your engine must output a line of the
1308 form "RESULT {comment}" (without the quotes), where RESULT is a PGN
1309 result code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Here
1310 "by rule" means that the game is definitely over because of what
1311 happened on the board. In normal chess, this includes checkmate,
1312 stalemate, triple repetition, the 50 move rule, or insufficient
1313 material; it does not include loss on time or the like.
1318 1/2-1/2 {Draw by repetition}
1323 xboard relays the result to the user, the ICS, the other engine in Two
1324 Machines mode, and the PGN save file as required.
1327 <dt><strong>resign</strong>
1328 <dd>If your engine wants to resign, it can send the command "resign".
1329 Alternatively, it can use the "RESULT {comment}" command if the string
1330 "resign" is included in the comment; for example "0-1 {White
1331 resigns}". xboard relays the resignation to the user, the ICS, the
1332 other engine in Two Machines mode, and the PGN save file as required.
1335 <dt><strong>offer draw</strong>
1336 <dd>If your engine wants to offer a draw by agreement (as opposed to
1337 claiming a draw by rule), it can send the command "offer draw".
1338 xboard relays the offer to the user, the ICS, the other engine in Two
1339 Machines mode, and the PGN save file as required. In Machine White,
1340 Machine Black, or Two Machines mode, the offer is considered valid
1341 until your engine has made two more moves.
1344 <dt><font color=red><strong>tellopponent MESSAGE</strong></font>
1345 <dd><font color=red>
1346 This command lets the engine give a message to its opponent,
1347 independent of whether the opponent is a user on the local machine or
1348 a remote ICS user (Zippy mode). MESSAGE consists of any characters,
1349 including whitespace, to the end of the line. When the engine is
1350 playing against a user on the local machine, xboard pops up an
1351 information dialog containing the message. When the engine is playing
1352 against an opponent on the ICS (Zippy mode), xboard sends "say
1353 MESSAGE\n" to the ICS.
1356 <dt><strong>tellothers MESSAGE</strong>
1357 <dd>This command lets the engine give a message to people watching the
1358 game other than the engine's opponent. MESSAGE consists of any
1359 characters, including whitespace, to the end of the line. When the
1360 engine is playing against a user on the local machine, this command
1361 does nothing. When the engine is playing against an opponent on the
1362 ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
1365 <dt><strong>tellall MESSAGE</strong>
1366 <dd>This command lets the engine give a message to its opponent and
1367 other people watching the game,
1368 independent of whether the opponent is a user on the local machine or
1369 a remote ICS user (Zippy mode). MESSAGE consists of any characters,
1370 including whitespace, to the end of the line. When the engine is
1371 playing against a user on the local machine, xboard pops up an
1372 information dialog containing the message. When the engine is playing
1373 against an opponent on the ICS (Zippy mode), xboard sends "kibitz
1374 MESSAGE\n" to the ICS.
1378 <dt><strong>telluser MESSAGE</strong>
1379 <dd>xboard pops up an information dialog containing the message.
1380 MESSAGE consists of any characters, including whitespace, to the end
1384 <dt><strong>tellusererror MESSAGE</strong>
1385 <dd>xboard pops up an error dialog containing the message.
1386 MESSAGE consists of any characters, including whitespace, to the end
1390 <dt><strong>askuser REPTAG MESSAGE</strong>
1391 <dd>Here REPTAG is a string containing no whitespace, and MESSAGE
1392 consists of any characters, including whitespace, to the end of the
1393 line. xboard pops up a question dialog that says MESSAGE and
1394 has a typein box. If the user types in "bar", xboard sends "REPTAG
1395 bar" to the engine. The user can cancel the dialog and send nothing.
1398 <dt><strong>tellics MESSAGE</strong>
1399 <dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists
1400 of any characters, including whitespace, to the end of the line.
1403 <dt><font color=red><strong>tellicsnoalias MESSAGE</strong></font>
1404 <dd><font color=red>
1405 In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a
1406 character that prevents the ICS from expanding command aliases, if
1407 xboard knows of such a character. (On chessclub.com and chess.net,
1408 "/" is used; on freechess.org, "$" is used.) MESSAGE consists of any
1409 characters, including whitespace, to the end of the line.
1414 <h2><a name="10">10. Thinking Output</a></h2>
1417 If the user asks your engine to "show thinking", xboard sends your
1418 engine the "post" command. It sends "nopost" to turn thinking off.
1419 In post mode, your engine sends output lines to show the progress of
1420 its thinking. The engine can send as many or few of these lines as it
1421 wants to, whenever it wants to. Typically they would be sent when the
1422 PV (principal variation) changes or the depth changes. The thinking
1423 output should be in the following format:
1426 <pre>ply score time nodes pv</pre>
1430 <tr align="left"><th>ply<td>Integer giving current search depth.
1431 <tr align="left"><th>score<td>Integer giving current evaluation in centipawns.
1432 <tr align="left"><th>time<td>Current search time in centiseconds (ex:
1433 1028 = 10.28 seconds).
1435 <tr align="left"><th>nodes<td>Nodes searched.
1436 <tr align="left"><th>pv<td>Freeform text giving current "best" line.
1437 You can continue the pv onto another line if you start each
1438 continuation line with at least four space characters.
1445 <pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
1451 9 ply, score=1.56, time = 10.84 seconds, nodes=48000,
1452 PV = "Nf3 Nc6 Nc3 Nf6"
1455 Longer example from actual Crafty output:
1458 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
1459 4 116 23 2252 1. Nf3 Nc6 2. e4 e6
1460 4 116 27 2589 1. Nf3 Nc6 2. e4 e6
1461 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4
1462 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4
1466 You can use the PV to show other things; for instance, while in book,
1467 Crafty shows the observed frequency of different reply moves in its
1468 book. In situations like this where your engine is not really
1469 searching, start the PV with a '(' character:
1473 0 0 0 0 (e4 64%, d4 24%)
1477 GNU Chess output is very slightly different. The ply number is
1478 followed by an extra nonblank character, and the time is in seconds,
1479 not hundredths of seconds. For compatibility, xboard accepts the
1480 extra character and takes it as a flag indicating the different time
1485 2. 14 0 38 d1d2 e8e7
1486 3+ 78 0 65 d1d2 e8e7 d2d3
1487 3& 14 0 89 d1d2 e8e7 d2d3
1488 3& 76 0 191 d1e2 e8e7 e2e3
1489 3. 76 0 215 d1e2 e8e7 e2e3
1490 4& 15 0 366 d1e2 e8e7 e2e3 e7e6
1491 4. 15 0 515 d1e2 e8e7 e2e3 e7e6
1492 5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4
1493 5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4
1494 5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4
1495 6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
1496 6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
1497 7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
1498 7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
1499 8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
1500 8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
1501 9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
1503 9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
1505 10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
1507 10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
1511 <p>If your engine is pondering (thinking on its opponent's time) in post
1512 mode, it can show its thinking then too. In this case your engine may
1513 omit the hint move (the move it is assuming its opponent will make)
1514 from the thinking lines <em>if and only if</em> it sends xboard the move in
1515 the usual "Hint: xxx" format before sending the first line.
1518 <h2><a name="11">11. Time control</a></h2>
1521 xboard supports three styles of time control: conventional chess clocks,
1522 the ICS-style incremental clock, and an exact number of seconds per move.
1525 <p>In conventional clock mode, every time control period is the same.
1526 That is, if the time control is 40 moves in 5 minutes, then after each
1527 side has made 40 moves, they each get an additional 5 minutes, and so
1528 on, ad infinitum. At some future time it would be nice to support a
1529 series of distinct time controls. This is very low on my personal
1530 priority list, but code donations to the xboard project are accepted,
1531 so feel free to take a swing at it. I suggest you talk to me first,
1536 The command to set a conventional time control looks like this:
1545 The 40 means that there are 40 moves per time control. The 5 means
1546 there are 5 minutes in the control. In the second example, the 0:30
1547 means there are 30 seconds. The final 0 means that we are in
1548 conventional clock mode.
1552 The command to set an incremental time control looks like this:
1560 Here the 0 means "play the whole game in this time control period",
1561 the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As
1562 in conventional clock mode, the second argument to level can be in
1563 minutes and seconds.
1567 At the start of the game, each player's clock is set to base minutes.
1568 Immediately after a player makes a move, inc seconds are added to his
1569 clock. A player's clock counts down while it is his turn. Your flag
1570 can be called whenever your clock is zero or negative. (Your clock
1571 can go negative and then become positive again because of the
1576 A special rule on some ICS implementations: if you ask for a game with
1577 base=0, the clocks really start at 10 seconds instead of 0. xboard
1578 itself does not know about this rule, so it passes the 0 on to the
1579 engine instead of changing it to 0:10.
1583 ICS also has time odds games. With time odds, each player has his own
1584 (base, inc) pair, but otherwise things work the same as in normal
1585 games. The Zippy xboard accepts time odds games but ignores the fact
1586 that the opponent's parameters are different; this is perhaps not
1587 quite the right thing to do, but gnuchess doesn't understand time
1588 odds. Time odds games are always unrated.
1592 The command to set an exact number of seconds per move looks like this:
1600 This means that each move must be made in at most 30 seconds. Time not used
1601 on one move does not accumulate for use on later moves.
1604 <h2><a name="12">12. Analyze Mode</a></h2>
1606 <p>xboard supports analyzing fresh games, edited positions, and games
1607 from files. However, all of these look the same from the chess
1608 engine's perspective. Basically, the engine just has to respond to the
1611 Beginning in protocol version 2,
1612 if your engine does not support analyze mode, it should use
1613 the feature command to set analyze=0.
1616 printing the error message "Error (unknown command): analyze" in
1617 response to the "analyze" command will also work, however.
1621 To enter analyze mode, xboard sends the command sequence "post", "analyze".
1622 Analyze mode in your engine should be
1623 similar to force mode, except that your engine thinks about what move
1624 it would make next if it were on move. Your engine should accept the
1625 following commands while in analyze mode:
1629 <li>Any legal move, as in force mode
1630 <li><strong>undo</strong> Back up one move and analyze previous position.
1631 <li><strong>new</strong> Reset position to start of game but stay in analyze mode.
1632 <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.
1634 <li><strong>exit</strong> Leave analyze mode.
1635 <li><strong>.</strong> Send a search status update (optional); see below.
1636 <li><font color=red>
1637 <strong>bk</strong> Show book moves from this position,
1638 if any; see above.</font>
1639 <li><font color=red>
1640 <strong>hint</strong> Show the predicted move from this
1641 position, if any; see above.</font>
1645 If the user selects "Periodic Updates", xboard will send the string
1646 ".\n" to the chess engine periodically during analyze mode, unless the
1647 last PV received began with a '(' character.
1651 The chess engine should respond to ".\n" with a line like this:
1655 stat01: time nodes ply mvleft mvtot <font color=red>mvname</font>
1660 <tr align="left"><th>time<td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).
1661 <tr align="left"><th>nodes<td>Nodes searched so far.
1662 <tr align="left"><th>ply<td>Search depth so far.
1663 <tr align="left"><th>mvleft<td>Number of moves left to consider at this depth.
1664 <tr align="left"><th>mvtot<td>Total number of moves to consider.
1665 <tr align="left"><th><font color=red>mvname</font><td><font color=red>
1666 Move currently being considered (SAN or coordinate notation). Optional;
1667 added in protocol version 2.</font>
1674 stat01: 1234 30000 7 5 30
1675 stat01: 1234 30000 7 5 30 Nf3
1682 <p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
1683 total of 30 legal moves, and I have 5 more moves to search
1684 before going to depth 8. In the second example, of the 30 legal
1685 moves, the one I am currently searching is Nf3.</p>
1688 Implementation of the "." command is optional. If the engine does not
1689 respond to the "." command with a "stat01..." line, xboard will stop
1690 sending "." commands. If the engine does not implement this command,
1691 the analysis window will use a shortened format to display the engine
1696 To give the user some extra information, the chess engine can output
1697 the strings "++\n" and "--\n", to indicate that the current search is
1698 failing high or low, respectively. You don't have to send anything
1699 else to say "Okay, I'm not failing high/low anymore." xboard will
1700 figure this out itself.
1703 <h2><a name="13">13. Idioms and backward compatibility features</a></h2>
1706 Some engines have variant interpretations of the force/go/white/black,
1707 time/otim, and hard/easy command sets.
1708 In order to accommodate these older engines, xboard uses these commands
1709 only according to the stylized patterns ("idioms") given in this section.
1710 The obsolete white and black commands
1711 have historically been particularly troublesome, and it is recommended
1712 that new engines set the feature colors=0 and/or ignore the commands.
1717 <dt><strong>time N</strong>
1718 <dt><strong>otim N</strong>
1719 <dt><strong>MOVE</strong>
1720 <dd>Sent when the opponent makes a move and the engine is already
1721 playing the opposite color.
1724 <dt><strong>white</strong>
1725 <dt><strong>go</strong>
1726 <dd>Sent when the engine is in force mode or playing Black but should
1727 switch to playing White. This sequence is sent only when White is
1730 If you set the feature colors=0, "white" is not sent.
1734 <dt><strong>black</strong>
1735 <dt><strong>go</strong>
1736 <dd>Sent when the engine is in force mode or playing White but should
1737 switch to playing Black. This sequence is sent only when Black is
1740 If you set the feature colors=0, "black" is not sent.
1744 <dt><strong>white</strong>
1745 <dt><strong>time N</strong>
1746 <dt><strong>otim N</strong>
1747 <dt><strong>black</strong>
1748 <dt><strong>go</strong>
1749 <dd>Sent when Black is on move, the engine is in force mode or playing
1750 White, and the engine's clock needs to be updated before it starts
1752 The initial "white" is a kludge to accommodate GNU Chess
1753 4's variant interpretation of these commands.
1755 If you set the feature colors=0, "white" and "black" are not sent.
1759 <dt><strong>black</strong>
1760 <dt><strong>time N</strong>
1761 <dt><strong>otim N</strong>
1762 <dt><strong>white</strong>
1763 <dt><strong>go</strong>
1764 <dd>Sent when White is on move, the engine is in force mode or playing
1765 Black, and the engine's clock needs to be updated before it starts
1766 playing. See previous idiom.
1767 The initial "black" is a kludge to accommodate GNU Chess
1768 4's variant interpretation of these commands.
1770 If you set the feature colors=0, "black" and "white" are not sent.
1774 <dt><strong>hard</strong>
1775 <dt><strong>easy</strong>
1776 <dd>Sent in sequence to turn off pondering if xboard is not sure
1777 whether it is on. When xboard is sure, it will send "hard" or "easy"
1778 alone. xboard does this because "easy" is a toggle in GNU Chess 4 but
1779 "hard" is an absolute on.
1784 To support older engines, certain additional commands from the engine
1785 to xboard are also recognized. (These are commands by themselves, not
1786 values to be placed in the comment field of the PGN result code.)
1787 These forms are not recommended for new engines; use the PGN result
1788 code commands or the resign command instead.
1792 <tr align="left"><th>Command <th>Interpreted as
1793 <tr align="left"><td>White resigns <td>0-1 {White resigns}
1794 <tr align="left"><td>Black resigns <td>1-0 {Black resigns}
1795 <tr align="left"><td>White <td>1-0 {White mates}
1796 <tr align="left"><td>Black <td>0-1 {Black mates}
1797 <tr align="left"><td>Draw <td>1/2-1/2 {Draw}
1798 <tr align="left"><td>computer mates <td>1-0 {White mates} or 0-1 {Black mates}
1799 <tr align="left"><td>opponent mates <td>1-0 {White mates} or 0-1 {Black mates}
1800 <tr align="left"><td>computer resigns <td>0-1 {White resigns} or 1-0 {Black resigns}
1801 <tr align="left"><td>game is a draw <td>1/2-1/2 {Draw}
1802 <tr align="left"><td>checkmate <td>1-0 {White mates} or 0-1 {Black mates}
1806 Commands in the above table are recognized if they begin a line and
1807 arbitrary characters follow, so (for example) "White mates" will be
1808 recognized as "White", and "game is a draw by the 50 move rule" will
1809 be recognized as "game is a draw". All the commands are
1814 An alternative move syntax is also recognized:
1818 <tr align="left"><th>Command <th>Interpreted as
1819 <tr align="left"><td>NUMBER ... MOVE <td>move MOVE
1823 Here NUMBER means any string of decimal digits, optionally ending in a
1824 period. MOVE is any string containing no whitespace. In this command
1825 format, xboard requires the "..." even if your engine is playing
1826 White. A command of the form NUMBER MOVE will be ignored. This odd
1827 treatment of the commands is needed for compatibility with gnuchessx.
1828 The original reasons for it are lost in the mists of time, but I
1829 suspect it was originally a bug in the earliest versions of xboard,
1830 before I started working on it, which someone "fixed" in the wrong
1831 way, by creating a special version of gnuchess (gnuchessx) instead of
1836 Any line that contains the words "offer" and "draw" is recognized as
1841 The "Illegal move" message is recognized even if spelled "illegal
1842 move" and even if the colon (":") is omitted. This accommodates GNU
1843 Chess 4, which prints messages like "Illegal move (no matching
1844 move)e2e4", and old versions of Crafty, which print just "illegal move".
1848 In Zippy mode, for compatibility with older versions of Crafty,
1849 xboard passes through to ICS any line that begins "kibitz", "whisper",
1850 "tell", or "draw". Do not use this feature in new code. Instead, use the
1851 commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),
1852 "1/2-1/2 {COMMENT}", or "offer draw", as appropriate.
1857 If the engine responds to the "sd DEPTH" command with an error message
1858 indicating the command is not supported (such as "Illegal move: sd"),
1859 xboard sets an internal flag and subsequently uses the command
1860 "depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the
1861 newline in the middle of this command! New engines should not rely on
1868 If the engine responds to the "st TIME" command with an error message
1869 indicating the command is not supported (such as "Illegal move: st"),
1870 xboard sets an internal flag and subsequently uses the command "level
1871 1 TIME" instead, for the benefit of GNU Chess 4. Note that this is
1872 not a standard use of the level command, as TIME seconds are not added
1873 after each player makes 1 move; rather, each move is made in at most
1874 TIME seconds. New engines should not implement or rely on this
1881 In support of the -firstHost/-secondHost features, which allow a chess
1882 engine to be run on another machine using the rsh protocol, xboard recognizes
1883 error messages that are likely to come from rsh as fatal errors. The following
1884 messages are currently recognized:
1889 No remote directory<br>
1893 Permission denied<br>
1899 ChessBase/Fritz now implements the xboard/winboard protocol and can use
1900 WinBoard-compatible engines in its GUI. ChessBase's version of the
1901 protocol is generally the same as version 1, except that they have
1902 added the commands <strong>fritz</strong>, <strong>reset</strong>, and
1903 <strong>ponder</strong>, and the edit subcommands
1904 <strong>castle</strong> and <strong>ep</strong>. If you want your
1905 engine to work well with the ChessBase/Fritz GUI, you may need to
1906 implement these additional commands, and you should also be aware of
1907 the peculiar way that ChessBase uses the protocol. See their <a
1908 href="http://www.chessbase.com/Products/engines/winboard/tech.htm"
1909 >web page</a> for documentation.
1915 ChessMaster 8000 also implements version 1 of the xboard/winboard
1916 protocol and can use WinBoard-compatible engines. The original
1917 release of CM8000 also has one additional restriction: only pure
1918 coordinate notation (e.g., e2e4) is accepted in the move command. A
1919 patch to correct this should be available from The Learning Company
1920 (makers of CM8000) in February 2001.
1924 <hr noshade size="2">
1925 <address>converted to HTML by <a href="http://www.jakob.at/steffen/">Steffen A. Jakob</a></address>