Computer Chess Club Archives




Subject: new autoplayer interface standard

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

  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.

  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.

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

  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.

  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

  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.

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

  The chess engine should immediately exit.

  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.

  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

  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.

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