From 10acef9e6f2d1f56a39c7f4b9ccf4b4be6f8bed7 Mon Sep 17 00:00:00 2001 From: Scott Gasch Date: Wed, 1 Jun 2016 19:04:57 -0700 Subject: A bunch of chess-related papers. --- programs/xboard.html | 1300 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1300 insertions(+) create mode 100644 programs/xboard.html (limited to 'programs/xboard.html') diff --git a/programs/xboard.html b/programs/xboard.html new file mode 100644 index 0000000..c02b03b --- /dev/null +++ b/programs/xboard.html @@ -0,0 +1,1300 @@ + + + +Chess Engine Communication Protocol + + + +

Chess Engine Communication Protocol

Tim Mann

+Last modified on Sun Sep 17 23:37:17 PDT 2000 by mann +

+ +

1. Introduction +
2. Connection +
3. Debugging +
4. How it got this way +
5. WinBoard requires Win32 engines +
6. Hints on input/output +
7. Interrupts +
8. Commands from xboard to the engine +
9. Commands from the engine to xboard +
10. Thinking Output +
11. Time control +
12. Analyze Mode +
13. Idioms and backward compatibility features +

+ +

1. Introduction

+ +

+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: +

You have, or are developing, a chess engine but you don't want to +write your own graphical interface. +
You have, or are developing,a chess engine, and you want to +interface it to the Internet Chess Server. +

+ +

+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, mann@pa.dec.com. Also, please join +the mailing list for authors of xboard/WinBoard compatible chess +engines. The list is now hosted by egroups.com; 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. +

+ +

2. Connection

+ +

+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. +

+ +

3. Debugging

+ +

+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. +

+ +

4. How it got this way

+ +

+Originally, xboard was just trying to talk to the existing +command-line interface of gnuchess, designed for people to type +commands to. So the communication protocol is very ad-hoc. (The +reason why there is a gnuchessx that's different from gnuchessr is +buried in the mists of time, before I started working on xboard, but I +think it was due to someone working around a stupid bug in xboard by +changing gnuchess instead of fixing the bug. The differences are +tiny.) It's now tough to change the interface, because xboard and +gnuchess are separate programs, and I don't want to force people to +upgrade them together to versions that match. +

+ +

+Things have changed a bit now that there are many more engines that +work with xboard. I've had to make the protocol description more +precise, and I've added some features that GNU Chess does not support. +In the latest version, I've specified a standard semantics for many +commands that differs in some details from what GNU Chess provides, +but is easier to work with. In the future I may release a modified +GNU Chess that conforms exactly to this protocol. +

+ +

5. WinBoard requires Win32 engines

+ +

+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://sourceware.cygnus.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. +

+ +

6. Hints on input/output

+ +

+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 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 descrbed 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 descrbed 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. +

+ +

7. Signals

+ +

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.

+ +

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 ignore it by calling signal(SIGTERM, SIG_IGN) at the +start of your program.

+ +

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 on +systems where its input polling code is broken or disabled. Because +they work in a rather peculiar way, it is recommended that you simply +ignore SIGINT when running under Unix in xboard mode. You can do this +by having your engine call signal(SIGINT, SIG_IGN). Alternatively, +you can configure your personal copy of xboard to not send SIGINT by +running configure with the --disable-sigint option. This won't help +you if you give your engine to other people who don't want to +recompile their xboard and possibly break its interaction with GNU +Chess. +

+ +

+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. The +first SIGINT stops it from pondering until the next move, but on some +systems, GNU Chess 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 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. (More Microsoft brain damage.) +

+ +

8. Commands from xboard to the engine

+ +

+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, give xboard the +-xreuse (or -xreuse2) command line option to disable reuse. xboard +will then ask the process to quit after each game and start a new +process for the next game. +

+ +

xboard +

This command will be sent once immediately after your engine +process is started. You can use it to put your engine into "xboard +mode" if that is needed. If your engine prints a prompt to ask for +user input, you must turn off the prompt and output a newline when the +"xboard" command comes in. +

+ +

new +

Reset the board to the standard chess starting position. Set +White on move. Leave force mode and set the engine to play Black. +Associate the engine's clock with Black and the opponent's clock with +White. Reset clocks and time controls to the start of a new game. +Stop clocks. Do not ponder on this move, even if pondering is on. +Remove any search depth limit previously set by the sd command. +

+ +

variant VARNAME +

If the game is not standard chess, but a variant, this command is +sent after "new" and before the first move or "edit" command. Currently +defined variant names are: + + +

wildcastle	Shuffle chess where king can castle from d file +
nocastle	Shuffle chess with no castling at all +
fischerandom	FischeRandom (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 (FICS) +
twokings	Weird ICC wild 9 +
kriegspiel	Kriegspiel (not really supported) +
atomic	Atomic (not really supported) +
3check	Win by giving check 3 times (not supported) +
unknown	Unknown variant (not supported) +

+ +

quit +

The chess engine should immediately exit. This command is used +when xboard is itself exiting, and also between games if the -xreuse +command line option is given (or -xreuse2 for the second engine). +See also Signals above. +

+ +

random +

This command is specific to GNU Chess. You can either ignore it +completely (that is, treat it as a no-op) or implement it as GNU Chess +does. The command toggles "random" mode (that is, it sets random = +!random). In random mode, the engine adds a small random value to its +evaluation function to vary its play. The "new" command sets random +mode off. +

+ +

force +

Set the engine to play neither color ("force mode"). Stop clocks. +The engine should check that moves received in force mode are legal +and made in the proper turn, but should not think, ponder, or make +moves of its own. +

+ +

white +

Set White on move. Set the engine to play Black. Stop clocks. +

+ +

black +

Set Black on move. Set the engine to play White. Stop clocks. +

+ +

level MPS BASE INC +

Set time controls. See the Time Control section below. +

+ +

st TIME +

Set time controls. See the Time Control section +below. The commands "level" and "st" are not used together. +

+ +

sd DEPTH +

The engine should limit its thinking to DEPTH ply. +

+ +

time N +

Set a clock that always belongs to the engine. N is a number in + centiseconds (units of 1/100 second). Even if the engine changes to + playing the opposite color, this clock remains with the engine. +

+ +

otim N + +

Set a clock that always belongs to the opponent. N is a number in +centiseconds (units of 1/100 second). Even if the opponent changes to +playing the opposite color, this clock remains with the opponent. +

+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. +

+ +

+If you can't handle the time and otim commands, you can ignore them +(that is, treat them as no-ops); or better, send back "Error (unknown +command): time" the first time you see "time", and xboard will realize +you don't implement the command. +

+ +

go + +

Leave force mode and set the engine to play the color that is on +move. Associate the engine's clock with the color that is on move, +the opponent's clock with the opposite color. Start the engine's +clock. Start thinking and eventually make a move. +

+ +

MOVE +

See below for the syntax of moves. If the move is illegal, print +an error message; see the section "Commands from the engine to +xboard". If the move is legal and in turn, make it. If not in force +mode, stop the opponent's clock, start the engine's clock, start +thinking, and eventually make a move. +

+When xboard sends your engine a move, it always sends coordinate +algebraic notation. There is no command name; the notation is just +sent as a line by itself. Examples: +

+ +
Normal moves: e2e4 +
Pawn promotion: e7e8q +
Castling: e1g1, e1c1, e8g8, e8c8 +
Bughouse drop: P@h3 +
ICS Wild 0/1 castling: d1f1, d1b1, d8f8, d8b8 +
FischerRandom castling: o-o, o-o-o (future) +
+ +

+If your engine can't handle this kind of output, change the routine +SendMoveToProgram in backend.c to send the kind of notation you need. +If you define SAN_TO_PROGRAM, your engine will be sent Standard +Algebraic Notation (as defined by the PGN standard); for example, e4, +Nf3, exd5, Bxf7+, Qxf7#, e8=Q, O-O, or P@h3. (The P@h3 notation is a +nonstandard extension to SAN.) In the future, I may make +SAN_TO_PROGRAM a runtime option if there is demand for it. +

+ +

+xboard doesn't reliably detect illegal moves, because it does not keep +track of castling unavailablity 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". +

+ +

? +

Move now. If your engine is thinking, it should move immediately; + otherwise, the command should be ignored (treated as a no-op). It + is permissible for your engine to always ignore the ? command. The + only bad consequence is that xboard's Move Now menu command will do + nothing. +

+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, or quit while the +engine is on move. +

+ +

draw +

The engine's opponent offers the engine a draw. To accept the +draw, send "offer draw". To decline, ignore the offer (that is, send +nothing). If you're playing on ICS, it's possible for the draw offer +to have been withdrawn by the time you accept it, so don't assume the +game is over because you accept a draw offer. Continue playing until +xboard tells you the game is over. See also "offer draw" below. +

+ +

result RESULT {COMMENT} +

After the end of each game, xboard will send you a result command. +You can use this command to trigger learning. RESULT is either 1-0, +0-1, 1/2-1/2, or *, indicating whether white won, black won, the game +was a draw, or the game was unfinished. The COMMENT string is purely +a human-readable comment; its content is unspecified and subject to +change. In ICS mode, it is passed through from ICS uninterpreted. +Example:

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. +

+ +

edit +

The edit command puts the chess engine into a special mode, where +it accepts the following subcommands: + +

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 for compatibility with engines that do not +interpret the "black" command according to the specification above; +see "Idioms" below. +

+ +

+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. +

+ +

hint +

If the user asks for a hint, xboard sends your engine the command +"hint". Your engine should respond with "Hint: xxx", where xxx is a +suggested move. If there is no move to suggest, you can ignore the +hint command (that is, treat it as a no-op). +

+ +

bk +

If the user selects "Book" from the xboard menu, xboard will send +your engine the command "bk". You can send any text you like as the +response, as long as each line begins with a blank space or tab (\t) +character, and you send an empty line at the end. The text pops up in +a modal information dialog. +

+ +

undo +

If the user asks to back up one move, xboard will send you the +"undo" command. xboard will not send this command without putting you +in "force" mode first, so you don't have to worry about what should +happen if the user asks to undo a move your engine made. (GNU Chess +actually switches to playing the opposite color in this case.) +

+ +

remove +

If the user asks to retract a move, xboard will send you the +"remove" command. It sends this command only when the user is on +move. Your engine should undo the last two moves (one for each +player) and continue playing the same color. +

+ +

hard +

Turn on pondering (thinking on the opponent's time, also known as +"permanent brain"). xboard will not make any assumption about what +your default is for pondering or whether "new" affects this setting. +

+ +

easy +

Turn off pondering. +

+ +

post +

Turn on thinking/pondering output. +See Thinking Output section. +

+ +

nopost +

Turn off thinking/pondering output. +

+ +

analyze +

Enter analyze mode. See Analyze Mode section. +

+ +

Here are some special commands for Zippy mode:

+ +

name X +

In ICS mode, xboard obtains the name of its opponent from ICS when +a game starts and saves it for use in the PGN tags. In Zippy mode, it +also passes the opponent's name on to the chess engine with the name +command. Example:

name mann

+ +

rating +

In ICS mode, xboard obtains the ICS opponent's rating from the +"Creating:" message that appears before each game. (This message may +not appear on servers using outdated versions of the FICS code.) In +Zippy mode, it sends these ratings on to the chess engine using the +"rating" command. The chess engine's own rating comes first, and if +either opponent is not rated, his rating is given as 0. Example: +

rating 2600 1500

+ +

computer +

The opponent is on the ICS computer list. +

+ +

Bughouse commands:

+ +

+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 <player> +

<player> is now your partner for future games. Example:

partner mann

+ +

partner +

Meaning: You no longer have a partner. +

+ +

ptell <text> +

Your partner told you <text>, either with a ptell or an ordinary tell. +

+ +

holding [<white>] [<black>] +

White currently holds <white>; black currently holds <black>. + Example:

holding [PPPRQ] []

+ +

holding [<white>] [<black>] <color><piece> +

White currently holds <white>; black currently holds <black>, after + <color> acquired <piece>. Example:

holding [PPPRQ] [R] BR

+ +

9. Commands from the engine to xboard

+ +

Illegal move: MOVE +

Illegal move (REASON): MOVE +

If your engine receives a MOVE command that is recognizably a move +but is not legal in the current position, your engine must print an +error message in one of the above formats so that xboard can pass the +error on to the user and retract the move. The (REASON) is entirely +optional. Examples: + +

+  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 (ERRORTYPE): COMMAND +

If your engine receives a command it does not understand or does +not implement, it should print an error message in the above format so +that xboard can parse it. Examples: +

+  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
+

+ +

+Note: versions of xboard prior to 3.6.11beta do not parse the "Error" +format. To ease the transition, it is acceptable to use the "Illegal +move" format for all errors, even if the command given was not a +move. +

+ +

move MOVE +

Your engine is making the move MOVE. Do not echo moves from + xboard with this command; send only new moves made by the engine. + +

+Note: versions of xboard prior to 3.6.11beta do not parse the above +format, so you may want to use the old "NUMBER ... MOVE" format +temporarily. See the section "Idioms and backward +compatibility features" below. +

+ +

+For the actual move text from your chess engine (in place of MOVE +above), xboard will accept any kind of unambiguous algebraic format, +including coordinate notation, SAN, and some slight variants of SAN. +You don't have to send the pure coordinate notation that xboard sends +to your engine; xboard parses the output with its general-purpose +move parser, which was built to extract human-typed game scores from +netnews messages. For example, the following will all work: +

+  e2e4
+  e4
+  Nf3
+  ed
+  exd
+  exd5
+  Nxd5
+  Nfd3
+  e8q
+  e8Q
+  e8=q
+  e8(Q)
+  e7e8q
+  o-o
+  O-O
+  0-0
+

+ +

+and many more. +

+ +

RESULT {COMMENT} +

When your engine detects that the game has ended by rule +(checkmate, stalemate, triple repetition, the 50 move rule, or +insufficient material), your engine must output a line of the form +"RESULT {comment}" (without the quotes), where RESULT is a PGN result +code (1-0, 0-1, or 1/2-1/2), and comment is the reason. Examples: +

+  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. +

+ +

resign +

If your engine wants to resign, it can send the command "resign". +Alternatively, it can use the "RESULT {comment}" command if the string +"resign" is included in the comment; for example "0-1 {White +resigns}". xboard relays the resignation to the user, the ICS, the +other engine in Two Machines mode, and the PGN save file as required. +

+ +

offer draw +

If your engine wants to offer a draw by agreement (as opposed to +claiming a draw by rule), it can send the command "offer draw". +xboard relays the offer to the user, the ICS, the other engine in Two +Machines mode, and the PGN save file as required. In Machine White, +Machine Black, or Two Machines mode, the offer is considered valid +until your engine has made two more moves. +

+ +

telluser MESSAGE +

xboard pops up a modal information dialog containing the message. +MESSAGE consists of any characters, including whitespace, to the end +of the line. +

+ +

tellusererror MESSAGE +

xboard pops up a non-modal error dialog containing the message. +MESSAGE consists of any characters, including whitespace, to the end +of the line. +

+ +

askuser REPTAG MESSAGE +

Here REPTAG is a string containing no whitespace, and MESSAGE +consists of any characters, including whitespace, to the end of the +line. xboard pops up a modal question dialog that says MESSAGE and +has a typein box. If the user types in "bar", xboard sends "REPTAG +bar" to the engine. The user can cancel the dialog and send nothing. +

+ +

tellics MESSAGE +

In Zippy mode, xboard sends "MESSAGE\n" to ICS. MESSAGE consists +of any characters, including whitespace, to the end of the line. + +

+ +

10. Thinking Output

+ +

+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. +

+ +

11. Time control

+ +

+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 ICS rule: 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 currently, so it may pass 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 30 seconds. Time not used +on one move does not accumulate for use on later moves. +

+ +

12. Analyze Mode

+ +

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. If your engine does not support analyze mode, it +should print the error message "Error (unknown command): analyze" in +response to the "analyze" command. +

+ +

+To enter analyze mode, xboard sends the command sequence "post", +"white" or "black", "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: +

+ +

Any legal move, as in force mode +
"undo" +
"new" (reset position to start of game but stay in analyze mode) +
"edit" (exiting edit mode returns to analyze mode) +
"exit" (leave analyze mode) +
"." (optional, see below) +

+ +

+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
+

+ +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. +

+ +

+Example: +

+  stat01: 1234 30000 7 5 30
+

+ +

+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.

+ +

+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. +

+ +

13. Idioms and backward compatibility features

+ +

+Some engines have variant interpretations of the force/go/white/black, +time/otim, and hard/easy command sets. New engines should not use +these interpretations, but in order to accommodate existing engines, +xboard is currently very conservative about how it uses these +commands. Only the following idioms are currently used. +

+ +

white +
go +: Sent when the engine is in force mode or playing Black but should +switch to playing White. This sequence is sent only when White is +already on move. +
+ +
black +
go +: Sent when the engine is in force mode or playing White but should +switch to playing Black. This sequence is sent only when Black is +already on move. +
+ +
time N +
otim N +
MOVE +: Sent when the opponent makes a move and the engine is already +playing the opposite color. +
+ +
white +
time N +
otim N +
black +
go +: Sent when Black is on move, the engine is in force mode or playing +White, and the engine's clock needs to be updated before it starts +playing. The initial "white" is a kludge to accommodate GNU Chess +4.0.77's variant interpretation of these commands. It may be removed +in the future, especially if it causes problems for other engines. +
+ +
black +
time N +
otim N +
white +
go +: Sent when White is on move, the engine is in force mode or playing +Black, and the engine's clock needs to be updated before it starts +playing. See previous idiom. +
+ +
hard +
easy +: Sent in sequence to turn off pondering if xboard is not sure +whether it is on. When xboard is sure, it will send "hard" or "easy" +alone. xboard does this because "easy" is a toggle in GNU Chess but +"hard" is an absolute on. + +

+ +

+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.0.77, 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 existing 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. +

+ +

+Before the "sd DEPTH" command, xboard also sends the command +"depth\nDEPTH", for the benefit of GNU Chess. Note the newline in the +middle of this command. Ugh. +

+ +

+For the benefit of GNU Chess, if an "st TIME"-style time control is +being used, TIME is also given to the engine as a command-line +argument when it is started. Ugh. +

+ +

converted to HTML by Steffen A. Jakob

+ + -- cgit v1.3

Normal moves:	e2e4 +
Pawn promotion:	e7e8q +
Castling:	e1g1, e1c1, e8g8, e8c8 +
Bughouse drop:	P@h3 +
ICS Wild 0/1 castling:	d1f1, d1b1, d8f8, d8b8 +
FischerRandom castling:	o-o, o-o-o (future) +