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.