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.
Beginning in protocol version 2 (in which N=2), this command will be sent immediately after the "xboard" command. If you receive some other command immediately after "xboard" (such as "new"), you can assume that protocol version 1 is in use. The "protover" command is the only new command that xboard always sends in version 2. All other new commands to the engine are sent only if the engine first enables them with the "feature" command. Protocol versions will always be simple integers so that they can easily be compared.
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
|