The Othello Engine Protocol

What is the Othello Engine Protocol?

The Othello Engine Protocol is a text protocol used by Cassio to communicate with Othello engines. The protocol was invented by Stéphane Nicolet, Bruno Causse (author of Roxane) and Richard Delorme (author of Edax) in 2009. Our hope is that this protocol will prove more and more popular, avoiding you the hassle of writing a complete GUI when you create an othello program.

An Othello engine runs as a separate process from Cassio itself, connected to Cassio through a pair of anonymous pipes. The engine does not have to do anything special to set up these pipes. Cassio 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. (note: for advices on how to do these communications efficiently, Othello engines authors are encouraged to read the "Hints on input/output" section (section 6) of this document which covers the similar case of chess engines using the xboard protocol).

Do you have a list of commands?

This is the official specification of the Othello Engine Protocol :

ENGINE-PROTOCOL init

Result:
This command is sent only once by the GUI at the beginning, after the engine has been started. The engine initializes all its internal stuff (hash table, evaluation data, etc.), and sends "ready." on the standard output. It then waits for the next command on its standard input, using as little CPU as possible.

Example:
ENGINE-PROTOCOL init ready.

ENGINE-PROTOCOL get-version

Result:
This command is sent by the GUI to get the version of the engine. The engine sends back on the standard output a line starting with the keyword "version:" followed by a space, its name and a version number, then sends "ready." on a second line.

Example:
ENGINE-PROTOCOL get-version version: Edax 4.0.6 ready.

ENGINE-PROTOCOL midgame-search position alpha beta depth precision

Result:
The engine searches the position using its midgame algorithm with the specified parameters: the [alpha;beta] window, the depth and the probcut precision. It then sends the results of its midgame calculations, followed by "ready.".

Example:
ENGINE-PROTOCOL midgame-search ---------------------------OX------XOX-------O------------------X -0.51 2.30 27 90 ---------------------------OX------XOX-------O------------------X, move E6, depth 27, @90%, B+2.57 <= v <= B+64.00, E6F4G5G6G4E7F3D6F7H3G3D3H6H5D8E2F2E3C2C3D7C1C4H7F1, node 2913524, time 0.192 ready.

ENGINE-PROTOCOL endgame-search position alpha beta precision

Result:
The engine searches the position using its endgame algorithm with the specified parameters: the [alpha;beta] window and the probcut precision, where a precision of 100 means no probcut at all. It then sends the results of its endgame calculations, followed by "ready.".

Example:
ENGINE-PROTOCOL endgame-search --O-------OXXXX---OXXXXO--OXXXXO--OXXOXO--OXOXXO--OOOOXO--OOXXX-O -13 -12 100 --O-------OXXXX---OXXXXO--OXXXXO--OXXOXO--OXOXXO--OOOOXO--OOXXX-O, move H8, depth 23, @100%, W-12.00 <= v <= W+64.00, H8B3H1G1H2F1E1B4B2D1A4A3A2B5B1A1A5A6B6B8A8B7A7, node 342732, time 0.027 ready.

ENGINE-PROTOCOL get-search-infos

Result:
If the engine is searching a position, it sends the number of nodes and the time used (in seconds) since the beginning of the search. If the engine is searching but these statistics are not available, the engine must send "ok.". Otherwise (if the engine is idle), it must send "ready.".

Examples:
ENGINE-PROTOCOL get-search-infos node 62034009, time 4.953
ENGINE-PROTOCOL get-search-infos ok.
ENGINE-PROTOCOL get-search-infos ready.

(empty line)

Result:
When the engine receives an empty line on its standard input, it must answer back with "ok." if it is searching a position, or with "ready." if it not searching. This command can be used by the GUI to check that the engine is alive.

Examples:
(empty line) ok.
(empty line) ready.

ENGINE-PROTOCOL stop

Result:
The engine stops immediately its calculations (if any), and sends "ready." on the standard output.

Example:
ENGINE-PROTOCOL stop ready.

ENGINE-PROTOCOL new-position

Result:
This command may be sent by the GUI to the engine as a hint that the following group of endgame or midgame searches are independant from the previous analysis. The engine prepares itself for a new analysis, then sends "ready."

Example:
ENGINE-PROTOCOL new-position ready.

ENGINE-PROTOCOL empty-hash

Result:
None, the engine empties its hash table (ie completely clears each entry of the hash table).

Example:
ENGINE-PROTOCOL empty-hash

ENGINE-PROTOCOL quit

Result:
None, the engine stops immediately its calculations and quits.

Example:
ENGINE-PROTOCOL quit