-$Id$
-Version 2; implemented in xboard/WinBoard 4.2.1 and later.
-Changes since version 1 are indicated in red.
-
-This document is a set of rough notes on the protocol that xboard and -WinBoard use to communicate with gnuchessx and other chess engines. -These notes may be useful if you want to connect a different chess -engine to xboard. Throughout the notes, "xboard" means both xboard -and WinBoard except where they are specifically contrasted. -
- --There are two reasons I can imagine someone wanting to do this: -
--In case (2), if you are using xboard, you will need to configure the -"Zippy" code into it, but WinBoard includes this code already. See -the file zippy.README -in the xboard or WinBoard distribution for more information. - -
- --These notes are unpolished, but I've attempted to make them complete -in this release. If you notice any errors, omissions, or misleading -statements, let me know. -
- --I'd like to hear from everyone who is trying to interface their own -chess engine to xboard/WinBoard. Please email me, -tim@tim-mann.org. Also, please join -the mailing list for authors of xboard/WinBoard compatible chess -engines. The list is now hosted by Yahoo Groups; you can join at http://www.egroups.com/group/chess-engines, or you can read the -list there without joining. The list is filtered to prevent spam. -
- --An xboard chess engine runs as a separate process from xboard itself, -connected to xboard through a pair of anonymous pipes. The engine -does not have to do anything special to set up these pipes. xboard -sets up the pipes itself and starts the engine with one pipe as its -standard input and the other as its standard output. The engine then -reads commands from its standard input and writes responses to its -standard output. This is, unfortunately, a little more complicated to -do right than it sounds; see section 6 below. -
- --And yes, contrary to some people's expectations, exactly the same -thing is true for WinBoard. Pipes and standard input/output are -implemented in Win32 and work fine. You don't have to use DDE, COM, -DLLs, BSOD, or any of the other infinite complexity that -Microsoft has created just to talk between two programs. A WinBoard -chess engine is a Win32 console program that simply reads from its -standard input and writes to its standard output. See sections -5 and 6 below for additional details. -
- --To diagnose problems in your engine's interaction with xboard, use the --debug flag on xboard's command line to see the messages that are -being exchanged. In WinBoard, these messages are written to the file -WinBoard.debug instead of going to the screen. -
- --You can turn debug mode on or off while WinBoard is running by -pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard -is running by binding DebugProc to a shortcut key (and pressing the -key!); see the instructions on shortcut keys in the xboard man page. -
- --While your engine is running under xboard/WinBoard, you can send a -command directly to the engine by pressing Shift+1 (xboard) or Alt+1 -(WinBoard 4.0.3 and later). This brings up a dialog that you can type -your command into. Press Shift+2 (Alt+2) instead to send to the -second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier, -Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict -with typing the @-sign on some European keyboards. -
- --Originally, xboard was just trying to talk to the existing -command-line interface of GNU Chess 3.1+ and 4, which was designed -for people to type commands to. So the communication protocol is very -ad-hoc. It might have been good to redesign it early on, but because -xboard and GNU Chess are separate programs, I didn't want to force -people to upgrade them together to versions that matched. I -particularly wanted to keep new versions of xboard working with old -versions of GNU Chess, to make it easier to compare the play of old -and new gnuchess versions. I didn't foresee the need for a clean -protocol to be used with other chess engines in the future. -
- --Circumstances have changed over the years, and now there are many more -engines that work with xboard. I've had to make the protocol -description more precise, I've added some features that GNU Chess -does not support, and I've specified the standard semantics of a few -features to be slightly different from what GNU Chess 4 does. -
- -
-
-This release of the protocol specification is the first to carry a
-version number of its own -- version 2. Previous releases simply
-carried a last-modified date and were loosely tied to specific
-releases of xboard and WinBoard. The version number "1" applies
-generally to all those older versions of the protocol.
-
-
-
- Protocol version 2 remains compatible with older engines but has
-several new capabilities. In particular, it adds the
-"feature" command, a new mechanism for making backward-compatible
-changes and extensions to the protocol. Engines that do not support a
-particular new feature do not have to use it; new features are not
-enabled unless the engine specifically requests them using the feature
-command. If an engine does not send the feature command at all, the
-protocol behavior is nearly identical to version 1. Several new
-features can be selected by the feature command in version 2,
-including the "ping" command (recommended for all engines), the
-"setboard" command, and many optional parameters. Additional features
-will probably be added in future versions.
-
-Due to some Microsoft brain damage that I don't understand, WinBoard -does not work with chess engines that were compiled to use a DOS -extender for 32-bit addressing. (Probably not with 16-bit DOS or -Windows programs either.) WinBoard works only with engines that are -compiled for the Win32 API. You can get a free compiler that targets -the Win32 API from http://sources.redhat.com/cygwin/. I think DJGPP 2.x should also -work if you use the RSXNTDJ extension, but I haven't tried it. Of -course, Microsoft Visual C++ will work. Most likely the other -commercial products that support Win32 will work too (Borland, etc.), -but I have not tried them. Delphi has been successfully used to write -engines for WinBoard; if you want to do this, Tony Werten has donated -some sample -code that should help you get started. -
- --Beware of using buffered I/O in your chess engine. The C stdio -library, C++ streams, and the I/O packages in most other languages use -buffering both on input and output. That means two things. First, -when your engine tries to write some characters to xboard, the library -stashes them in an internal buffer and does not actually write them to -the pipe connected to xboard until either the buffer fills up or you -call a special library routine asking for it to be flushed. (In C -stdio, this routine is named fflush.) Second, when your engine tries -to read some characters from xboard, the library does not read just -the characters you asked for -- it reads all the characters that are -currently available (up to some limit) and stashes any characters you -are not yet ready for in an internal buffer. The next time you ask to -read, you get the characters from the buffer (if any) before the -library tries to read more data from the actual pipe. -
- --Why does this cause problems? First, on the output side, remember -that your engine produces output in small quantities (say, a few -characters for a move, or a line or two giving the current analysis), -and that data always needs to be delivered to xboard/WinBoard for -display immediately. If you use buffered output, the data you print -will sit in a buffer in your own address space instead of being -delivered. -
- --You can usually fix the output buffering problem by asking for the -buffering to be turned off. In C stdio, you do this by calling -setbuf(stdout, NULL). A more laborious and error-prone -method is to carefully call fflush(stdout) after every line -you output; I don't recommend this. In C++, you can try -cout.setf(ios::unitbuf), which is documented in current -editions of "The C++ Programming Language," but not older ones. -Another C++ method that might work is -cout.rdbuf()->setbuf(NULL, 0). Alternatively, you can -carefully call cout.flush() after every line you output; -again, I don't recommend this. -
- --Another way to fix the problem is to use unbuffered operating system -calls to write directly to the file descriptor for standard output. -On Unix, this means write(1, ...) -- see the man page for write(2). -On Win32, you can use either the Unix-like _write(1, ...) or Win32 -native routines like WriteFile. -
- --Second, on the input side, you are likely to want to poll during your -search and stop it if new input has come in. If you implement -pondering, you'll need this so that pondering stops when the user -makes a move. You should also poll during normal thinking on your -move, so that you can implement the "?" (move now) command, and so -that you can respond promptly to a "result", "force", or "quit" -command if xboard wants to end the game or terminate your engine. -Buffered input makes polling more complicated -- when you poll, you -must stop your search if there are either characters in the buffer -or characters available from the underlying file descriptor. -
- --The most direct way to fix this problem is to use unbuffered operating -system calls to read (and poll) the underlying file descriptor -directly. On Unix, use read(0, ...) to read from standard input, and -use select() to poll it. See the man pages read(2) and select(2). -(Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to -poll for input. It is not very portable; that is, it does not exist -on all versions of Unix, and is broken on some that do have it.) On -Win32, you can use either the Unix-like _read(0, ...) or the native -Win32 ReadFile() to read. Unfortunately, under Win32, the function to -use for polling is different depending on whether the input device is -a pipe, a console, or something else. (More Microsoft brain damage -here -- did they never hear of device independence?) For pipes, you -can use PeekNamedPipe to poll (even when the pipe is unnamed). -For consoles, -you can use GetNumberOfConsoleInputEvents. For sockets only, you can -use select(). It might be possible to use -WaitForSingleObject more -generally, but I have not tried it. Some code to do these things can -be found in Crafty's utility.c, but I don't guarantee that it's all -correct or optimal. -
- --A second way to fix the problem might be to ask your I/O library not -to buffer on input. It should then be safe to poll the underlying -file descriptor as described above. With C, you can try calling -setbuf(stdin, NULL). However, I have never tried this. Also, there -could be problems if you use scanf(), at least with certain patterns, -because scanf() sometimes needs to read one extra character and "push -it back" into the buffer; hence, there is a one-character pushback -buffer even if you asked for stdio to be unbuffered. With C++, you -can try cin.rdbuf()->setbuf(NULL, 0), but again, I have never tried -this. -
- --A third way to fix the problem is to check whether there are -characters in the buffer whenever you poll. C I/O libraries generally -do not provide any portable way to do this. Under C++, you can use -cin.rdbuf()->in_avail(). This method has been reported to -work with -EXchess. Remember that if there are no characters in the buffer, you -still have to poll the underlying file descriptor too, using the -method described above. -
- --A fourth way to fix the problem is to use a separate thread to read -from stdin. This way works well if you are familiar with thread -programming. This thread can be blocked waiting for input to come in -at all times, while the main thread of your engine does its thinking. -When input arrives, you have the thread put the input into a buffer -and set a flag in a global variable. Your search routine then -periodically tests the global variable to see if there is input to -process, and stops if there is. WinBoard and my Win32 ports of ICC -timestamp and FICS timeseal use threads to handle multiple input -sources. -
- -Engines that run on Unix need to be concerned with two Unix -signals: SIGTERM and SIGINT. This applies both to -engines that run under xboard and (the unusual case of) engines that -WinBoard remotely runs on a Unix host using the -firstHost or --secondHost feature. It does not apply to engines that run on -Windows, because Windows does not have Unix-style signals. - -Beginning with version 2, you can now turn off the use of -either or both -signals. See the "feature" command in section 9 below. - -
- -First, when an engine is sent the "quit" command, it is also given -a SIGTERM signal shortly afterward to make sure it goes away. -If your engine reliably responds to "quit", and the signal causes -problems for you, you should either ignore it by calling -signal(SIGTERM, SIG_IGN) at the start of your program, -or disable it with the "feature" command.
- -Second, xboard will send an interrupt signal (SIGINT) at -certain times when it believes the engine may not be listening to user -input (thinking or pondering). WinBoard currently does this only when -the engine is running remotely using the -firstHost or -secondHost -feature, not when it is running locally. You probably need to know -only enough about this grungy feature to keep it from getting in your -way. -
- --The SIGINTs are basically tailored to the needs of GNU Chess 4 -on systems where its input polling code is broken or disabled. -Because they work in a rather peculiar way, it is recommended that you -either ignore SIGINT by having your engine call -signal(SIGINT, SIG_IGN), or disable it with the "feature" -command.
- --Here are details for the curious. If xboard needs to send a command -when it is the chess engine's move (such as before the "?" command), -it sends a SIGINT first. If xboard needs to send commands when it is -not the chess engine's move, but the chess engine may be pondering -(thinking on its opponent's time) or analyzing (analysis or analyze -file mode), xboard sends a SIGINT before the first such command only. -Another SIGINT is not sent until another move is made, even if xboard -issues more commands. This behavior is necessary for GNU Chess 4. The -first SIGINT stops it from pondering until the next move, but on some -systems, GNU Chess 4 will die if it receives a SIGINT when not -actually thinking or pondering. -
- --There are two reasons why WinBoard does not send the Win32 equivalent -of SIGINT (which is called CTRL_C_EVENT) to local -engines. First, the Win32 GNU Chess 4 port does not need it. Second, I -could not find a way to get it to work. Win32 seems to be designed -under the assumption that only console applications, not windowed -applications, would ever want to send a CTRL_C_EVENT. -
- --All commands from xboard to the engine end with a newline (\n), even -where that is not explicitly stated. All your output to xboard must -be in complete lines; any form of prompt or partial line will cause -problems. -
- --At the beginning of each game, xboard sends an initialization string. -This is currently "new\nrandom\n" unless the user changes it with the -initString or secondInitString option. -
- --xboard normally reuses the same chess engine process for multiple -games. At the end of a game, xboard will send the "force" command -(see below) to make sure your engine stops thinking about the current -position. It will later send the initString again to start a new -game. If your engine can't play multiple games, you can disable reuse - -either with the "feature" command (beginning in protocol version -2; see below) or - -with xboard's -xreuse (or -xreuse2) command line -option. xboard will then ask the process to quit after each game and -start a new process for the next game. -
- -- -
Your engine should reply to the protover command by sending the -"feature" command (see below) with the list of non-default feature -settings that you require, if any. - -
Your engine should never refuse to run due to receiving a higher -protocol version number than it is expecting! New protocol versions -will always be compatible with older ones by default; the larger -version number is simply a hint that additional "feature" command -options added in later protocol versions may be accepted. -
-- -
- -
- -
| wildcastle | Shuffle chess where king can castle from d file - |
|---|---|
| nocastle | Shuffle chess with no castling at all - |
| fischerandom | Fischer Random (not supported yet) - |
| bughouse | Bughouse, ICC/FICS rules - |
| crazyhouse | Crazyhouse, ICC/FICS rules - |
| losers | Win by losing all pieces or getting mated (ICC) - |
| suicide | Win by losing all pieces including king, -or by having fewer pieces when one player has no legal moves (FICS) - |
| giveaway - | Win by losing all pieces including king, -or by having no legal moves (ICC) - |
| twokings | Weird ICC wild 9 - |
| kriegspiel | Kriegspiel (engines not supported) - |
| atomic | Atomic - |
| 3check | Win by giving check 3 times - |
| unknown | Unknown variant (not supported) - |
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
-If needed for purposes of board display in force mode (where the -engine is not participating in the game) the time clock should be -associated with the last color that the engine was set to play, the -otim clock with the opposite color. -
- -- -Beginning in protocol version 2, if you can't handle the time and -otim commands, you can use the "feature" command to disable them; see -below. - -The following techniques from older protocol versions also -work: You can ignore the time and otim commands (that is, treat them -as no-ops), or send back "Error (unknown command): time" the first -time you see "time". -
- --When xboard sends your engine a move, it normally sends coordinate -algebraic notation. Examples: -
-
| Normal moves: | e2e4 - |
| Pawn promotion: | e7e8q - |
| Castling: | e1g1, e1c1, e8g8, e8c8 - |
| Bughouse/crazyhouse drop: | P@h3 - |
| ICS Wild 0/1 castling: | d1f1, d1b1, d8f8, d8b8 - |
| FischerRandom castling: | O-O, O-O-O (oh, not zero) - |
- -Beginning in protocol version 2, you can use the feature command -to select SAN (standard algebraic notation) instead; for example, e4, -Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form, -P@h3, is a extension to the PGN standard's definition of SAN, which does -not support bughouse or crazyhouse. - -
- --xboard doesn't reliably detect illegal moves, because it does not keep -track of castling unavailability due to king or rook moves, or en -passant availability. If xboard sends an illegal move, send back an -error message so that xboard can retract it and inform the user; see -the section "Commands from the engine to xboard". -
- --It is also permissible for your engine to move immediately if it gets -any command while thinking, as long as it processes the command right -after moving, but it's preferable if you don't do this. For example, -xboard may send post, nopost, easy, hard, force, quit, - -or other commands - -while the engine is on move. -
- --The ping command is new in protocol version 2 and will not be sent -unless you enable it with the "feature" command. Its purpose is to -allow several race conditions that could occur in previous versions of -the protocol to be fixed, so it is highly recommended that you -implement it. It is especially important in simple engines that do -not ponder and do not poll for input while thinking, but it is needed in all -engines. -
- - -- -
result 1-0 {White mates}
--Here are some notes on interpreting the "result" command. Some apply -only to playing on ICS ("Zippy" mode). -
- --If you won but did not just play a mate, your opponent must have -resigned or forfeited. If you lost but were not just mated, you -probably forfeited on time, or perhaps the operator resigned manually. -If there was a draw for some nonobvious reason, perhaps your opponent -called your flag when he had insufficient mating material (or vice -versa), or perhaps the operator agreed to a draw manually. -
- --You will get a result command even if you already know the game ended --- for example, after you just checkmated your opponent. In fact, if -you send the "RESULT {COMMENT}" command (discussed below), you will -simply get the same thing fed back to you with "result" tacked in -front. You might not always get a "result *" command, however. In -particular, you won't get one in local chess engine mode when the user -stops playing by selecting Reset, Edit Game, Exit or the like. -
- -Illegal positions: Note that either setboard or edit can -be used to send an illegal position to the engine. The user can -create any position with xboard's Edit Position command (even, say, -an empty board, or a board with 64 white kings and no black ones). -If your engine receives a position that it considers illegal, -I suggest that you send the response "tellusererror Illegal position", -and then respond to any attempted move with "Illegal move" until -the next new, edit, or setboard command.
- -- -
| c | change current piece color, initially white - |
|---|---|
| Pa4 (for example) | place pawn of current color on a4 - |
| xa4 (for example) | empty the square a4 (not used by xboard) - |
| # | clear board - |
| . | leave edit mode - |
The edit command does not change the side to move. To set up a -black-on-move position, xboard uses the following command sequence: -
-- new - force - a2a3 - edit - <edit commands> - . -- -
-This sequence is used to avoid the "black" command, which is now -considered obsolete and which many engines never did implement as -specified in this document. -
- --After an edit command is complete, if a king and a rook are on their -home squares, castling is assumed to be available to them. En passant -capture is assumed to be illegal on the current move regardless of the -positions of the pawns. The clock for the 50 move rule starts at -zero, and for purposes of the draw by repetition rule, no prior -positions are deemed to have occurred. -
- -- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
rating 2600 1500-
- -
- -
- -
-xboard now supports bughouse engines when in Zippy mode. See -zippy.README for information on Zippy mode and how to turn on the -bughouse support. The bughouse move format is given above. xboard -sends the following additional commands to the engine when in bughouse -mode. -Commands to inform your engine of the partner's game state may -be added in the future. -
- -partner mann-
- -
- -
- -
holding [PPPRQ] []- -
holding [PPPRQ] [R] BR-
- -In general, an engine should not send any output to xboard that is not -described in this document. As the protocol is extended, newer -versions of xboard may recognize additional strings as commands that -were previously not assigned a meaning. - -
- --Your engine should send one or more feature commands immediately after -receiving the "protover" command, since xboard needs to know the -values of some features before sending further commands to the engine. -Because engines that predate protocol version 2 do not send "feature", -xboard uses a timeout mechanism: when it first starts your engine, it -sends "xboard" and "protover N", then listens for feature commands for -two seconds before sending any other commands. To end this timeout -and avoid the wait, set the feature "done=1" at the end of your last -feature command. To increase the timeout, if needed, set the feature -"done=0" before your first feature command and "done=1" at the end. -If needed, it is okay for your engine to set done=0 soon as it starts, -even before it receives the xboard and protover commands. This can be -useful if your engine takes a long time to initialize itself. It -should be harmless even if you are talking to a (version 1) user -interface that does not understand the "feature" command, since such -interfaces generally ignore commands from the engine that they do not -understand. -
- --The feature command is designed to let the protocol change without -breaking engines that were written for older protocol versions. When -a new feature is added to the protocol, its default value is always -chosen to be compatible with older versions of the protocol that did -not have the feature. Any feature that your engine does not set in a -"feature" command retains its default value, so as the protocol -changes, you do not have to change your engine to keep up with it -unless you want to take advantage of a new feature. Because some -features are improvements to the protocol, while others are meant to -cater to engines that do not implement all the protocol features, the -recommended setting for a feature is not always the same as the -default setting. The listing below gives both default and recommended -settings for most features. -
- --You may want to code your engine so as to be able to work with -multiple versions of the engine protocol. Protocol version 1 does not -send the protover command and does not implement the feature command; -if you send a feature command in protocol version 1, it will have no -effect and there will be no response. In protocol version 2 or later, -each feature F that you set generates the response "accepted F" if the -feature is implemented, or "rejected F" if it is not. Thus an engine -author can request any feature without having to keep track of which -protocol version it was introduced in; you need only check whether the -feature is accepted or rejected. This mechanism also makes it -possible for a user interface author to implement a subset of a -protocol version by rejecting some features that are defined in that -version; however, you should realize that engine authors are likely to -code for xboard and may not be prepared to have a feature that they -depend on be rejected. -
- --Here are the features that are currently defined. -
- - -- -
- Illegal move: e2e4 - Illegal move (in check): Nf3 - Illegal move (moving into check): e1g1 --
-Generally, xboard will never send an ambiguous move, so it does not -matter whether you respond to such a move with an Illegal move message -or an Error message. -
- -- Error (ambiguous move): Nf3 - Error (unknown command): analyze - Error (command not legal now): undo - Error (too many parameters): level 1 2 3 4 5 6 7 -- -
For the actual move text from your chess engine (in place of MOVE -above), your move should be either -
Warning: Even though all versions of this protocol specification -have indicated that xboard accepts SAN moves, some non-xboard -interfaces are known to accept only coordinate notation. See the -Idioms section for more information on the known limitations of some -non-xboard interfaces. It should be safe to send SAN moves if you -receive a "protover 2" (or later) command from the interface, but -otherwise it is best to stick to coordinate notation for maximum -compatibility. An even more conservative approach would be for your -engine to send SAN to the interface only if you have set feature san=1 -(which causes the interface to send SAN to you) and have received -"accepted san" in reply. -
- - -
- 0-1 {Black mates}
- 1-0 {White mates}
- 1/2-1/2 {Draw by repetition}
- 1/2-1/2 {Stalemate}
-
-
--xboard relays the result to the user, the ICS, the other engine in Two -Machines mode, and the PGN save file as required. -
- -- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
-If the user asks your engine to "show thinking", xboard sends your -engine the "post" command. It sends "nopost" to turn thinking off. -In post mode, your engine sends output lines to show the progress of -its thinking. The engine can send as many or few of these lines as it -wants to, whenever it wants to. Typically they would be sent when the -PV (principal variation) changes or the depth changes. The thinking -output should be in the following format: -
- -ply score time nodes pv- -Where: -
| ply | Integer giving current search depth. - |
|---|---|
| score | Integer giving current evaluation in centipawns. - |
| time | Current search time in centiseconds (ex: -1028 = 10.28 seconds). - - |
| nodes | Nodes searched. - |
| pv | Freeform text giving current "best" line. -You can continue the pv onto another line if you start each -continuation line with at least four space characters. - |
-Example: -
- -9 156 1084 48000 Nf3 Nc6 Nc3 Nf6- -
-Meaning: -
- -9 ply, score=1.56, time = 10.84 seconds, nodes=48000, -PV = "Nf3 Nc6 Nc3 Nf6" - --Longer example from actual Crafty output: -
-- 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6 - 4 116 23 2252 1. Nf3 Nc6 2. e4 e6 - 4 116 27 2589 1. Nf3 Nc6 2. e4 e6 - 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4 - 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4 -- -
-You can use the PV to show other things; for instance, while in book, -Crafty shows the observed frequency of different reply moves in its -book. In situations like this where your engine is not really -searching, start the PV with a '(' character: -
- -- 0 0 0 0 (e4 64%, d4 24%) -- -
-GNU Chess output is very slightly different. The ply number is -followed by an extra nonblank character, and the time is in seconds, -not hundredths of seconds. For compatibility, xboard accepts the -extra character and takes it as a flag indicating the different time -units. Example: -
- -- 2. 14 0 38 d1d2 e8e7 - 3+ 78 0 65 d1d2 e8e7 d2d3 - 3& 14 0 89 d1d2 e8e7 d2d3 - 3& 76 0 191 d1e2 e8e7 e2e3 - 3. 76 0 215 d1e2 e8e7 e2e3 - 4& 15 0 366 d1e2 e8e7 e2e3 e7e6 - 4. 15 0 515 d1e2 e8e7 e2e3 e7e6 - 5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4 - 5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4 - 5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4 - 6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 - 6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 - 7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 - 7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 - 8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5 - 8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5 - 9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4 - d4e4 - 9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4 - d4e4 -10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4 - d4e4 f7f5 e4f4 -10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4 - d4e4 f7f5 e4f4 -- -
If your engine is pondering (thinking on its opponent's time) in post -mode, it can show its thinking then too. In this case your engine may -omit the hint move (the move it is assuming its opponent will make) -from the thinking lines if and only if it sends xboard the move in -the usual "Hint: xxx" format before sending the first line. -
- --xboard supports three styles of time control: conventional chess clocks, -the ICS-style incremental clock, and an exact number of seconds per move. -
- -In conventional clock mode, every time control period is the same. -That is, if the time control is 40 moves in 5 minutes, then after each -side has made 40 moves, they each get an additional 5 minutes, and so -on, ad infinitum. At some future time it would be nice to support a -series of distinct time controls. This is very low on my personal -priority list, but code donations to the xboard project are accepted, -so feel free to take a swing at it. I suggest you talk to me first, -though. -
- --The command to set a conventional time control looks like this: -
- -- level 40 5 0 - level 40 0:30 0 -- -
-The 40 means that there are 40 moves per time control. The 5 means -there are 5 minutes in the control. In the second example, the 0:30 -means there are 30 seconds. The final 0 means that we are in -conventional clock mode. -
- --The command to set an incremental time control looks like this: -
- -- level 0 2 12 -- -
-Here the 0 means "play the whole game in this time control period", -the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As -in conventional clock mode, the second argument to level can be in -minutes and seconds. -
- --At the start of the game, each player's clock is set to base minutes. -Immediately after a player makes a move, inc seconds are added to his -clock. A player's clock counts down while it is his turn. Your flag -can be called whenever your clock is zero or negative. (Your clock -can go negative and then become positive again because of the -increment.) -
- --A special rule on some ICS implementations: if you ask for a game with -base=0, the clocks really start at 10 seconds instead of 0. xboard -itself does not know about this rule, so it passes the 0 on to the -engine instead of changing it to 0:10. -
- --ICS also has time odds games. With time odds, each player has his own -(base, inc) pair, but otherwise things work the same as in normal -games. The Zippy xboard accepts time odds games but ignores the fact -that the opponent's parameters are different; this is perhaps not -quite the right thing to do, but gnuchess doesn't understand time -odds. Time odds games are always unrated. -
- --The command to set an exact number of seconds per move looks like this: -
- -- st 30 -- -
-This means that each move must be made in at most 30 seconds. Time not used -on one move does not accumulate for use on later moves. -
- -xboard supports analyzing fresh games, edited positions, and games -from files. However, all of these look the same from the chess -engine's perspective. Basically, the engine just has to respond to the -"analyze" command. - -Beginning in protocol version 2, -if your engine does not support analyze mode, it should use -the feature command to set analyze=0. - -The older method of -printing the error message "Error (unknown command): analyze" in -response to the "analyze" command will also work, however. -
- --To enter analyze mode, xboard sends the command sequence "post", "analyze". -Analyze mode in your engine should be -similar to force mode, except that your engine thinks about what move -it would make next if it were on move. Your engine should accept the -following commands while in analyze mode: -
- --If the user selects "Periodic Updates", xboard will send the string -".\n" to the chess engine periodically during analyze mode, unless the -last PV received began with a '(' character. -
- --The chess engine should respond to ".\n" with a line like this: -
- --stat01: time nodes ply mvleft mvtot mvname -- -Where: -
| time | Elapsed search time in centiseconds (ie: 567 = 5.67 seconds). - |
|---|---|
| nodes | Nodes searched so far. - |
| ply | Search depth so far. - |
| mvleft | Number of moves left to consider at this depth. - |
| mvtot | Total number of moves to consider. - |
| mvname | -Move currently being considered (SAN or coordinate notation). Optional; -added in protocol version 2. - |
-Examples: -
-- stat01: 1234 30000 7 5 30 - stat01: 1234 30000 7 5 30 Nf3 -- -
-Meaning: -
- -After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a - total of 30 legal moves, and I have 5 more moves to search - before going to depth 8. In the second example, of the 30 legal - moves, the one I am currently searching is Nf3.
- --Implementation of the "." command is optional. If the engine does not -respond to the "." command with a "stat01..." line, xboard will stop -sending "." commands. If the engine does not implement this command, -the analysis window will use a shortened format to display the engine -info. -
- --To give the user some extra information, the chess engine can output -the strings "++\n" and "--\n", to indicate that the current search is -failing high or low, respectively. You don't have to send anything -else to say "Okay, I'm not failing high/low anymore." xboard will -figure this out itself. -
- --Some engines have variant interpretations of the force/go/white/black, -time/otim, and hard/easy command sets. -In order to accommodate these older engines, xboard uses these commands -only according to the stylized patterns ("idioms") given in this section. -The obsolete white and black commands -have historically been particularly troublesome, and it is recommended -that new engines set the feature colors=0 and/or ignore the commands. -
- -- -
- -
- -
- -
- -
-To support older engines, certain additional commands from the engine -to xboard are also recognized. (These are commands by themselves, not -values to be placed in the comment field of the PGN result code.) -These forms are not recommended for new engines; use the PGN result -code commands or the resign command instead. -
- -| Command | Interpreted as - |
|---|---|
| White resigns | 0-1 {White resigns} - |
| Black resigns | 1-0 {Black resigns} - |
| White | 1-0 {White mates} - |
| Black | 0-1 {Black mates} - |
| Draw | 1/2-1/2 {Draw} - |
| computer mates | 1-0 {White mates} or 0-1 {Black mates} - |
| opponent mates | 1-0 {White mates} or 0-1 {Black mates} - |
| computer resigns | 0-1 {White resigns} or 1-0 {Black resigns} - |
| game is a draw | 1/2-1/2 {Draw} - |
| checkmate | 1-0 {White mates} or 0-1 {Black mates} - |
-Commands in the above table are recognized if they begin a line and -arbitrary characters follow, so (for example) "White mates" will be -recognized as "White", and "game is a draw by the 50 move rule" will -be recognized as "game is a draw". All the commands are -case-sensitive. -
- --An alternative move syntax is also recognized: -
- -| Command | Interpreted as - |
|---|---|
| NUMBER ... MOVE | move MOVE - |
-Here NUMBER means any string of decimal digits, optionally ending in a -period. MOVE is any string containing no whitespace. In this command -format, xboard requires the "..." even if your engine is playing -White. A command of the form NUMBER MOVE will be ignored. This odd -treatment of the commands is needed for compatibility with gnuchessx. -The original reasons for it are lost in the mists of time, but I -suspect it was originally a bug in the earliest versions of xboard, -before I started working on it, which someone "fixed" in the wrong -way, by creating a special version of gnuchess (gnuchessx) instead of -changing xboard. -
- --Any line that contains the words "offer" and "draw" is recognized as -"offer draw". -
- --The "Illegal move" message is recognized even if spelled "illegal -move" and even if the colon (":") is omitted. This accommodates GNU -Chess 4, which prints messages like "Illegal move (no matching -move)e2e4", and old versions of Crafty, which print just "illegal move". -
- --In Zippy mode, for compatibility with older versions of Crafty, -xboard passes through to ICS any line that begins "kibitz", "whisper", -"tell", or "draw". Do not use this feature in new code. Instead, use the -commands "tellall", "tellothers", "tellopponent", "tellics" (if needed), -"1/2-1/2 {COMMENT}", or "offer draw", as appropriate. -
- -- -If the engine responds to the "sd DEPTH" command with an error message -indicating the command is not supported (such as "Illegal move: sd"), -xboard sets an internal flag and subsequently uses the command -"depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the -newline in the middle of this command! New engines should not rely on -this feature. - -
- -- -If the engine responds to the "st TIME" command with an error message -indicating the command is not supported (such as "Illegal move: st"), -xboard sets an internal flag and subsequently uses the command "level -1 TIME" instead, for the benefit of GNU Chess 4. Note that this is -not a standard use of the level command, as TIME seconds are not added -after each player makes 1 move; rather, each move is made in at most -TIME seconds. New engines should not implement or rely on this -feature. - -
- - --In support of the -firstHost/-secondHost features, which allow a chess -engine to be run on another machine using the rsh protocol, xboard recognizes -error messages that are likely to come from rsh as fatal errors. The following -messages are currently recognized: -
- --unknown host- - -
-No remote directory
-not found
-No such file
-can't alloc
-Permission denied
-
- -ChessBase/Fritz now implements the xboard/winboard protocol and can use -WinBoard-compatible engines in its GUI. ChessBase's version of the -protocol is generally the same as version 1, except that they have -added the commands fritz, reset, and -ponder, and the edit subcommands -castle and ep. If you want your -engine to work well with the ChessBase/Fritz GUI, you may need to -implement these additional commands, and you should also be aware of -the peculiar way that ChessBase uses the protocol. See their web page for documentation. - -
- -- -ChessMaster 8000 also implements version 1 of the xboard/winboard -protocol and can use WinBoard-compatible engines. The original -release of CM8000 also has one additional restriction: only pure -coordinate notation (e.g., e2e4) is accepted in the move command. A -patch to correct this should be available from The Learning Company -(makers of CM8000) in February 2001. - -
- -
+Version 2; implemented in xboard/WinBoard 4.2.1 and later. (Sept 3, 2009)
+Changes since version 1 are indicated in red.
+Changes for WinBoard 4.3.xx are indicated in green.
+Changes for WinBoard 4.4.xx are indicated in blue.
+
+This document is a set of rough notes on the protocol that xboard and +WinBoard use to communicate with gnuchessx and other chess engines. +These notes may be useful if you want to connect a different chess +engine to xboard. Throughout the notes, "xboard" means both xboard +and WinBoard except where they are specifically contrasted. +
+ ++There are two reasons I can imagine someone wanting to do this: +
++In case (2), if you are using xboard, you will need to configure the +"Zippy" code into it, but WinBoard includes this code already. See +the file zippy.README +in the xboard or WinBoard distribution for more information. + +
+ ++These notes are unpolished, but I've attempted to make them complete +in this release. If you notice any errors, omissions, or misleading +statements, let me know. +
+ ++I'd like to hear from everyone who is trying to interface their own +chess engine to xboard/WinBoard. Please join the mailing list for +authors of xboard/WinBoard compatible chess engines and post a message +about what you're doing. The list is now hosted by Yahoo Groups; you +can join at http://groups.yahoo.com/group/chess-engines, or you can read the +list there without joining. The list is filtered to prevent spam. +
++ +Note that the WinBoard 4.3.xx line was developed independently of the +original GNU project, by H.G.Muller. +If you have questions about WinBoard 4.3.xx, or want to report bugs in it, +report them in the appropriate section of the +WinBoard forum. + +
+ ++An xboard chess engine runs as a separate process from xboard itself, +connected to xboard through a pair of anonymous pipes. The engine +does not have to do anything special to set up these pipes. xboard +sets up the pipes itself and starts the engine with one pipe as its +standard input and the other as its standard output. The engine then +reads commands from its standard input and writes responses to its +standard output. This is, unfortunately, a little more complicated to +do right than it sounds; see section 6 below. +
+ ++And yes, contrary to some people's expectations, exactly the same +thing is true for WinBoard. Pipes and standard input/output are +implemented in Win32 and work fine. You don't have to use DDE, COM, +DLLs, BSOD, or any of the other infinite complexity that +Microsoft has created just to talk between two programs. A WinBoard +chess engine is a Win32 console program that simply reads from its +standard input and writes to its standard output. See sections +5 and 6 below for additional details. +
+ ++To diagnose problems in your engine's interaction with xboard, use the +-debug flag on xboard's command line to see the messages that are +being exchanged. In WinBoard, these messages are written to the file +WinBoard.debug instead of going to the screen. +
+ ++You can turn debug mode on or off while WinBoard is running by +pressing Ctrl+Alt+F12. You can turn debug mode on or off while xboard +is running by binding DebugProc to a shortcut key (and pressing the +key!); see the instructions on shortcut keys in the xboard man page. +
+ ++While your engine is running under xboard/WinBoard, you can send a +command directly to the engine by pressing Shift+1 (xboard) or Alt+1 +(WinBoard 4.0.3 and later). This brings up a dialog that you can type +your command into. Press Shift+2 (Alt+2) instead to send to the +second chess engine in Two Machines mode. On WinBoard 4.0.2 and earlier, +Ctrl+Alt is used in place of Alt; this had to be changed due to a conflict +with typing the @-sign on some European keyboards. +
+ ++Originally, xboard was just trying to talk to the existing +command-line interface of GNU Chess 3.1+ and 4, which was designed +for people to type commands to. So the communication protocol is very +ad-hoc. It might have been good to redesign it early on, but because +xboard and GNU Chess are separate programs, I didn't want to force +people to upgrade them together to versions that matched. I +particularly wanted to keep new versions of xboard working with old +versions of GNU Chess, to make it easier to compare the play of old +and new gnuchess versions. I didn't foresee the need for a clean +protocol to be used with other chess engines in the future. +
+ ++Circumstances have changed over the years, and now there are many more +engines that work with xboard. I've had to make the protocol +description more precise, I've added some features that GNU Chess +does not support, and I've specified the standard semantics of a few +features to be slightly different from what GNU Chess 4 does. +
+ +
+
+This release of the protocol specification is the first to carry a
+version number of its own -- version 2. Previous releases simply
+carried a last-modified date and were loosely tied to specific
+releases of xboard and WinBoard. The version number "1" applies
+generally to all those older versions of the protocol.
+
+
+
+ Protocol version 2 remains compatible with older engines but has
+several new capabilities. In particular, it adds the
+"feature" command, a new mechanism for making backward-compatible
+changes and extensions to the protocol. Engines that do not support a
+particular new feature do not have to use it; new features are not
+enabled unless the engine specifically requests them using the feature
+command. If an engine does not send the feature command at all, the
+protocol behavior is nearly identical to version 1. Several new
+features can be selected by the feature command in version 2,
+including the "ping" command (recommended for all engines), the
+"setboard" command, and many optional parameters. Additional features
+will probably be added in future versions.
+
+
+If it is necessary to have a separate name,
+it would be best to refer to the protocol including the green additions as version 2f.
+I really don't think it is a different protocol from version 2, though.
+I just tried to clarify some ambiguities in the original definition,
+now that the WinBoard 4.3.xx line has implemented them in a specific way.
+The hand-shaking protocol for features as defined in protocol 2 perfectly
+allows addition of an occasional new features without any need for stepping up the protocol version number,
+and I think refraining from the latter would enormously lower the barrier for actual
+implementation of these features in engines.
+
+The two really new things are the engine debug comments, and the "nps" command.
+The former merely tries to regulate an extremely common existing pactice
+of having engines dump debug messages on WinBoard in an unprotected way,
+as usually you get away with that.
+
+
+
+Due to some Microsoft brain damage that I don't understand, WinBoard +does not work with chess engines that were compiled to use a DOS +extender for 32-bit addressing. (Probably not with 16-bit DOS or +Windows programs either.) WinBoard works only with engines that are +compiled for the Win32 API. You can get a free compiler that targets +the Win32 API from http://sources.redhat.com/cygwin/. I think DJGPP 2.x should also +work if you use the RSXNTDJ extension, but I haven't tried it. Of +course, Microsoft Visual C++ will work. Most likely the other +commercial products that support Win32 will work too (Borland, etc.), +but I have not tried them. Delphi has been successfully used to write +engines for WinBoard; if you want to do this, Tony Werten has donated +some sample +code that should help you get started. +
+ ++Beware of using buffered I/O in your chess engine. The C stdio +library, C++ streams, and the I/O packages in most other languages use +buffering both on input and output. That means two things. First, +when your engine tries to write some characters to xboard, the library +stashes them in an internal buffer and does not actually write them to +the pipe connected to xboard until either the buffer fills up or you +call a special library routine asking for it to be flushed. (In C +stdio, this routine is named fflush.) Second, when your engine tries +to read some characters from xboard, the library does not read just +the characters you asked for -- it reads all the characters that are +currently available (up to some limit) and stashes any characters you +are not yet ready for in an internal buffer. The next time you ask to +read, you get the characters from the buffer (if any) before the +library tries to read more data from the actual pipe. +
+ ++Why does this cause problems? First, on the output side, remember +that your engine produces output in small quantities (say, a few +characters for a move, or a line or two giving the current analysis), +and that data always needs to be delivered to xboard/WinBoard for +display immediately. If you use buffered output, the data you print +will sit in a buffer in your own address space instead of being +delivered. +
+ ++You can usually fix the output buffering problem by asking for the +buffering to be turned off. In C stdio, you do this by calling +setbuf(stdout, NULL). A more laborious and error-prone +method is to carefully call fflush(stdout) after every line +you output; I don't recommend this. In C++, you can try +cout.setf(ios::unitbuf), which is documented in current +editions of "The C++ Programming Language," but not older ones. +Another C++ method that might work is +cout.rdbuf()->setbuf(NULL, 0). Alternatively, you can +carefully call cout.flush() after every line you output; +again, I don't recommend this. +
+ ++Another way to fix the problem is to use unbuffered operating system +calls to write directly to the file descriptor for standard output. +On Unix, this means write(1, ...) -- see the man page for write(2). +On Win32, you can use either the Unix-like _write(1, ...) or Win32 +native routines like WriteFile. +
+ ++Second, on the input side, you are likely to want to poll during your +search and stop it if new input has come in. If you implement +pondering, you'll need this so that pondering stops when the user +makes a move. You should also poll during normal thinking on your +move, so that you can implement the "?" (move now) command, and so +that you can respond promptly to a "result", "force", or "quit" +command if xboard wants to end the game or terminate your engine. +Buffered input makes polling more complicated -- when you poll, you +must stop your search if there are either characters in the buffer +or characters available from the underlying file descriptor. +
+ ++The most direct way to fix this problem is to use unbuffered operating +system calls to read (and poll) the underlying file descriptor +directly. On Unix, use read(0, ...) to read from standard input, and +use select() to poll it. See the man pages read(2) and select(2). +(Don't follow the example of GNU Chess 4 and use the FIONREAD ioctl to +poll for input. It is not very portable; that is, it does not exist +on all versions of Unix, and is broken on some that do have it.) On +Win32, you can use either the Unix-like _read(0, ...) or the native +Win32 ReadFile() to read. Unfortunately, under Win32, the function to +use for polling is different depending on whether the input device is +a pipe, a console, or something else. (More Microsoft brain damage +here -- did they never hear of device independence?) For pipes, you +can use PeekNamedPipe to poll (even when the pipe is unnamed). +For consoles, +you can use GetNumberOfConsoleInputEvents. For sockets only, you can +use select(). It might be possible to use +WaitForSingleObject more +generally, but I have not tried it. Some code to do these things can +be found in Crafty's utility.c, but I don't guarantee that it's all +correct or optimal. +
+ ++A second way to fix the problem might be to ask your I/O library not +to buffer on input. It should then be safe to poll the underlying +file descriptor as described above. With C, you can try calling +setbuf(stdin, NULL). However, I have never tried this. Also, there +could be problems if you use scanf(), at least with certain patterns, +because scanf() sometimes needs to read one extra character and "push +it back" into the buffer; hence, there is a one-character pushback +buffer even if you asked for stdio to be unbuffered. With C++, you +can try cin.rdbuf()->setbuf(NULL, 0), but again, I have never tried +this. +
+ ++A third way to fix the problem is to check whether there are +characters in the buffer whenever you poll. C I/O libraries generally +do not provide any portable way to do this. Under C++, you can use +cin.rdbuf()->in_avail(). This method has been reported to +work with +EXchess. Remember that if there are no characters in the buffer, you +still have to poll the underlying file descriptor too, using the +method described above. +
+ ++A fourth way to fix the problem is to use a separate thread to read +from stdin. This way works well if you are familiar with thread +programming. This thread can be blocked waiting for input to come in +at all times, while the main thread of your engine does its thinking. +When input arrives, you have the thread put the input into a buffer +and set a flag in a global variable. Your search routine then +periodically tests the global variable to see if there is input to +process, and stops if there is. WinBoard and my Win32 ports of ICC +timestamp and FICS timeseal use threads to handle multiple input +sources. +
+ +Engines that run on Unix need to be concerned with two Unix +signals: SIGTERM and SIGINT. This applies both to +engines that run under xboard and (the unusual case of) engines that +WinBoard remotely runs on a Unix host using the -firstHost or +-secondHost feature. It does not apply to engines that run on +Windows, because Windows does not have Unix-style signals. + +Beginning with version 2, you can now turn off the use of +either or both +signals. See the "feature" command in section 9 below. + +
+ +First, when an engine is sent the "quit" command, it is also given +a SIGTERM signal shortly afterward to make sure it goes away. +If your engine reliably responds to "quit", and the signal causes +problems for you, you should either ignore it by calling +signal(SIGTERM, SIG_IGN) at the start of your program, +or disable it with the "feature" command.
+ +Second, xboard will send an interrupt signal (SIGINT) at +certain times when it believes the engine may not be listening to user +input (thinking or pondering). WinBoard currently does this only when +the engine is running remotely using the -firstHost or -secondHost +feature, not when it is running locally. You probably need to know +only enough about this grungy feature to keep it from getting in your +way. +
+ ++The SIGINTs are basically tailored to the needs of GNU Chess 4 +on systems where its input polling code is broken or disabled. +Because they work in a rather peculiar way, it is recommended that you +either ignore SIGINT by having your engine call +signal(SIGINT, SIG_IGN), or disable it with the "feature" +command.
+ ++Here are details for the curious. If xboard needs to send a command +when it is the chess engine's move (such as before the "?" command), +it sends a SIGINT first. If xboard needs to send commands when it is +not the chess engine's move, but the chess engine may be pondering +(thinking on its opponent's time) or analyzing (analysis or analyze +file mode), xboard sends a SIGINT before the first such command only. +Another SIGINT is not sent until another move is made, even if xboard +issues more commands. This behavior is necessary for GNU Chess 4. The +first SIGINT stops it from pondering until the next move, but on some +systems, GNU Chess 4 will die if it receives a SIGINT when not +actually thinking or pondering. +
+ ++There are two reasons why WinBoard does not send the Win32 equivalent +of SIGINT (which is called CTRL_C_EVENT) to local +engines. First, the Win32 GNU Chess 4 port does not need it. Second, I +could not find a way to get it to work. Win32 seems to be designed +under the assumption that only console applications, not windowed +applications, would ever want to send a CTRL_C_EVENT. +
+ ++All commands from xboard to the engine end with a newline (\n), even +where that is not explicitly stated. All your output to xboard must +be in complete lines; any form of prompt or partial line will cause +problems. +
+ ++At the beginning of each game, xboard sends an initialization string. +This is currently "new\nrandom\n" unless the user changes it with the +initString or secondInitString option. +
+ ++xboard normally reuses the same chess engine process for multiple +games. At the end of a game, xboard will send the "force" command +(see below) to make sure your engine stops thinking about the current +position. It will later send the initString again to start a new +game. If your engine can't play multiple games, you can disable reuse + +either with the "feature" command (beginning in protocol version +2; see below) or + +with xboard's -xreuse (or -xreuse2) command line +option. xboard will then ask the process to quit after each game and +start a new process for the next game. +
+ ++ +
Your engine should reply to the protover command by sending the +"feature" command (see below) with the list of non-default feature +settings that you require, if any. + +
Your engine should never refuse to run due to receiving a higher +protocol version number than it is expecting! New protocol versions +will always be compatible with older ones by default; the larger +version number is simply a hint that additional "feature" command +options added in later protocol versions may be accepted. +
++ +
+ +
+ +
| wildcastle | Shuffle chess where king can castle from d file + |
|---|---|
| nocastle | Shuffle chess with no castling at all + |
| fischerandom | Fischer Random + |
| bughouse | Bughouse, ICC/FICS rules + |
| crazyhouse | Crazyhouse, ICC/FICS rules + |
| losers | Win by losing all pieces or getting mated (ICC) + |
| suicide | Win by losing all pieces including king, +or by having fewer pieces when one player has no legal moves (FICS) + |
| giveaway + | Win by losing all pieces including king, +or by having no legal moves (ICC) + |
| twokings | Weird ICC wild 9 + |
| kriegspiel | Kriegspiel (engines not supported) + |
| atomic | Atomic + |
| 3check | Win by giving check 3 times + |
| xiangqi + | Chinese Chess (9x10 board) + |
| shogi + | Japanese Chess (9x9 bord) + |
| capablanca + | Capablanca Chess (10x8 board, with Archbishop and Chancellor) + |
| gothic + | Gothic Chess (10x8 board, same with better opening setup) + |
| falcon + | Falcon Chess (10x8 board, with two Falcon pieces) + |
| shatranj + | ancient Arabic Chess, with Elephants and General in stead of B and Q + |
| courier + | Courier Chess (12x8 board, a medieval precursor of modern Chess + |
| knightmate + | King moves as Knight and vice versa + |
| berolina | +Pawns capture straight ahead, and move diagonally + |
| janus | +Janus Chess (10x8, with two Archbishops) + |
| caparandom + | shuffle variant like FRC (10x8 board) + |
| cylinder + | Pieces wrap around between side edges, like board is a cylinder + |
| super + | Superchess: a shuffle variant with 4 fairy pieces on 8x8 board + |
| great + | Great Shatranj: sliders are replaced by corresponding short-range pieces on a 10x8 board + |
| unknown | Unknown variant (not supported) + |
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+The "new" command should set the search depth back to unlimited. This +is already stated in the spec. The "level" command should not affect +the search depth. As it happens, xboard/WinBoard currently always +sends sd (if needed) right after level, but that isn't part of the +spec. +
+ +
+ +
+ +
+If needed for purposes of board display in force mode (where the +engine is not participating in the game) the time clock should be +associated with the last color that the engine was set to play, the +otim clock with the opposite color. +
++This business of "clocks remaining with the engine" is apparently so ambiguous +that many engines implement it wrong. +The clocks in fact always remain with the color. +Which clock reading is relayed with "time", and which by "otim", is determined by which side the engine plays. +Note that the way the clocks operate and receive extra time (in accordance with the selected time control) +is not affected in any way by which moves are made by the engine, which by the opponent, and which were forced. + +
++ +Beginning in protocol version 2, if you can't handle the time and +otim commands, you can use the "feature" command to disable them; see +below. + +The following techniques from older protocol versions also +work: You can ignore the time and otim commands (that is, treat them +as no-ops), or send back "Error (unknown command): time" the first +time you see "time". +
+ ++When xboard sends your engine a move, it normally sends coordinate +algebraic notation. Examples: +
+
| Normal moves: | e2e4 + |
| Pawn promotion: | e7e8q + |
| Castling: | e1g1, e1c1, e8g8, e8c8 + |
| Bughouse/crazyhouse drop: | P@h3 + |
| ICS Wild 0/1 castling: | d1f1, d1b1, d8f8, d8b8 + |
| FischerRandom castling: | O-O, O-O-O (oh, not zero) + |
+ +Note that on boards with more than 9 ranks, counting of the ranks starts at 0. + +
++ +Beginning in protocol version 2, you can use the feature command +to select SAN (standard algebraic notation) instead; for example, e4, +Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. Note that the last form, +P@h3, is a extension to the PGN standard's definition of SAN, which does +not support bughouse or crazyhouse. + +
+ ++xboard doesn't reliably detect illegal moves, because it does not keep +track of castling unavailability due to king or rook moves, or en +passant availability. If xboard sends an illegal move, send back an +error message so that xboard can retract it and inform the user; see +the section "Commands from the engine to xboard". +
+ ++It is also permissible for your engine to move immediately if it gets +any command while thinking, as long as it processes the command right +after moving, but it's preferable if you don't do this. For example, +xboard may send post, nopost, easy, hard, force, quit, + +or other commands + +while the engine is on move. +
+ ++The ping command is new in protocol version 2 and will not be sent +unless you enable it with the "feature" command. Its purpose is to +allow several race conditions that could occur in previous versions of +the protocol to be fixed, so it is highly recommended that you +implement it. It is especially important in simple engines that do +not ponder and do not poll for input while thinking, but it is needed in all +engines. +
+ + ++ +
result 1-0 {White mates}
++Here are some notes on interpreting the "result" command. Some apply +only to playing on ICS ("Zippy" mode). +
+ ++If you won but did not just play a mate, your opponent must have +resigned or forfeited. If you lost but were not just mated, you +probably forfeited on time, or perhaps the operator resigned manually. +If there was a draw for some nonobvious reason, perhaps your opponent +called your flag when he had insufficient mating material (or vice +versa), or perhaps the operator agreed to a draw manually. +
+ ++You will get a result command even if you already know the game ended +-- for example, after you just checkmated your opponent. In fact, if +you send the "RESULT {COMMENT}" command (discussed below), you will +simply get the same thing fed back to you with "result" tacked in +front. You might not always get a "result *" command, however. In +particular, you won't get one in local chess engine mode when the user +stops playing by selecting Reset, Edit Game, Exit or the like. +
+ +Illegal positions: Note that either setboard or edit can +be used to send an illegal position to the engine. The user can +create any position with xboard's Edit Position command (even, say, +an empty board, or a board with 64 white kings and no black ones). +If your engine receives a position that it considers illegal, +I suggest that you send the response "tellusererror Illegal position", +and then respond to any attempted move with "Illegal move" until +the next new, edit, or setboard command.
+ ++ +
| c | change current piece color, initially white + |
|---|---|
| Pa4 (for example) | place pawn of current color on a4 + |
| xa4 (for example) | empty the square a4 (not used by xboard) + |
| # | clear board + |
| . | leave edit mode + |
The edit command does not change the side to move. To set up a +black-on-move position, xboard uses the following command sequence: +
++ new + force + a2a3 + edit + <edit commands> + . ++ +
+This sequence is used to avoid the "black" command, which is now +considered obsolete and which many engines never did implement as +specified in this document. +
+ ++After an edit command is complete, if a king and a rook are on their +home squares, castling is assumed to be available to them. En passant +capture is assumed to be illegal on the current move regardless of the +positions of the pawns. The clock for the 50 move rule starts at +zero, and for purposes of the draw by repetition rule, no prior +positions are deemed to have occurred. + +In FRC or CRC, any rook and king put on the back rank should be considered to +have castling rights, even if it later becomes apparent that they cannot be both in the +initial position, because the position just set up is asymmetric. +It is upto WinBoard to find work-around in cases where this is not desired, +similar to the "black kludge" shown above, by setting up an earlier position, +and then do a move to destroy castling rights or create e.p. rights. +(Don't bet your life on it...) + +
+ ++ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
rating 2600 1500+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+xboard now supports bughouse engines when in Zippy mode. See +zippy.README for information on Zippy mode and how to turn on the +bughouse support. The bughouse move format is given above. xboard +sends the following additional commands to the engine when in bughouse +mode. +Commands to inform your engine of the partner's game state may +be added in the future. +
+ +partner mann+
+ +
+ +
+ +
holding [PPPRQ] []+ +
holding [PPPRQ] [R] BR+
+ +In general, an engine should not send any output to xboard that is not +described in this document. As the protocol is extended, newer +versions of xboard may recognize additional strings as commands that +were previously not assigned a meaning. + +
+ ++Your engine should send one or more feature commands immediately after +receiving the "protover" command, since xboard needs to know the +values of some features before sending further commands to the engine. +Because engines that predate protocol version 2 do not send "feature", +xboard uses a timeout mechanism: when it first starts your engine, it +sends "xboard" and "protover N", then listens for feature commands for +two seconds before sending any other commands. To end this timeout +and avoid the wait, set the feature "done=1" at the end of your last +feature command. To increase the timeout, if needed, set the feature +"done=0" before your first feature command and "done=1" at the end. +If needed, it is okay for your engine to set done=0 soon as it starts, +even before it receives the xboard and protover commands. This can be +useful if your engine takes a long time to initialize itself. It +should be harmless even if you are talking to a (version 1) user +interface that does not understand the "feature" command, since such +interfaces generally ignore commands from the engine that they do not +understand. +
+ ++The feature command is designed to let the protocol change without +breaking engines that were written for older protocol versions. When +a new feature is added to the protocol, its default value is always +chosen to be compatible with older versions of the protocol that did +not have the feature. Any feature that your engine does not set in a +"feature" command retains its default value, so as the protocol +changes, you do not have to change your engine to keep up with it +unless you want to take advantage of a new feature. Because some +features are improvements to the protocol, while others are meant to +cater to engines that do not implement all the protocol features, the +recommended setting for a feature is not always the same as the +default setting. The listing below gives both default and recommended +settings for most features. +
+ ++You may want to code your engine so as to be able to work with +multiple versions of the engine protocol. Protocol version 1 does not +send the protover command and does not implement the feature command; +if you send a feature command in protocol version 1, it will have no +effect and there will be no response. In protocol version 2 or later, +each feature F that you set generates the response "accepted F" if the +feature is implemented, or "rejected F" if it is not. Thus an engine +author can request any feature without having to keep track of which +protocol version it was introduced in; you need only check whether the +feature is accepted or rejected. This mechanism also makes it +possible for a user interface author to implement a subset of a +protocol version by rejecting some features that are defined in that +version; however, you should realize that engine authors are likely to +code for xboard and may not be prepared to have a feature that they +depend on be rejected. +If the GUI rejects an option feature because of the +syntax of the value, it should print the value string with the +"rejected" command, e.g. "rejected option nonsense" in response +to receiving feature option="nonsense". +
+ ++Here are the features that are currently defined. +
+ + ++ +
+ Illegal move: e2e4 + Illegal move (in check): Nf3 + Illegal move (moving into check): e1g1 ++
+Generally, xboard will never send an ambiguous move, so it does not +matter whether you respond to such a move with an Illegal move message +or an Error message. +
+ ++ Error (ambiguous move): Nf3 + Error (unknown command): analyze + Error (command not legal now): undo + Error (too many parameters): level 1 2 3 4 5 6 7 ++ +
For the actual move text from your chess engine (in place of MOVE +above), your move should be either +
Warning: Even though all versions of this protocol specification +have indicated that xboard accepts SAN moves, some non-xboard +interfaces are known to accept only coordinate notation. See the +Idioms section for more information on the known limitations of some +non-xboard interfaces. It should be safe to send SAN moves if you +receive a "protover 2" (or later) command from the interface, but +otherwise it is best to stick to coordinate notation for maximum +compatibility. An even more conservative approach would be for your +engine to send SAN to the interface only if you have set feature san=1 +(which causes the interface to send SAN to you) and have received +"accepted san" in reply. +
+ + +
+ 0-1 {Black mates}
+ 1-0 {White mates}
+ 1/2-1/2 {Draw by repetition}
+ 1/2-1/2 {Stalemate}
+
+
++xboard relays the result to the user, the ICS, the other engine in Two +Machines mode, and the PGN save file as required. +Note that "definitey over" above means that sending this command +will be taken by WinBoard as an unconditional refusal of the engine to play on, +which might cause you to forfeit if the game was in fact not over. +This command should thus not be used to offer draws, accept draws, +or make draw-by-rule claims that are not yet valid in the current position +(but will be after you move). +For offering and claiming such draws, "offer draw" should be used. +
+ +Note that (in accordance with FIDE rules) only KK, KNK, KBK and KBKB with all bishops on the +same color can be claimed as draws on the basis of insufficient mating material. +The end-games KNNK, KBKN, KNKN and KBKB with unlike bishops do have mate positions, +and cannot be claimed. +Complex draws based on locked Pawn chains will not be recognized as draws by most interfaces, +so do not claim in such positions, but just offer a draw or play on. + +
+ +Note to GUI programmers: RESULT commands that the engine sends immediately after its move +might be detected by the GUI only after the opponent has moved, because of communication +and scheduling delays, no matter how fast the engine sent it. +Any judgement of the validity of RESULT claims based on te "current" board position +will have to account for this uncertainty. + +
+ ++ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+If the user asks your engine to "show thinking", xboard sends your +engine the "post" command. It sends "nopost" to turn thinking off. +In post mode, your engine sends output lines to show the progress of +its thinking. The engine can send as many or few of these lines as it +wants to, whenever it wants to. Typically they would be sent when the +PV (principal variation) changes or the depth changes. The thinking +output should be in the following format: +
+ +ply score time nodes pv+ +Where: +
| ply | Integer giving current search depth. + |
|---|---|
| score | Integer giving current evaluation in centipawns. + |
| time | Current search time in centiseconds (ex: +1028 = 10.28 seconds). + + |
| nodes | Nodes searched. + |
| pv | Freeform text giving current "best" line. +You can continue the pv onto another line if you start each +continuation line with at least four space characters. + |
+Example: +
+ +9 156 1084 48000 Nf3 Nc6 Nc3 Nf6+ +
+Meaning: +
+ +9 ply, score=1.56, time = 10.84 seconds, nodes=48000, +PV = "Nf3 Nc6 Nc3 Nf6" + ++Longer example from actual Crafty output: +
++ 4 109 14 1435 1. e4 d5 2. Qf3 dxe4 3. Qxe4 Nc6 + 4 116 23 2252 1. Nf3 Nc6 2. e4 e6 + 4 116 27 2589 1. Nf3 Nc6 2. e4 e6 + 5 141 44 4539 1. Nf3 Nc6 2. O-O e5 3. e4 + 5 141 54 5568 1. Nf3 Nc6 2. O-O e5 3. e4 ++ +
+You can use the PV to show other things; for instance, while in book, +Crafty shows the observed frequency of different reply moves in its +book. In situations like this where your engine is not really +searching, start the PV with a '(' character: +
+ ++ 0 0 0 0 (e4 64%, d4 24%) ++ +
+GNU Chess output is very slightly different. The ply number is +followed by an extra nonblank character, and the time is in seconds, +not hundredths of seconds. For compatibility, xboard accepts the +extra character and takes it as a flag indicating the different time +units. Example: +
+ ++ 2. 14 0 38 d1d2 e8e7 + 3+ 78 0 65 d1d2 e8e7 d2d3 + 3& 14 0 89 d1d2 e8e7 d2d3 + 3& 76 0 191 d1e2 e8e7 e2e3 + 3. 76 0 215 d1e2 e8e7 e2e3 + 4& 15 0 366 d1e2 e8e7 e2e3 e7e6 + 4. 15 0 515 d1e2 e8e7 e2e3 e7e6 + 5+ 74 0 702 d1e2 f7f5 e2e3 e8e7 e3f4 + 5& 71 0 1085 d1e2 e8e7 e2e3 e7e6 e3f4 + 5. 71 0 1669 d1e2 e8e7 e2e3 e7e6 e3f4 + 6& 48 0 3035 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 + 6. 48 0 3720 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 + 7& 48 0 6381 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 + 7. 48 0 10056 d1e2 e8e7 e2e3 e7e6 e3e4 f7f5 e4d4 + 8& 66 1 20536 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5 + 8. 66 1 24387 d1e2 e8e7 e2e3 e7e6 e3d4 g7g5 a2a4 f7f5 + 9& 62 2 38886 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4 + d4e4 + 9. 62 4 72578 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 a2a4 h5h4 + d4e4 +10& 34 7 135944 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4 + d4e4 f7f5 e4f4 +10. 34 9 173474 d1e2 e8e7 e2e3 e7e6 e3d4 h7h5 c2c4 h5h4 + d4e4 f7f5 e4f4 ++ +
If your engine is pondering (thinking on its opponent's time) in post +mode, it can show its thinking then too. In this case your engine may +omit the hint move (the move it is assuming its opponent will make) +from the thinking lines if and only if it sends xboard the move in +the usual "Hint: xxx" format before sending the first line. +
+ ++xboard supports three styles of time control: conventional chess clocks, +the ICS-style incremental clock, and an exact number of seconds per move. +
+ +In conventional clock mode, every time control period is the same. +That is, if the time control is 40 moves in 5 minutes, then after each +side has made 40 moves, they each get an additional 5 minutes, and so +on, ad infinitum. At some future time it would be nice to support a +series of distinct time controls. This is very low on my personal +priority list, but code donations to the xboard project are accepted, +so feel free to take a swing at it. I suggest you talk to me first, +though. +
+ ++The command to set a conventional time control looks like this: +
+ ++ level 40 5 0 + level 40 0:30 0 ++ +
+The 40 means that there are 40 moves per time control. The 5 means +there are 5 minutes in the control. In the second example, the 0:30 +means there are 30 seconds. The final 0 means that we are in +conventional clock mode. +
+ ++ +Note that the time parameter in this command is not a pure numeric argument, +but in general is a character string, in order to pass the number of seconds. +Engines are encouraged to ignore any unexpected characters at the end of this string, +i.e. following the MIN or MIN:SEC specification. +Future protocol versions might (under control of an appropriate feature) +append such extra characters to this argument, +in order to inform the engine in advance of the time control it can expect after the current session completes. +E.g. "level 40 25+5 0" could mean that the engine has to play 40 moves in 25 minutes, +but should expect to get only 5 minutes for the entire remainder of the game after that, +rather than another 25 minutes for the next 40 moves. +When the time comes, (i.e. after the 40 moves), +it will be informed of the time-control change by receiving a new "level 0 5 0" command, +but engines with advanced time management might want to plan for this in advance. + +
+ ++The command to set an incremental time control looks like this: +
+ ++ level 0 2 12 ++ +
+Here the 0 means "play the whole game in this time control period", +the 2 means "base=2 minutes", and the 12 means "inc=12 seconds". As +in conventional clock mode, the second argument to level can be in +minutes and seconds. +
+ ++At the start of the game, each player's clock is set to base minutes. +Immediately after a player makes a move, inc seconds are added to his +clock. A player's clock counts down while it is his turn. Your flag +can be called whenever your clock is zero or negative. (Your clock +can go negative and then become positive again because of the +increment.) +
+ ++The number of moves given in the level command (when non-zero) should +be taken as the number of moves still to do before the specified time +will be added to the clock, if the "level" command is received after +some moves have already been played. +The time given should be interpreted as the time left on its clock +(including any time left over from the previous sessions), +and not necessarily the time that will be added to the clock +after the specified number of moves has been played. +This is only relevant in WinBoard 4.3.xx, which might send the engine +"level" commands during a game, +just before the engine has to start thinking about the first move of +a new time-control session. +Example: if at the start of the game "level 40 60 0" was given +(40 moves per hour), +and the engine receives "level 20 22 0" just before move 41, +it should understand that it should do the next 20 moves in 22 minutes +(pehaps because the secondary session was 20 moves per 15 minutes, +and it had 7 minutes left on its clock after the first 40 moves). +
+ ++A special rule on some ICS implementations: if you ask for a game with +base=0, the clocks really start at 10 seconds instead of 0. xboard +itself does not know about this rule, so it passes the 0 on to the +engine instead of changing it to 0:10. +
+ ++ICS also has time odds games. With time odds, each player has his own +(base, inc) pair, but otherwise things work the same as in normal +games. The Zippy xboard accepts time odds games but ignores the fact +that the opponent's parameters are different; this is perhaps not +quite the right thing to do, but gnuchess doesn't understand time +odds. Time odds games are always unrated. +
+ ++The command to set an exact number of seconds per move looks like this: +
+ ++ st 30 ++ +
+This means that each move must be made in at most 30 seconds. Time not used +on one move does not accumulate for use on later moves. +
+ +xboard supports analyzing fresh games, edited positions, and games +from files. However, all of these look the same from the chess +engine's perspective. Basically, the engine just has to respond to the +"analyze" command. + +Beginning in protocol version 2, +if your engine does not support analyze mode, it should use +the feature command to set analyze=0. + +The older method of +printing the error message "Error (unknown command): analyze" in +response to the "analyze" command will also work, however. +
+ ++To enter analyze mode, xboard sends the command sequence "post", "analyze". +Analyze mode in your engine should be +similar to force mode, except that your engine thinks about what move +it would make next if it were on move. Your engine should accept the +following commands while in analyze mode: +
+ ++If the user selects "Periodic Updates", xboard will send the string +".\n" to the chess engine periodically during analyze mode, unless the +last PV received began with a '(' character. +
+ ++The chess engine should respond to ".\n" with a line like this: +
+ ++stat01: time nodes ply mvleft mvtot mvname ++ +Where: +
| time | Elapsed search time in centiseconds (ie: 567 = 5.67 seconds). + |
|---|---|
| nodes | Nodes searched so far. + |
| ply | Search depth so far. + |
| mvleft | Number of moves left to consider at this depth. + |
| mvtot | Total number of moves to consider. + |
| mvname | +Move currently being considered (SAN or coordinate notation). Optional; +added in protocol version 2. + |
+Examples: +
++ stat01: 1234 30000 7 5 30 + stat01: 1234 30000 7 5 30 Nf3 ++ +
+Meaning: +
+ +After 12.34 seconds, I've searched 7 ply/30000 nodes, there are a + total of 30 legal moves, and I have 5 more moves to search + before going to depth 8. In the second example, of the 30 legal + moves, the one I am currently searching is Nf3.
+ ++Implementation of the "." command is optional. If the engine does not +respond to the "." command with a "stat01..." line, xboard will stop +sending "." commands. If the engine does not implement this command, +the analysis window will use a shortened format to display the engine +info. +
+ ++To give the user some extra information, the chess engine can output +the strings "++\n" and "--\n", to indicate that the current search is +failing high or low, respectively. You don't have to send anything +else to say "Okay, I'm not failing high/low anymore." xboard will +figure this out itself. +
+ ++Some engines have variant interpretations of the force/go/white/black, +time/otim, and hard/easy command sets. +In order to accommodate these older engines, xboard uses these commands +only according to the stylized patterns ("idioms") given in this section. +The obsolete white and black commands +have historically been particularly troublesome, and it is recommended +that new engines set the feature colors=0 and/or ignore the commands. +
+ ++ +
+ +
+ +
+ +
+ +
+To support older engines, certain additional commands from the engine +to xboard are also recognized. (These are commands by themselves, not +values to be placed in the comment field of the PGN result code.) +These forms are not recommended for new engines; use the PGN result +code commands or the resign command instead. +
+ +| Command | Interpreted as + |
|---|---|
| White resigns | 0-1 {White resigns} + |
| Black resigns | 1-0 {Black resigns} + |
| White | 1-0 {White mates} + |
| Black | 0-1 {Black mates} + |
| Draw | 1/2-1/2 {Draw} + |
| computer mates | 1-0 {White mates} or 0-1 {Black mates} + |
| opponent mates | 1-0 {White mates} or 0-1 {Black mates} + |
| computer resigns | 0-1 {White resigns} or 1-0 {Black resigns} + |
| game is a draw | 1/2-1/2 {Draw} + |
| checkmate | 1-0 {White mates} or 0-1 {Black mates} + |
+Commands in the above table are recognized if they begin a line and +arbitrary characters follow, so (for example) "White mates" will be +recognized as "White", and "game is a draw by the 50 move rule" will +be recognized as "game is a draw". All the commands are +case-sensitive. +
+ ++An alternative move syntax is also recognized: +
+ +| Command | Interpreted as + |
|---|---|
| NUMBER ... MOVE | move MOVE + |
+Here NUMBER means any string of decimal digits, optionally ending in a +period. MOVE is any string containing no whitespace. In this command +format, xboard requires the "..." even if your engine is playing +White. A command of the form NUMBER MOVE will be ignored. This odd +treatment of the commands is needed for compatibility with gnuchessx. +The original reasons for it are lost in the mists of time, but I +suspect it was originally a bug in the earliest versions of xboard, +before I started working on it, which someone "fixed" in the wrong +way, by creating a special version of gnuchess (gnuchessx) instead of +changing xboard. +
+ ++Any line that contains the words "offer" and "draw" is recognized as +"offer draw". +
+ ++The "Illegal move" message is recognized even if spelled "illegal +move" and even if the colon (":") is omitted. This accommodates GNU +Chess 4, which prints messages like "Illegal move (no matching +move)e2e4", and old versions of Crafty, which print just "illegal move". +
+ ++In Zippy mode, for compatibility with older versions of Crafty, +xboard passes through to ICS any line that begins "kibitz", "whisper", +"tell", or "draw". Do not use this feature in new code. Instead, use the +commands "tellall", "tellothers", "tellopponent", "tellics" (if needed), +"1/2-1/2 {COMMENT}", or "offer draw", as appropriate. +
+ ++ +If the engine responds to the "sd DEPTH" command with an error message +indicating the command is not supported (such as "Illegal move: sd"), +xboard sets an internal flag and subsequently uses the command +"depth\nDEPTH" instead, for the benefit of GNU Chess 4. Note the +newline in the middle of this command! New engines should not rely on +this feature. + +
+ ++ +If the engine responds to the "st TIME" command with an error message +indicating the command is not supported (such as "Illegal move: st"), +xboard sets an internal flag and subsequently uses the command "level +1 TIME" instead, for the benefit of GNU Chess 4. Note that this is +not a standard use of the level command, as TIME seconds are not added +after each player makes 1 move; rather, each move is made in at most +TIME seconds. New engines should not implement or rely on this +feature. + +
+ + ++In support of the -firstHost/-secondHost features, which allow a chess +engine to be run on another machine using the rsh protocol, xboard recognizes +error messages that are likely to come from rsh as fatal errors. The following +messages are currently recognized: +
+ ++unknown host+ + +
+No remote directory
+not found
+No such file
+can't alloc
+Permission denied
+
+ +ChessBase/Fritz now implements the xboard/winboard protocol and can use +WinBoard-compatible engines in its GUI. ChessBase's version of the +protocol is generally the same as version 1, except that they have +added the commands fritz, reset, and +ponder, and the edit subcommands +castle and ep. If you want your +engine to work well with the ChessBase/Fritz GUI, you may need to +implement these additional commands, and you should also be aware of +the peculiar way that ChessBase uses the protocol. See their web page for documentation. + +
+ ++ +ChessMaster 8000 also implements version 1 of the xboard/winboard +protocol and can use WinBoard-compatible engines. The original +release of CM8000 also has one additional restriction: only pure +coordinate notation (e.g., e2e4) is accepted in the move command. A +patch to correct this should be available from The Learning Company +(makers of CM8000) in February 2001. + +
+ +