3 <title>Chess Engine Communication Protocol</title>
\r
7 <hr noshade size="2">
\r
8 <h1>Chess Engine Communication Protocol</h1>
\r
9 <h1><font color=green>Discussion Proposal</font></h1>
\r
10 <h2><a href="http://www.tim-mann.org/">Tim Mann</a> & <a href="http://home.hccnet.nl/h.g.muller/winboardF.html">H.G.Muller</a></h2>
\r
12 $Id: engine-intf.html,v 2.1 2003/10/27 19:21:00 mann Exp $<br>
\r
13 Version 2; implemented in xboard/WinBoard 4.2.1 and later.<br>
\r
14 Changes since version 1 are indicated in <font color=red>red</font>.<br>
\r
15 Changes for WinBoard 4.3.xx are indicated in <font color=green>green</font>.
\r
16 <hr noshade size="2">
\r
19 <li><a href="#1">1. Introduction</a>
\r
20 <li><a href="#2">2. Connection</a>
\r
21 <li><a href="#3">3. Debugging</a>
\r
22 <li><a href="#4">4. How it got this way</a>
\r
23 <li><a href="#5">5. WinBoard requires Win32 engines</a>
\r
24 <li><a href="#6">6. Hints on input/output</a>
\r
25 <li><a href="#7">7. Signals</a>
\r
26 <li><a href="#8">8. Commands from xboard to the engine</a>
\r
27 <li><a href="#9">9. Commands from the engine to xboard</a>
\r
28 <li><a href="#10">10. Thinking Output</a>
\r
29 <li><a href="#11">11. Time control</a>
\r
30 <li><a href="#12">12. Analyze Mode</a>
\r
31 <li><a href="#13">13. Idioms and backward compatibility features</a>
\r
34 <hr noshade size="2">
\r
36 <h2><a name="1">1. Introduction</a></h2>
\r
39 This document is a set of rough notes on the protocol that xboard and
\r
40 WinBoard use to communicate with gnuchessx and other chess engines.
\r
41 These notes may be useful if you want to connect a different chess
\r
42 engine to xboard. Throughout the notes, "xboard" means both xboard
\r
43 and WinBoard except where they are specifically contrasted.
\r
47 There are two reasons I can imagine someone wanting to do this:
\r
50 <li>You have, or are developing, a chess engine but you don't want to
\r
51 write your own graphical interface.
\r
52 <li>You have, or are developing,a chess engine, and you want to
\r
53 interface it to the Internet Chess Server.
\r
57 In case (2), if you are using xboard, you will need to configure the
\r
58 "Zippy" code into it, but WinBoard includes this code already. See
\r
60 href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
\r
61 in the xboard or WinBoard distribution for more information.
\r
66 These notes are unpolished, but I've attempted to make them complete
\r
67 in this release. If you notice any errors, omissions, or misleading
\r
68 statements, let me know.
\r
72 I'd like to hear from everyone who is trying to interface their own
\r
73 chess engine to xboard/WinBoard. Please email me,
\r
74 tim<a name="nospam">@</a>tim-mann.org. Also, please join
\r
75 the mailing list for authors of xboard/WinBoard compatible chess
\r
76 engines. The list is now hosted by Yahoo Groups; you can join at <a
\r
77 href="http://www.egroups.com/group/chess-engines"
\r
78 >http://www.egroups.com/group/chess-engines</a>, or you can read the
\r
79 list there without joining. The list is filtered to prevent spam.
\r
83 Note that the WinBoard 4.3.xx line is developed independently of the
\r
84 original GNU project, by H.G.Muller.
\r
85 If you have questions about WinBoard 4.3.xx, or want to report bugs in it,
\r
86 report them in the appropriate section of the
\r
87 <a href="http://www.open-aurec.com/wbforum/">WinBoard forum</a>.
\r
91 <h2><a name="2">2. Connection</a></h2>
\r
94 An xboard chess engine runs as a separate process from xboard itself,
\r
95 connected to xboard through a pair of anonymous pipes. The engine
\r
96 does not have to do anything special to set up these pipes. xboard
\r
97 sets up the pipes itself and starts the engine with one pipe as its
\r
98 standard input and the other as its standard output. The engine then
\r
99 reads commands from its standard input and writes responses to its
\r
100 standard output. This is, unfortunately, a little more complicated to
\r
101 do right than it sounds; see <a href="#6">section 6</a> below.
\r
105 And yes, contrary to some people's expectations, exactly the same
\r
106 thing is true for WinBoard. Pipes and standard input/output are
\r
107 implemented in Win32 and work fine. You don't have to use DDE, COM,
\r
108 DLLs, BSOD, or any of the other infinite complexity that
\r
109 Microsoft has created just to talk between two programs. A WinBoard
\r
110 chess engine is a Win32 console program that simply reads from its
\r
111 standard input and writes to its standard output. See sections
\r
112 <a href="#5">5</a> and <a href="#6">6</a> below for additional details.
\r
115 <h2><a name="3">3. Debugging</a></h2>
\r
118 To diagnose problems in your engine's interaction with xboard, use the
\r
119 -debug flag on xboard's command line to see the messages that are
\r
120 being exchanged. In WinBoard, these messages are written to the file
\r
121 WinBoard.debug instead of going to the screen.
\r
125 You can turn debug mode on or off while WinBoard is running by
\r
126 pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard
\r
127 is running by binding DebugProc to a shortcut key (and pressing the
\r
128 key!); see the instructions on shortcut keys in the xboard man page.
\r
132 While your engine is running under xboard/WinBoard, you can send a
\r
133 command directly to the engine by pressing Shift+1 (xboard) or Alt+1
\r
134 (WinBoard 4.0.3 and later). This brings up a dialog that you can type
\r
135 your command into. Press Shift+2 (Alt+2) instead to send to the
\r
136 second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier,
\r
137 Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict
\r
138 with typing the @-sign on some European keyboards.
\r
141 <h2><a name="4">4. How it got this way</a></h2>
\r
144 Originally, xboard was just trying to talk to the existing
\r
145 command-line interface of GNU Chess 3.1+ and 4, which was designed
\r
146 for people to type commands to. So the communication protocol is very
\r
147 ad-hoc. It might have been good to redesign it early on, but because
\r
148 xboard and GNU Chess are separate programs, I didn't want to force
\r
149 people to upgrade them together to versions that matched. I
\r
150 particularly wanted to keep new versions of xboard working with old
\r
151 versions of GNU Chess, to make it easier to compare the play of old
\r
152 and new gnuchess versions. I didn't foresee the need for a clean
\r
153 protocol to be used with other chess engines in the future.
\r
157 Circumstances have changed over the years, and now there are many more
\r
158 engines that work with xboard. I've had to make the protocol
\r
159 description more precise, I've added some features that GNU Chess
\r
160 does not support, and I've specified the standard semantics of a few
\r
161 features to be slightly different from what GNU Chess 4 does.
\r
166 This release of the protocol specification is the first to carry a
\r
167 version number of its own -- version 2. Previous releases simply
\r
168 carried a last-modified date and were loosely tied to specific
\r
169 releases of xboard and WinBoard. The version number "1" applies
\r
170 generally to all those older versions of the protocol.
\r
174 <p>Protocol version 2 remains compatible with older engines but has
\r
175 several new capabilities. In particular, it adds the
\r
176 "feature" command, a new mechanism for making backward-compatible
\r
177 changes and extensions to the protocol. Engines that do not support a
\r
178 particular new feature do not have to use it; new features are not
\r
179 enabled unless the engine specifically requests them using the feature
\r
180 command. If an engine does not send the feature command at all, the
\r
181 protocol behavior is nearly identical to version 1. Several new
\r
182 features can be selected by the feature command in version 2,
\r
183 including the "ping" command (recommended for all engines), the
\r
184 "setboard" command, and many optional parameters. Additional features
\r
185 will probably be added in future versions.
\r
190 If it is necessary to have a separate name,
\r
191 it would be best to refer to the protocol including the green additions as version 2f.
\r
192 I really don't think it is a different protocol from version 2, though.
\r
193 I just tried to clarify some ambiguities in the original definition,
\r
194 now that the WinBoard 4.3.xx line has implemented them in a specific way.
\r
195 The hand-shaking protocol for features as defined in protocol 2 perfectly
\r
196 allows addition of an occasional new features without any need for stepping up the protocol version number,
\r
197 and I think refraining from the latter would enormously lower the barrier for actual
\r
198 implementation of these features in engines.
\r
200 The two really new things are the engine debug comments, and the "nps" command.
\r
201 The former merely tries to regulate an extremely common existing pactice
\r
202 of having engines dump debug messages on WinBoard in an unprotected way,
\r
203 as usually you get away with that.
\r
208 <h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
\r
211 Due to some Microsoft brain damage that I don't understand, WinBoard
\r
212 does not work with chess engines that were compiled to use a DOS
\r
213 extender for 32-bit addressing. (Probably not with 16-bit DOS or
\r
214 Windows programs either.) WinBoard works only with engines that are
\r
215 compiled for the Win32 API. You can get a free compiler that targets
\r
216 the Win32 API from <a href="http://sources.redhat.com/cygwin/"
\r
217 >http://sources.redhat.com/cygwin/</a>. I think DJGPP 2.x should also
\r
218 work if you use the RSXNTDJ extension, but I haven't tried it. Of
\r
219 course, Microsoft Visual C++ will work. Most likely the other
\r
220 commercial products that support Win32 will work too (Borland, etc.),
\r
221 but I have not tried them. Delphi has been successfully used to write
\r
222 engines for WinBoard; if you want to do this, Tony Werten has donated
\r
223 some <a href="http://www.tim-mann.org/winboard/delphi.txt" >sample
\r
224 code</a> that should help you get started.
\r
227 <h2><a name="6">6. Hints on input/output</a></h2>
\r
230 Beware of using buffered I/O in your chess engine. The C stdio
\r
231 library, C++ streams, and the I/O packages in most other languages use
\r
232 buffering both on input and output. That means two things. First,
\r
233 when your engine tries to write some characters to xboard, the library
\r
234 stashes them in an internal buffer and does not actually write them to
\r
235 the pipe connected to xboard until either the buffer fills up or you
\r
236 call a special library routine asking for it to be flushed. (In C
\r
237 stdio, this routine is named <tt>fflush</tt>.) Second, when your engine tries
\r
238 to read some characters from xboard, the library does not read just
\r
239 the characters you asked for -- it reads all the characters that are
\r
240 currently available (up to some limit) and stashes any characters you
\r
241 are not yet ready for in an internal buffer. The next time you ask to
\r
242 read, you get the characters from the buffer (if any) before the
\r
243 library tries to read more data from the actual pipe.
\r
247 Why does this cause problems? First, on the output side, remember
\r
248 that your engine produces output in small quantities (say, a few
\r
249 characters for a move, or a line or two giving the current analysis),
\r
250 and that data always needs to be delivered to xboard/WinBoard for
\r
251 display immediately. If you use buffered output, the data you print
\r
252 will sit in a buffer in your own address space instead of being
\r
257 You can usually fix the output buffering problem by asking for the
\r
258 buffering to be turned off. In C stdio, you do this by calling
\r
259 <tt>setbuf(stdout, NULL)</tt>. A more laborious and error-prone
\r
260 method is to carefully call <tt>fflush(stdout)</tt> after every line
\r
261 you output; I don't recommend this. In C++, you can try
\r
262 <tt>cout.setf(ios::unitbuf)</tt>, which is documented in current
\r
263 editions of "The C++ Programming Language," but not older ones.
\r
264 Another C++ method that might work is
\r
265 <tt>cout.rdbuf()->setbuf(NULL, 0)</tt>. Alternatively, you can
\r
266 carefully call <tt>cout.flush()</tt> after every line you output;
\r
267 again, I don't recommend this.
\r
271 Another way to fix the problem is to use unbuffered operating system
\r
272 calls to write directly to the file descriptor for standard output.
\r
273 On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).
\r
274 On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32
\r
275 native routines like <tt>WriteFile</tt>.
\r
279 Second, on the input side, you are likely to want to poll during your
\r
280 search and stop it if new input has come in. If you implement
\r
281 pondering, you'll need this so that pondering stops when the user
\r
282 makes a move. You should also poll during normal thinking on your
\r
283 move, so that you can implement the "?" (move now) command, and so
\r
284 that you can respond promptly to a "result", "force", or "quit"
\r
285 command if xboard wants to end the game or terminate your engine.
\r
286 Buffered input makes polling more complicated -- when you poll, you
\r
287 must stop your search if there are <em>either</em> characters in the buffer
\r
288 <em>or</em> characters available from the underlying file descriptor.
\r
292 The most direct way to fix this problem is to use unbuffered operating
\r
293 system calls to read (and poll) the underlying file descriptor
\r
294 directly. On Unix, use <tt>read(0, ...)</tt> to read from standard input, and
\r
295 use <tt>select()</tt> to poll it. See the man pages read(2) and select(2).
\r
296 (Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to
\r
297 poll for input. It is not very portable; that is, it does not exist
\r
298 on all versions of Unix, and is broken on some that do have it.) On
\r
299 Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native
\r
300 Win32 <tt>ReadFile()</tt> to read. Unfortunately, under Win32, the function to
\r
301 use for polling is different depending on whether the input device is
\r
302 a pipe, a console, or something else. (More Microsoft brain damage
\r
303 here -- did they never hear of device independence?) For pipes, you
\r
304 can use <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).
\r
306 you can use <tt>GetNumberOfConsoleInputEvents</tt>. For sockets only, you can
\r
307 use <tt>select()</tt>. It might be possible to use
\r
308 <tt>WaitForSingleObject</tt> more
\r
309 generally, but I have not tried it. Some code to do these things can
\r
310 be found in Crafty's utility.c, but I don't guarantee that it's all
\r
311 correct or optimal.
\r
315 A second way to fix the problem might be to ask your I/O library not
\r
316 to buffer on input. It should then be safe to poll the underlying
\r
317 file descriptor as described above. With C, you can try calling
\r
318 <tt>setbuf(stdin, NULL)</tt>. However, I have never tried this. Also, there
\r
319 could be problems if you use <tt>scanf()</tt>, at least with certain patterns,
\r
320 because <tt>scanf()</tt> sometimes needs to read one extra character and "push
\r
321 it back" into the buffer; hence, there is a one-character pushback
\r
322 buffer even if you asked for stdio to be unbuffered. With C++, you
\r
323 can try <tt>cin.rdbuf()->setbuf(NULL, 0)</tt>, but again, I have never tried
\r
328 A third way to fix the problem is to check whether there are
\r
329 characters in the buffer whenever you poll. C I/O libraries generally
\r
330 do not provide any portable way to do this. Under C++, you can use
\r
331 <tt>cin.rdbuf()->in_avail()</tt>. This method has been reported to
\r
333 EXchess. Remember that if there are no characters in the buffer, you
\r
334 still have to poll the underlying file descriptor too, using the
\r
335 method described above.
\r
339 A fourth way to fix the problem is to use a separate thread to read
\r
340 from stdin. This way works well if you are familiar with thread
\r
341 programming. This thread can be blocked waiting for input to come in
\r
342 at all times, while the main thread of your engine does its thinking.
\r
343 When input arrives, you have the thread put the input into a buffer
\r
344 and set a flag in a global variable. Your search routine then
\r
345 periodically tests the global variable to see if there is input to
\r
346 process, and stops if there is. WinBoard and my Win32 ports of ICC
\r
347 timestamp and FICS timeseal use threads to handle multiple input
\r
351 <h2><a name="7">7. Signals</a></h2>
\r
353 <p>Engines that run on Unix need to be concerned with two Unix
\r
354 signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>. This applies both to
\r
355 engines that run under xboard and (the unusual case of) engines that
\r
356 WinBoard remotely runs on a Unix host using the -firstHost or
\r
357 -secondHost feature. It does not apply to engines that run on
\r
358 Windows, because Windows does not have Unix-style signals.
\r
360 Beginning with version 2, you can now turn off the use of
\r
362 signals. See the "feature" command in <a href="#6">section 9</a> below.
\r
366 <p>First, when an engine is sent the "quit" command, it is also given
\r
367 a <tt>SIGTERM</tt> signal shortly afterward to make sure it goes away.
\r
368 If your engine reliably responds to "quit", and the signal causes
\r
369 problems for you, you should either ignore it by calling
\r
370 <tt>signal(SIGTERM, SIG_IGN)</tt> at the start of your program,
\r
371 or disable it with the "feature" command.</p>
\r
373 <p>Second, xboard will send an interrupt signal (<tt>SIGINT</tt>) at
\r
374 certain times when it believes the engine may not be listening to user
\r
375 input (thinking or pondering). WinBoard currently does this only when
\r
376 the engine is running remotely using the -firstHost or -secondHost
\r
377 feature, not when it is running locally. You probably need to know
\r
378 only enough about this grungy feature to keep it from getting in your
\r
383 The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess 4
\r
384 on systems where its input polling code is broken or disabled.
\r
385 Because they work in a rather peculiar way, it is recommended that you
\r
386 either ignore <tt>SIGINT</tt> by having your engine call
\r
387 <tt>signal(SIGINT, SIG_IGN)</tt>, or disable it with the "feature"
\r
391 Here are details for the curious. If xboard needs to send a command
\r
392 when it is the chess engine's move (such as before the "?" command),
\r
393 it sends a <tt>SIGINT</tt> first. If xboard needs to send commands when it is
\r
394 not the chess engine's move, but the chess engine may be pondering
\r
395 (thinking on its opponent's time) or analyzing (analysis or analyze
\r
396 file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.
\r
397 Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard
\r
398 issues more commands. This behavior is necessary for GNU Chess 4. The
\r
399 first <tt>SIGINT</tt> stops it from pondering until the next move, but on some
\r
400 systems, GNU Chess 4 will die if it receives a <tt>SIGINT</tt> when not
\r
401 actually thinking or pondering.
\r
405 There are two reasons why WinBoard does not send the Win32 equivalent
\r
406 of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local
\r
407 engines. First, the Win32 GNU Chess 4 port does not need it. Second, I
\r
408 could not find a way to get it to work. Win32 seems to be designed
\r
409 under the assumption that only console applications, not windowed
\r
410 applications, would ever want to send a <tt>CTRL_C_EVENT</tt>.
\r
413 <h2><a name="8">8. Commands from xboard to the engine</a></h2>
\r
416 All commands from xboard to the engine end with a newline (\n), even
\r
417 where that is not explicitly stated. All your output to xboard must
\r
418 be in complete lines; any form of prompt or partial line will cause
\r
423 At the beginning of each game, xboard sends an initialization string.
\r
424 This is currently "new\nrandom\n" unless the user changes it with the
\r
425 initString or secondInitString option.
\r
429 xboard normally reuses the same chess engine process for multiple
\r
430 games. At the end of a game, xboard will send the "force" command
\r
431 (see below) to make sure your engine stops thinking about the current
\r
432 position. It will later send the initString again to start a new
\r
433 game. If your engine can't play multiple games, you can disable reuse
\r
435 either with the "feature" command (beginning in protocol version
\r
438 with xboard's -xreuse (or -xreuse2) command line
\r
439 option. xboard will then ask the process to quit after each game and
\r
440 start a new process for the next game.
\r
444 <dt><strong>xboard</strong>
\r
445 <dd>This command will be sent once immediately after your engine
\r
446 process is started. You can use it to put your engine into "xboard
\r
447 mode" if that is needed. If your engine prints a prompt to ask for
\r
448 user input, you must turn off the prompt and output a newline when the
\r
449 "xboard" command comes in.
\r
452 <dt><font color=red><strong>protover N</strong></font>
\r
453 <dd><font color=red>
\r
454 Beginning in protocol version 2 (in which N=2), this command will
\r
455 be sent immediately after the "xboard" command. If you receive some
\r
456 other command immediately after "xboard" (such as "new"), you can
\r
457 assume that protocol version 1 is in use. The "protover" command is
\r
458 the only new command that xboard always sends in version 2. All other
\r
459 new commands to the engine are sent only if the engine first enables
\r
460 them with the "feature" command. Protocol versions will always be
\r
461 simple integers so that they can easily be compared.
\r
463 <p>Your engine should reply to the protover command by sending the
\r
464 "feature" command (see below) with the list of non-default feature
\r
465 settings that you require, if any.
\r
467 <p>Your engine should never refuse to run due to receiving a higher
\r
468 protocol version number than it is expecting! New protocol versions
\r
469 will always be compatible with older ones by default; the larger
\r
470 version number is simply a hint that additional "feature" command
\r
471 options added in later protocol versions may be accepted.
\r
475 <dt><font color=red><strong>accepted</strong></font>
\r
476 <dt><font color=red><strong>rejected</strong></font>
\r
477 <dd><font color=red>
\r
478 These commands may be sent to your engine in reply to the "feature"
\r
479 command; see its documentation below.
\r
483 <dt><strong>new</strong>
\r
484 <dd>Reset the board to the standard chess starting position. Set
\r
485 White on move. Leave force mode and set the engine to play Black.
\r
486 Associate the engine's clock with Black and the opponent's clock with
\r
487 White. Reset clocks and time controls to the start of a new game.
\r
488 Use wall clock for time measurement.
\r
489 Stop clocks. Do not ponder on this move, even if pondering is on.
\r
490 Remove any search depth limit previously set by the sd command.
\r
493 <dt><strong>variant VARNAME</strong>
\r
494 <dd>If the game is not standard chess, but a variant, this command is
\r
495 sent after "new" and before the first move or "edit" command. Currently
\r
496 defined variant names are:
\r
499 <tr align="left"><th>wildcastle<td>Shuffle chess where king can castle from d file
\r
500 <tr align="left"><th>nocastle<td>Shuffle chess with no castling at all
\r
501 <tr align="left"><th>fischerandom<td>Fischer Random
\r
502 <tr align="left"><th>bughouse<td>Bughouse, ICC/FICS rules
\r
503 <tr align="left"><th>crazyhouse<td>Crazyhouse, ICC/FICS rules
\r
504 <tr align="left"><th>losers<td>Win by losing all pieces or getting mated (ICC)
\r
505 <tr align="left"><th>suicide<td>Win by losing all pieces including king,
\r
506 or by having fewer pieces when one player has no legal moves (FICS)
\r
507 <tr align="left"><th><font color=red>giveaway</font>
\r
508 <td><font color=red>Win by losing all pieces including king,
\r
509 or by having no legal moves (ICC)</font>
\r
510 <tr align="left"><th>twokings<td>Weird ICC wild 9
\r
511 <tr align="left"><th>kriegspiel<td>Kriegspiel (engines not supported)
\r
512 <tr align="left"><th>atomic<td>Atomic
\r
513 <tr align="left"><th>3check<td>Win by giving check 3 times
\r
514 <tr align="left"><th><font color=green>xiangqi</font>
\r
515 <td><font color=green>Chinese Chess (9x10 board)</font>
\r
516 <tr align="left"><th><font color=green>shogi</font>
\r
517 <td><font color=green>Japanese Chess (9x9 bord)</font>
\r
518 <tr align="left"><th><font color=green>capablanca</font>
\r
519 <td><font color=green>Capablanca Chess (10x8 board, with Archbishop and Chancellor)</font>
\r
520 <tr align="left"><th><font color=green>gothic</font>
\r
521 <td><font color=green>Gothic Chess (10x8 board, same with better opening setup)</font>
\r
522 <tr align="left"><th><font color=green>falcon</font>
\r
523 <td><font color=green>Falcon Chess (10x8 board, with two Falcon pieces)</font>
\r
524 <tr align="left"><th><font color=green>shatranj</font>
\r
525 <td><font color=green>ancient Arabic Chess, with Elephants and General in stead of B and Q</font>
\r
526 <tr align="left"><th><font color=green>courier</font>
\r
527 <td><font color=green>Courier Chess (12x8 board, a medieval precursor of modern Chess</font>
\r
528 <tr align="left"><th><font color=green>knightmate</font>
\r
529 <td><font color=green>King moves as Knight and vice versa</font>
\r
530 <tr align="left"><th><font color=green>berolina</font><td>
\r
531 <font color=green>Pawns capture straight ahead, and move diagonally</font>
\r
532 <tr align="left"><th><font color=green>janus</font><td>
\r
533 <font color=green>Janus Chess (10x8, with two Archbishops)</font>
\r
534 <tr align="left"><th><font color=green>caparandom</font>
\r
535 <td><font color=green>shuffle variant like FRC (10x8 board)</font>
\r
536 <tr align="left"><th><font color=green>cylinder</font>
\r
537 <td><font color=green>Pieces wrap around between side edges, like board is a cylinder</font>
\r
538 <tr align="left"><th>unknown<td>Unknown variant (not supported)
\r
542 <dt><strong>quit</strong>
\r
543 <dd>The chess engine should immediately exit. This command is used
\r
544 when xboard is itself exiting, and also between games if the -xreuse
\r
545 command line option is given (or -xreuse2 for the second engine).
\r
546 See also <a href="#7">Signals</a> above.
\r
549 <dt><strong>random</strong>
\r
550 <dd>This command is specific to GNU Chess 4. You can either ignore it
\r
551 completely (that is, treat it as a no-op) or implement it as GNU Chess
\r
552 does. The command toggles "random" mode (that is, it sets random =
\r
553 !random). In random mode, the engine adds a small random value to its
\r
554 evaluation function to vary its play. The "new" command sets random
\r
558 <dt><strong>force</strong>
\r
559 <dd>Set the engine to play neither color ("force mode"). Stop clocks.
\r
560 The engine should check that moves received in force mode are legal
\r
561 and made in the proper turn, but should not think, ponder, or make
\r
565 <dt><strong>go</strong>
\r
566 <dd>Leave force mode and set the engine to play the color that is on
\r
567 move. Associate the engine's clock with the color that is on move,
\r
568 the opponent's clock with the color that is not on move. Start the engine's
\r
569 clock. Start thinking and eventually make a move.
\r
572 <dt><font color=red><strong>playother</strong></font>
\r
575 (This command is new in protocol version 2. It is not
\r
576 sent unless you enable it with the feature command.)
\r
577 Leave force mode and set the engine to play the color that is <i>not</i> on
\r
578 move. Associate the opponent's clock with the color that is on move,
\r
579 the engine's clock with the color that is not on move. Start the opponent's
\r
580 clock. If pondering is enabled, the engine should begin pondering.
\r
581 If the engine later receives a move, it should start thinking and eventually
\r
586 <dt><strong>white</strong>
\r
589 (This command is obsolete as of protocol version 2, but is still
\r
590 sent in some situations to accommodate older engines unless you disable it
\r
591 with the feature command.)
\r
593 Set White on move. Set the engine to play Black. Stop clocks.
\r
596 <dt><strong>black</strong>
\r
599 (This command is obsolete as of protocol version 2, but is still
\r
600 sent in some situations to accommodate older engines unless you disable it
\r
601 with the feature command.)
\r
603 Set Black on move. Set the engine to play White. Stop clocks.
\r
606 <dt><strong>level MPS BASE INC</strong>
\r
607 <dd>Set time controls. See the <a href="#11">Time Control</a> section below.
\r
610 <dt><strong>st TIME</strong>
\r
611 <dd>Set time controls. See the <a href="#11">Time Control</a> section
\r
615 <dt><strong>sd DEPTH</strong>
\r
616 <dd>The engine should limit its thinking to DEPTH ply.
\r
617 <font color=green>The commands "level" or "st" and "sd" can be used together in an orthogonal way.
\r
618 If both are issued, the engine should observe both limitations.</font>
\r
621 <dt><font color=green><strong>nps NODE_RATE</strong></font>
\r
622 <dd><font color=green>The engine should not use wall-clock time to make its timing decisions,
\r
623 but an own internal time measure based on the number of nodes it has searched
\r
624 (and will report as "thinking output", see <a href="#10">section 10</a>),
\r
625 converted to seconds through dividing by the given NODE_RATE.
\r
626 Example: after receiving the commands "st 8" and "nps 10000",
\r
627 the engine should never use more that 80,000 nodes in the search for any move.
\r
628 In this mode, the engine should report user CPU time used (in its thinking output),
\r
629 rather than wall-clock time.
\r
630 This even holds if NODE_RATE is given as 0,
\r
631 but in that case it should also use the user CPU time for its timing decisions.
\r
632 The effect of an "nps" command should persist until the next "new" command.
\r
636 <dt><strong>time N</strong>
\r
637 <dd>Set a clock that always belongs to the engine. N is a number in
\r
638 centiseconds (units of 1/100 second). Even if the engine changes to
\r
639 playing the opposite color, this clock remains with the engine.
\r
642 <dt><strong>otim N</strong>
\r
644 <dd>Set a clock that always belongs to the opponent. N is a number in
\r
645 centiseconds (units of 1/100 second). Even if the opponent changes to
\r
646 playing the opposite color, this clock remains with the opponent.
\r
648 If needed for purposes of board display in force mode (where the
\r
649 engine is not participating in the game) the time clock should be
\r
650 associated with the last color that the engine was set to play, the
\r
651 otim clock with the opposite color.
\r
654 <font color=green>This business of "clocks remaining with the engine" is apparently so ambiguous
\r
655 that many engines implement it wrong.
\r
656 The clocks in fact always remain with the color.
\r
657 Which clock reading is relayed with "time", and which by "otim", is determined by which side the engine plays.
\r
658 Not that the way the clocks operate and receive extra time (in accordance with the selected time control)
\r
659 is not affected in any way by which moves are made by the engine, which by the opponent, and which were forced.
\r
664 Beginning in protocol version 2, if you can't handle the time and
\r
665 otim commands, you can use the "feature" command to disable them; see
\r
668 The following techniques from older protocol versions also
\r
669 work: You can ignore the time and otim commands (that is, treat them
\r
670 as no-ops), or send back "Error (unknown command): time" the first
\r
671 time you see "time".
\r
674 <dt><strong>MOVE</strong>
\r
675 <dd>See below for the syntax of moves. If the move is illegal, print
\r
676 an error message; see the section "<a href="#9">Commands from the engine to
\r
677 xboard</a>". If the move is legal and in turn, make it. If not in force
\r
678 mode, stop the opponent's clock, start the engine's clock, start
\r
679 thinking, and eventually make a move.
\r
681 When xboard sends your engine a move, it normally sends coordinate
\r
682 algebraic notation. Examples:
\r
685 <tr align="left"><td>Normal moves:<td>e2e4
\r
686 <tr align="left"><td>Pawn promotion:<td>e7e8q
\r
687 <tr align="left"><td>Castling:<td>e1g1, e1c1, e8g8, e8c8
\r
688 <tr align="left"><td>Bughouse/crazyhouse drop:<td>P@h3
\r
689 <tr align="left"><td>ICS Wild 0/1 castling:<td>d1f1, d1b1, d8f8, d8b8
\r
690 <tr align="left"><td>FischerRandom castling:<td>O-O, O-O-O (oh, not zero)
\r
695 Note that on boards with more than 9 ranks, counting of the ranks starts at 0.
\r
700 Beginning in protocol version 2, you can use the feature command
\r
701 to select SAN (standard algebraic notation) instead; for example, e4,
\r
702 Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form,
\r
703 P@h3, is a extension to the PGN standard's definition of SAN, which does
\r
704 not support bughouse or crazyhouse.
\r
709 xboard doesn't reliably detect illegal moves, because it does not keep
\r
710 track of castling unavailability due to king or rook moves, or en
\r
711 passant availability. If xboard sends an illegal move, send back an
\r
712 error message so that xboard can retract it and inform the user; see
\r
713 the section "<a href="#9">Commands from the engine to xboard</a>".
\r
716 <dt><font color=red><strong>usermove MOVE</strong></font>
\r
717 <dd><font color=red>
\r
718 By default, moves are sent to the engine without a command name;
\r
719 the notation is just sent as a line by itself.
\r
720 Beginning in protocol version 2, you can use the feature command
\r
721 to cause the command name "usermove" to be sent before the move.
\r
722 Example: "usermove e2e4".
\r
726 <dt><strong>?</strong>
\r
727 <dd>Move now. If your engine is thinking, it should move immediately;
\r
728 otherwise, the command should be ignored (treated as a no-op). It
\r
729 is permissible for your engine to always ignore the ? command. The
\r
730 only bad consequence is that xboard's Move Now menu command will do
\r
733 It is also permissible for your engine to move immediately if it gets
\r
734 any command while thinking, as long as it processes the command right
\r
735 after moving, but it's preferable if you don't do this. For example,
\r
736 xboard may send post, nopost, easy, hard, force, quit,
\r
740 while the engine is on move.
\r
743 <dt><font color=red><strong>ping N</strong></font>
\r
746 In this command, N is a decimal number. When you receive the command,
\r
747 reply by sending the string <strong>pong N</strong>, where N is the
\r
748 same number you received. Important: You must not reply to a "ping"
\r
749 command until you have finished executing all commands that you
\r
750 received before it. Pondering does not count; if you receive a ping
\r
751 while pondering, you should reply immediately and continue pondering.
\r
752 Because of the way xboard uses the ping command, if you implement the
\r
753 other commands in this protocol, you should never see a "ping" command
\r
754 when it is your move; however, if you do, you must not send the "pong"
\r
755 reply to xboard until after you send your move. For example, xboard
\r
756 may send "?" immediately followed by "ping". If you implement the "?"
\r
757 command, you will have moved by the time you see the subsequent ping
\r
758 command. Similarly, xboard may send a sequence like "force", "new",
\r
759 "ping". You must not send the pong response until after you have
\r
760 finished executing the "new" command and are ready for the new game to
\r
764 The ping command is new in protocol version 2 and will not be sent
\r
765 unless you enable it with the "feature" command. Its purpose is to
\r
766 allow several race conditions that could occur in previous versions of
\r
767 the protocol to be fixed, so it is highly recommended that you
\r
768 implement it. It is especially important in simple engines that do
\r
769 not ponder and do not poll for input while thinking, but it is needed in all
\r
774 <dt><strong>draw</strong>
\r
775 <dd>The engine's opponent offers the engine a draw. To accept the
\r
776 draw, send "offer draw". To decline, ignore the offer (that is, send
\r
777 nothing). If you're playing on ICS, it's possible for the draw offer
\r
778 to have been withdrawn by the time you accept it, so don't assume the
\r
779 game is over because you accept a draw offer. Continue playing until
\r
780 xboard tells you the game is over. See also "offer draw" below.
\r
783 <dt><strong>result RESULT {COMMENT}</strong>
\r
784 <dd>After the end of each game, xboard will send you a result command.
\r
785 You can use this command to trigger learning. RESULT is either 1-0,
\r
786 0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
\r
787 was a draw, or the game was unfinished. The COMMENT string is purely
\r
788 a human-readable comment; its content is unspecified and subject to
\r
789 change. In ICS mode, it is passed through from ICS uninterpreted.
\r
790 Example: <pre>result 1-0 {White mates}</pre>
\r
792 Here are some notes on interpreting the "result" command. Some apply
\r
793 only to playing on ICS ("Zippy" mode).
\r
797 If you won but did not just play a mate, your opponent must have
\r
798 resigned or forfeited. If you lost but were not just mated, you
\r
799 probably forfeited on time, or perhaps the operator resigned manually.
\r
800 If there was a draw for some nonobvious reason, perhaps your opponent
\r
801 called your flag when he had insufficient mating material (or vice
\r
802 versa), or perhaps the operator agreed to a draw manually.
\r
806 You will get a result command even if you already know the game ended
\r
807 -- for example, after you just checkmated your opponent. In fact, if
\r
808 you send the "RESULT {COMMENT}" command (discussed below), you will
\r
809 simply get the same thing fed back to you with "result" tacked in
\r
810 front. You might not always get a "result *" command, however. In
\r
811 particular, you won't get one in local chess engine mode when the user
\r
812 stops playing by selecting Reset, Edit Game, Exit or the like.
\r
815 <dt><font color=red><strong>setboard FEN</strong></font>
\r
816 <dd><font color=red>
\r
817 The setboard command is the new way to set up positions, beginning
\r
818 in protocol version 2. It is not used unless it has been selected
\r
819 with the feature command. Here FEN is a position in Forsythe-Edwards
\r
820 Notation, as defined in the PGN standard.</font>
\r
821 <font color=green>In FRC or CRC, WinBoard will use Shredder-FEN or X-FEN standard,
\r
822 i.e. it can use the rook-file indicator letter to represent a castling right (like HAha)
\r
823 whenever it wants, but if it uses KQkq, this will always refer to the outermost rook on the given side</font>
\r
826 <p><i>Illegal positions:</i> Note that either setboard or edit can
\r
827 be used to send an illegal position to the engine. The user can
\r
828 create any position with xboard's Edit Position command (even, say,
\r
829 an empty board, or a board with 64 white kings and no black ones).
\r
830 If your engine receives a position that it considers illegal,
\r
831 I suggest that you send the response "tellusererror Illegal position",
\r
832 and then respond to any attempted move with "Illegal move" until
\r
833 the next new, edit, or setboard command.</p>
\r
837 <dt><strong>edit</strong>
\r
840 The edit command is the old way to set up positions. For compatibility
\r
841 with old engines, it is still used by default, but new engines may prefer
\r
842 to use the feature command (see below) to cause xboard to use setboard instead.
\r
844 The edit command puts the chess engine into a special mode, where
\r
845 it accepts the following subcommands:
\r
847 <tr align="left"><th>c<td>change current piece color, initially white
\r
848 <tr align="left"><th>Pa4 (for example)<td>place pawn of current color on a4
\r
849 <tr align="left"><th>xa4 (for example)<td>empty the square a4 (not used by xboard)
\r
850 <tr align="left"><th>#<td>clear board
\r
851 <tr align="left"><th>.<td>leave edit mode
\r
854 See the Idioms section below for additional subcommands used in
\r
855 ChessBase's implementation of the protocol.
\r
858 <p>The edit command does not change the side to move. To set up a
\r
859 black-on-move position, xboard uses the following command sequence:
\r
866 <edit commands>
\r
871 This sequence is used to avoid the "black" command, which is now
\r
872 considered obsolete and which many engines never did implement as
\r
873 specified in this document.
\r
877 After an edit command is complete, if a king and a rook are on their
\r
878 home squares, castling is assumed to be available to them. En passant
\r
879 capture is assumed to be illegal on the current move regardless of the
\r
880 positions of the pawns. The clock for the 50 move rule starts at
\r
881 zero, and for purposes of the draw by repetition rule, no prior
\r
882 positions are deemed to have occurred.
\r
884 In FRC or CRC, any rook and king put on the back rank should be considered to
\r
885 have castling rights, even if it later becomes apparent that they cannot be both in the
\r
886 initial position, because the position just set up is asymmetric.
\r
887 It is upto WinBoard to find work-around in cases where this is not desired,
\r
888 similar to the "black kludge" shown above, by setting up an earlier position,
\r
889 and then do a move to destroy castling rights or create e.p. rights.
\r
890 (Don't bet your life on it...)
\r
894 <dt><strong>hint</strong>
\r
895 <dd>If the user asks for a hint, xboard sends your engine the command
\r
896 "hint". Your engine should respond with "Hint: xxx", where xxx is a
\r
897 suggested move. If there is no move to suggest, you can ignore the
\r
898 hint command (that is, treat it as a no-op).
\r
901 <dt><strong>bk</strong>
\r
902 <dd>If the user selects "Book" from the xboard menu, xboard will send
\r
903 your engine the command "bk". You can send any text you like as the
\r
904 response, as long as each line begins with a blank space or tab (\t)
\r
905 character, and you send an empty line at the end. The text pops up in
\r
906 a modal information dialog.
\r
909 <dt><strong>undo</strong>
\r
910 <dd>If the user asks to back up one move, xboard will send you the
\r
911 "undo" command. xboard will not send this command without putting you
\r
912 in "force" mode first, so you don't have to worry about what should
\r
913 happen if the user asks to undo a move your engine made. (GNU Chess 4
\r
914 actually switches to playing the opposite color in this case.)
\r
917 <dt><strong>remove</strong>
\r
918 <dd>If the user asks to retract a move, xboard will send you the
\r
919 "remove" command. It sends this command only when the user is on
\r
920 move. Your engine should undo the last two moves (one for each
\r
921 player) and continue playing the same color.
\r
924 <dt><strong>hard</strong>
\r
925 <dd>Turn on pondering (thinking on the opponent's time, also known as
\r
926 "permanent brain"). xboard will not make any assumption about what
\r
927 your default is for pondering or whether "new" affects this setting.
\r
930 <dt><strong>easy</strong>
\r
931 <dd>Turn off pondering.
\r
934 <dt><strong>post</strong>
\r
935 <dd>Turn on thinking/pondering output.
\r
936 See <a href="#10">Thinking Output</a> section.
\r
939 <dt><strong>nopost</strong>
\r
940 <dd>Turn off thinking/pondering output.
\r
943 <dt><strong>analyze</strong>
\r
944 <dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.
\r
947 <dt><strong>name X</strong> <dd>This command informs the engine of its
\r
948 opponent's name. When the engine is playing on a chess server, xboard
\r
949 obtains the opponent's name from the server.
\r
952 playing locally against a human user, xboard obtains the user's login
\r
953 name from the local operating system. When the engine is playing
\r
954 locally against another engine, xboard uses either the other engine's
\r
955 filename or the name that the other engine supplied in the myname
\r
956 option to the feature command. By default, xboard uses the name
\r
957 command only when the engine is playing on a chess server. Beginning
\r
958 in protocol version 2, you can change this with the name option to the
\r
959 feature command; see below.
\r
963 <dt><strong>rating</strong>
\r
964 <dd>In ICS mode, xboard obtains the ICS opponent's rating from the
\r
965 "Creating:" message that appears before each game. (This message may
\r
966 not appear on servers using outdated versions of the FICS code.) In
\r
967 Zippy mode, it sends these ratings on to the chess engine using the
\r
968 "rating" command. The chess engine's own rating comes first, and if
\r
969 either opponent is not rated, his rating is given as 0.
\r
971 In the future this command may also be used in other modes, if ratings
\r
974 Example: <pre>rating 2600 1500</pre>
\r
977 <dt><font color=red><strong>ics HOSTNAME</strong></font>
\r
978 <dd><font color=red>
\r
979 If HOSTNAME is "-", the engine is playing against a local
\r
980 opponent; otherwise, the engine is playing on an Internet Chess Server
\r
981 (ICS) with the given hostname. This command is new in protocol
\r
982 version 2 and is not sent unless the engine has enabled it with
\r
983 the "feature" command. Example: "ics freechess.org"
\r
987 <dt><strong>computer</strong>
\r
988 <dd>The opponent is also a computer chess engine. Some engines alter
\r
989 their playing style when they receive this command.
\r
992 <dt><font color=red><strong>pause</strong></font>
\r
993 <dt><font color=red><strong>resume</strong></font>
\r
994 <dd><font color=red>(These commands are new in protocol
\r
995 version 2 and will not be sent unless feature pause=1 is set. At
\r
996 this writing, xboard actually does not use the commands at all, but it
\r
997 or other interfaces may use them in the future.)
\r
998 The "pause" command puts the engine into a special state where it
\r
999 does not think, ponder, or otherwise consume significant CPU time.
\r
1000 The current thinking or pondering (if any) is suspended and both
\r
1001 player's clocks are stopped. The only command that the interface may
\r
1002 send to the engine while it is in the paused state is "resume". The
\r
1003 paused thinking or pondering (if any) resumes from exactly where it
\r
1004 left off, and the clock of the player on move resumes running from
\r
1009 <h3>Bughouse commands:</h3>
\r
1012 xboard now supports bughouse engines when in Zippy mode. See
\r
1013 <a href="http://www.tim-mann.org/xboard/zippy.README"
\r
1014 >zippy.README</a> for information on Zippy mode and how to turn on the
\r
1015 bughouse support. The bughouse move format is given above. xboard
\r
1016 sends the following additional commands to the engine when in bughouse
\r
1018 Commands to inform your engine of the partner's game state may
\r
1019 be added in the future.
\r
1023 <dt><strong>partner <player></strong>
\r
1024 <dd><player> is now your partner for future games. Example: <pre>partner mann</pre>
\r
1027 <dt><strong>partner</strong>
\r
1028 <dd>Meaning: You no longer have a partner.
\r
1031 <dt><strong>ptell <text></strong>
\r
1032 <dd>Your partner told you <text>, either with a ptell or an ordinary tell.
\r
1035 <dt><strong>holding [<white>] [<black>]</strong>
\r
1036 <dd>White currently holds <white>; black currently holds <black>.
\r
1037 Example: <pre>holding [PPPRQ] []</pre>
\r
1039 <dt><strong>holding [<white>] [<black>] <color><piece></strong>
\r
1040 <dd>White currently holds <white>; black currently holds <black>, after
\r
1041 <color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre>
\r
1044 <h2><a name="9">9. Commands from the engine to xboard</a></h2>
\r
1048 In general, an engine should not send any output to xboard that is not
\r
1049 described in this document. As the protocol is extended, newer
\r
1050 versions of xboard may recognize additional strings as commands that
\r
1051 were previously not assigned a meaning.
\r
1056 <dt><font color=red>
\r
1057 <strong>feature FEATURE1=VALUE1 FEATURE2=VALUE2 ...</strong>
\r
1060 <dd><font color=red>
\r
1061 Beginning with version 2, the protocol includes the "feature"
\r
1062 command, which lets your engine control certain optional protocol
\r
1063 features. Feature settings are written as FEATURE=VALUE, where
\r
1064 FEATURE is a name from the list below and VALUE is the value to be
\r
1065 assigned. Features can take string, integer, or boolean values; the
\r
1066 type of value is listed for each feature. String values are written
\r
1067 in double quotes (for example, <tt>feature myname="Miracle Chess
\r
1068 0.9"</tt>), integers are written in decimal, and boolean values are
\r
1069 written as 0 for false, 1 for true. Any number of features can be set
\r
1070 in one feature command, or multiple feature commands can be given.
\r
1073 Your engine should send one or more feature commands immediately after
\r
1074 receiving the "protover" command, since xboard needs to know the
\r
1075 values of some features before sending further commands to the engine.
\r
1076 Because engines that predate protocol version 2 do not send "feature",
\r
1077 xboard uses a timeout mechanism: when it first starts your engine, it
\r
1078 sends "xboard" and "protover N", then listens for feature commands for
\r
1079 two seconds before sending any other commands. To end this timeout
\r
1080 and avoid the wait, set the feature "done=1" at the end of your last
\r
1081 feature command. To increase the timeout, if needed, set the feature
\r
1082 "done=0" before your first feature command and "done=1" at the end.
\r
1083 If needed, it is okay for your engine to set done=0 soon as it starts,
\r
1084 even before it receives the xboard and protover commands. This can be
\r
1085 useful if your engine takes a long time to initialize itself. It
\r
1086 should be harmless even if you are talking to a (version 1) user
\r
1087 interface that does not understand the "feature" command, since such
\r
1088 interfaces generally ignore commands from the engine that they do not
\r
1093 The feature command is designed to let the protocol change without
\r
1094 breaking engines that were written for older protocol versions. When
\r
1095 a new feature is added to the protocol, its default value is always
\r
1096 chosen to be compatible with older versions of the protocol that did
\r
1097 not have the feature. Any feature that your engine does not set in a
\r
1098 "feature" command retains its default value, so as the protocol
\r
1099 changes, you do not have to change your engine to keep up with it
\r
1100 unless you want to take advantage of a new feature. Because some
\r
1101 features are improvements to the protocol, while others are meant to
\r
1102 cater to engines that do not implement all the protocol features, the
\r
1103 recommended setting for a feature is not always the same as the
\r
1104 default setting. The listing below gives both default and recommended
\r
1105 settings for most features.
\r
1109 You may want to code your engine so as to be able to work with
\r
1110 multiple versions of the engine protocol. Protocol version 1 does not
\r
1111 send the protover command and does not implement the feature command;
\r
1112 if you send a feature command in protocol version 1, it will have no
\r
1113 effect and there will be no response. In protocol version 2 or later,
\r
1114 each feature F that you set generates the response "accepted F" if the
\r
1115 feature is implemented, or "rejected F" if it is not. Thus an engine
\r
1116 author can request any feature without having to keep track of which
\r
1117 protocol version it was introduced in; you need only check whether the
\r
1118 feature is accepted or rejected. This mechanism also makes it
\r
1119 possible for a user interface author to implement a subset of a
\r
1120 protocol version by rejecting some features that are defined in that
\r
1121 version; however, you should realize that engine authors are likely to
\r
1122 code for xboard and may not be prepared to have a feature that they
\r
1123 depend on be rejected.
\r
1127 Here are the features that are currently defined.
\r
1132 <dt><font color=red>
\r
1133 <strong>ping</strong> (boolean, default 0, recommended 1)
\r
1135 <dd><font color=red>
\r
1136 If ping=1, xboard may use the protocol's new "ping" command;
\r
1137 if ping=0, xboard will not use the command.
\r
1140 <dt><font color=red>
\r
1141 <strong>setboard</strong> (boolean, default 0, recommended 1)
\r
1143 <dd><font color=red>
\r
1144 If setboard=1, xboard will use the protocol's new "setboard" command
\r
1145 to set up positions; if setboard=0, it will use the older "edit" command.
\r
1148 <dt><font color=red>
\r
1149 <strong>playother</strong> (boolean, default 0, recommended 1)
\r
1151 <dd><font color=red>
\r
1152 If playother=1, xboard will use the protocol's new "playother" command
\r
1153 when appropriate; if playother=0, it will not use the command.
\r
1156 <dt><font color=red>
\r
1157 <strong>san</strong> (boolean, default 0)
\r
1159 <dd><font color=red>
\r
1160 If san=1, xboard will send moves to the engine in standard algebraic
\r
1161 notation (SAN); for example, Nf3. If san=0, xboard will send moves in
\r
1162 coordinate notation; for example, g1f3. See MOVE in
\r
1163 <a href="#8">section 8</a> above for more details of both kinds of notation.
\r
1166 <dt><font color=red>
\r
1167 <strong>usermove</strong> (boolean, default 0)
\r
1169 <dd><font color=red>
\r
1170 If usermove=1, xboard will send moves to the engine with the
\r
1171 command "usermove MOVE"; if usermove=0, xboard will send just the move,
\r
1172 with no command name.
\r
1175 <dt><font color=red>
\r
1176 <strong>time</strong> (boolean, default 1, recommended 1)
\r
1178 <dd><font color=red>
\r
1179 If time=1, xboard will send the "time" and "otim" commands to
\r
1180 update the engine's clocks; if time=0, it will not.
\r
1183 <dt><font color=red>
\r
1184 <strong>draw</strong> (boolean, default 1, recommended 1)
\r
1186 <dd><font color=red>
\r
1187 If draw=1, xboard will send the "draw" command if the engine's opponent
\r
1188 offers a draw; if draw=0, xboard will not inform the engine about
\r
1189 draw offers. Note that if draw=1, you may receive a draw offer while you
\r
1190 are on move; if this will cause you to move immediately, you should set
\r
1194 <dt><font color=red>
\r
1195 <strong>sigint</strong> (boolean, default 1)
\r
1197 <dd><font color=red>
\r
1198 If sigint=1, xboard may send SIGINT (the interrupt signal) to
\r
1199 the engine as <a href="#7">section 7</a> above; if sigint=0, it will
\r
1203 <dt><font color=red>
\r
1204 <strong>sigterm</strong> (boolean, default 1)
\r
1206 <dd><font color=red>
\r
1207 If sigterm=1, xboard may send SIGTERM (the termination signal) to
\r
1208 the engine as <a href="#7">section 7</a> above; if sigterm=0, it will
\r
1212 <dt><font color=red>
\r
1213 <strong>reuse</strong> (boolean, default 1, recommended 1)
\r
1215 <dd><font color=red>
\r
1216 If reuse=1, xboard may reuse your engine for multiple games. If
\r
1217 reuse=0 (or if the user has set the -xreuse option on xboard's command
\r
1218 line), xboard will kill the engine process after every game and start
\r
1219 a fresh process for the next game.
\r
1222 <dt><font color=red>
\r
1223 <strong>analyze</strong> (boolean, default 1, recommended 1)
\r
1225 <dd><font color=red>
\r
1226 If analyze=0, xboard will not try to use the "analyze" command; it
\r
1227 will pop up an error message if the user asks for analysis mode. If
\r
1228 analyze=1, xboard will try to use the command if the user asks for
\r
1232 <dt><font color=red>
\r
1233 <strong>myname</strong> (string, default determined from engine filename)
\r
1235 <dd><font color=red>
\r
1236 This feature lets you set the name that xboard will use for your
\r
1237 engine in window banners, in the PGN tags of saved game files, and when
\r
1238 sending the "name" command to another engine.
\r
1241 <dt><font color=red>
\r
1242 <strong>variants</strong> (string, see text below)
\r
1244 <dd><font color=red>
\r
1245 This feature indicates which chess variants your engine accepts.
\r
1246 It should be a comma-separated list of variant names. See the table
\r
1247 under the "variant" command in <a href="#8">section 8</a> above. If
\r
1248 you do not set this feature, xboard will assume by default that your
\r
1249 engine supports all variants. (However, the -zippyVariants
\r
1250 command-line option still limits which variants will be accepted in
\r
1251 Zippy mode.) It is recommended that you set this feature to the
\r
1252 correct value for your engine (just "normal" in most cases) rather
\r
1253 than leaving the default in place, so that the user will get an
\r
1254 appropriate error message if he tries to play a variant that your
\r
1255 engine does not support.
\r
1257 If your engine can play variants on a deviating board size,
\r
1258 like capablanca on an 8x8 board, or capablanca crazyhouse,
\r
1259 it can list them amongst the variants with a prefix spcifying board size plus
\r
1260 holdings size, like 8x8+0_capablanca or 10x8+7_capablanca.
\r
1261 If it is capable of playing any variant with an arbitrary board size,
\r
1262 it should list "boardsize" as one of the variants.
\r
1263 If there is a maximum to the board size, this can be prefixed,
\r
1264 e.g. "12x10+0_boardsize".
\r
1267 <dt><font color=red>
\r
1268 <strong>colors</strong> (boolean, default 1, recommended 0)
\r
1270 <dd><font color=red>
\r
1271 If colors=1, xboard uses the obsolete "white" and "black"
\r
1272 commands in a stylized way that works with most older chess engines
\r
1273 that require the commands. See the "<a href="#13">Idioms</a>" section
\r
1274 below for details. If colors=0, xboard does not use the "white" and
\r
1275 "black" commands at all.
\r
1278 <dt><font color=red>
\r
1279 <strong>ics</strong> (boolean, default 0)
\r
1281 <dd><font color=red>
\r
1282 If ics=1, xboard will use the protocol's new "ics" command
\r
1283 to inform the engine of whether or not it is playing on a chess server;
\r
1284 if ics=0, it will not.
\r
1287 <dt><font color=red>
\r
1288 <strong>name</strong> (boolean, see text below)
\r
1290 <dd><font color=red>
\r
1291 If name=1, xboard will use the protocol's "name" command
\r
1292 to inform the engine of the opponent's name; if name=0, it will not.
\r
1293 By default, name=1 if the engine is playing on a chess server; name=0 if not.
\r
1296 <dt><font color=red>
\r
1297 <strong>pause</strong> (boolean, default 0)
\r
1299 <dd><font color=red>
\r
1300 If pause=1, xboard may use the protocol's new "pause" command;
\r
1301 if pause=0, xboard assumes that the engine does not support this command.
\r
1304 <dt><font color=green>
\r
1305 <strong>nps</strong> (boolean, default ?)
\r
1307 <dd><font color=green>
\r
1308 If nps=1, it means the engine supports the nps command.
\r
1309 If nps=0, it means the engine does not support it, and WinBoard should refrain from sending it.
\r
1310 Default is that WinBoard sends it, in an attempt to try out if the engine understand it.
\r
1311 The engine should properly respond with "Error (unkown command): nps" if it does not implement it,
\r
1312 (as any protocol version pre-scribes),
\r
1313 or WinBoard might assume that the engine did understand the command.
\r
1314 In that case the use of different time standards that ensues could lead to time forfeits for the engine.
\r
1317 <dt><font color=green>
\r
1318 <strong>debug</strong> (boolean, default 0)
\r
1320 <dd><font color=green>
\r
1321 If debug=1, it means the engine wants to send debug output prefixed by '#',
\r
1322 which WinBoard should ignore, except for including it in the winboard.debug file.
\r
1323 As this feature is added to protocol 2 ony late,
\r
1324 so that not all protocol-2 supporting versions of WinBoard might implement it,
\r
1325 it is important that engines check if WinBoard accepts the feature.
\r
1326 If the feature is rejected,
\r
1327 engines must refrain from sending the debug output,
\r
1328 or do so at their own risk.
\r
1331 <dt><font color=red>
\r
1332 <strong>done</strong> (integer, no default)
\r
1334 <dd><font color=red>
\r
1335 If you set done=1 during the initial two-second timeout after
\r
1336 xboard sends you the "xboard" command, the
\r
1337 timeout will end and xboard will not look for any more feature
\r
1338 commands before starting normal operation.
\r
1339 If you set done=0, the initial timeout is increased to one hour;
\r
1340 in this case, you must set done=1 before xboard will enter normal operation.
\r
1345 <dt><strong>Illegal move: MOVE</strong>
\r
1346 <dt><strong>Illegal move (REASON): MOVE</strong>
\r
1347 <dd>If your engine receives a MOVE command that is recognizably a move
\r
1348 but is not legal in the current position, your engine must print an
\r
1349 error message in one of the above formats so that xboard can pass the
\r
1350 error on to the user and retract the move. The (REASON) is entirely
\r
1351 optional. Examples:
\r
1354 Illegal move: e2e4
\r
1355 Illegal move (in check): Nf3
\r
1356 Illegal move (moving into check): e1g1
\r
1359 Generally, xboard will never send an ambiguous move, so it does not
\r
1360 matter whether you respond to such a move with an Illegal move message
\r
1361 or an Error message.
\r
1364 <dt><strong>Error (ERRORTYPE): COMMAND</strong>
\r
1365 <dd>If your engine receives a command it does not understand or does
\r
1366 not implement, it should print an error message in the above format so
\r
1367 that xboard can parse it. Examples:
\r
1369 Error (ambiguous move): Nf3
\r
1370 Error (unknown command): analyze
\r
1371 Error (command not legal now): undo
\r
1372 Error (too many parameters): level 1 2 3 4 5 6 7
\r
1375 <dt><strong>move MOVE</strong>
\r
1376 <dd>Your engine is making the move MOVE. Do not echo moves from
\r
1377 xboard with this command; send only new moves made by the engine.
\r
1380 <p>For the actual move text from your chess engine (in place of MOVE
\r
1381 above), your move should be either
\r
1383 <li>in coordinate notation (e.g.,
\r
1384 e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,
\r
1386 <li>in Standard Algebraic Notation (SAN) as defined in the
\r
1387 Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),
\r
1388 with the extension piece@square (e.g., P@f7) to handle piece placement
\r
1389 in bughouse and crazyhouse.
\r
1391 xboard itself also accepts some variants of SAN, but for compatibility
\r
1392 with non-xboard interfaces, it is best not to rely on this behavior.
\r
1395 <p>Warning: Even though all versions of this protocol specification
\r
1396 have indicated that xboard accepts SAN moves, some non-xboard
\r
1397 interfaces are known to accept only coordinate notation. See the
\r
1398 Idioms section for more information on the known limitations of some
\r
1399 non-xboard interfaces. It should be safe to send SAN moves if you
\r
1400 receive a "protover 2" (or later) command from the interface, but
\r
1401 otherwise it is best to stick to coordinate notation for maximum
\r
1402 compatibility. An even more conservative approach would be for your
\r
1403 engine to send SAN to the interface only if you have set feature san=1
\r
1404 (which causes the interface to send SAN to you) and have received
\r
1405 "accepted san" in reply.
\r
1409 <dt><strong>RESULT {COMMENT}</strong> <dd>When your engine detects
\r
1410 that the game has ended by rule, your engine must output a line of the
\r
1411 form "RESULT {comment}" (without the quotes), where RESULT is a PGN
\r
1412 result code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Here
\r
1413 "by rule" means that the game is definitely over because of what
\r
1414 happened on the board. In normal chess, this includes checkmate,
\r
1415 stalemate, triple repetition, the 50 move rule, or insufficient
\r
1416 material; it does not include loss on time or the like.
\r
1421 1/2-1/2 {Draw by repetition}
\r
1422 1/2-1/2 {Stalemate}
\r
1426 xboard relays the result to the user, the ICS, the other engine in Two
\r
1427 Machines mode, and the PGN save file as required.
\r
1428 <font color=green>Note that "definitey over" above means that sending this command
\r
1429 will be taken by WinBoard as an unconditional refusal of the engine to play on,
\r
1430 which might cause you to forfeit if the game was in fact not over.
\r
1431 This command should thus not be used to offer draws, accept draws,
\r
1432 or make draw-by-rule claims that might not be valid
\r
1433 (because it is not your move, and the opponent already moved without you knowing it yet).
\r
1434 For offering and claiming draws, "offer draw" should be used.</font>
\r
1437 <dt><strong>resign</strong>
\r
1438 <dd>If your engine wants to resign, it can send the command "resign".
\r
1439 Alternatively, it can use the "RESULT {comment}" command if the string
\r
1440 "resign" is included in the comment; for example "0-1 {White
\r
1441 resigns}". xboard relays the resignation to the user, the ICS, the
\r
1442 other engine in Two Machines mode, and the PGN save file as required.
\r
1445 <dt><strong>offer draw</strong>
\r
1446 <dd>If your engine wants to offer a draw by agreement (as opposed to
\r
1447 claiming a draw by rule), it can send the command "offer draw".
\r
1448 xboard relays the offer to the user, the ICS, the other engine in Two
\r
1449 Machines mode, and the PGN save file as required. In Machine White,
\r
1450 Machine Black, or Two Machines mode, the offer is considered valid
\r
1451 until your engine has made two more moves.
\r
1452 <font color=green>This command must also be used to accept a draw offer.
\r
1453 Do not use the 1/2-1/2 command for that, as the offer might be no longer valid,
\r
1454 in which case a refusal to play on implied by the RESULT command would make you forfeit the game.
\r
1455 "offer draw" should also be used to claim 50-move and 3-fold-repetition draws
\r
1456 that will occur <em>after</em> your move, by sending it <em>before</em> making the move.
\r
1457 WinBoard will grant draw offers without the opponent having any say in
\r
1458 it in situations where draws can be claimed.
\r
1459 Only if the draw cannot be claimed, the offer will be passed to your opponent after you make your next move,
\r
1460 just before WinBoard relays this move to the opponent.
\r
1464 <dt><font color=red><strong>tellopponent MESSAGE</strong></font>
\r
1465 <dd><font color=red>
\r
1466 This command lets the engine give a message to its opponent,
\r
1467 independent of whether the opponent is a user on the local machine or
\r
1468 a remote ICS user (Zippy mode). MESSAGE consists of any characters,
\r
1469 including whitespace, to the end of the line. When the engine is
\r
1470 playing against a user on the local machine, xboard pops up an
\r
1471 information dialog containing the message. When the engine is playing
\r
1472 against an opponent on the ICS (Zippy mode), xboard sends "say
\r
1473 MESSAGE\n" to the ICS.
\r
1476 <dt><strong>tellothers MESSAGE</strong>
\r
1477 <dd>This command lets the engine give a message to people watching the
\r
1478 game other than the engine's opponent. MESSAGE consists of any
\r
1479 characters, including whitespace, to the end of the line. When the
\r
1480 engine is playing against a user on the local machine, this command
\r
1481 does nothing. When the engine is playing against an opponent on the
\r
1482 ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
\r
1485 <dt><strong>tellall MESSAGE</strong>
\r
1486 <dd>This command lets the engine give a message to its opponent and
\r
1487 other people watching the game,
\r
1488 independent of whether the opponent is a user on the local machine or
\r
1489 a remote ICS user (Zippy mode). MESSAGE consists of any characters,
\r
1490 including whitespace, to the end of the line. When the engine is
\r
1491 playing against a user on the local machine, xboard pops up an
\r
1492 information dialog containing the message. When the engine is playing
\r
1493 against an opponent on the ICS (Zippy mode), xboard sends "kibitz
\r
1494 MESSAGE\n" to the ICS.
\r
1498 <dt><strong>telluser MESSAGE</strong>
\r
1499 <dd>xboard pops up an information dialog containing the message.
\r
1500 MESSAGE consists of any characters, including whitespace, to the end
\r
1504 <dt><strong>tellusererror MESSAGE</strong>
\r
1505 <dd>xboard pops up an error dialog containing the message.
\r
1506 MESSAGE consists of any characters, including whitespace, to the end
\r
1510 <dt><strong>askuser REPTAG MESSAGE</strong>
\r
1511 <dd>Here REPTAG is a string containing no whitespace, and MESSAGE
\r
1512 consists of any characters, including whitespace, to the end of the
\r
1513 line. xboard pops up a question dialog that says MESSAGE and
\r
1514 has a typein box. If the user types in "bar", xboard sends "REPTAG
\r
1515 bar" to the engine. The user can cancel the dialog and send nothing.
\r
1518 <dt><strong>tellics MESSAGE</strong>
\r
1519 <dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists
\r
1520 of any characters, including whitespace, to the end of the line.
\r
1523 <dt><font color=red><strong>tellicsnoalias MESSAGE</strong></font>
\r
1524 <dd><font color=red>
\r
1525 In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a
\r
1526 character that prevents the ICS from expanding command aliases, if
\r
1527 xboard knows of such a character. (On chessclub.com and chess.net,
\r
1528 "/" is used; on freechess.org, "$" is used.) MESSAGE consists of any
\r
1529 characters, including whitespace, to the end of the line.
\r
1533 <dt><font color=green><strong># COMMENT</strong></font>
\r
1534 <dd><font color=green>
\r
1535 The engine can send any string of printable characters, terminated by a newline,
\r
1536 for inclusion in the winboard.debug file, provided the line starts with a '#' character.
\r
1537 If the engine has set feature debug=1,
\r
1538 it is guaranteed that WinBoard (and any future version of it) will completely ignore
\r
1539 these lines in any other respect.
\r
1544 <h2><a name="10">10. Thinking Output</a></h2>
\r
1547 If the user asks your engine to "show thinking", xboard sends your
\r
1548 engine the "post" command. It sends "nopost" to turn thinking off.
\r
1549 In post mode, your engine sends output lines to show the progress of
\r
1550 its thinking. The engine can send as many or few of these lines as it
\r
1551 wants to, whenever it wants to. Typically they would be sent when the
\r
1552 PV (principal variation) changes or the depth changes. The thinking
\r
1553 output should be in the following format:
\r
1556 <pre>ply score time nodes pv</pre>
\r
1560 <tr align="left"><th>ply<td>Integer giving current search depth.
\r
1561 <tr align="left"><th>score<td>Integer giving current evaluation in centipawns.
\r
1562 <tr align="left"><th>time<td>Current search time in centiseconds (ex:
\r
1563 1028 = 10.28 seconds).
\r
1565 <tr align="left"><th>nodes<td>Nodes searched.
\r
1566 <tr align="left"><th>pv<td>Freeform text giving current "best" line.
\r
1567 You can continue the pv onto another line if you start each
\r
1568 continuation line with at least four space characters.
\r
1575 <pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
\r
1581 9 ply, score=1.56, time = 10.84 seconds, nodes=48000,
\r
1582 PV = "Nf3 Nc6 Nc3 Nf6"
\r
1585 Longer example from actual Crafty output:
\r
1588 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
\r
1589 4 116 23 2252 1. Nf3 Nc6 2. e4 e6
\r
1590 4 116 27 2589 1. Nf3 Nc6 2. e4 e6
\r
1591 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4
\r
1592 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4
\r
1596 You can use the PV to show other things; for instance, while in book,
\r
1597 Crafty shows the observed frequency of different reply moves in its
\r
1598 book. In situations like this where your engine is not really
\r
1599 searching, start the PV with a '(' character:
\r
1603 0 0 0 0 (e4 64%, d4 24%)
\r
1607 GNU Chess output is very slightly different. The ply number is
\r
1608 followed by an extra nonblank character, and the time is in seconds,
\r
1609 not hundredths of seconds. For compatibility, xboard accepts the
\r
1610 extra character and takes it as a flag indicating the different time
\r
1615 2. 14 0 38 d1d2 e8e7
\r
1616 3+ 78 0 65 d1d2 e8e7 d2d3
\r
1617 3& 14 0 89 d1d2 e8e7 d2d3
\r
1618 3& 76 0 191 d1e2 e8e7 e2e3
\r
1619 3. 76 0 215 d1e2 e8e7 e2e3
\r
1620 4& 15 0 366 d1e2 e8e7 e2e3 e7e6
\r
1621 4. 15 0 515 d1e2 e8e7 e2e3 e7e6
\r
1622 5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4
\r
1623 5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4
\r
1624 5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4
\r
1625 6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
1626 6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
1627 7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
1628 7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
1629 8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
\r
1630 8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
\r
1631 9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
\r
1633 9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
\r
1635 10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
\r
1637 10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
\r
1641 <p>If your engine is pondering (thinking on its opponent's time) in post
\r
1642 mode, it can show its thinking then too. In this case your engine may
\r
1643 omit the hint move (the move it is assuming its opponent will make)
\r
1644 from the thinking lines <em>if and only if</em> it sends xboard the move in
\r
1645 the usual "Hint: xxx" format before sending the first line.
\r
1648 <h2><a name="11">11. Time control</a></h2>
\r
1651 xboard supports three styles of time control: conventional chess clocks,
\r
1652 the ICS-style incremental clock, and an exact number of seconds per move.
\r
1655 <p>In conventional clock mode, every time control period is the same.
\r
1656 That is, if the time control is 40 moves in 5 minutes, then after each
\r
1657 side has made 40 moves, they each get an additional 5 minutes, and so
\r
1658 on, ad infinitum. At some future time it would be nice to support a
\r
1659 series of distinct time controls. This is very low on my personal
\r
1660 priority list, but code donations to the xboard project are accepted,
\r
1661 so feel free to take a swing at it. I suggest you talk to me first,
\r
1666 The command to set a conventional time control looks like this:
\r
1675 The 40 means that there are 40 moves per time control. The 5 means
\r
1676 there are 5 minutes in the control. In the second example, the 0:30
\r
1677 means there are 30 seconds. The final 0 means that we are in
\r
1678 conventional clock mode.
\r
1682 <font color=green>
\r
1683 Note that the time parameter in this command is not a pure numeric argument,
\r
1684 but in general is a character string, in order to pass the number of seconds.
\r
1685 Engines are encouraged to ignore any unexpected characters at the end of this string,
\r
1686 i.e. following the MIN or MIN:SEC specification.
\r
1687 Future protocol versions might (under control of an appropriate feature)
\r
1688 append such extra characters to this argument,
\r
1689 in order to inform the engine in advance of the time control it can expect after the current session completes.
\r
1690 E.g. "level 40 25+5 0" could mean that the engine has to play 40 moves in 25 minutes,
\r
1691 but should expect to get only 5 minutes for the entire remainder of the game after that,
\r
1692 rather than another 25 minutes for the next 40 moves.
\r
1693 When the time comes, (i.e. after the 40 moves),
\r
1694 it will be informed of the time-control change by receiving a new "level 0 5 0" command,
\r
1695 but engines with advanced time management might want to plan for this in advance.
\r
1700 The command to set an incremental time control looks like this:
\r
1708 Here the 0 means "play the whole game in this time control period",
\r
1709 the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As
\r
1710 in conventional clock mode, the second argument to level can be in
\r
1711 minutes and seconds.
\r
1715 At the start of the game, each player's clock is set to base minutes.
\r
1716 Immediately after a player makes a move, inc seconds are added to his
\r
1717 clock. A player's clock counts down while it is his turn. Your flag
\r
1718 can be called whenever your clock is zero or negative. (Your clock
\r
1719 can go negative and then become positive again because of the
\r
1724 The number of moves given in the level command (when non-zero) should
\r
1725 be taken as the number of moves still to do before the specified time
\r
1726 will be added to the clock, if the "level" command is received after
\r
1727 some moves have already been played.
\r
1728 The time given should be interpreted as the time left on its clock
\r
1729 (including any time left over from the previous sessions),
\r
1730 and not necessarily the time that will be added to the clock
\r
1731 after the specified number of moves has been played.
\r
1732 This is only relevant in WinBoard 4.3.xx, which might send the engine
\r
1733 "level" commands during a game,
\r
1734 just before the engine has to start thinking about the first move of
\r
1735 a new time-control session.
\r
1736 Example: if at the start of the game "level 40 60 0" was given
\r
1737 (40 moves per hour),
\r
1738 and the engine receives "level 20 22 0" just before move 41,
\r
1739 it should understand that it should do the next 20 moves in 22 minutes
\r
1740 (pehaps because the secondary session was 20 moves per 15 minutes,
\r
1741 and it had 7 minutes left on its clock after the first 40 moves).
\r
1745 A special rule on some ICS implementations: if you ask for a game with
\r
1746 base=0, the clocks really start at 10 seconds instead of 0. xboard
\r
1747 itself does not know about this rule, so it passes the 0 on to the
\r
1748 engine instead of changing it to 0:10.
\r
1752 ICS also has time odds games. With time odds, each player has his own
\r
1753 (base, inc) pair, but otherwise things work the same as in normal
\r
1754 games. The Zippy xboard accepts time odds games but ignores the fact
\r
1755 that the opponent's parameters are different; this is perhaps not
\r
1756 quite the right thing to do, but gnuchess doesn't understand time
\r
1757 odds. Time odds games are always unrated.
\r
1761 The command to set an exact number of seconds per move looks like this:
\r
1769 This means that each move must be made in at most 30 seconds. Time not used
\r
1770 on one move does not accumulate for use on later moves.
\r
1773 <h2><a name="12">12. Analyze Mode</a></h2>
\r
1775 <p>xboard supports analyzing fresh games, edited positions, and games
\r
1776 from files. However, all of these look the same from the chess
\r
1777 engine's perspective. Basically, the engine just has to respond to the
\r
1778 "analyze" command.
\r
1780 Beginning in protocol version 2,
\r
1781 if your engine does not support analyze mode, it should use
\r
1782 the feature command to set analyze=0.
\r
1784 The older method of
\r
1785 printing the error message "Error (unknown command): analyze" in
\r
1786 response to the "analyze" command will also work, however.
\r
1790 To enter analyze mode, xboard sends the command sequence "post", "analyze".
\r
1791 Analyze mode in your engine should be
\r
1792 similar to force mode, except that your engine thinks about what move
\r
1793 it would make next if it were on move. Your engine should accept the
\r
1794 following commands while in analyze mode:
\r
1798 <li>Any legal move, as in force mode
\r
1799 <li><strong>undo</strong> Back up one move and analyze previous position.
\r
1800 <li><strong>new</strong> Reset position to start of game but stay in analyze mode.
\r
1801 <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.
\r
1803 <li><strong>exit</strong> Leave analyze mode.
\r
1804 <li><strong>.</strong> Send a search status update (optional); see below.
\r
1805 <li><font color=red>
\r
1806 <strong>bk</strong> Show book moves from this position,
\r
1807 if any; see above.</font>
\r
1808 <li><font color=red>
\r
1809 <strong>hint</strong> Show the predicted move from this
\r
1810 position, if any; see above.</font>
\r
1814 If the user selects "Periodic Updates", xboard will send the string
\r
1815 ".\n" to the chess engine periodically during analyze mode, unless the
\r
1816 last PV received began with a '(' character.
\r
1820 The chess engine should respond to ".\n" with a line like this:
\r
1824 stat01: time nodes ply mvleft mvtot <font color=red>mvname</font>
\r
1829 <tr align="left"><th>time<td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).
\r
1830 <tr align="left"><th>nodes<td>Nodes searched so far.
\r
1831 <tr align="left"><th>ply<td>Search depth so far.
\r
1832 <tr align="left"><th>mvleft<td>Number of moves left to consider at this depth.
\r
1833 <tr align="left"><th>mvtot<td>Total number of moves to consider.
\r
1834 <tr align="left"><th><font color=red>mvname</font><td><font color=red>
\r
1835 Move currently being considered (SAN or coordinate notation). Optional;
\r
1836 added in protocol version 2.</font>
\r
1843 stat01: 1234 30000 7 5 30
\r
1844 stat01: 1234 30000 7 5 30 Nf3
\r
1851 <p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
\r
1852 total of 30 legal moves, and I have 5 more moves to search
\r
1853 before going to depth 8. In the second example, of the 30 legal
\r
1854 moves, the one I am currently searching is Nf3.</p>
\r
1857 Implementation of the "." command is optional. If the engine does not
\r
1858 respond to the "." command with a "stat01..." line, xboard will stop
\r
1859 sending "." commands. If the engine does not implement this command,
\r
1860 the analysis window will use a shortened format to display the engine
\r
1865 To give the user some extra information, the chess engine can output
\r
1866 the strings "++\n" and "--\n", to indicate that the current search is
\r
1867 failing high or low, respectively. You don't have to send anything
\r
1868 else to say "Okay, I'm not failing high/low anymore." xboard will
\r
1869 figure this out itself.
\r
1872 <h2><a name="13">13. Idioms and backward compatibility features</a></h2>
\r
1875 Some engines have variant interpretations of the force/go/white/black,
\r
1876 time/otim, and hard/easy command sets.
\r
1877 In order to accommodate these older engines, xboard uses these commands
\r
1878 only according to the stylized patterns ("idioms") given in this section.
\r
1879 The obsolete white and black commands
\r
1880 have historically been particularly troublesome, and it is recommended
\r
1881 that new engines set the feature colors=0 and/or ignore the commands.
\r
1886 <dt><strong>time N</strong>
\r
1887 <dt><strong>otim N</strong>
\r
1888 <dt><strong>MOVE</strong>
\r
1889 <dd>Sent when the opponent makes a move and the engine is already
\r
1890 playing the opposite color.
\r
1893 <dt><strong>white</strong>
\r
1894 <dt><strong>go</strong>
\r
1895 <dd>Sent when the engine is in force mode or playing Black but should
\r
1896 switch to playing White. This sequence is sent only when White is
\r
1899 If you set the feature colors=0, "white" is not sent.
\r
1903 <dt><strong>black</strong>
\r
1904 <dt><strong>go</strong>
\r
1905 <dd>Sent when the engine is in force mode or playing White but should
\r
1906 switch to playing Black. This sequence is sent only when Black is
\r
1909 If you set the feature colors=0, "black" is not sent.
\r
1913 <dt><strong>white</strong>
\r
1914 <dt><strong>time N</strong>
\r
1915 <dt><strong>otim N</strong>
\r
1916 <dt><strong>black</strong>
\r
1917 <dt><strong>go</strong>
\r
1918 <dd>Sent when Black is on move, the engine is in force mode or playing
\r
1919 White, and the engine's clock needs to be updated before it starts
\r
1921 The initial "white" is a kludge to accommodate GNU Chess
\r
1922 4's variant interpretation of these commands.
\r
1924 If you set the feature colors=0, "white" and "black" are not sent.
\r
1928 <dt><strong>black</strong>
\r
1929 <dt><strong>time N</strong>
\r
1930 <dt><strong>otim N</strong>
\r
1931 <dt><strong>white</strong>
\r
1932 <dt><strong>go</strong>
\r
1933 <dd>Sent when White is on move, the engine is in force mode or playing
\r
1934 Black, and the engine's clock needs to be updated before it starts
\r
1935 playing. See previous idiom.
\r
1936 The initial "black" is a kludge to accommodate GNU Chess
\r
1937 4's variant interpretation of these commands.
\r
1939 If you set the feature colors=0, "black" and "white" are not sent.
\r
1943 <dt><strong>hard</strong>
\r
1944 <dt><strong>easy</strong>
\r
1945 <dd>Sent in sequence to turn off pondering if xboard is not sure
\r
1946 whether it is on. When xboard is sure, it will send "hard" or "easy"
\r
1947 alone. xboard does this because "easy" is a toggle in GNU Chess 4 but
\r
1948 "hard" is an absolute on.
\r
1953 To support older engines, certain additional commands from the engine
\r
1954 to xboard are also recognized. (These are commands by themselves, not
\r
1955 values to be placed in the comment field of the PGN result code.)
\r
1956 These forms are not recommended for new engines; use the PGN result
\r
1957 code commands or the resign command instead.
\r
1961 <tr align="left"><th>Command <th>Interpreted as
\r
1962 <tr align="left"><td>White resigns <td>0-1 {White resigns}
\r
1963 <tr align="left"><td>Black resigns <td>1-0 {Black resigns}
\r
1964 <tr align="left"><td>White <td>1-0 {White mates}
\r
1965 <tr align="left"><td>Black <td>0-1 {Black mates}
\r
1966 <tr align="left"><td>Draw <td>1/2-1/2 {Draw}
\r
1967 <tr align="left"><td>computer mates <td>1-0 {White mates} or 0-1 {Black mates}
\r
1968 <tr align="left"><td>opponent mates <td>1-0 {White mates} or 0-1 {Black mates}
\r
1969 <tr align="left"><td>computer resigns <td>0-1 {White resigns} or 1-0 {Black resigns}
\r
1970 <tr align="left"><td>game is a draw <td>1/2-1/2 {Draw}
\r
1971 <tr align="left"><td>checkmate <td>1-0 {White mates} or 0-1 {Black mates}
\r
1975 Commands in the above table are recognized if they begin a line and
\r
1976 arbitrary characters follow, so (for example) "White mates" will be
\r
1977 recognized as "White", and "game is a draw by the 50 move rule" will
\r
1978 be recognized as "game is a draw". All the commands are
\r
1983 An alternative move syntax is also recognized:
\r
1987 <tr align="left"><th>Command <th>Interpreted as
\r
1988 <tr align="left"><td>NUMBER ... MOVE <td>move MOVE
\r
1992 Here NUMBER means any string of decimal digits, optionally ending in a
\r
1993 period. MOVE is any string containing no whitespace. In this command
\r
1994 format, xboard requires the "..." even if your engine is playing
\r
1995 White. A command of the form NUMBER MOVE will be ignored. This odd
\r
1996 treatment of the commands is needed for compatibility with gnuchessx.
\r
1997 The original reasons for it are lost in the mists of time, but I
\r
1998 suspect it was originally a bug in the earliest versions of xboard,
\r
1999 before I started working on it, which someone "fixed" in the wrong
\r
2000 way, by creating a special version of gnuchess (gnuchessx) instead of
\r
2005 Any line that contains the words "offer" and "draw" is recognized as
\r
2010 The "Illegal move" message is recognized even if spelled "illegal
\r
2011 move" and even if the colon (":") is omitted. This accommodates GNU
\r
2012 Chess 4, which prints messages like "Illegal move (no matching
\r
2013 move)e2e4", and old versions of Crafty, which print just "illegal move".
\r
2017 In Zippy mode, for compatibility with older versions of Crafty,
\r
2018 xboard passes through to ICS any line that begins "kibitz", "whisper",
\r
2019 "tell", or "draw". Do not use this feature in new code. Instead, use the
\r
2020 commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),
\r
2021 "1/2-1/2 {COMMENT}", or "offer draw", as appropriate.
\r
2026 If the engine responds to the "sd DEPTH" command with an error message
\r
2027 indicating the command is not supported (such as "Illegal move: sd"),
\r
2028 xboard sets an internal flag and subsequently uses the command
\r
2029 "depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the
\r
2030 newline in the middle of this command! New engines should not rely on
\r
2037 If the engine responds to the "st TIME" command with an error message
\r
2038 indicating the command is not supported (such as "Illegal move: st"),
\r
2039 xboard sets an internal flag and subsequently uses the command "level
\r
2040 1 TIME" instead, for the benefit of GNU Chess 4. Note that this is
\r
2041 not a standard use of the level command, as TIME seconds are not added
\r
2042 after each player makes 1 move; rather, each move is made in at most
\r
2043 TIME seconds. New engines should not implement or rely on this
\r
2050 In support of the -firstHost/-secondHost features, which allow a chess
\r
2051 engine to be run on another machine using the rsh protocol, xboard recognizes
\r
2052 error messages that are likely to come from rsh as fatal errors. The following
\r
2053 messages are currently recognized:
\r
2058 No remote directory<br>
\r
2062 Permission denied<br>
\r
2068 ChessBase/Fritz now implements the xboard/winboard protocol and can use
\r
2069 WinBoard-compatible engines in its GUI. ChessBase's version of the
\r
2070 protocol is generally the same as version 1, except that they have
\r
2071 added the commands <strong>fritz</strong>, <strong>reset</strong>, and
\r
2072 <strong>ponder</strong>, and the edit subcommands
\r
2073 <strong>castle</strong> and <strong>ep</strong>. If you want your
\r
2074 engine to work well with the ChessBase/Fritz GUI, you may need to
\r
2075 implement these additional commands, and you should also be aware of
\r
2076 the peculiar way that ChessBase uses the protocol. See their <a
\r
2077 href="http://www.chessbase.com/Products/engines/winboard/tech.htm"
\r
2078 >web page</a> for documentation.
\r
2084 ChessMaster 8000 also implements version 1 of the xboard/winboard
\r
2085 protocol and can use WinBoard-compatible engines. The original
\r
2086 release of CM8000 also has one additional restriction: only pure
\r
2087 coordinate notation (e.g., e2e4) is accepted in the move command. A
\r
2088 patch to correct this should be available from The Learning Company
\r
2089 (makers of CM8000) in February 2001.
\r
2093 <hr noshade size="2">
\r
2094 <address>converted to HTML by <a href="http://www.jakob.at/steffen/">Steffen A. Jakob</a></address>
\r
projects / xboard.git / blob