Basic UCI Protocol

The communication between the Graphical User Interface (GUI) and the chess engine is quite one-sided: the protocol requests the chess engine information, and the chess engine provides it.

Example: Conversation between Nageune and Arena GUI

Before I explain the details, here is an example of a conversation between a chess engine and the GUI.

                > uci 
< id name Nageune
< id author Seung Jae Lee
< uciok
> isready
< readyok
> ucinewgame
> position startpos
> go infinite
< info depth 1 score 50 pv b1c3
< info depth 2 score 0 pv b1c3 b8c6
< info depth 3 score 50 pv b1c3 b8c6 g1f3
< info depth 4 score 0 pv b1c3 b8c6 g1f3 g8f6
> stop
< bestmove b1c3

Step 1: Initialize

The first command the engine will receive is the uci command. The command requests the chess engine to provide necessary information about the name of the engine, the name of the author, and the options the chess engine supports. For this example let us disregard giving information about possible options.

If the name of the chess engine is Nageune and the name of the author is Seung Jae Lee, the engine will respond the following way:

                > uci 
< id name Nageune
< id author Seung Jae Lee
< uciok
The uciok command tells the GUI that the engine has provided all the necessary information.

                > isready 
< readyok
The GUI will often send the isready command to the chess engine. This is to synchronize the GUI and the engine. The GUI can use this command to make sure the chess engine is ready for another command. The chess engine should respond to the GUI with readyok command.

Step 2: Setup Game


                > ucinewgame 
The command ucinewgame can be sent by the GUI when it wants to start a new game.

Step 3: Play Game


                > position fen [FEN] ... 

                > position startpos ...
When it is the engine's turn, the GUI gives the engine the current board using the position command and asks the engine to start calculation with the go command. There are two ways to specify the current position of the board: using FEN string or using the default starting position of chess. After the keyword fen or startpos, GUI can list a number of moves to make from the FEN or starting position to reach the desired position. For example, consider Giuoco Piano (1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5) opening. The GUI can send this position in the following ways:

                > position fen r1bqk1nr/pppp1ppp/2n5/2b1p3/2B1P3/5N2/PPPP1PPP/RNBQK2R

                > position startpos e2e4 e7e5 g1f3 b8c6 f1c4 f8c5
Now that the GUI gave the position, GUI can ask the engine to perform calculations on that board. The go command can be followed by numerous commands that can limit the depth, search moves, and nodes or provide information about the chess clock. However, for simplicity, let us assume go infinite, which tells the engine to search until stop command is given.

While the search is happening, the chess engine can provide the GUI information about how its search is going. There are numerous information that can be given, but some of the most popular ones are: depth for depth of search; time for milliseconds spent searching; nodes for number of nodes searched; pv for the principal variation found; score for relative score of the board on centipawns; and mate if the engine found a mate in certain plies. These give great information about the efficiency of the chess engine.

The chess engine can call info many times, but I recommend that info is only be called when significant change has occured to the search: if the engine moves on to the next depth; if a better principal variation has been found; or if a mate has been found.

                > go infinite 
< info ...
> stop
< bestmove ...
After the search function has been completed or after the stop command is given, the chess engine needs to tell the GUI which move it wants to make. This can be done using bestmove command.

Conclusion

As the short page suggests, the basic UCI protocol is very easy to implement. Yet it offers amazing customizability when option and setoption commands are used. If you have developed a chess engine that you want to test against humans or other chess engines, implement a basic UCI protocol! It will make the test a lot simpler :)