cecpnotes.txt

#FEATURES
setboard (boolean, default 0, recommended 1)
usermove (boolean, default 0)
myname (string, default determined from engine filename)


#FROM XBOARD
xboard
quit
force
go
time
otime
usermove
?   (move now)
draw
setmove FEN
undo
remove
hard
easy
post
nopost
analyze
pause
resume
quit


#TO XBOARD
move MOVE
Error (ERRORTYPE): COMMAND
FEATURE 






-->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.
protover N

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.

accepted
rejected
These commands may be sent to your engine in reply to the "feature" command; see its documentation below.
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. Use wall clock for time measurement. Stop clocks. Do not ponder on this move, even if pondering is on. Remove any search depth limit previously set by the sd command.


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.

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.

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 color that is not on move. Start the engine's clock. Start thinking and eventually make a move.

playother
(This command is new in protocol version 2. It is not sent unless you enable it with the feature command.) Leave force mode and set the engine to play the color that is not on move. Associate the opponent's clock with the color that is on move, the engine's clock with the color that is not on move. Start the opponent's clock. If pondering is enabled, the engine should begin pondering. If the engine later receives a move, it should start thinking and eventually reply.

level MPS BASE INC
Set time controls. See the Time Control section below.

st TIME
Set time controls. See the Time Control section below.

sd DEPTH
The engine should limit its thinking to DEPTH ply. The commands "level" or "st" and "sd" can be used together in an orthogonal way. If both are issued, the engine should observe both limitations: In the protocol, the "sd" command isn't a time control. It doesn't say that your engine has unlimited time but must search to exactly the given depth. It says that you should pay attention to the time control as normal, but cut off the search at the specified depth even if you have time to search deeper. If you don't have time to search to the specified depth, given your normal time management algorithm, then you will want to stop sooner than the given depth.
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.

nps NODE_RATE
The engine should not use wall-clock time to make its timing decisions, but an own internal time measure based on the number of nodes it has searched (and will report as "thinking output", see section 10), converted to seconds through dividing by the given NODE_RATE. Example: after receiving the commands "st 8" and "nps 10000", the engine should never use more that 80,000 nodes in the search for any move. In this mode, the engine should report user CPU time used (in its thinking output), rather than wall-clock time. This even holds if NODE_RATE is given as 0, but in that case it should also use the user CPU time for its timing decisions. The effect of an "nps" command should persist until the next "new" command.

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

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


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

usermove MOVE
By default, moves are sent to the engine without a command name; the notation is just sent as a line by itself. Beginning in protocol version 2, you can use the feature command to cause the command name "usermove" to be sent before the move. Example: "usermove e2e4".
?
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, quit, or other commands while the engine is on move.

ping N
In this command, N is a decimal number. When you receive the command, reply by sending the string pong N, where N is the same number you received. Important: You must not reply to a "ping" command until you have finished executing all commands that you received before it. Pondering does not count; if you receive a ping while pondering, you should reply immediately and continue pondering. Because of the way xboard uses the ping command, if you implement the other commands in this protocol, you should never see a "ping" command when it is your move; however, if you do, you must not send the "pong" reply to xboard until after you send your move. For example, xboard may send "?" immediately followed by "ping". If you implement the "?" command, you will have moved by the time you see the subsequent ping command. Similarly, xboard may send a sequence like "force", "new", "ping". You must not send the pong response until after you have finished executing the "new" command and are ready for the new game to start.
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.

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


-->setboard FEN
The setboard command is the new way to set up positions, beginning in protocol version 2. It is not used unless it has been selected with the feature command. Here FEN is a position in Forsythe-Edwards Notation, as defined in the PGN standard. Note that this PGN standard referred to here only applies to normal Chess; Obviously in variants that cannot be described by a FEN for normal Chess, e.g. because the board is not 8x8, other pieces then PNBRQK participate, there are holdings that need to be specified, etc., xboard will use a FEN format that is standard or suitable for that varant. In particular, in FRC or CRC, WinBoard will use Shredder-FEN or X-FEN standard, i.e. it can use the rook-file indicator letter to represent a castling right (like HAha) whenever it wants, but if it uses KQkq, this will always refer to the outermost rook on the given side.
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.


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


-->pause
-->resume
(These commands are new in protocol version 2 and will not be sent unless feature pause=1 is set. At this writing, xboard actually does not use the commands at all, but it or other interfaces may use them in the future.) The "pause" command puts the engine into a special state where it does not think, ponder, or otherwise consume significant CPU time. The current thinking or pondering (if any) is suspended and both player's clocks are stopped. The only command that the interface may send to the engine while it is in the paused state is "resume". The paused thinking or pondering (if any) resumes from exactly where it left off, and the clock of the player on move resumes running from where it stopped.



9. Commands from the engine to xboard

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.

feature FEATURE1=VALUE1 FEATURE2=VALUE2 ...
Beginning with version 2, the protocol includes the "feature" command, which lets your engine control certain optional protocol features. Feature settings are written as FEATURE=VALUE, where FEATURE is a name from the list below and VALUE is the value to be assigned. Features can take string, integer, or boolean values; the type of value is listed for each feature. String values are written in double quotes (for example, feature myname="Miracle Chess 0.9"), integers are written in decimal, and boolean values are written as 0 for false, 1 for true. Any number of features can be set in one feature command, or multiple feature commands can be given.
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.

ping (boolean, default 0, recommended 1)
If ping=1, xboard may use the protocol's new "ping" command; if ping=0, xboard will not use the command.
-->setboard (boolean, default 0, recommended 1)
-->If setboard=1, xboard will use the protocol's new "setboard" command to set up positions; if setboard=0, it will use the older "edit" command.

playother (boolean, default 0, recommended 1)
If playother=1, xboard will use the protocol's new "playother" command when appropriate; if playother=0, it will not use the command.

-->usermove (boolean, default 0)
-->If usermove=1, xboard will send moves to the engine with the command "usermove MOVE"; if usermove=0, xboard will send just the move, with no command name.

analyze (boolean, default 1, recommended 1)
If analyze=0, xboard will not try to use the "analyze" command; it will pop up an error message if the user asks for analysis mode. If analyze=1, xboard will try to use the command if the user asks for analysis mode.

-->myname (string, default determined from engine filename)
-->This feature lets you set the name that xboard will use for your engine in window banners, in the PGN tags of saved game files, and when sending the "name" command to another engine.

colors (boolean, default 1, recommended 0)
If colors=1, xboard uses the obsolete "white" and "black" commands in a stylized way that works with most older chess engines that require the commands. See the "Idioms" section below for details. If colors=0, xboard does not use the "white" and "black" commands at all.
ics (boolean, default 0)
If ics=1, xboard will use the protocol's new "ics" command to inform the engine of whether or not it is playing on a chess server; if ics=0, it will not.
name (boolean, see text below)
If name=1, xboard will use the protocol's "name" command to inform the engine of the opponent's name; if name=0, it will not. By default, name=1 if the engine is playing on a chess server; name=0 if not.
pause (boolean, default 0)
If pause=1, xboard may use the protocol's new "pause" command; if pause=0, xboard assumes that the engine does not support this command.
nps (boolean, default ?)
If nps=1, it means the engine supports the nps command. If nps=0, it means the engine does not support it, and WinBoard should refrain from sending it. Default is that WinBoard sends it, in an attempt to try out if the engine understand it. The engine should properly respond with "Error (unkown command): nps" if it does not implement it, (as any protocol version pre-scribes), or WinBoard might assume that the engine did understand the command. In that case the use of different time standards that ensues could lead to time forfeits for the engine.
debug (boolean, default 0)
If debug=1, it means the engine wants to send debug output prefixed by '#', which WinBoard should ignore, except for including it in the winboard.debug file. As this feature is added to protocol 2 ony late, so that not all protocol-2 supporting versions of WinBoard might implement it, it is important that engines check if WinBoard accepts the feature. If the feature is rejected, engines must refrain from sending the debug output, or do so at their own risk.
memory (boolean, default 0)
If memory=1, the size of the total amount of memory available for the memory-consuming tables of the engine (e.g. hash, EGTB cache) will be set by the GUI through the "memory" command.
smp (boolean, default 0)
If smp=1, the GUI will send the "cores" command to the engine to inform it how many CPU cores it can use. Note that sending smp=1 does not imply the engine can use more than one CPU; just that it wants to receive the "cores" command.
egt (string, see text below)
This feature indicates which end-game table formats the engine supports. It should be a comma-separated list of format names. See under the "egtpath" command in section 8 above. If you do not set this feature, xboard will assume the engine does not support end-game tables, and will not send any "egtpath" commands to inform the engine about their whereabouts.
option (string, see text below)
This feature is used by the engine to define an option command to appear in a GUI menu, so that the user can change the corresponding setting of the engine through the GUI interactively. The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range. Unlike other features, option features are accumulated by the GUI, and the GUI must be able to add a new option to the list at any time, even after having received feature done=1. There are ten different options types, each requiring a slighly different syntax of the defining string: 
feature option="NAME -button" 
feature option="NAME -save" 
feature option="NAME -reset" 
feature option="NAME -check VALUE" 
feature option="NAME -string VALUE" 
feature option="NAME -spin VALUE MIN MAX" 
feature option="NAME -combo CHOICE1 /// CHOICE2 ..." 
feature option="NAME -slider VALUE MIN MAX" 
feature option="NAME -file VALUE" 
feature option="NAME -path VALUE" 
NAME is an arbitrary alphanumeric string which can contain spaces; the other words in capitals would be replaced by the current (default) setting of the option, (a character string for -string options, a decimal number for -spin and -check options, were the latter uses 1=checked, 0=unchecked), the minimum or maximum value of numeric (-spin) options, or arbitrary text labels (for -combo option). In the latter case, the current value will be preceded by an asterisk. The -file and -path options are similar to -string, but can be used to inform the GUI that the text represents a file name or folder name respectively, so the GUI dialog could add the appropriate browse button to the text-edit field. Similarly, a -slider option is like a -spin, but the GUI might make a different graphical representation for it. A -save option is like a -button, and defines an immediate command to be sent by the engine. With -save the GUI will make sure all current option settings are flushed to the engine before it sends this command. A -reset option is like a -button, but use of it purges the list of options before sending the corresponding option command to the engine. This enables the engine to completely redefine its options or their current settings, by sending a new set of option feature commands to the GUI, terminated by feature done=1. (The effect of sending an option feature for an option with the same name as was defined before, without first receiving a -reset option command, is undefined.)
done (integer, no default)
If you set done=1 during the initial two-second timeout after xboard sends you the "xboard" command, the timeout will end and xboard will not look for any more feature commands before starting normal operation. If you set done=0, the initial timeout is increased to one hour; in this case, you must set done=1 before xboard will enter normal operation.
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
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.
For the actual move text from your chess engine (in place of MOVE above), your move should be either

in coordinate notation (e.g., e2e4, e7e8q) with castling indicated by the King's two-square move (e.g., e1g1), or
in Standard Algebraic Notation (SAN) as defined in the Portable Game Notation standard (e.g, e4, Nf3, O-O, cxb5, Nxe4, e8=Q), with the extension piece@square (e.g., P@f7) to handle piece placement in bughouse and crazyhouse.
xboard itself also accepts some variants of SAN, but for compatibility with non-xboard interfaces, it is best not to rely on this behavior.
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.

RESULT {COMMENT}
When your engine detects that the game has ended by rule, 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. Here "by rule" means that the game is definitely over because of what happened on the board. In normal chess, this includes checkmate, stalemate, triple repetition, the 50 move rule, or insufficient material; it does not include loss on time or the like. 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. 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.

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. Note that many interfaces work more smoothly if you resign before you move.


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. This command must also be used to accept a draw offer. Do not use the 1/2-1/2 command for that, as the offer might be no longer valid, in which case a refusal to play on implied by the RESULT command might make you forfeit the game. "offer draw" should also be used to claim 50-move and 3-fold-repetition draws that will occur after your move, by sending it before making the move. WinBoard will grant draw offers without the opponent having any say in it in situations where draws can be claimed. Only if the draw cannot be claimed, the offer will be passed to your opponent after you make your next move, just before WinBoard relays this move to the opponent.


# COMMENT
The engine can send any string of printable characters, terminated by a newline, for inclusion in the winboard.debug file, provided the line starts with a '#' character. If the engine has set feature debug=1, it is guaranteed that WinBoard (and any future version of it) will completely ignore these lines in any other respect.