Author: Robert Hyatt
Date: 07:57:31 09/15/98
Below is some excerpts from the current xboard/winboard interface standard that can serve as a jumping-off point for developing an autoplayer that should finally be able to connect windows and unix boxes together using serial or network connections. ======================================================================== Chess Engine Communication Protocol ======================================================================== 1. Commands to the engine All commands from the interface to the engine end with a newline (\n), even where that is not explicitly stated. All your output to the interface must be in complete lines; any form of prompt or partial line will cause problems. draw The engine's opponent offers the engine a draw. To accept the draw, send "draw". To decline, ignore the offer, or send "decline". Note that 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 the interface tells you the game is over. go Start a search *now* for the side on move. For the program that is playing white, it will receive "go" for the first "move" to cause that program to make a move for white. The program playing black won't see this command, it will simply get a move. level MOVES TIME INC Set time controls. See the Time Control section below. MOVES is moves per session (time control), TIME is the initial clock time, INC is the Fischer-clock increment (0 if not used). level MOVES1 TIME1 MOVES2 TIME2 Set time controls. This is a more traditional type of time control with a first time control (MOVES1 in TIME1 minutes, then MOVES2 in TIME2 minutes repeated until the game ends. move See below for the syntax of moves. If the move is illegal, then the other engine has a problem and the game will have to be aborted. Note that there is no "MOVE" command, the interface will send the move to the engine as either SAN (e4 or Nf3) or coordinate algebraic (e2e4). For non-SAN move (an interface option) moves will look like this: Normal moves: e2e4 Pawn promotion: e7e8q Castling: e1g1, e1c1, e8g8, e8c8 name X specifies the name of the opponent, if known. new Reset the board to the standard chess starting position. Set White on move. otim N Set a clock that always belongs to the opponent. N is a number in centiseconds (units of 1/100 second). quit The chess engine should immediately exit. rating specifies the rating of the program receiving this message and the rating of the opponent, if both are available. This can be used in any way desired, such as setting the "contempt factor" for draws and so forth. result RESULT {COMMENT} After the end of each game, the interface 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. * is used to end a game due to a technical problem and avoid having a program think that it won or lost, incorrectly. setpos <fen string> specifies the starting position, if it is not the normal position with white to move, all pieces on their original square. The <fen string> is the typical position format supported by most programs with 8 ranks of data separated by slashes (/) followed by the side on move (w or b), possible castling opportunities for both sides, and an enpassant target square if an enpassant pawn capture is possible. time N Set a clock that always belongs to the engine. N is a number in centiseconds (units of 1/100 second). This tells the engine how much time *it* has left on the clock, and generally won't be sent in normal auto-play mode, but may be used if we choose to make the interface "smarter" and let it control the entire game including maintaining the clocks for both programs. 2. Commands from the engine to interface 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, 1/2-1/2 and *), 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} * {illegal move from other engine} Note the special case * that lets an engine terminate the current game immediately when it receives an illegal move, an invalid promotion, or something else that would make the game impossible to continue. draw If your engine wants to offer a draw by agreement (as opposed to claiming a draw by rule), it can send the command "draw". The interface relays the offer to the other engine. This can be declined by the opponent's sending you a "decline" command, or by his sending a valid move instead. move MOVE Your engine is making the move MOVE. You should not echo moves from the interface with this command; send only new moves made by the engine. Note that we need to make a decision on SAN moves or the more non-standard coordinate algebraic notation (Nf3 or g1f3). I'd suggest SAN since this is in the PGN standard, and it's far more common. time N This is used to tell the interface how much time your engine has left on its clock, typically right after making a move. This will be turned into an "otim N" command and sent to the other engine so that it can adjust its value for your remaining time. Other considerations: This assumes that the two chess engines will talk to two interface modules that will take care of the "connection" between the two machines, whether by serial null-modem cable, a direct modem connection, or a network connection using TCP/IP. Questions remaining: 1. should the interface program be "smart" and understand the rules of chess and take care of 50 move draws, draws by repetition, and so forth, or should we make the engines handle this themselves. I vote for the latter, since an engine should handle this as part of the game, and it will tend to keep the interface program simpler. 2. move format? I vote for SAN. Easier to read, is more standard, is the PGN standard, etc. 3. should the engine be able to communicate with the interface program for any reason? IE might the interface program have a window open for each program and let the programs send "analysis" to it for display in the appropriate window? Or should we "keep it simple, stupid" and not worry about this? I envision an interface program that might be started on two machines like this: interface -master -port 5020 -tc 40/120/20/60 -engine crafty interface -slave -host crafty.cis.uab.edu -port 5020 -engine gnuchessx -modem /dev/ttyS2 As an example. either -host to specify the hostname and port number or the -modem to specify a modem device/serial port with null-modem cable. we will add options to set the time control, name the engine for the "name" command, specify the rating of the engine, and so forth... the -master is used on the interface that is started first (in TCP/IP, one interface has to create a socket, bind it to a specific port number (5020 in the above example) and then wait for the other interface to connect, to establish communication. -master would be the interface that does this. -slave would simply connect to the master machine, using the port specified. Note that this could be used to play engine-vs-engine on the same computer so long as "thinking on opponent's time" is properly disabled. We'd probably want to add some sort of option to pass command-line options to each engine when they are started, as we do in xboard/winboard.
This page took 0.02 seconds to execute
Last modified: Thu, 15 Apr 21 08:11:13 -0700
Current Computer Chess Club Forums at Talkchess. This site by Sean Mintz.