1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
\r
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
\r
5 <title>Chess Engine Communication Protocol</title>
\r
6 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
\r
7 <style type="text/css">
\r
9 border-top:2px solid black;
\r
10 border-bottom:2px solid black;
\r
12 .version1 { color: red;}
\r
13 .version43 { color: green;}
\r
14 .version44 { color: blue; }
\r
15 .version47 { color: purple; }
\r
16 .version48 { color: brown; }
\r
18 table tr { text-align: left}
\r
19 tr > td:first-child { font-weight:bold;}
\r
20 dt { font-weight:bold;}
\r
27 <div class="header">
\r
28 <h1>Chess Engine Communication Protocol</h1>
\r
29 <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
31 Version 2; implemented in xboard/WinBoard 4.2.1 and later. (Sept 3, 2009)<br />
\r
32 Changes since version 1 are indicated in <span class="version1">red</span>.<br />
\r
33 Changes for WinBoard 4.3.xx are indicated in <span class="version43">green</span>.<br />
\r
34 Changes for WinBoard 4.4.xx are indicated in <span class="version44">blue</span>.
\r
39 <li><a href="#1">1. Introduction</a></li>
\r
40 <li><a href="#2">2. Connection</a></li>
\r
41 <li><a href="#3">3. Debugging</a></li>
\r
42 <li><a href="#4">4. How it got this way</a></li>
\r
43 <li><a href="#5">5. WinBoard requires Win32 engines</a></li>
\r
44 <li><a href="#6">6. Hints on input/output</a></li>
\r
45 <li><a href="#7">7. Signals</a></li>
\r
46 <li><a href="#8">8. Commands from xboard to the engine</a></li>
\r
47 <li><a href="#9">9. Commands from the engine to xboard</a></li>
\r
48 <li><a href="#10">10. Thinking Output</a></li>
\r
49 <li><a href="#11">11. Time control</a></li>
\r
50 <li><a href="#12">12. Analyze Mode</a></li>
\r
51 <li><a href="#13">13. Idioms and backward compatibility features</a></li>
\r
56 <h2><a name="1">1. Introduction</a></h2>
\r
59 This document is a set of rough notes on the protocol that xboard and
\r
60 WinBoard use to communicate with gnuchessx and other chess engines.
\r
61 These notes may be useful if you want to connect a different chess
\r
62 engine to xboard. Throughout the notes, "xboard" means both xboard
\r
63 and WinBoard except where they are specifically contrasted.
\r
67 There are two reasons I can imagine someone wanting to do this:
\r
71 <li>You have, or are developing, a chess engine but you don't want to
\r
72 write your own graphical interface. </li>
\r
73 <li>You have, or are developing,a chess engine, and you want to
\r
74 interface it to the Internet Chess Server.</li>
\r
78 In case (2), if you are using xboard, you will need to configure the
\r
79 "Zippy" code into it, but WinBoard includes this code already. See
\r
81 href="http://www.tim-mann.org/xboard/zippy.README">zippy.README</a>
\r
82 in the xboard or WinBoard distribution for more information.
\r
86 These notes are unpolished, but I've attempted to make them complete
\r
87 in this release. If you notice any errors, omissions, or misleading
\r
88 statements, let me know.
\r
92 I'd like to hear from everyone who is trying to interface their own
\r
93 chess engine to xboard/WinBoard. Please join the mailing list for
\r
94 authors of xboard/WinBoard compatible chess engines and post a message
\r
95 about what you're doing. The list is now hosted by Yahoo Groups; you
\r
96 can join at <a href="http://groups.yahoo.com/group/chess-engines"
\r
97 >http://groups.yahoo.com/group/chess-engines</a>, or you can read the
\r
98 list there without joining. The list is filtered to prevent spam.
\r
101 <p class="version43">
\r
102 Note that the WinBoard 4.3.xx line was developed independently of the
\r
103 original GNU project, by H.G.Muller.
\r
104 If you have questions about WinBoard 4.3.xx, or want to report bugs in it,
\r
105 report them in the appropriate section of the
\r
106 <a href="http://www.open-aurec.com/wbforum/">WinBoard forum</a>.
\r
109 <h2><a name="2">2. Connection</a></h2>
\r
112 An xboard chess engine runs as a separate process from xboard itself,
\r
113 connected to xboard through a pair of anonymous pipes. The engine
\r
114 does not have to do anything special to set up these pipes. xboard
\r
115 sets up the pipes itself and starts the engine with one pipe as its
\r
116 standard input and the other as its standard output. The engine then
\r
117 reads commands from its standard input and writes responses to its
\r
118 standard output. This is, unfortunately, a little more complicated to
\r
119 do right than it sounds; see <a href="#6">section 6</a> below.
\r
123 And yes, contrary to some people's expectations, exactly the same
\r
124 thing is true for WinBoard. Pipes and standard input/output are
\r
125 implemented in Win32 and work fine. You don't have to use DDE, COM,
\r
126 DLLs, BSOD, or any of the other infinite complexity that
\r
127 Microsoft has created just to talk between two programs. A WinBoard
\r
128 chess engine is a Win32 console program that simply reads from its
\r
129 standard input and writes to its standard output. See sections
\r
130 <a href="#5">5</a> and <a href="#6">6</a> below for additional details.
\r
133 <h2><a name="3">3. Debugging</a></h2>
\r
136 To diagnose problems in your engine's interaction with xboard, use the
\r
137 -debug flag on xboard's command line to see the messages that are
\r
138 being exchanged. In WinBoard, these messages are written to the file
\r
139 WinBoard.debug instead of going to the screen.
\r
143 You can turn debug mode on or off while WinBoard is running by
\r
144 pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard
\r
145 is running by binding DebugProc to a shortcut key (and pressing the
\r
146 key!); see the instructions on shortcut keys in the xboard man page.
\r
150 While your engine is running under xboard/WinBoard, you can send a
\r
151 command directly to the engine by pressing Shift+1 (xboard) or Alt+1
\r
152 (WinBoard 4.0.3 and later). This brings up a dialog that you can type
\r
153 your command into. Press Shift+2 (Alt+2) instead to send to the
\r
154 second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier,
\r
155 Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict
\r
156 with typing the @-sign on some European keyboards.
\r
159 <h2><a name="4">4. How it got this way</a></h2>
\r
162 Originally, xboard was just trying to talk to the existing
\r
163 command-line interface of GNU Chess 3.1+ and 4, which was designed
\r
164 for people to type commands to. So the communication protocol is very
\r
165 ad-hoc. It might have been good to redesign it early on, but because
\r
166 xboard and GNU Chess are separate programs, I didn't want to force
\r
167 people to upgrade them together to versions that matched. I
\r
168 particularly wanted to keep new versions of xboard working with old
\r
169 versions of GNU Chess, to make it easier to compare the play of old
\r
170 and new gnuchess versions. I didn't foresee the need for a clean
\r
171 protocol to be used with other chess engines in the future.
\r
175 Circumstances have changed over the years, and now there are many more
\r
176 engines that work with xboard. I've had to make the protocol
\r
177 description more precise, I've added some features that GNU Chess
\r
178 does not support, and I've specified the standard semantics of a few
\r
179 features to be slightly different from what GNU Chess 4 does.
\r
182 <p class="version1">
\r
183 This release of the protocol specification is the first to carry a
\r
184 version number of its own -- version 2. Previous releases simply
\r
185 carried a last-modified date and were loosely tied to specific
\r
186 releases of xboard and WinBoard. The version number "1" applies
\r
187 generally to all those older versions of the protocol.
\r
190 <p class="version1">
\r
191 Protocol version 2 remains compatible with older engines but has
\r
192 several new capabilities. In particular, it adds the
\r
193 "feature" command, a new mechanism for making backward-compatible
\r
194 changes and extensions to the protocol. Engines that do not support a
\r
195 particular new feature do not have to use it; new features are not
\r
196 enabled unless the engine specifically requests them using the feature
\r
197 command. If an engine does not send the feature command at all, the
\r
198 protocol behavior is nearly identical to version 1. Several new
\r
199 features can be selected by the feature command in version 2,
\r
200 including the "ping" command (recommended for all engines), the
\r
201 "setboard" command, and many optional parameters. Additional features
\r
202 will probably be added in future versions.
\r
205 <p class="version43">
\r
206 If it is necessary to have a separate name,
\r
207 it would be best to refer to the protocol including the green additions as version 2f.
\r
208 I really don't think it is a different protocol from version 2, though.
\r
209 I just tried to clarify some ambiguities in the original definition,
\r
210 now that the WinBoard 4.3.xx line has implemented them in a specific way.
\r
211 The hand-shaking protocol for features as defined in protocol 2 perfectly
\r
212 allows addition of an occasional new features without any need for stepping up the protocol version number,
\r
213 and I think refraining from the latter would enormously lower the barrier for actual
\r
214 implementation of these features in engines.
\r
216 The two really new things are the engine debug comments, and the "nps" command.
\r
217 The former merely tries to regulate an extremely common existing pactice
\r
218 of having engines dump debug messages on WinBoard in an unprotected way,
\r
219 as usually you get away with that.
\r
222 <h2><a name="5">5. WinBoard requires Win32 engines</a></h2>
\r
225 Due to some Microsoft brain damage that I don't understand, WinBoard
\r
226 does not work with chess engines that were compiled to use a DOS
\r
227 extender for 32-bit addressing. (Probably not with 16-bit DOS or
\r
228 Windows programs either.) WinBoard works only with engines that are
\r
229 compiled for the Win32 API. You can get a free compiler that targets
\r
230 the Win32 API from <a href="http://sources.redhat.com/cygwin/"
\r
231 >http://sources.redhat.com/cygwin/</a>. I think DJGPP 2.x should also
\r
232 work if you use the RSXNTDJ extension, but I haven't tried it. Of
\r
233 course, Microsoft Visual C++ will work. Most likely the other
\r
234 commercial products that support Win32 will work too (Borland, etc.),
\r
235 but I have not tried them. Delphi has been successfully used to write
\r
236 engines for WinBoard; if you want to do this, Tony Werten has donated
\r
237 some <a href="http://www.tim-mann.org/winboard/delphi.txt" >sample
\r
238 code</a> that should help you get started.
\r
241 <h2><a name="6">6. Hints on input/output</a></h2>
\r
244 Beware of using buffered I/O in your chess engine. The C stdio
\r
245 library, C++ streams, and the I/O packages in most other languages use
\r
246 buffering both on input and output. That means two things. First,
\r
247 when your engine tries to write some characters to xboard, the library
\r
248 stashes them in an internal buffer and does not actually write them to
\r
249 the pipe connected to xboard until either the buffer fills up or you
\r
250 call a special library routine asking for it to be flushed. (In C
\r
251 stdio, this routine is named <tt>fflush</tt>.) Second, when your engine tries
\r
252 to read some characters from xboard, the library does not read just
\r
253 the characters you asked for -- it reads all the characters that are
\r
254 currently available (up to some limit) and stashes any characters you
\r
255 are not yet ready for in an internal buffer. The next time you ask to
\r
256 read, you get the characters from the buffer (if any) before the
\r
257 library tries to read more data from the actual pipe.
\r
261 Why does this cause problems? First, on the output side, remember
\r
262 that your engine produces output in small quantities (say, a few
\r
263 characters for a move, or a line or two giving the current analysis),
\r
264 and that data always needs to be delivered to xboard/WinBoard for
\r
265 display immediately. If you use buffered output, the data you print
\r
266 will sit in a buffer in your own address space instead of being
\r
271 You can usually fix the output buffering problem by asking for the
\r
272 buffering to be turned off. In C stdio, you do this by calling
\r
273 <tt>setbuf(stdout, NULL)</tt>. A more laborious and error-prone
\r
274 method is to carefully call <tt>fflush(stdout)</tt> after every line
\r
275 you output; I don't recommend this. In C++, you can try
\r
276 <tt>cout.setf(ios::unitbuf)</tt>, which is documented in current
\r
277 editions of "The C++ Programming Language," but not older ones.
\r
278 Another C++ method that might work is
\r
279 <tt>cout.rdbuf()->setbuf(NULL, 0)</tt>. Alternatively, you can
\r
280 carefully call <tt>cout.flush()</tt> after every line you output;
\r
281 again, I don't recommend this.
\r
285 Another way to fix the problem is to use unbuffered operating system
\r
286 calls to write directly to the file descriptor for standard output.
\r
287 On Unix, this means <tt>write(1, ...)</tt> -- see the man page for write(2).
\r
288 On Win32, you can use either the Unix-like <tt>_write(1, ...)</tt> or Win32
\r
289 native routines like <tt>WriteFile</tt>.
\r
293 Second, on the input side, you are likely to want to poll during your
\r
294 search and stop it if new input has come in. If you implement
\r
295 pondering, you'll need this so that pondering stops when the user
\r
296 makes a move. You should also poll during normal thinking on your
\r
297 move, so that you can implement the "?" (move now) command, and so
\r
298 that you can respond promptly to a "result", "force", or "quit"
\r
299 command if xboard wants to end the game or terminate your engine.
\r
300 Buffered input makes polling more complicated -- when you poll, you
\r
301 must stop your search if there are <em>either</em> characters in the buffer
\r
302 <em>or</em> characters available from the underlying file descriptor.
\r
306 The most direct way to fix this problem is to use unbuffered operating
\r
307 system calls to read (and poll) the underlying file descriptor
\r
308 directly. On Unix, use <tt>read(0, ...)</tt> to read from standard input, and
\r
309 use <tt>select()</tt> to poll it. See the man pages read(2) and select(2).
\r
310 (Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to
\r
311 poll for input. It is not very portable; that is, it does not exist
\r
312 on all versions of Unix, and is broken on some that do have it.) On
\r
313 Win32, you can use either the Unix-like <tt>_read(0, ...)</tt> or the native
\r
314 Win32 <tt>ReadFile()</tt> to read. Unfortunately, under Win32, the function to
\r
315 use for polling is different depending on whether the input device is
\r
316 a pipe, a console, or something else. (More Microsoft brain damage
\r
317 here -- did they never hear of device independence?) For pipes, you
\r
318 can use <tt>PeekNamedPipe</tt> to poll (even when the pipe is unnamed).
\r
320 you can use <tt>GetNumberOfConsoleInputEvents</tt>. For sockets only, you can
\r
321 use <tt>select()</tt>. It might be possible to use
\r
322 <tt>WaitForSingleObject</tt> more
\r
323 generally, but I have not tried it. Some code to do these things can
\r
324 be found in Crafty's utility.c, but I don't guarantee that it's all
\r
325 correct or optimal.
\r
329 A second way to fix the problem might be to ask your I/O library not
\r
330 to buffer on input. It should then be safe to poll the underlying
\r
331 file descriptor as described above. With C, you can try calling
\r
332 <tt>setbuf(stdin, NULL)</tt>. However, I have never tried this. Also, there
\r
333 could be problems if you use <tt>scanf()</tt>, at least with certain patterns,
\r
334 because <tt>scanf()</tt> sometimes needs to read one extra character and "push
\r
335 it back" into the buffer; hence, there is a one-character pushback
\r
336 buffer even if you asked for stdio to be unbuffered. With C++, you
\r
337 can try <tt>cin.rdbuf()->setbuf(NULL, 0)</tt>, but again, I have never tried
\r
342 A third way to fix the problem is to check whether there are
\r
343 characters in the buffer whenever you poll. C I/O libraries generally
\r
344 do not provide any portable way to do this. Under C++, you can use
\r
345 <tt>cin.rdbuf()->in_avail()</tt>. This method has been reported to
\r
347 EXchess. Remember that if there are no characters in the buffer, you
\r
348 still have to poll the underlying file descriptor too, using the
\r
349 method described above.
\r
353 A fourth way to fix the problem is to use a separate thread to read
\r
354 from stdin. This way works well if you are familiar with thread
\r
355 programming. This thread can be blocked waiting for input to come in
\r
356 at all times, while the main thread of your engine does its thinking.
\r
357 When input arrives, you have the thread put the input into a buffer
\r
358 and set a flag in a global variable. Your search routine then
\r
359 periodically tests the global variable to see if there is input to
\r
360 process, and stops if there is. WinBoard and my Win32 ports of ICC
\r
361 timestamp and FICS timeseal use threads to handle multiple input
\r
365 <h2><a name="7">7. Signals</a></h2>
\r
367 <p>Engines that run on Unix need to be concerned with two Unix
\r
368 signals: <tt>SIGTERM</tt> and <tt>SIGINT</tt>. This applies both to
\r
369 engines that run under xboard and (the unusual case of) engines that
\r
370 WinBoard remotely runs on a Unix host using the -firstHost or
\r
371 -secondHost feature. It does not apply to engines that run on
\r
372 Windows, because Windows does not have Unix-style signals.
\r
373 <span class="version1">
\r
374 Beginning with version 2, you can now turn off the use of
\r
376 signals. See the "feature" command in <a href="#6">section 9</a> below.
\r
380 <p>First, when an engine is sent the "quit" command, it is also given
\r
381 a <tt>SIGTERM</tt> signal shortly afterward to make sure it goes away.
\r
382 If your engine reliably responds to "quit", and the signal causes
\r
383 problems for you, you should either ignore it by calling
\r
384 <tt>signal(SIGTERM, SIG_IGN)</tt> at the start of your program,
\r
385 or disable it with the "feature" command.</p>
\r
387 <p>Second, xboard will send an interrupt signal (<tt>SIGINT</tt>) at
\r
388 certain times when it believes the engine may not be listening to user
\r
389 input (thinking or pondering). WinBoard currently does this only when
\r
390 the engine is running remotely using the -firstHost or -secondHost
\r
391 feature, not when it is running locally. You probably need to know
\r
392 only enough about this grungy feature to keep it from getting in your
\r
397 The <tt>SIGINT</tt>s are basically tailored to the needs of GNU Chess 4
\r
398 on systems where its input polling code is broken or disabled.
\r
399 Because they work in a rather peculiar way, it is recommended that you
\r
400 either ignore <tt>SIGINT</tt> by having your engine call
\r
401 <tt>signal(SIGINT, SIG_IGN)</tt>, or disable it with the "feature"
\r
405 Here are details for the curious. If xboard needs to send a command
\r
406 when it is the chess engine's move (such as before the "?" command),
\r
407 it sends a <tt>SIGINT</tt> first. If xboard needs to send commands when it is
\r
408 not the chess engine's move, but the chess engine may be pondering
\r
409 (thinking on its opponent's time) or analyzing (analysis or analyze
\r
410 file mode), xboard sends a <tt>SIGINT</tt> before the first such command only.
\r
411 Another <tt>SIGINT</tt> is not sent until another move is made, even if xboard
\r
412 issues more commands. This behavior is necessary for GNU Chess 4. The
\r
413 first <tt>SIGINT</tt> stops it from pondering until the next move, but on some
\r
414 systems, GNU Chess 4 will die if it receives a <tt>SIGINT</tt> when not
\r
415 actually thinking or pondering.
\r
419 There are two reasons why WinBoard does not send the Win32 equivalent
\r
420 of <tt>SIGINT</tt> (which is called <tt>CTRL_C_EVENT</tt>) to local
\r
421 engines. First, the Win32 GNU Chess 4 port does not need it. Second, I
\r
422 could not find a way to get it to work. Win32 seems to be designed
\r
423 under the assumption that only console applications, not windowed
\r
424 applications, would ever want to send a <tt>CTRL_C_EVENT</tt>.
\r
427 <h2><a name="8">8. Commands from xboard to the engine</a></h2>
\r
430 All commands from xboard to the engine end with a newline (\n), even
\r
431 where that is not explicitly stated. All your output to xboard must
\r
432 be in complete lines; any form of prompt or partial line will cause
\r
437 At the beginning of each game, xboard sends an initialization string.
\r
438 This is currently "new\nrandom\n" unless the user changes it with the
\r
439 initString or secondInitString option.
\r
443 xboard normally reuses the same chess engine process for multiple
\r
444 games. At the end of a game, xboard will send the "force" command
\r
445 (see below) to make sure your engine stops thinking about the current
\r
446 position. It will later send the initString again to start a new
\r
447 game. If your engine can't play multiple games, you can disable reuse
\r
448 <span class="version1">
\r
449 either with the "feature" command (beginning in protocol version
\r
452 with xboard's -xreuse (or -xreuse2) command line
\r
453 option. xboard will then ask the process to quit after each game and
\r
454 start a new process for the next game.
\r
459 <dd>This command will be sent once immediately after your engine
\r
460 process is started. You can use it to put your engine into "xboard
\r
461 mode" if that is needed. If your engine prints a prompt to ask for
\r
462 user input, you must turn off the prompt and output a newline when the
\r
463 "xboard" command comes in.
\r
466 <dt class="version1">protover N</dt>
\r
467 <dd class="version1">
\r
468 <p>Beginning in protocol version 2 (in which N=2), this command will
\r
469 be sent immediately after the "xboard" command. If you receive some
\r
470 other command immediately after "xboard" (such as "new"), you can
\r
471 assume that protocol version 1 is in use. The "protover" command is
\r
472 the only new command that xboard always sends in version 2. All other
\r
473 new commands to the engine are sent only if the engine first enables
\r
474 them with the "feature" command. Protocol versions will always be
\r
475 simple integers so that they can easily be compared.
\r
478 <p>Your engine should reply to the protover command by sending the
\r
479 "feature" command (see below) with the list of non-default feature
\r
480 settings that you require, if any.</p>
\r
482 <p>Your engine should never refuse to run due to receiving a higher
\r
483 protocol version number than it is expecting! New protocol versions
\r
484 will always be compatible with older ones by default; the larger
\r
485 version number is simply a hint that additional "feature" command
\r
486 options added in later protocol versions may be accepted.
\r
490 <dt class="version1">accepted</dt>
\r
491 <dt class="version1">rejected</dt>
\r
492 <dd class="version1">
\r
493 These commands may be sent to your engine in reply to the "feature"
\r
494 command; see its documentation below.
\r
498 <dd>Reset the board to the standard chess starting position. Set
\r
499 White on move. Leave force mode and set the engine to play Black.
\r
500 Associate the engine's clock with Black and the opponent's clock with
\r
501 White. Reset clocks and time controls to the start of a new game.
\r
502 Use wall clock for time measurement.
\r
503 Stop clocks. Do not ponder on this move, even if pondering is on.
\r
504 Remove any search depth limit previously set by the sd command.
\r
507 <dt>variant VARNAME</dt>
\r
508 <dd>If the game is not standard chess, but a variant, this command is
\r
509 sent after "new" and before the first move or "edit" command. Currently
\r
510 defined variant names are:
\r
513 <tr><td>wildcastle</td><td>Shuffle chess where king can castle from d file</td></tr>
\r
514 <tr><td>nocastle</td><td>Shuffle chess with no castling at all</td></tr>
\r
515 <tr><td>fischerandom</td><td>Fischer Random</td></tr>
\r
516 <tr><td>bughouse</td><td>Bughouse, ICC/FICS rules</td></tr>
\r
517 <tr><td>crazyhouse</td><td>Crazyhouse, ICC/FICS rules</td></tr>
\r
518 <tr><td>losers</td><td>Win by losing all pieces or getting mated (ICC)</td></tr>
\r
519 <tr><td>suicide</td><td>Win by losing all pieces including king,
\r
520 or by having fewer pieces when one player has no legal moves (FICS)</td></tr>
\r
521 <tr class="version1"><td>giveaway</td><td>Win by losing all pieces including king,
\r
522 or by having no legal moves (ICC)</td></tr>
\r
523 <tr><td>twokings</td><td>Weird ICC wild 9</td></tr>
\r
524 <tr><td>kriegspiel</td><td>Kriegspiel (engines not supported)</td></tr>
\r
525 <tr><td>atomic</td><td>Atomic</td></tr>
\r
526 <tr><td>3check</td><td>Win by giving check 3 times</td></tr>
\r
527 <tr class="version43"><td>xiangqi </td><td>Chinese Chess (9x10 board)</td></tr>
\r
528 <tr class="version43"><td>shogi </td><td>Japanese Chess (9x9 bord)</td></tr>
\r
529 <tr class="version43"><td>capablanca</td><td>Capablanca Chess (10x8 board, with Archbishop and Chancellor)</td></tr>
\r
530 <tr class="version43"><td>gothic </td><td>Gothic Chess (10x8 board, same with better opening setup)</td></tr>
\r
531 <tr class="version43"><td>falcon </td><td>Falcon Chess (10x8 board, with two Falcon pieces)</td></tr>
\r
532 <tr class="version43"><td>shatranj </td><td>ancient Arabic Chess, with Elephants and General in stead of B and Q</td></tr>
\r
533 <tr class="version43"><td>courier </td><td>Courier Chess (12x8 board, a medieval precursor of modern Chess</td></tr>
\r
534 <tr class="version43"><td>knightmate </td><td>King moves as Knight and vice versa</td></tr>
\r
535 <tr class="version43"><td>berolina</td><td> Pawns capture straight ahead, and move diagonally</td></tr>
\r
536 <tr class="version43"><td>janus</td><td> Janus Chess (10x8, with two Archbishops)</td></tr>
\r
537 <tr class="version43"><td>caparandom </td><td>shuffle variant like FRC (10x8 board)</td></tr>
\r
538 <tr class="version43"><td>cylinder </td><td>Pieces wrap around between side edges, like board is a cylinder</td></tr>
\r
539 <tr class="version44"><td>super </td><td>Superchess: a shuffle variant with 4 fairy pieces on 8x8 board</td></tr>
\r
540 <tr class="version44"><td>great </td><td>Great Shatranj: sliders are replaced by corresponding short-range pieces on a 10x8 board</td></tr>
\r
541 <tr class="version48"><td>lion </td><td>Mighty-Lion Chess, with a super-knight, more powerful than a Queen</td></tr>
\r
542 <tr class="version48"><td>elven </td><td>Elven Chess: hybrid between Chess and Chu Shogi on 10x10 board</td></tr>
\r
543 <tr class="version48"><td>chu </td><td>Chu Shogi: Edo-period Japanese Chess on a 12x12 board</td></tr>
\r
544 <tr><td>unknown</td><td>Unknown variant (not supported)</td></tr>
\r
547 <span class="version48">As of XBoard 4.8, engines can define arbitrary variant names; see the "feature" and "setup" commands in <a href="#9">section 9</a>.</span>
\r
551 <dd>The chess engine should immediately exit. This command is used
\r
552 when xboard is itself exiting, and also between games if the -xreuse
\r
553 command line option is given (or -xreuse2 for the second engine).
\r
554 See also <a href="#7">Signals</a> above.
\r
558 <dd>This command is specific to GNU Chess 4. You can either ignore it
\r
559 completely (that is, treat it as a no-op) or implement it as GNU Chess
\r
560 does. The command toggles "random" mode (that is, it sets random =
\r
561 !random). In random mode, the engine adds a small random value to its
\r
562 evaluation function to vary its play. The "new" command sets random
\r
567 <dd>Set the engine to play neither color ("force mode"). Stop clocks.
\r
568 The engine should check that moves received in force mode are legal
\r
569 and made in the proper turn, but should not think, ponder, or make
\r
574 <dd>Leave force mode and set the engine to play the color that is on
\r
575 move. Associate the engine's clock with the color that is on move,
\r
576 the opponent's clock with the color that is not on move. Start the engine's
\r
577 clock. Start thinking and eventually make a move.
\r
580 <dt class="version1">playother</dt>
\r
581 <dd class="version1">
\r
582 (This command is new in protocol version 2. It is not
\r
583 sent unless you enable it with the feature command.)
\r
584 Leave force mode and set the engine to play the color that is <i>not</i> on
\r
585 move. Associate the opponent's clock with the color that is on move,
\r
586 the engine's clock with the color that is not on move. Start the opponent's
\r
587 clock. If pondering is enabled, the engine should begin pondering.
\r
588 If the engine later receives a move, it should start thinking and eventually
\r
594 <p><span class="version1">
\r
595 (This command is obsolete as of protocol version 2, but is still
\r
596 sent in some situations to accommodate older engines unless you disable it
\r
597 with the feature command.)
\r
599 Set White on move. Set the engine to play Black. Stop clocks.
\r
605 <span class="version1">
\r
606 (This command is obsolete as of protocol version 2, but is still
\r
607 sent in some situations to accommodate older engines unless you disable it
\r
608 with the feature command.)
\r
610 Set Black on move. Set the engine to play White. Stop clocks.
\r
613 <dt>level MPS BASE INC</dt>
\r
614 <dd>Set time controls. See the <a href="#11">Time Control</a> section below.
\r
618 <dd>Set time controls. See the <a href="#11">Time Control</a> section
\r
624 <p>The engine should limit its thinking to DEPTH ply.
\r
625 <span class="version43">The commands "level" or "st" and "sd" can be used together in an orthogonal way.
\r
626 If both are issued, the engine should observe both limitations:</span>
\r
627 In the protocol, the "sd" command isn't a time control. It doesn't
\r
628 say that your engine has unlimited time but must search to exactly the
\r
629 given depth. It says that you should pay attention to the time
\r
630 control as normal, but cut off the search at the specified depth even
\r
631 if you have time to search deeper. If you don't have time to search
\r
632 to the specified depth, given your normal time management algorithm,
\r
633 then you will want to stop sooner than the given depth.
\r
635 The "new" command should set the search depth back to unlimited. This
\r
636 is already stated in the spec. The "level" command should not affect
\r
637 the search depth. As it happens, xboard/WinBoard currently always
\r
638 sends sd (if needed) right after level, but that isn't part of the
\r
642 <dt><span class="version43">nps NODE_RATE</span></dt>
\r
643 <dd><span class="version43">The engine should not use wall-clock time to make its timing decisions,
\r
644 but an own internal time measure based on the number of nodes it has searched
\r
645 (and will report as "thinking output", see <a href="#10">section 10</a>),
\r
646 converted to seconds through dividing by the given NODE_RATE.
\r
647 Example: after receiving the commands "st 8" and "nps 10000",
\r
648 the engine should never use more that 80,000 nodes in the search for any move.
\r
649 In this mode, the engine should report user CPU time used (in its thinking output),
\r
650 rather than wall-clock time.
\r
651 This even holds if NODE_RATE is given as 0,
\r
652 but in that case it should also use the user CPU time for its timing decisions.
\r
653 The effect of an "nps" command should persist until the next "new" command.
\r
658 <dd>Set a clock that always belongs to the engine. N is a number in
\r
659 centiseconds (units of 1/100 second). Even if the engine changes to
\r
660 playing the opposite color, this clock remains with the engine.
\r
665 <dd><p>Set a clock that always belongs to the opponent. N is a number in
\r
666 centiseconds (units of 1/100 second). Even if the opponent changes to
\r
667 playing the opposite color, this clock remains with the opponent.
\r
669 If needed for purposes of board display in force mode (where the
\r
670 engine is not participating in the game) the time clock should be
\r
671 associated with the last color that the engine was set to play, the
\r
672 otim clock with the opposite color.
\r
675 <span class="version43">This business of "clocks remaining with the engine" is apparently so ambiguous
\r
676 that many engines implement it wrong.
\r
677 The clocks in fact always remain with the color.
\r
678 Which clock reading is relayed with "time", and which by "otim", is determined by which side the engine plays.
\r
679 Note that the way the clocks operate and receive extra time (in accordance with the selected time control)
\r
680 is not affected in any way by which moves are made by the engine, which by the opponent, and which were forced.
\r
684 <span class="version1">
\r
685 Beginning in protocol version 2, if you can't handle the time and
\r
686 otim commands, you can use the "feature" command to disable them; see
\r
689 The following techniques from older protocol versions also
\r
690 work: You can ignore the time and otim commands (that is, treat them
\r
691 as no-ops), or send back "Error (unknown command): time" the first
\r
692 time you see "time".
\r
697 <p>See below for the syntax of moves. If the move is illegal, print
\r
698 an error message; see the section "<a href="#9">Commands from the engine to
\r
699 xboard</a>". If the move is legal and in turn, make it. If not in force
\r
700 mode, stop the opponent's clock, start the engine's clock, start
\r
701 thinking, and eventually make a move.
\r
703 When xboard sends your engine a move, it normally sends coordinate
\r
704 algebraic notation. Examples:
\r
707 <tr><td>Normal moves:</td><td>e2e4</td></tr>
\r
708 <tr><td>Pawn promotion:</td><td>e7e8q</td></tr>
\r
709 <tr><td>Castling:</td><td>e1g1, e1c1, e8g8, e8c8</td></tr>
\r
710 <tr><td>Bughouse/crazyhouse drop:</td><td>P@h3</td></tr>
\r
711 <tr><td>ICS Wild 0/1 castling:</td><td>d1f1, d1b1, d8f8, d8b8</td></tr>
\r
712 <tr><td>FischerRandom castling:</td><td>O-O, O-O-O (oh, not zero)</td></tr>
\r
713 <tr class="version48"><td>Multi-leg move:</td><td>c4d5,d5e4 (legs separated by comma)</td></tr>
\r
714 <tr class="version48"><td>Null move:</td><td>@@@@</td></tr>
\r
717 <p class="version43">
\r
718 Note that on boards with <span class="version48">exactly 10</span> ranks, counting of the ranks starts at 0.
\r
720 <p class="version1">
\r
721 Beginning in protocol version 2, you can use the feature command
\r
722 to select SAN (standard algebraic notation) instead; for example, e4,
\r
723 Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form,
\r
724 P@h3, is a extension to the PGN standard's definition of SAN, which does
\r
725 not support bughouse or crazyhouse.
\r
729 xboard doesn't reliably detect illegal moves, because it does not keep
\r
730 track of castling unavailability due to king or rook moves, or en
\r
731 passant availability. If xboard sends an illegal move, send back an
\r
732 error message so that xboard can retract it and inform the user; see
\r
733 the section "<a href="#9">Commands from the engine to xboard</a>".
\r
736 <dt class="version1">usermove MOVE</dt>
\r
737 <dd class="version1">
\r
738 By default, moves are sent to the engine without a command name;
\r
739 the notation is just sent as a line by itself.
\r
740 Beginning in protocol version 2, you can use the feature command
\r
741 to cause the command name "usermove" to be sent before the move.
\r
742 Example: "usermove e2e4".
\r
746 <dd><p>Move now. If your engine is thinking, it should move immediately;
\r
747 otherwise, the command should be ignored (treated as a no-op). It
\r
748 is permissible for your engine to always ignore the ? command. The
\r
749 only bad consequence is that xboard's Move Now menu command will do
\r
752 It is also permissible for your engine to move immediately if it gets
\r
753 any command while thinking, as long as it processes the command right
\r
754 after moving, but it's preferable if you don't do this. For example,
\r
755 xboard may send post, nopost, easy, hard, force, quit,
\r
756 <span class="version1">
\r
759 while the engine is on move.
\r
763 <dt class="version1">ping N</dt>
\r
764 <dd class="version1">
\r
765 <p>In this command, N is a decimal number. When you receive the command,
\r
766 reply by sending the string <strong>pong N</strong>, where N is the
\r
767 same number you received. Important: You must not reply to a "ping"
\r
768 command until you have finished executing all commands that you
\r
769 received before it. Pondering does not count; if you receive a ping
\r
770 while pondering, you should reply immediately and continue pondering.
\r
771 Because of the way xboard uses the ping command, if you implement the
\r
772 other commands in this protocol, you should never see a "ping" command
\r
773 when it is your move; however, if you do, you must not send the "pong"
\r
774 reply to xboard until after you send your move. For example, xboard
\r
775 may send "?" immediately followed by "ping". If you implement the "?"
\r
776 command, you will have moved by the time you see the subsequent ping
\r
777 command. Similarly, xboard may send a sequence like "force", "new",
\r
778 "ping". You must not send the pong response until after you have
\r
779 finished executing the "new" command and are ready for the new game to
\r
783 The ping command is new in protocol version 2 and will not be sent
\r
784 unless you enable it with the "feature" command. Its purpose is to
\r
785 allow several race conditions that could occur in previous versions of
\r
786 the protocol to be fixed, so it is highly recommended that you
\r
787 implement it. It is especially important in simple engines that do
\r
788 not ponder and do not poll for input while thinking, but it is needed in all
\r
794 <dd>The engine's opponent offers the engine a draw. To accept the
\r
795 draw, send "offer draw". To decline, ignore the offer (that is, send
\r
796 nothing). If you're playing on ICS, it's possible for the draw offer
\r
797 to have been withdrawn by the time you accept it, so don't assume the
\r
798 game is over because you accept a draw offer. Continue playing until
\r
799 xboard tells you the game is over. See also "offer draw" below.
\r
802 <dt>result RESULT {COMMENT}</dt>
\r
803 <dd>After the end of each game, xboard will send you a result command.
\r
804 You can use this command to trigger learning. RESULT is either 1-0,
\r
805 0-1, 1/2-1/2, or *, indicating whether white won, black won, the game
\r
806 was a draw, or the game was unfinished. The COMMENT string is purely
\r
807 a human-readable comment; its content is unspecified and subject to
\r
808 change. In ICS mode, it is passed through from ICS uninterpreted.
\r
809 Example: <pre>result 1-0 {White mates}</pre>
\r
811 Here are some notes on interpreting the "result" command. Some apply
\r
812 only to playing on ICS ("Zippy" mode).
\r
816 If you won but did not just play a mate, your opponent must have
\r
817 resigned or forfeited. If you lost but were not just mated, you
\r
818 probably forfeited on time, or perhaps the operator resigned manually.
\r
819 If there was a draw for some nonobvious reason, perhaps your opponent
\r
820 called your flag when he had insufficient mating material (or vice
\r
821 versa), or perhaps the operator agreed to a draw manually.
\r
825 You will get a result command even if you already know the game ended
\r
826 -- for example, after you just checkmated your opponent. In fact, if
\r
827 you send the "RESULT {COMMENT}" command (discussed below), you will
\r
828 simply get the same thing fed back to you with "result" tacked in
\r
829 front. You might not always get a "result *" command, however. In
\r
830 particular, you won't get one in local chess engine mode when the user
\r
831 stops playing by selecting Reset, Edit Game, Exit or the like.
\r
835 <dt><span class="version1">setboard FEN</span></dt>
\r
837 <p><span class="version1">
\r
838 The setboard command is the new way to set up positions, beginning
\r
839 in protocol version 2. It is not used unless it has been selected
\r
840 with the feature command. Here FEN is a position in Forsythe-Edwards
\r
841 Notation, as defined in the PGN standard.</span>
\r
842 <span class="version43">Note that this PGN standard referred to here
\r
843 only applies to normal Chess;
\r
844 Obviously in variants that cannot be described by a FEN for normal Chess,
\r
845 e.g. because the board is not 8x8, other pieces then PNBRQK participate,
\r
846 there are holdings that need to be specified, etc.,
\r
847 xboard will use a FEN format that is standard or suitable for that variant.
\r
848 In particular, in FRC or CRC, WinBoard will use Shredder-FEN or X-FEN standard,
\r
849 i.e. it can use the rook-file indicator letter to represent a castling right
\r
850 (like HAha) whenever it wants, but if it uses KQkq, this will always refer
\r
851 to the outermost rook on the given side.</span>
\r
854 <p class="version1">
\r
855 <em>Illegal positions:</em> Note that either setboard or edit can
\r
856 be used to send an illegal position to the engine. The user can
\r
857 create any position with xboard's Edit Position command (even, say,
\r
858 an empty board, or a board with 64 white kings and no black ones).
\r
859 If your engine receives a position that it considers illegal,
\r
860 I suggest that you send the response "tellusererror Illegal position",
\r
861 and then respond to any attempted move with "Illegal move" until
\r
862 the next new, edit, or setboard command.
\r
868 <p><span class="version1">
\r
869 The edit command is the old way to set up positions. For compatibility
\r
870 with old engines, it is still used by default, but new engines may prefer
\r
871 to use the feature command (see below) to cause xboard to use setboard instead.
\r
873 The edit command puts the chess engine into a special mode, where
\r
874 it accepts the following subcommands:</p>
\r
876 <tr><td>c</td><td>change current piece color, initially white</td></tr>
\r
877 <tr><td>Pa4 (for example)</td><td>place pawn of current color on a4</td></tr>
\r
878 <tr><td>xa4 (for example)</td><td>empty the square a4 (not used by xboard)</td></tr>
\r
879 <tr><td>#</td><td>clear board</td></tr>
\r
880 <tr><td>.</td><td>leave edit mode</td></tr>
\r
882 <p class="version1">
\r
883 See the Idioms section below for additional subcommands used in
\r
884 ChessBase's implementation of the protocol.
\r
887 <p>The edit command does not change the side to move. To set up a
\r
888 black-on-move position, xboard uses the following command sequence:
\r
895 <edit commands>
\r
900 This sequence is used to avoid the "black" command, which is now
\r
901 considered obsolete and which many engines never did implement as
\r
902 specified in this document.
\r
906 After an edit command is complete, if a king and a rook are on their
\r
907 home squares, castling is assumed to be available to them. En passant
\r
908 capture is assumed to be illegal on the current move regardless of the
\r
909 positions of the pawns. The clock for the 50 move rule starts at
\r
910 zero, and for purposes of the draw by repetition rule, no prior
\r
911 positions are deemed to have occurred.
\r
912 <span class="version43">
\r
913 In FRC or CRC, any rook and king put on the back rank should be considered to
\r
914 have castling rights, even if it later becomes apparent that they cannot be both in the
\r
915 initial position, because the position just set up is asymmetric.
\r
916 It is upto WinBoard to find work-around in cases where this is not desired,
\r
917 similar to the "black kludge" shown above, by setting up an earlier position,
\r
918 and then do a move to destroy castling rights or create e.p. rights.
\r
919 (Don't bet your life on it...)
\r
925 <dd>If the user asks for a hint, xboard sends your engine the command
\r
926 "hint". Your engine should respond with "Hint: xxx", where xxx is a
\r
927 suggested move. If there is no move to suggest, you can ignore the
\r
928 hint command (that is, treat it as a no-op).
\r
932 <dd>If the user selects "Book" from the xboard menu, xboard will send
\r
933 your engine the command "bk". You can send any text you like as the
\r
934 response, as long as each line begins with a blank space or tab (\t)
\r
935 character, and you send an empty line at the end. The text pops up in
\r
936 a modal information dialog.
\r
940 <dd>If the user asks to back up one move, xboard will send you the
\r
941 "undo" command. xboard will not send this command without putting you
\r
942 in "force" mode first, so you don't have to worry about what should
\r
943 happen if the user asks to undo a move your engine made. (GNU Chess 4
\r
944 actually switches to playing the opposite color in this case.)
\r
948 <dd>If the user asks to retract a move, xboard will send you the
\r
949 "remove" command. It sends this command only when the user is on
\r
950 move. Your engine should undo the last two moves (one for each
\r
951 player) and continue playing the same color.
\r
955 <dd>Turn on pondering (thinking on the opponent's time, also known as
\r
956 "permanent brain"). xboard will not make any assumption about what
\r
957 your default is for pondering or whether "new" affects this setting.
\r
961 <dd>Turn off pondering.</dd>
\r
964 <dd>Turn on thinking/pondering output.
\r
965 See <a href="#10">Thinking Output</a> section.</dd>
\r
968 <dd>Turn off thinking/pondering output.</dd>
\r
971 <dd>Enter analyze mode. See <a href="#12">Analyze Mode</a> section.</dd>
\r
974 <dd>This command informs the engine of its
\r
975 opponent's name. When the engine is playing on a chess server, xboard
\r
976 obtains the opponent's name from the server.
\r
977 <span class="version1">
\r
979 playing locally against a human user, xboard obtains the user's login
\r
980 name from the local operating system. When the engine is playing
\r
981 locally against another engine, xboard uses either the other engine's
\r
982 filename or the name that the other engine supplied in the myname
\r
983 option to the feature command. By default, xboard uses the name
\r
984 command only when the engine is playing on a chess server. Beginning
\r
985 in protocol version 2, you can change this with the name option to the
\r
986 feature command; see below.
\r
991 <dd>In ICS mode, xboard obtains the ICS opponent's rating from the
\r
992 "Creating:" message that appears before each game. (This message may
\r
993 not appear on servers using outdated versions of the FICS code.) In
\r
994 Zippy mode, it sends these ratings on to the chess engine using the
\r
995 "rating" command. The chess engine's own rating comes first, and if
\r
996 either opponent is not rated, his rating is given as 0.
\r
997 <span class="version1">
\r
998 In the future this command may also be used in other modes, if ratings
\r
1001 Example: <pre>rating 2600 1500</pre>
\r
1004 <dt><span class="version1">ics HOSTNAME</span></dt>
\r
1005 <dd class="version1">
\r
1006 If HOSTNAME is "-", the engine is playing against a local
\r
1007 opponent; otherwise, the engine is playing on an Internet Chess Server
\r
1008 (ICS) with the given hostname. This command is new in protocol
\r
1009 version 2 and is not sent unless the engine has enabled it with
\r
1010 the "feature" command. Example: "ics freechess.org"
\r
1014 <dd>The opponent is also a computer chess engine. Some engines alter
\r
1015 their playing style when they receive this command.
\r
1018 <dt class="version1">pause</dt>
\r
1019 <dt class="version1">resume</dt>
\r
1020 <dd class="version1">(These commands are new in protocol
\r
1021 version 2 and will not be sent unless feature pause=1 is set. At
\r
1022 this writing, xboard actually does not use the commands at all, but it
\r
1023 or other interfaces may use them in the future.)
\r
1024 The "pause" command puts the engine into a special state where it
\r
1025 does not think, ponder, or otherwise consume significant CPU time.
\r
1026 The current thinking or pondering (if any) is suspended and both
\r
1027 player's clocks are stopped. The only command that the interface may
\r
1028 send to the engine while it is in the paused state is "resume". The
\r
1029 paused thinking or pondering (if any) resumes from exactly where it
\r
1030 left off, and the clock of the player on move resumes running from
\r
1034 <dt class="version44">memory N</dt>
\r
1035 <dd class="version44">
\r
1036 This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes.
\r
1037 On receipt of this command, the engine should adapt the size of its hash tables accordingly.
\r
1038 This command does only fix the total memory use,
\r
1039 the engine has to decide for itself
\r
1040 (or be configured by the user by other means)
\r
1041 how to divide up the available memory between the various tables it wants to use
\r
1042 (e.g. main hash, pawn hash, tablebase cache, bitbases).
\r
1043 This command will only be sent to engines that have requested it through the memory feature,
\r
1044 and only at the start of a game,
\r
1045 as the first of the commands to relay engine option settings just before each "new" command.
\r
1048 <dt class="version44">cores N</dt>
\r
1049 <dd class="version44">
\r
1050 This command informs the engine on how many CPU cores it is allowed to use maximally.
\r
1051 This could be interpreted as the number of search threads for SMP engines.
\r
1052 (Threads that do not consume significant amounts of CPU time, like I/O threads, need not be included in the count.)
\r
1053 This command will only be sent to engines that have requested it through the smp feature.
\r
1054 The engine should be able to respond to the "cores" command any time during a game,
\r
1055 but it is allowed to finish a search in progress before procesing the command.
\r
1056 (Obeying the command should take priority over finishing a ponder search, though.)
\r
1057 In any case it will be sent at the start of every game
\r
1058 as the last command to relay engine option settings before the "new" command.
\r
1061 <dt class="version44">egtpath TYPE PATH</dt>
\r
1062 <dd class="version44">
\r
1063 This command informs the engine in which directory (given by the PATH argument)
\r
1064 it can find end-game tables of the specified TYPE.
\r
1065 The TYPE argument can be any character string which does not contain spaces.
\r
1066 Currently <strong>nalimov</strong> and <strong>scorpio</strong> are defined types,
\r
1067 for Nalimov tablebases and Scorpio bitbases, respectively,
\r
1068 but future developers of other formats are free to define their own format names.
\r
1069 The GUI simply matches the TYPE names the engine says it supports
\r
1070 with those that the user supplied when configuring xboard.
\r
1071 For every match, it sends a separate "y" command.
\r
1072 The PATH argument would normally (for Nalimov) be the pathname of the directory the EGT files are in,
\r
1073 but could also be the name of a file, or in fact anything the particular EGT type requires.
\r
1074 It is upto the developer of the EGT format to specify the syntax of this parameter.
\r
1075 This command will only be sent to engines that have told the GUI they support EGTs of the given TYPE
\r
1076 through the egt feature.
\r
1077 It will be sent at the start of each game, before the "new" command.
\r
1080 <dt class="version44">option NAME[=VALUE]</dt>
\r
1081 <dd class="version44">
\r
1082 This command changes the setting of the option NAME defined by the engine
\r
1083 (through an earlier feature command)
\r
1084 to the given VALUE.
\r
1085 XBoard will in general have no idea what the option means,
\r
1086 and will send the command only when a user changes the value of this option through a menu,
\r
1087 or at startup of the engine
\r
1088 (before the first 'cores' command or, if that is not sent, the first 'new' command)
\r
1089 in reaction to command-line options.
\r
1090 The NAME echoes back to the engine the string that was identified as an option NAME
\r
1091 in the feature command defining the option.
\r
1092 The VALUE is of the type (numeric or text or absent) that was implied by the option type
\r
1093 specified in this feature command,
\r
1094 i.e. with 'spin' and 'check' options VALUE will be a decimal integer (in the latter case 0 or 1),
\r
1095 with 'combo' and 'string' options VALUE will be a text string,
\r
1096 and with 'button' and 'save' options no VALUE will be sent at all.
\r
1099 <dt class="version47">exclude MOVE</dt>
\r
1100 <dt class="version47">include MOVE</dt>
\r
1101 <dt class="version47">exclude all</dt>
\r
1102 <dt class="version47">include all</dt>
\r
1103 <dd class="version47">
\r
1104 These commands change the set of moves that the engine should consider in the root node of its search,
\r
1105 by removing or adding the mentioned MOVE from this set.
\r
1106 After reaching a new position, (e.g. through a usermove, undo, new or setboard command),
\r
1107 or after receiving "include all",
\r
1108 this set should always be reset to all legal moves from that position.
\r
1109 If the set of moves changes during a search,
\r
1110 the engine could start a new search from scratch, or it can try to be smart,
\r
1111 and continue the current search with the new set of moves
\r
1112 (e.g. after exclusion of a move that has not been searched yet in the current iteration).
\r
1113 After "exclude all", the engine would have no legal moves in the root,
\r
1114 which logically should make it behave as if it is (stale)mated,
\r
1115 but it is allowed to defer any effects of this command on a search in progress
\r
1116 to when the set gets non-empty again through addition of a move.
\r
1117 These commands will only be sent to engines that have requested such through the exclude feature.
\r
1120 <dt class="version47">setscore SCORE DEPTH</dt>
\r
1121 <dd class="version47">
\r
1122 This command instructs the engine to treat future search requests on the current position
\r
1123 (also when it is encountered inside a larger search tree)
\r
1124 upto the given DEPTH as if these result is SCORE centi-Pawn in favor of the side that has the move in this position.
\r
1125 It is entirely up to the engine to decide when the effect of this option should expire.
\r
1126 (E.g. it could last upto the next "new" or "quit" command,
\r
1127 or even into future sessions until the user explicitly clears it through an engine-defined option.)
\r
1128 This command will only be sent to engines that have requested it through the setscore feature.
\r
1131 <dt class="version48">lift SQUARE</dt>
\r
1132 <dt class="version48">put SQUARE</dt>
\r
1133 <dt class="version48">hover SQUARE</dt>
\r
1134 <dd class="version48">
\r
1135 These commands are only important for variants the GUI does not know the rules of,
\r
1136 and keep the engine aware of how the user is manipulating pieces in the GUI,
\r
1137 so that it can supply relevant rule information.
\r
1138 The "lift" command is sent by the GUI when the user 'picks up' (or selects) a piece from the mentioned SQUARE,
\r
1139 so that the engine can reply with a "highlight" command to mark the squares where that piece can move to.
\r
1140 The "put" command similarly indicates where the user releases that piece;
\r
1141 as the GUI clears the highlights on that event by itself, usually no engine response would be required.
\r
1142 For promotion moves you can get a double "put" command, the first one sent when the piece lands on the square,
\r
1143 without being decided yet what it promotes to, so the engine can send a "choice" command to
\r
1144 specify the promotion choice the GUI should offer when promotion wasn't already implied by the "lift" location.
\r
1145 The "hover" command is sent whenever the mouse pointer enters a square that is currently marked in red,
\r
1146 (reserved for captures)
\r
1147 so that the engine can (optionally) reply with a "highlight" command to mark victims of non-standard capture
\r
1148 (such as e.p. capture in Chess, or jump capture in Checkers) when the user would move the currently selected piece there.
\r
1149 These commands will only be sent to engines that have requested such through the highlight feature.
\r
1153 <h3>Bughouse commands:</h3>
\r
1156 xboard now supports bughouse engines when in Zippy mode. See
\r
1157 <a href="http://www.tim-mann.org/xboard/zippy.README"
\r
1158 >zippy.README</a> for information on Zippy mode and how to turn on the
\r
1159 bughouse support. The bughouse move format is given above. xboard
\r
1160 sends the following additional commands to the engine when in bughouse
\r
1162 Commands to inform your engine of the partner's game state may
\r
1163 be added in the future.
\r
1167 <dt>partner <player></dt>
\r
1168 <dd><player> is now your partner for future games. Example: <pre>partner mann</pre>
\r
1172 <dd>Meaning: You no longer have a partner.
\r
1175 <dt>ptell <text></dt>
\r
1176 <dd>Your partner told you <text>, either with a ptell or an ordinary tell.
\r
1179 <dt>holding [<white>] [<black>]</dt>
\r
1180 <dd>White currently holds <white>; black currently holds <black>.
\r
1181 Example: <pre>holding [PPPRQ] []</pre></dd>
\r
1183 <dt>holding [<white>] [<black>] <color><piece></dt>
\r
1184 <dd>White currently holds <white>; black currently holds <black>, after
\r
1185 <color> acquired <piece>. Example: <pre>holding [PPPRQ] [R] BR</pre></dd>
\r
1188 <h2><a name="9">9. Commands from the engine to xboard</a></h2>
\r
1190 <p class="version1">
\r
1191 In general, an engine should not send any output to xboard that is not
\r
1192 described in this document. As the protocol is extended, newer
\r
1193 versions of xboard may recognize additional strings as commands that
\r
1194 were previously not assigned a meaning.
\r
1199 <dt class="version1"> feature FEATURE1=VALUE1 FEATURE2=VALUE2 ... </dt>
\r
1200 <dd class="version1">
\r
1201 <p>Beginning with version 2, the protocol includes the "feature"
\r
1202 command, which lets your engine control certain optional protocol
\r
1203 features. Feature settings are written as FEATURE=VALUE, where
\r
1204 FEATURE is a name from the list below and VALUE is the value to be
\r
1205 assigned. Features can take string, integer, or boolean values; the
\r
1206 type of value is listed for each feature. String values are written
\r
1207 in double quotes (for example, <tt>feature myname="Miracle Chess
\r
1208 0.9"</tt>), integers are written in decimal, and boolean values are
\r
1209 written as 0 for false, 1 for true. Any number of features can be set
\r
1210 in one feature command, or multiple feature commands can be given.</p>
\r
1213 Your engine should send one or more feature commands immediately after
\r
1214 receiving the "protover" command, since xboard needs to know the
\r
1215 values of some features before sending further commands to the engine.
\r
1216 Because engines that predate protocol version 2 do not send "feature",
\r
1217 xboard uses a timeout mechanism: when it first starts your engine, it
\r
1218 sends "xboard" and "protover N", then listens for feature commands for
\r
1219 two seconds before sending any other commands. To end this timeout
\r
1220 and avoid the wait, set the feature "done=1" at the end of your last
\r
1221 feature command. To increase the timeout, if needed, set the feature
\r
1222 "done=0" before your first feature command and "done=1" at the end.
\r
1223 If needed, it is okay for your engine to set done=0 soon as it starts,
\r
1224 even before it receives the xboard and protover commands. This can be
\r
1225 useful if your engine takes a long time to initialize itself. It
\r
1226 should be harmless even if you are talking to a (version 1) user
\r
1227 interface that does not understand the "feature" command, since such
\r
1228 interfaces generally ignore commands from the engine that they do not
\r
1233 The feature command is designed to let the protocol change without
\r
1234 breaking engines that were written for older protocol versions. When
\r
1235 a new feature is added to the protocol, its default value is always
\r
1236 chosen to be compatible with older versions of the protocol that did
\r
1237 not have the feature. Any feature that your engine does not set in a
\r
1238 "feature" command retains its default value, so as the protocol
\r
1239 changes, you do not have to change your engine to keep up with it
\r
1240 unless you want to take advantage of a new feature. Because some
\r
1241 features are improvements to the protocol, while others are meant to
\r
1242 cater to engines that do not implement all the protocol features, the
\r
1243 recommended setting for a feature is not always the same as the
\r
1244 default setting. The listing below gives both default and recommended
\r
1245 settings for most features.
\r
1249 You may want to code your engine so as to be able to work with
\r
1250 multiple versions of the engine protocol. Protocol version 1 does not
\r
1251 send the protover command and does not implement the feature command;
\r
1252 if you send a feature command in protocol version 1, it will have no
\r
1253 effect and there will be no response. In protocol version 2 or later,
\r
1254 each feature F that you set generates the response "accepted F" if the
\r
1255 feature is implemented, or "rejected F" if it is not. Thus an engine
\r
1256 author can request any feature without having to keep track of which
\r
1257 protocol version it was introduced in; you need only check whether the
\r
1258 feature is accepted or rejected. This mechanism also makes it
\r
1259 possible for a user interface author to implement a subset of a
\r
1260 protocol version by rejecting some features that are defined in that
\r
1261 version; however, you should realize that engine authors are likely to
\r
1262 code for xboard and may not be prepared to have a feature that they
\r
1263 depend on be rejected.
\r
1264 <span class="version44">If the GUI rejects an option feature because of the
\r
1265 syntax of the value, it should print the value string with the
\r
1266 "rejected" command, e.g. "rejected option nonsense" in response
\r
1267 to receiving feature option="nonsense".</span>
\r
1271 Here are the features that are currently defined.
\r
1275 <dt class="version1">ping (boolean, default 0, recommended 1)</dt>
\r
1276 <dd class="version1">
\r
1277 If ping=1, xboard may use the protocol's new "ping" command;
\r
1278 if ping=0, xboard will not use the command.
\r
1281 <dt class="version1">setboard (boolean, default 0, recommended 1)</dt>
\r
1282 <dd class="version1">
\r
1283 If setboard=1, xboard will use the protocol's new "setboard" command
\r
1284 to set up positions; if setboard=0, it will use the older "edit" command.
\r
1287 <dt class="version1">playother (boolean, default 0, recommended 1)</dt>
\r
1288 <dd class="version1">
\r
1289 If playother=1, xboard will use the protocol's new "playother" command
\r
1290 when appropriate; if playother=0, it will not use the command.
\r
1293 <dt class="version1">san (boolean, default 0)</dt>
\r
1294 <dd class="version1">
\r
1295 If san=1, xboard will send moves to the engine in standard algebraic
\r
1296 notation (SAN); for example, Nf3. If san=0, xboard will send moves in
\r
1297 coordinate notation; for example, g1f3. See MOVE in
\r
1298 <a href="#8">section 8</a> above for more details of both kinds of notation.
\r
1301 <dt class="version1">usermove (boolean, default 0)</dt>
\r
1302 <dd class="version1">
\r
1303 If usermove=1, xboard will send moves to the engine with the
\r
1304 command "usermove MOVE"; if usermove=0, xboard will send just the move,
\r
1305 with no command name.
\r
1308 <dt class="version1">time (boolean, default 1, recommended 1)</dt>
\r
1309 <dd class="version1">
\r
1310 If time=1, xboard will send the "time" and "otim" commands to
\r
1311 update the engine's clocks; if time=0, it will not.
\r
1314 <dt class="version1">draw (boolean, default 1, recommended 1)</dt>
\r
1315 <dd class="version1">
\r
1316 If draw=1, xboard will send the "draw" command if the engine's opponent
\r
1317 offers a draw; if draw=0, xboard will not inform the engine about
\r
1318 draw offers. Note that if draw=1, you may receive a draw offer while you
\r
1319 are on move; if this will cause you to move immediately, you should set
\r
1323 <dt class="version1">sigint (boolean, default 1)</dt>
\r
1324 <dd class="version1">
\r
1325 If sigint=1, xboard may send SIGINT (the interrupt signal) to
\r
1326 the engine as <a href="#7">section 7</a> above; if sigint=0, it will
\r
1330 <dt class="version1">sigterm (boolean, default 1)</dt>
\r
1331 <dd class="version1">
\r
1332 If sigterm=1, xboard may send SIGTERM (the termination signal) to
\r
1333 the engine as <a href="#7">section 7</a> above; if sigterm=0, it will
\r
1337 <dt class="version1">reuse (boolean, default 1, recommended 1) </dt>
\r
1338 <dd class="version1">
\r
1339 If reuse=1, xboard may reuse your engine for multiple games. If
\r
1340 reuse=0 (or if the user has set the -xreuse option on xboard's command
\r
1341 line), xboard will kill the engine process after every game and start
\r
1342 a fresh process for the next game.
\r
1345 <dt class="version1">analyze (boolean, default 1, recommended 1)</dt>
\r
1346 <dd class="version1">
\r
1347 If analyze=0, xboard will not try to use the "analyze" command; it
\r
1348 will pop up an error message if the user asks for analysis mode. If
\r
1349 analyze=1, xboard will try to use the command if the user asks for
\r
1353 <dt class="version1">myname (string, default determined from engine filename)</dt>
\r
1354 <dd class="version1">
\r
1355 This feature lets you set the name that xboard will use for your
\r
1356 engine in window banners, in the PGN tags of saved game files, and when
\r
1357 sending the "name" command to another engine.
\r
1360 <dt class="version1">variants (string, see text below)</dt>
\r
1361 <dd><span class="version1">
\r
1362 This feature indicates which chess variants your engine accepts.
\r
1363 It should be a comma-separated list of variant names. See the table
\r
1364 under the "variant" command in <a href="#8">section 8</a> above. If
\r
1365 you do not set this feature, xboard will assume by default that your
\r
1366 engine supports all variants. (However, the -zippyVariants
\r
1367 command-line option still limits which variants will be accepted in
\r
1368 Zippy mode.) It is recommended that you set this feature to the
\r
1369 correct value for your engine (just "normal" in most cases) rather
\r
1370 than leaving the default in place, so that the user will get an
\r
1371 appropriate error message if he tries to play a variant that your
\r
1372 engine does not support.</span>
\r
1373 <span class="version48">As of XBoard 4.8 a variant name not known to the GUI will be
\r
1374 considered an engine-defined variant.
\r
1375 The user will be given the opportunity to select such variants,
\r
1376 but when this happens, the engine should define its meaning
\r
1377 in detail with the aid of a "setup" command defined below,
\r
1378 in order to avoid an error.</span>
\r
1380 <span class="version43">If your engine can play variants on a deviating board size,
\r
1381 like capablanca on an 8x8 board, or capablanca crazyhouse,
\r
1382 it can list them amongst the variants with a prefix specifying board size plus
\r
1383 holdings size, like 8x8+0_capablanca or 10x8+7_capablanca.
\r
1384 If it is capable of playing any variant with an arbitrary board size,
\r
1385 it should list "boardsize" as one of the variants.
\r
1386 If there is a maximum to the board size, this can be prefixed,
\r
1387 e.g. "12x10+0_boardsize".
\r
1391 <dt class="version1">colors (boolean, default 1, recommended 0) </dt>
\r
1392 <dd><span class="version1">
\r
1393 If colors=1, xboard uses the obsolete "white" and "black"
\r
1394 commands in a stylized way that works with most older chess engines
\r
1395 that require the commands. See the "<a href="#13">Idioms</a>" section
\r
1396 below for details. If colors=0, xboard does not use the "white" and
\r
1397 "black" commands at all.
\r
1401 <dt class="version1">ics (boolean, default 0)</dt>
\r
1402 <dd class="version1">
\r
1403 If ics=1, xboard will use the protocol's new "ics" command
\r
1404 to inform the engine of whether or not it is playing on a chess server;
\r
1405 if ics=0, it will not.
\r
1408 <dt class="version1">name (boolean, see text below)</dt>
\r
1409 <dd class="version1">
\r
1410 If name=1, xboard will use the protocol's "name" command
\r
1411 to inform the engine of the opponent's name; if name=0, it will not.
\r
1412 By default, name=1 if the engine is playing on a chess server; name=0 if not.
\r
1415 <dt class="version1">pause (boolean, default 0)</dt>
\r
1416 <dd class="version1">
\r
1417 If pause=1, xboard may use the protocol's new "pause" command;
\r
1418 if pause=0, xboard assumes that the engine does not support this command.
\r
1421 <dt class="version43">nps (boolean, default ?)</dt>
\r
1422 <dd class="version43">
\r
1423 If nps=1, it means the engine supports the nps command.
\r
1424 If nps=0, it means the engine does not support it, and WinBoard should refrain from sending it.
\r
1425 Default is that WinBoard sends it, in an attempt to try out if the engine understand it.
\r
1426 The engine should properly respond with "Error (unkown command): nps" if it does not implement it,
\r
1427 (as any protocol version pre-scribes),
\r
1428 or WinBoard might assume that the engine did understand the command.
\r
1429 In that case the use of different time standards that ensues could lead to time forfeits for the engine.
\r
1432 <dt class="version43">debug (boolean, default 0)</dt>
\r
1433 <dd class="version43">
\r
1434 If debug=1, it means the engine wants to send debug output prefixed by '#',
\r
1435 which WinBoard should ignore, except for including it in the winboard.debug file.
\r
1436 As this feature is added to protocol 2 ony late,
\r
1437 so that not all protocol-2 supporting versions of WinBoard might implement it,
\r
1438 it is important that engines check if WinBoard accepts the feature.
\r
1439 If the feature is rejected,
\r
1440 engines must refrain from sending the debug output,
\r
1441 or do so at their own risk.
\r
1444 <dt class="version44">memory (boolean, default 0)</dt>
\r
1445 <dd class="version44">
\r
1446 If memory=1, the size of the total amount of memory available for the memory-consuming tables of the engine
\r
1447 (e.g. hash, EGTB cache)
\r
1448 will be set by the GUI through the "memory" command.
\r
1451 <dt class="version44">smp (boolean, default 0)</dt>
\r
1452 <dd class="version44">
\r
1453 If smp=1, the GUI will send the "cores" command to the engine to inform it how many CPU cores it can use.
\r
1454 Note that sending smp=1 does not imply the engine can use more than one CPU;
\r
1455 just that it wants to receive the "cores" command.
\r
1458 <dt class="version44">egt (string, see text below)</dt>
\r
1459 <dd class="version44">
\r
1460 This feature indicates which end-game table formats the engine supports.
\r
1461 It should be a comma-separated list of format names.
\r
1462 See under the "egtpath" command in <a href="#8">section 8</a> above.
\r
1463 If you do not set this feature, xboard will assume the engine does not support end-game tables,
\r
1464 and will not send any "egtpath" commands to inform the engine about their whereabouts.
\r
1467 <dt class="version44">option (string, see text below)</dt>
\r
1468 <dd><span class="version44">
\r
1469 This feature is used by the engine to define an option command to appear in a GUI menu,
\r
1470 so that the user can change the corresponding setting of the engine through the GUI interactively.
\r
1471 The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range.
\r
1472 Unlike other features, option features are accumulated by the GUI,
\r
1473 and the GUI must be able to add a new option to the list at any time,
\r
1474 even after having received feature done=1.
\r
1475 There are ten different options types, each requiring a slighly different syntax of the defining string:
\r
1477 feature option="NAME -button"
\r
1479 feature option="NAME -save"
\r
1481 feature option="NAME -reset"
\r
1483 feature option="NAME -check VALUE"
\r
1485 feature option="NAME -string VALUE"
\r
1487 feature option="NAME -spin VALUE MIN MAX"
\r
1489 feature option="NAME -combo CHOICE1 /// CHOICE2 ..."
\r
1491 feature option="NAME -slider VALUE MIN MAX"
\r
1493 feature option="NAME -file VALUE"
\r
1495 feature option="NAME -path VALUE"
\r
1497 NAME is an arbitrary alphanumeric string which can contain spaces;
\r
1498 the other words in capitals would be replaced by the current (default) setting of the option,
\r
1499 (a character string for -string options, a decimal number for -spin and -check options,
\r
1500 were the latter uses 1=checked, 0=unchecked),
\r
1501 the minimum or maximum value of numeric (-spin) options,
\r
1502 or arbitrary text labels (for -combo option).
\r
1503 In the latter case, the current value will be preceded by an asterisk.
\r
1504 The -file and -path options are similar to -string, but can be used to inform the GUI that
\r
1505 the text represents a file name or folder name respectively,
\r
1506 so the GUI dialog could add the appropriate browse button to the text-edit field.
\r
1507 Similarly, a -slider option is like a -spin, but the GUI might make a different
\r
1508 graphical representation for it.
\r
1509 A -save option is like a -button, and defines an immediate command to be sent by the engine.
\r
1510 With -save the GUI will make sure all current option settings are flushed to the engine
\r
1511 before it sends this command.
\r
1512 A -reset option is like a -button, but use of it purges the list of options before sending
\r
1513 the corresponding option command to the engine.
\r
1514 This enables the engine to completely redefine its options or their current settings,
\r
1515 by sending a new set of option feature commands to the GUI,
\r
1516 terminated by feature done=1.
\r
1517 (The effect of sending an option feature for an option with the same name as was defined before,
\r
1518 without first receiving a -reset option command, is undefined.)
\r
1522 <dt class="version47">exclude (boolean, default 0)</dt>
\r
1523 <dd class="version47">
\r
1524 If exclude=1 the GUI can send "exclude" and "include" commands to control which moves
\r
1525 from the root position should be searched.
\r
1528 <dt class="version47">setscore (boolean, default 0)</dt>
\r
1529 <dd class="version47">
\r
1530 If setscore=1 the GUI can send "setscore" commands to define the score of the current position.
\r
1533 <dt class="version48">highlight (boolean, default 0)</dt>
\r
1534 <dd class="version48">
\r
1535 If highlight=1 the GUI will send "lift", "put" and "hover" commands to the engine,
\r
1536 to keep the latter aware of the user's piece manipulation before the move entry is completed,
\r
1537 so it can respond with the proper "highlight" and "click" commands.
\r
1540 <dt class="version1">done (integer, no default)</dt>
\r
1541 <dd><span class="version1">
\r
1542 If you set done=1 during the initial two-second timeout after
\r
1543 xboard sends you the "xboard" command, the
\r
1544 timeout will end and xboard will not look for any more feature
\r
1545 commands before starting normal operation.
\r
1546 If you set done=0, the initial timeout is increased to one hour;
\r
1547 in this case, you must set done=1 before xboard will enter normal operation.
\r
1554 <dt>setup FEN</dt>
\r
1555 <dt>setup (PIECETOCHAR) FEN</dt>
\r
1556 <dt>setup (PIECETOCHAR) WxH+S_PARENTVARIANT FEN</dt>
\r
1557 <dd>The engine can optionally send a setup command to the GUI in reply
\r
1558 to the variant command.
\r
1559 In the simplest form this sends the FEN of the initial position.
\r
1560 This can be used to implement engines for non-standard variants
\r
1561 that only differ from standard variants through the initial position.
\r
1562 (E.g. many of the 'wild' boards you can play on an ICS.)
\r
1563 Whether the GUI should obey or ignore this command depends on the situation.
\r
1564 Normally it would ignore it in variants where it knows the standard initial position
\r
1565 and legality testing is on, or when the user specified an initial position.
\r
1566 In other cases it will use the FEN sent by the first engine
\r
1567 for setting up the initial position, as if it was an externally supplied position.
\r
1568 Such a position will always be sent to a second engine that might be involved,
\r
1569 and any setup commands received from the latter will always be ignored.
\r
1570 (This to allow for shuffle games, where the two engines might pick different setups.)
\r
1571 When no initial position is known, such as for 'catch-all' variants like fairy,
\r
1572 or whenever the board width is overruled to a non-standard value,
\r
1573 the FEN will be used as default initial position even when legality testing is on.
\r
1575 Optionally the meaning of the piece ID letters in the FEN can be defined
\r
1576 between parentheses; this will be interpreted as if it was the value of a
\r
1577 -pieceToCharTable command-line option, mapping letters to GUI piece types.
\r
1578 Also optionally behind that, the setup command can specify board width W,
\r
1579 board height H and holdings size S, as well as a 'parent variant'.
\r
1580 This is typically done in response to a variant command with a non-standard name,
\r
1581 about which the GUI is not supposed to know anything at all.
\r
1582 The engine can then specify board size, participating pieces, initial setup,
\r
1583 and other rule details (inherited from the parent variant),
\r
1584 saving the user the trouble to configure the GUI for this non-standard variant.
\r
1587 setup (PN.RQKpn.rqk) 6x6+0_fairy rnqknr/pppppp/6/6/PPPPPP/RNQKNR w - - 0 1
\r
1589 could be used by an engine for Los-Alamos Chess in response to 'variant losalamos',
\r
1590 and would automatically switch the GUI to this variant as soon as the user
\r
1591 selected it from the GUI menu.
\r
1592 The PIECETOCHAR element would ensure a Bishop would not be accepted as promotion choice.
\r
1596 <dt><span class="version48">piece ID PIECEDESC</span></dt>
\r
1597 <dd><span class="version48">The engine can send one or more piece commands
\r
1598 in response to a variant command, in order to specify that the piece
\r
1599 indicated by ID moves in a non-standard way in this variant.
\r
1600 (This to enable the GUI to reliably perform mate detection, and produce good SAN.)
\r
1601 Like in FEN the ID is a case-sensitive letter, specifying the color.
\r
1602 When it is a capital suffixed by &, the description is valid for both colors.
\r
1603 PIECEDESC describes the moves in 'Betza notation',
\r
1604 basically a concatenation of one-letter (upper-case) codes for all of its moves.
\r
1605 These codes can be prefixed with lower-case 'modifiers' to indicate directional sub-sets
\r
1606 (combinations of fblrvs, if the piece is not totally symmetric),
\r
1607 move modality (non-capture, capture, e.p. capture; mce),
\r
1608 and whether the move can jump directly to its destination,
\r
1609 or can be blocked (n).
\r
1610 Moves only valid for a virgin piece are prefixed by 'i'.
\r
1611 An optional numeric suffix on the move indicates the maximum number of times
\r
1612 the move can be repeated in the same direction,
\r
1613 to indicate sliders / riders (with the convention 0 = infinite).
\r
1618 <dt>Illegal move: MOVE</dt>
\r
1619 <dt>Illegal move (REASON): MOVE</dt>
\r
1620 <dd>If your engine receives a MOVE command that is recognizably a move
\r
1621 but is not legal in the current position, your engine must print an
\r
1622 error message in one of the above formats so that xboard can pass the
\r
1623 error on to the user and retract the move. The (REASON) is entirely
\r
1624 optional. Examples:
\r
1627 Illegal move: e2e4
\r
1628 Illegal move (in check): Nf3
\r
1629 Illegal move (moving into check): e1g1
\r
1632 Generally, xboard will never send an ambiguous move, so it does not
\r
1633 matter whether you respond to such a move with an Illegal move message
\r
1634 or an Error message.
\r
1638 <dt>Error (ERRORTYPE): COMMAND</dt>
\r
1639 <dd>If your engine receives a command it does not understand or does
\r
1640 not implement, it should print an error message in the above format so
\r
1641 that xboard can parse it. Examples:
\r
1643 Error (ambiguous move): Nf3
\r
1644 Error (unknown command): analyze
\r
1645 Error (command not legal now): undo
\r
1646 Error (too many parameters): level 1 2 3 4 5 6 7
\r
1650 <dt>move MOVE</dt>
\r
1651 <dd>Your engine is making the move MOVE. Do not echo moves from
\r
1652 xboard with this command; send only new moves made by the engine.
\r
1654 <div class="version1">
\r
1655 <p>For the actual move text from your chess engine (in place of MOVE
\r
1656 above), your move should be either</p>
\r
1658 <li>in coordinate notation (e.g.,
\r
1659 e2e4, e7e8q) with castling indicated by the King's two-square move (e.g.,
\r
1661 <li>in Standard Algebraic Notation (SAN) as defined in the
\r
1662 Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q),
\r
1663 with the extension piece@square (e.g., P@f7) to handle piece placement
\r
1664 in bughouse and crazyhouse.</li>
\r
1667 xboard itself also accepts some variants of SAN, but for compatibility
\r
1668 with non-xboard interfaces, it is best not to rely on this behavior.
\r
1671 <p>Warning: Even though all versions of this protocol specification
\r
1672 have indicated that xboard accepts SAN moves, some non-xboard
\r
1673 interfaces are known to accept only coordinate notation. See the
\r
1674 Idioms section for more information on the known limitations of some
\r
1675 non-xboard interfaces. It should be safe to send SAN moves if you
\r
1676 receive a "protover 2" (or later) command from the interface, but
\r
1677 otherwise it is best to stick to coordinate notation for maximum
\r
1678 compatibility. An even more conservative approach would be for your
\r
1679 engine to send SAN to the interface only if you have set feature san=1
\r
1680 (which causes the interface to send SAN to you) and have received
\r
1681 "accepted san" in reply.
\r
1684 <p class="version48">
\r
1685 For a multi-leg move, each leg will have to be sent in a separate "move" command,
\r
1686 a comma at the end of all non-final legs indicating there is more to follow.
\r
1691 <dt>RESULT {COMMENT}</dt>
\r
1692 <dd>When your engine detects
\r
1693 that the game has ended by rule, your engine must output a line of the
\r
1694 form "RESULT {comment}" (without the quotes), where RESULT is a PGN
\r
1695 result code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Here
\r
1696 "by rule" means that the game is definitely over because of what
\r
1697 happened on the board. In normal chess, this includes checkmate,
\r
1698 stalemate, triple repetition, the 50 move rule, or insufficient
\r
1699 material; it does not include loss on time or the like.
\r
1704 1/2-1/2 {Draw by repetition}
\r
1705 1/2-1/2 {Stalemate}
\r
1709 xboard relays the result to the user, the ICS, the other engine in Two
\r
1710 Machines mode, and the PGN save file as required.
\r
1711 <span class="version43">Note that "definitey over" above means that sending this command
\r
1712 will be taken by WinBoard as an unconditional refusal of the engine to play on,
\r
1713 which might cause you to forfeit if the game was in fact not over.
\r
1714 This command should thus not be used to offer draws, accept draws,
\r
1715 or make draw-by-rule claims that are not yet valid in the current position
\r
1716 (but will be after you move).
\r
1717 For offering and claiming such draws, "offer draw" should be used.</span>
\r
1720 <p class="version44">
\r
1721 Note that (in accordance with FIDE rules) only KK, KNK, KBK and KBKB with all bishops on the
\r
1722 same color can be claimed as draws on the basis of insufficient mating material.
\r
1723 The end-games KNNK, KBKN, KNKN and KBKB with unlike bishops do have mate positions,
\r
1724 and cannot be claimed.
\r
1725 Complex draws based on locked Pawn chains will not be recognized as draws by most interfaces,
\r
1726 so do not claim in such positions, but just offer a draw or play on.
\r
1729 <p class="version44">
\r
1730 Note to GUI programmers: RESULT commands that the engine sends immediately after its move
\r
1731 might be detected by the GUI only after the opponent has moved, because of communication
\r
1732 and scheduling delays, no matter how fast the engine sent it.
\r
1733 Any judgement of the validity of RESULT claims based on te "current" board position
\r
1734 will have to account for this uncertainty.
\r
1739 <dd>If your engine wants to resign, it can send the command "resign".
\r
1740 Alternatively, it can use the "RESULT {comment}" command if the string
\r
1741 "resign" is included in the comment; for example "0-1 {White
\r
1742 resigns}". xboard relays the resignation to the user, the ICS, the
\r
1743 other engine in Two Machines mode, and the PGN save file as required.
\r
1744 <span class="version44">Note that many interfaces work more smoothly if you resign <em>before</em>
\r
1748 <dt>offer draw</dt>
\r
1749 <dd>If your engine wants to offer a draw by agreement (as opposed to
\r
1750 claiming a draw by rule), it can send the command "offer draw".
\r
1751 xboard relays the offer to the user, the ICS, the other engine in Two
\r
1752 Machines mode, and the PGN save file as required. In Machine White,
\r
1753 Machine Black, or Two Machines mode, the offer is considered valid
\r
1754 until your engine has made two more moves.
\r
1755 <span class="version43">This command must also be used to accept a draw offer.
\r
1756 Do not use the 1/2-1/2 command for that, as the offer might be no longer valid,
\r
1757 in which case a refusal to play on implied by the RESULT command might make you forfeit the game.
\r
1758 "offer draw" should also be used to claim 50-move and 3-fold-repetition draws
\r
1759 that will occur <em>after</em> your move, by sending it <em>before</em> making the move.
\r
1760 WinBoard will grant draw offers without the opponent having any say in
\r
1761 it in situations where draws can be claimed.
\r
1762 Only if the draw cannot be claimed, the offer will be passed to your opponent after you make your next move,
\r
1763 just before WinBoard relays this move to the opponent.
\r
1767 <dt class="version1">tellopponent MESSAGE</dt>
\r
1768 <dd class="version1">
\r
1769 This command lets the engine give a message to its opponent,
\r
1770 independent of whether the opponent is a user on the local machine or
\r
1771 a remote ICS user (Zippy mode). MESSAGE consists of any characters,
\r
1772 including whitespace, to the end of the line. When the engine is
\r
1773 playing against a user on the local machine, xboard pops up an
\r
1774 information dialog containing the message. When the engine is playing
\r
1775 against an opponent on the ICS (Zippy mode), xboard sends "say
\r
1776 MESSAGE\n" to the ICS.
\r
1779 <dt class="version1">tellothers MESSAGE </dt>
\r
1780 <dd class="version1">This command lets the engine give a message to people watching the
\r
1781 game other than the engine's opponent. MESSAGE consists of any
\r
1782 characters, including whitespace, to the end of the line. When the
\r
1783 engine is playing against a user on the local machine, this command
\r
1784 does nothing. When the engine is playing against an opponent on the
\r
1785 ICS (Zippy mode), xboard sends "whisper MESSAGE\n" to the ICS.
\r
1788 <dt class="version1">tellall MESSAGE</dt>
\r
1789 <dd class="version1">This command lets the engine give a message to its opponent and
\r
1790 other people watching the game,
\r
1791 independent of whether the opponent is a user on the local machine or
\r
1792 a remote ICS user (Zippy mode). MESSAGE consists of any characters,
\r
1793 including whitespace, to the end of the line. When the engine is
\r
1794 playing against a user on the local machine, xboard pops up an
\r
1795 information dialog containing the message. When the engine is playing
\r
1796 against an opponent on the ICS (Zippy mode), xboard sends "kibitz
\r
1797 MESSAGE\n" to the ICS.
\r
1800 <dt>telluser MESSAGE</dt>
\r
1801 <dd>xboard pops up an information dialog containing the message.
\r
1802 MESSAGE consists of any characters, including whitespace, to the end
\r
1806 <dt>tellusererror MESSAGE</dt>
\r
1807 <dd>xboard pops up an error dialog containing the message.
\r
1808 MESSAGE consists of any characters, including whitespace, to the end
\r
1812 <dt>askuser REPTAG MESSAGE</dt>
\r
1813 <dd>Here REPTAG is a string containing no whitespace, and MESSAGE
\r
1814 consists of any characters, including whitespace, to the end of the
\r
1815 line. xboard pops up a question dialog that says MESSAGE and
\r
1816 has a typein box. If the user types in "bar", xboard sends "REPTAG
\r
1817 bar" to the engine. The user can cancel the dialog and send nothing.
\r
1820 <dt>tellics MESSAGE</dt>
\r
1821 <dd>In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists
\r
1822 of any characters, including whitespace, to the end of the line.
\r
1825 <dt class="version1">tellicsnoalias MESSAGE</dt>
\r
1826 <dd class="version1">
\r
1827 In Zippy mode, xboard sends "xMESSAGE\n" to ICS, where "x" is a
\r
1828 character that prevents the ICS from expanding command aliases, if
\r
1829 xboard knows of such a character. (On chessclub.com and chess.net,
\r
1830 "/" is used; on freechess.org, "$" is used.) MESSAGE consists of any
\r
1831 characters, including whitespace, to the end of the line.
\r
1834 <dt class="version43"># COMMENT</dt>
\r
1835 <dd class="version43">
\r
1836 The engine can send any string of printable characters, terminated by a newline,
\r
1837 for inclusion in the winboard.debug file, provided the line starts with a '#' character.
\r
1838 If the engine has set feature debug=1,
\r
1839 it is guaranteed that WinBoard (and any future version of it) will completely ignore
\r
1840 these lines in any other respect.
\r
1843 <dt class="version48">highlight COLORFEN</dt>
\r
1844 <dd class="version48">
\r
1845 Through this command the engine can apply markers to the board squares,
\r
1846 of the same type as the GUI uses for indicating where the user could put down a piece he grabs.
\r
1847 The COLORFEN is a construct similar to the board part of a FEN,
\r
1848 in which the letters indicate colors rather than piece types.
\r
1849 Eight colors are available, through the single-letter codes: RYGCBMWD,
\r
1850 for red, yellow, green, cyan, blue, magenta, white, black ('dark'), respectively.
\r
1851 For example, "highlight 8/8/8/8/4y3/4yr2/8/8" would mark e3 and e4 yellow, and f3 red.
\r
1852 Some colors have special meaning to the GUI:
\r
1854 <tr><th>color</th><th>used for</th><th>effect</th><tr>
\r
1855 <tr><td>red</td><td>capture</td><td>hovering over the square makes the GUI send a "hover" command</td><tr>
\r
1856 <tr><td>magenta</td><td>promotion</td><td>moving to the square will be treated by the GUI as a promotion</td><tr>
\r
1857 <tr><td>cyan</td><td>multi-move</td><td>moving to the square will not complete the move entry</td><tr>
\r
1858 <tr><td>green</td><td>victims</td><td>no real effect, but used by convention to indicate capture victims on "hover"</td><tr>
\r
1860 The GUI will use the markers for legality checking,
\r
1861 and will consider moves to squares left non-marked in a highlight command as illegal even when legality checking is off.
\r
1862 This way the GUI can be made aware of the rules of unknown variants,
\r
1863 popping up promotion dialogs where it would otherwise not,
\r
1864 and knowing where to wait for more input on multi-leg moves.
\r
1865 When it would be necessary to mark squares where no legal moves go to
\r
1866 (e.g. to indicate side effects),
\r
1867 the corresponding lower-case character can be used for the color.
\r
1868 For indicating a legal destination square without visibly marking it, T (transparent) can be used.
\r
1871 <dt class="version48">choice PIECESTRING</dt>
\r
1872 <dd class="version48">
\r
1873 This command can be sent to the GUI in response to a 'lift' or 'put' command that implies a promotion move,
\r
1874 to alter the choice offered to the user for the promotion piece from what the GUI would naturally assume,
\r
1875 to the piece IDs mentioned in the PIECESTRING.
\r
1876 The IDs in that string should be given as capitals irrespective of color.
\r
1877 The first piece mentioned will be the default choice.
\r
1881 <dt class="version48">click SQUARE</dt>
\r
1882 <dd class="version48">
\r
1883 The GUI will treat this command as if the user had clicked the mentioned SQUARE.
\r
1884 This can be used to implement one-click moving in variants the GUI does not know the rules of
\r
1885 (having the engine send the clicks needed to complete the move).
\r
1886 It can also be used to implement side effects of the move the GUI would not know about
\r
1887 (e.g. moving the Rook in a non-standard castling).
\r
1891 <h2><a name="10">10. Thinking Output</a></h2>
\r
1894 If the user asks your engine to "show thinking", xboard sends your
\r
1895 engine the "post" command. It sends "nopost" to turn thinking off.
\r
1896 In post mode, your engine sends output lines to show the progress of
\r
1897 its thinking. The engine can send as many or few of these lines as it
\r
1898 wants to, whenever it wants to. Typically they would be sent when the
\r
1899 PV (principal variation) changes or the depth changes. The thinking
\r
1900 output should be in the following format:
\r
1903 <pre>ply score time nodes pv</pre>
\r
1907 <tr><td>ply</td><td>Integer giving current search depth.</td></tr>
\r
1908 <tr><td>score</td><td>Integer giving current evaluation in centipawns.</td></tr>
\r
1909 <tr><td>time</td><td>Current search time in centiseconds (ex:1028 = 10.28 seconds).</td></tr>
\r
1910 <tr><td>nodes</td><td>Nodes searched.</td></tr>
\r
1911 <tr><td>*selective depth</td><td>Maximium length of any branch in the current search.</td></tr>
\r
1912 <tr><td>*speed</td><td>Nodes per second in last measured time interval.</td></tr>
\r
1913 <tr><td>*</td><td>Reserved for future extensions.</td></tr>
\r
1914 <tr><td>*tbhits</td><td>Number of tablebase probes made in the current search.</td></tr>
\r
1915 <tr><td>pv</td><td>Freeform text giving current "best" line.
\r
1916 You can continue the pv onto another line if you start each
\r
1917 continuation line with at least four space characters.</td></tr>
\r
1920 <p class="version48">
\r
1921 The items marked with * are optional.
\r
1922 If any of these items is present, the <b>pv</b> field must be preceeded directly by a tab character;
\r
1923 if no tab character preceeds the first non-integer token,
\r
1924 the <b>pv</b> field will start at the first non-blank character after <b>nodes</b>.
\r
1925 Otherwise it will start after the last tab that is not behind any non-integer token.
\r
1926 Of all integers between <b>nodes</b> and <b>pv</b> the last one is intepreted as <b>tbhits</b>.
\r
1927 Of any remaining ones the first is interpreted as <b>selective depth</b>,
\r
1928 and a second as <b>speed</b>.
\r
1929 More infos could be added to this in the future.
\r
1930 Note that older interfaces might consider the optional infos to be part of the <b>pv</b> field,
\r
1931 and display them exactly as sent.
\r
1932 It is therefore encouraged that engines use tabs or spaces to format this optional info
\r
1933 so that it will display nicely in (not too wide) columns.
\r
1936 <p class="version48">
\r
1937 A question mark as the last character in the <b>pv</b> field should be used to indicate
\r
1938 the reported score is from a fail low, and thus represents an upper bound only.
\r
1939 Similarly, an exclamation point should be used to indicate a fail high / lower bound.
\r
1942 <p class="version48">
\r
1943 Mate scores should be indicated as 100000 + N for "mate in N moves",
\r
1944 and -100000 - N for "mated in N moves".
\r
1951 <pre> 9 156 1084 48000 Nf3 Nc6 Nc3 Nf6</pre>
\r
1958 9 ply, score=1.56, time = 10.84 seconds, nodes=48000, PV = "Nf3 Nc6 Nc3 Nf6"
\r
1962 Longer example from actual Crafty output:
\r
1966 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6
\r
1967 4 116 23 2252 1. Nf3 Nc6 2. e4 e6
\r
1968 4 116 27 2589 1. Nf3 Nc6 2. e4 e6
\r
1969 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4
\r
1970 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4
\r
1974 You can use the PV to show other things; for instance, while in book,
\r
1975 Crafty shows the observed frequency of different reply moves in its
\r
1976 book. In situations like this where your engine is not really
\r
1977 searching, start the PV with a '(' character:
\r
1981 0 0 0 0 (e4 64%, d4 24%)
\r
1985 GNU Chess output is very slightly different. The ply number is
\r
1986 followed by an extra nonblank character, and the time is in seconds,
\r
1987 not hundredths of seconds. For compatibility, xboard accepts the
\r
1988 extra character and takes it as a flag indicating the different time
\r
1993 2. 14 0 38 d1d2 e8e7
\r
1994 3+ 78 0 65 d1d2 e8e7 d2d3
\r
1995 3& 14 0 89 d1d2 e8e7 d2d3
\r
1996 3& 76 0 191 d1e2 e8e7 e2e3
\r
1997 3. 76 0 215 d1e2 e8e7 e2e3
\r
1998 4& 15 0 366 d1e2 e8e7 e2e3 e7e6
\r
1999 4. 15 0 515 d1e2 e8e7 e2e3 e7e6
\r
2000 5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4
\r
2001 5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4
\r
2002 5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4
\r
2003 6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
2004 6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
2005 7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
2006 7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4
\r
2007 8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
\r
2008 8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5
\r
2009 9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
\r
2011 9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4
\r
2013 10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
\r
2015 10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4
\r
2019 <p>If your engine is pondering (thinking on its opponent's time) in post
\r
2020 mode, it can show its thinking then too. In this case your engine may
\r
2021 omit the hint move (the move it is assuming its opponent will make)
\r
2022 from the thinking lines <em>if and only if</em> it sends xboard the move in
\r
2023 the usual "Hint: xxx" format before sending the first line.
\r
2026 <h2><a name="11">11. Time control</a></h2>
\r
2029 xboard supports three styles of time control: conventional chess clocks,
\r
2030 the ICS-style incremental clock, and an exact number of seconds per move.
\r
2033 <p>In conventional clock mode, every time control period is the same.
\r
2034 That is, if the time control is 40 moves in 5 minutes, then after each
\r
2035 side has made 40 moves, they each get an additional 5 minutes, and so
\r
2036 on, ad infinitum. At some future time it would be nice to support a
\r
2037 series of distinct time controls. This is very low on my personal
\r
2038 priority list, but code donations to the xboard project are accepted,
\r
2039 so feel free to take a swing at it. I suggest you talk to me first,
\r
2044 The command to set a conventional time control looks like this:
\r
2053 The 40 means that there are 40 moves per time control. The 5 means
\r
2054 there are 5 minutes in the control. In the second example, the 0:30
\r
2055 means there are 30 seconds. The final 0 means that we are in
\r
2056 conventional clock mode.
\r
2059 <p class="version43">
\r
2060 Note that the time parameter in this command is not a pure numeric argument,
\r
2061 but in general is a character string, in order to pass the number of seconds.
\r
2062 Engines are encouraged to ignore any unexpected characters at the end of this string,
\r
2063 i.e. following the MIN or MIN:SEC specification.
\r
2064 Future protocol versions might (under control of an appropriate feature)
\r
2065 append such extra characters to this argument,
\r
2066 in order to inform the engine in advance of the time control it can expect after the current session completes.
\r
2067 E.g. "level 40 25+5 0" could mean that the engine has to play 40 moves in 25 minutes,
\r
2068 but should expect to get only 5 minutes for the entire remainder of the game after that,
\r
2069 rather than another 25 minutes for the next 40 moves.
\r
2070 When the time comes, (i.e. after the 40 moves),
\r
2071 it will be informed of the time-control change by receiving a new "level 0 5 0" command,
\r
2072 but engines with advanced time management might want to plan for this in advance.
\r
2076 The command to set an incremental time control looks like this:
\r
2084 Here the 0 means "play the whole game in this time control period",
\r
2085 the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As
\r
2086 in conventional clock mode, the second argument to level can be in
\r
2087 minutes and seconds.
\r
2091 At the start of the game, each player's clock is set to base minutes.
\r
2092 Immediately after a player makes a move, inc seconds are added to his
\r
2093 clock. A player's clock counts down while it is his turn. Your flag
\r
2094 can be called whenever your clock is zero or negative. (Your clock
\r
2095 can go negative and then become positive again because of the
\r
2099 <p class="version44">
\r
2100 The number of moves given in the level command (when non-zero) should
\r
2101 be taken as the number of moves still to do before the specified time
\r
2102 will be added to the clock, if the "level" command is received after
\r
2103 some moves have already been played.
\r
2104 The time given should be interpreted as the time left on its clock
\r
2105 (including any time left over from the previous sessions),
\r
2106 and not necessarily the time that will be added to the clock
\r
2107 after the specified number of moves has been played.
\r
2108 This is only relevant in WinBoard 4.3.xx, which might send the engine
\r
2109 "level" commands during a game,
\r
2110 just before the engine has to start thinking about the first move of
\r
2111 a new time-control session.
\r
2112 Example: if at the start of the game "level 40 60 0" was given
\r
2113 (40 moves per hour),
\r
2114 and the engine receives "level 20 22 0" just before move 41,
\r
2115 it should understand that it should do the next 20 moves in 22 minutes
\r
2116 (pehaps because the secondary session was 20 moves per 15 minutes,
\r
2117 and it had 7 minutes left on its clock after the first 40 moves).
\r
2121 A special rule on some ICS implementations: if you ask for a game with
\r
2122 base=0, the clocks really start at 10 seconds instead of 0. xboard
\r
2123 itself does not know about this rule, so it passes the 0 on to the
\r
2124 engine instead of changing it to 0:10.
\r
2128 ICS also has time odds games. With time odds, each player has his own
\r
2129 (base, inc) pair, but otherwise things work the same as in normal
\r
2130 games. The Zippy xboard accepts time odds games but ignores the fact
\r
2131 that the opponent's parameters are different; this is perhaps not
\r
2132 quite the right thing to do, but gnuchess doesn't understand time
\r
2133 odds. Time odds games are always unrated.
\r
2137 The command to set an exact number of seconds per move looks like this:
\r
2145 This means that each move must be made in at most 30 seconds. Time not used
\r
2146 on one move does not accumulate for use on later moves.
\r
2149 <h2><a name="12">12. Analyze Mode</a></h2>
\r
2151 <p>xboard supports analyzing fresh games, edited positions, and games
\r
2152 from files. However, all of these look the same from the chess
\r
2153 engine's perspective. Basically, the engine just has to respond to the
\r
2154 "analyze" command.
\r
2155 <span class="version1">
\r
2156 Beginning in protocol version 2,
\r
2157 if your engine does not support analyze mode, it should use
\r
2158 the feature command to set analyze=0.
\r
2160 The older method of
\r
2161 printing the error message "Error (unknown command): analyze" in
\r
2162 response to the "analyze" command will also work, however.
\r
2166 To enter analyze mode, xboard sends the command sequence "post", "analyze".
\r
2167 Analyze mode in your engine should be
\r
2168 similar to force mode, except that your engine thinks about what move
\r
2169 it would make next if it were on move. Your engine should accept the
\r
2170 following commands while in analyze mode:
\r
2174 <li>Any legal move, as in force mode</li>
\r
2175 <li><strong>undo</strong> Back up one move and analyze previous position.</li>
\r
2176 <li><strong>new</strong> Reset position to start of game but stay in analyze mode.</li>
\r
2177 <li><span class="version1"><strong>setboard</strong> if you have set feature setboard=1; otherwise <strong>edit</strong>. Exiting edit mode returns to analyze mode.</span></li>
\r
2178 <li><strong>exit</strong> Leave analyze mode.</li>
\r
2179 <li><strong>.</strong> Send a search status update (optional); see below.</li>
\r
2180 <li><span class="version1">
\r
2181 <strong>bk</strong> Show book moves from this position,
\r
2182 if any; see above.</span></li>
\r
2183 <li><span class="version1">
\r
2184 <strong>hint</strong> Show the predicted move from this
\r
2185 position, if any; see above.</span></li>
\r
2189 If the user selects "Periodic Updates", xboard will send the string
\r
2190 ".\n" to the chess engine periodically during analyze mode, unless the
\r
2191 last PV received began with a '(' character.
\r
2195 The chess engine should respond to ".\n" with a line like this:
\r
2199 stat01: time nodes ply mvleft mvtot <span class="version1">mvname</span>
\r
2204 <tr><td>time</td><td>Elapsed search time in centiseconds (ie: 567 = 5.67 seconds).</td></tr>
\r
2205 <tr><td>nodes</td><td>Nodes searched so far.</td></tr>
\r
2206 <tr><td>ply</td><td>Search depth so far.</td></tr>
\r
2207 <tr><td>mvleft</td><td>Number of moves left to consider at this depth.</td></tr>
\r
2208 <tr><td>mvtot</td><td>Total number of moves to consider.</td></tr>
\r
2209 <tr class="version1"><td>mvname</td><td>Move currently being considered (SAN or coordinate notation). Optional;
\r
2210 added in protocol version 2.</td></tr>
\r
2217 stat01: 1234 30000 7 5 30
\r
2218 stat01: 1234 30000 7 5 30 Nf3
\r
2225 <p>After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a
\r
2226 total of 30 legal moves, and I have 5 more moves to search
\r
2227 before going to depth 8. In the second example, of the 30 legal
\r
2228 moves, the one I am currently searching is Nf3.</p>
\r
2231 Implementation of the "." command is optional. If the engine does not
\r
2232 respond to the "." command with a "stat01..." line, xboard will stop
\r
2233 sending "." commands. If the engine does not implement this command,
\r
2234 the analysis window will use a shortened format to display the engine
\r
2239 To give the user some extra information, the chess engine can output
\r
2240 the strings "++\n" and "--\n", to indicate that the current search is
\r
2241 failing high or low, respectively. You don't have to send anything
\r
2242 else to say "Okay, I'm not failing high/low anymore." xboard will
\r
2243 figure this out itself.
\r
2246 <h2><a name="13">13. Idioms and backward compatibility features</a></h2>
\r
2249 Some engines have variant interpretations of the force/go/white/black,
\r
2250 time/otim, and hard/easy command sets.
\r
2251 In order to accommodate these older engines, xboard uses these commands
\r
2252 only according to the stylized patterns ("idioms") given in this section.
\r
2253 The obsolete white and black commands
\r
2254 have historically been particularly troublesome, and it is recommended
\r
2255 that new engines set the feature colors=0 and/or ignore the commands.
\r
2263 <dd>Sent when the opponent makes a move and the engine is already
\r
2264 playing the opposite color.
\r
2268 <dd>Sent when the engine is in force mode or playing Black but should
\r
2269 switch to playing White. This sequence is sent only when White is
\r
2271 <span class="version1">
\r
2272 If you set the feature colors=0, "white" is not sent.
\r
2278 <dd>Sent when the engine is in force mode or playing White but should
\r
2279 switch to playing Black. This sequence is sent only when Black is
\r
2281 <span class="version1">
\r
2282 If you set the feature colors=0, "black" is not sent.
\r
2291 <dd>Sent when Black is on move, the engine is in force mode or playing
\r
2292 White, and the engine's clock needs to be updated before it starts
\r
2294 The initial "white" is a kludge to accommodate GNU Chess
\r
2295 4's variant interpretation of these commands.
\r
2296 <span class="version1">
\r
2297 If you set the feature colors=0, "white" and "black" are not sent.
\r
2306 <dd>Sent when White is on move, the engine is in force mode or playing
\r
2307 Black, and the engine's clock needs to be updated before it starts
\r
2308 playing. See previous idiom.
\r
2309 The initial "black" is a kludge to accommodate GNU Chess
\r
2310 4's variant interpretation of these commands.
\r
2311 <span class="version1">
\r
2312 If you set the feature colors=0, "black" and "white" are not sent.
\r
2318 <dd>Sent in sequence to turn off pondering if xboard is not sure
\r
2319 whether it is on. When xboard is sure, it will send "hard" or "easy"
\r
2320 alone. xboard does this because "easy" is a toggle in GNU Chess 4 but
\r
2321 "hard" is an absolute on.
\r
2326 To support older engines, certain additional commands from the engine
\r
2327 to xboard are also recognized. (These are commands by themselves, not
\r
2328 values to be placed in the comment field of the PGN result code.)
\r
2329 These forms are not recommended for new engines; use the PGN result
\r
2330 code commands or the resign command instead.
\r
2334 <tr><th>Command</th> <th>Interpreted as</th></tr>
\r
2335 <tr><td>White resigns </td><td>0-1 {White resigns}</td></tr>
\r
2336 <tr><td>Black resigns </td><td>1-0 {Black resigns}</td></tr>
\r
2337 <tr><td>White </td><td>1-0 {White mates}</td></tr>
\r
2338 <tr><td>Black </td><td>0-1 {Black mates}</td></tr>
\r
2339 <tr><td>Draw </td><td>1/2-1/2 {Draw}</td></tr>
\r
2340 <tr><td>computer mates </td><td>1-0 {White mates} or 0-1 {Black mates}</td></tr>
\r
2341 <tr><td>opponent mates </td><td>1-0 {White mates} or 0-1 {Black mates}</td></tr>
\r
2342 <tr><td>computer resigns </td><td>0-1 {White resigns} or 1-0 {Black resigns}</td></tr>
\r
2343 <tr><td>game is a draw </td><td>1/2-1/2 {Draw}</td></tr>
\r
2344 <tr><td>checkmate </td><td>1-0 {White mates} or 0-1 {Black mates}</td></tr>
\r
2348 Commands in the above table are recognized if they begin a line and
\r
2349 arbitrary characters follow, so (for example) "White mates" will be
\r
2350 recognized as "White", and "game is a draw by the 50 move rule" will
\r
2351 be recognized as "game is a draw". All the commands are
\r
2356 An alternative move syntax is also recognized:
\r
2360 <tr><th>Command </th><th>Interpreted as</th></tr>
\r
2361 <tr><td>NUMBER ... MOVE </td><td>move MOVE</td></tr>
\r
2365 Here NUMBER means any string of decimal digits, optionally ending in a
\r
2366 period. MOVE is any string containing no whitespace. In this command
\r
2367 format, xboard requires the "..." even if your engine is playing
\r
2368 White. A command of the form NUMBER MOVE will be ignored. This odd
\r
2369 treatment of the commands is needed for compatibility with gnuchessx.
\r
2370 The original reasons for it are lost in the mists of time, but I
\r
2371 suspect it was originally a bug in the earliest versions of xboard,
\r
2372 before I started working on it, which someone "fixed" in the wrong
\r
2373 way, by creating a special version of gnuchess (gnuchessx) instead of
\r
2378 Any line that contains the words "offer" and "draw" is recognized as
\r
2383 The "Illegal move" message is recognized even if spelled "illegal
\r
2384 move" and even if the colon (":") is omitted. This accommodates GNU
\r
2385 Chess 4, which prints messages like "Illegal move (no matching
\r
2386 move)e2e4", and old versions of Crafty, which print just "illegal move".
\r
2390 In Zippy mode, for compatibility with older versions of Crafty,
\r
2391 xboard passes through to ICS any line that begins "kibitz", "whisper",
\r
2392 "tell", or "draw". Do not use this feature in new code. Instead, use the
\r
2393 commands "tellall", "tellothers", "tellopponent", "tellics" (if needed),
\r
2394 "1/2-1/2 {COMMENT}", or "offer draw", as appropriate.
\r
2397 <p class="version1">
\r
2398 If the engine responds to the "sd DEPTH" command with an error message
\r
2399 indicating the command is not supported (such as "Illegal move: sd"),
\r
2400 xboard sets an internal flag and subsequently uses the command
\r
2401 "depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the
\r
2402 newline in the middle of this command! New engines should not rely on
\r
2406 <p class="version1">
\r
2407 If the engine responds to the "st TIME" command with an error message
\r
2408 indicating the command is not supported (such as "Illegal move: st"),
\r
2409 xboard sets an internal flag and subsequently uses the command "level
\r
2410 1 TIME" instead, for the benefit of GNU Chess 4. Note that this is
\r
2411 not a standard use of the level command, as TIME seconds are not added
\r
2412 after each player makes 1 move; rather, each move is made in at most
\r
2413 TIME seconds. New engines should not implement or rely on this
\r
2417 <div class="version1">
\r
2419 In support of the -firstHost/-secondHost features, which allow a chess
\r
2420 engine to be run on another machine using the rsh protocol, xboard recognizes
\r
2421 error messages that are likely to come from rsh as fatal errors. The following
\r
2422 messages are currently recognized:
\r
2426 <li>unknown host</li>
\r
2427 <li>No remote directory</li>
\r
2428 <li>not found</li>
\r
2429 <li>No such file</li>
\r
2430 <li>can't alloc</li>
\r
2431 <li>Permission denied</li>
\r
2435 <p class="version1">
\r
2436 ChessBase/Fritz now implements the xboard/winboard protocol and can use
\r
2437 WinBoard-compatible engines in its GUI. ChessBase's version of the
\r
2438 protocol is generally the same as version 1, except that they have
\r
2439 added the commands <strong>fritz</strong>, <strong>reset</strong>, and
\r
2440 <strong>ponder</strong>, and the edit subcommands
\r
2441 <strong>castle</strong> and <strong>ep</strong>. If you want your
\r
2442 engine to work well with the ChessBase/Fritz GUI, you may need to
\r
2443 implement these additional commands, and you should also be aware of
\r
2444 the peculiar way that ChessBase uses the protocol. See their <a
\r
2445 href="http://www.chessbase.com/Products/engines/winboard/tech.htm"
\r
2446 >web page</a> for documentation.
\r
2449 <p class="version1">
\r
2450 ChessMaster 8000 also implements version 1 of the xboard/winboard
\r
2451 protocol and can use WinBoard-compatible engines. The original
\r
2452 release of CM8000 also has one additional restriction: only pure
\r
2453 coordinate notation (e.g., e2e4) is accepted in the move command. A
\r
2454 patch to correct this should be available from The Learning Company
\r
2455 (makers of CM8000) in February 2001.
\r
projects / xboard.git / blob