The UCI Protocol

This page aims to provide a basic description of the UCI Protocol and all of its commands.
This page is based on this document.

• The UCI protocol is an asymetric protocol with to sides, refered to as ENGINE and GUI.

• All communication with the Engine happens via stdin/stdout in form of text commands.

• The engine must always be able to process input from stdin, even while thinking.

• All commands are terminated with a line ending.
  Note: Line ending encodings vary between different os

  Windows	Unix	Legacy Mac
  <CR><LF>	<LF>	<CR>

• unknown commands and tokens must be handled gracefully, i.e.: should be ignored.

• if the engine receiveces a command wich is not supposed to come, it should ignored.

• The engine should boot and wait for input from the GUI, the engine should wait for the isready or setoption command to set up its internal parameters.

• By default all the opening book handling is done by the GUI, however there is an option for the engine to use its own book.

• The GUI must send a position command before it sends one or more go commands

• The engine will always be in forced mode wich means it should never start calculating or pondering without receiving a go command first

Move Format

The move format is in long algebraic notation. A nullmove from the engine to the GUI should be send as 0000. Examples: e2e4, e7e5, e1g1 (white short castling), e7e8q (for promotion)

GUI commands

These are the commands send by the GUI to the engine.

UCI

uci

Tell engine to use the uci. This will be send once as a first command after program boot To tell the engine to switch to uci mode. After receiving the uci command the engine must identify itself with the "id" command and sent the "option" commands to tell the GUI which engine settings the engine supports if any. After that the engine should sent "uciok" to acknowledge the uci mode. If no uciok is sent within a certain time period, the engine task may be killed by the GUI.

Debug

debug on | off

Switch debug mode on or off. In debug mode the engine should sent additional infos to the GUI to help debugging. The engine should not be in debug mode by default and must be able to switch any time, even while thinking.

IsReady

isready

This is used to sync with the engine. When the GUI as sent commands that can take some time to complete, this command can be used to wait for the engine to be ready again or to ping the engine to find out if its still alive. This command is also required once before the engine is asked to do any search to wait for the engine to finish initializing.

SetOption

setoption name <name> [value <value>]

This is sent to the engine when the user wants to change the internal parameters of the engine. Changing multiple parameters requires multiple setoption commands. This command must be sent when the engine is waiting. <name> should not be case sensitive and may include spaces. <value> also may contain spaces. Note: To allow unambiguous parsing substrings "name" and "value" should be avoided in both, <name> and <value>

Register

register later
register name <name> code <code>

This is the command to try to register an engine or to tell the engine that registration will be done later. This command should always be sent if the engine has send registration error at program startup.

UciNewGame

ucinewgame

This is sent to the engine when the next search (started with position and go) will be from a different game. This can be a new game the engine should play or a new game it should analyse but also the next position from a testsuite with positions only. If the GUI hasn't sent a ucinewgame before the first position command, the engine shouldn't expect any further ucinewgame commands as the GUI is probably not supporting the ucinewgame command. So the engine should not rely on this command even though all new GUIs should support it. As the engine's reaction to ucinewgame can take some time the GUI should always send isready after ucinewgame to wait for the engine to finish its operation.

Position

position startpos [moves <moves>]
position fen <fen> [moves <moves>]

Tell the engine to set its internal board to <fen> or startpos and play the moves <moves> on it. If this position is from a different game, a ucinewgame command should have preceeded this one.

Go

go [options]

Start calculating on the current position set up with the position command. There are a number of options that can follow this command, all on the same line as the command. If an option is not send, its value should be interpreted as if it would not influence the search.

Options

• searchmoves <move>

  Restrict search to this moves only.

• ponder

  Start searching in pondering mode. Do not exit the search in ponder mode, even if its mate! This means that the last move sent in the position string is the ponder move. The engine can do what it wants to do, but after a ponderhit command it should execute the suggested move to ponder on. This means that the ponder move sent by the GUI can be interpreted as a recommendation about which move to ponder. However, if the engine decides to ponder on a different move, it should not display any mainlines as the are likely to be misinterpreted by the GUI because thie GUI expects the engine to ponder on the suggested move.

• wtime <x>
btime <x>

  white/black has x ms left on the clock

• winc <x>
binc <x>

  white/black increment per move in ms if x > 0

• movestogo <x>

  There are x moves to the next time control. This must only be sent if x > 0. if wtime and btime are sent but not this command, then its a sudden death.

• depth <x>

  search x plies only.

• nodes <x>

  search x nodes only

• mate <x>

  search for mate in x moves

• movetime <x>

  search for x ms, not more or less.

• infinite

  search until the stop command is sent by the GUI. The engine must not exit search without being told so in this mode.

Stop

stop

Stop calculating as soon as possible. The engine must answer with the bestmove command when finishing the search.

PonderHit

ponderhit

The user has played the expected move. This will be sent if the engine was told to ponder on the same move the user has played. The engine should continue searching but switch from pondering to normal search.

Quit

quit

Quit the program as soon as possible.

Engine commands

These are the commands send by the engine to the GUI.

Id

id name <name>
id author <author>

This must be sent after receiving the `uci command to identify the engine.

UciOk

uciok

Must be sent after the id and optional engine options to tell the GUI that the engine has sent all infos and is ready in uci mode.

ReadyOk

readyok

This must be sent when the engine has received an isready command and has processed all input and is ready to accept new commands now.

Bestmove

bestmove <move> [ponder <ponder-move>]

The engine has stopped searching and found the move best in this position. The engine can send the move it likes to ponder on. The engine must not start pondering automatically. This command must always be sent if the engine stops searching, also in pondering mode if there is a stop command, ie. for every go command a bestmove command is needed! Directly before that the engine should send a final info command with the final search information.

CopyProtection

copyprotection checking
copyprotection ok
copyprotection error

This is needed for copyprotected engines. After the uciok command the engine can tell the GUI, that it will check the copy protection now. If there is an error, the engine may not function properly but should not quit alone.

Registration

registration checking
registration ok
registration error

This is needed for engines that need a username and/or a code to function with all features. The engine must work, even if registration fails, but may disable features.

Info

info [infos]

The engine wants to send infos to the GUI. This should be done whenever one of the info has changed. The engine may choose which infos to send and infos may be grouped into one info command. All infos belonging to the pv should be sent together. It is suggested to start sending currmove, currmovenumber, currline and refutation only after one second to avoid to much traffic.

Infos

• depth <n> [seldepth <sn>]

  (selective) search depth in plies

• time <t>

  time searched in ms, should be send with pv

• nodes <n>

  n nodes searched, should be sent regularly

• pv <moves>

  the best line found

• multipv <k>

  This is for the multi pv mode. For the best move/pv add multipv 1 when you send the pv. in k-best mode always send all k variantsin k commands together.

• score [lowerbound | upperbound] [cp <x>] [mate <m>]

  • cp <x> - the score from the engines point of view in centipawns
  • mate <m> - mate in m moves, if the engine is getting mated use negativ values for m.
  • [lowerbound | upperbound] - the score is just a lower-/upperbound.

• currmove <move>

  currently searching this move

• currmovenumber <i>

  currently searching move number i (1-based indexing)

• hasfull <x>

  The hash is x permill full, the engine should send this info regularly.

• nps <x>

  x nodes per second searched, the engine should send this info regularly.

• tbhits <x>

  x positions where found in the endgame table bases.

• cpuload <x>

  The cpu usage of the engine is x permill

• string <info>

  if there is a string info, the rest of the line will be interpreted as .

• refutation <moves>

  The first move in moves is refuted by the line moves[2..]. If there is no refutation just the first move in moves should be sent. Sending this info depends on the value of the UCI_ShowRefutations option.

• currline [<thread-id>] <moves>

  This is the current line the engine is calculating. Sending this info depends on the value of the UCI_ShowCurrLine option.

Option

option name <name> type check | string default <default>
option name <name> type spin default <default> min <min> max <max>
option name <name> type combo default <default> var <var1> ...
option name <name> type button

This command tells the GUI which parameters can be changed in the engine. This should be sent once at engine startup after the "uci" and the "id" commands if they can be changed. One option per command.

Types

• check

  A checkbox that can either be true or false.

• spin

  A spin wheel that can be an integer in a certain range.

• combo

  A combo box that can have different predefined strings as value. All values must be passed seperate with the var option in the same command.

• button

  A button that can be pressed to send a command to the engine.

• string

  A text field, that has a string as a value. An empty string is send as ""

Predefined engine parameters (aka options)

These parameters have fixed semantics. Often, these parameters arent displayed by the GUI. Also any option prefixed by UCI_ shouldnt be displayed by the GUI, whether defined here or not.

Hash

option name Hash type spin ...

How much memory in MB hash tables should occupy. Since the engine should use a very small default value, the GUI should change this value to a higher option with the setoption command first thing after receiving this option command.

NalimovPath

option name NalimovPath type string ...

This is the path to the Nalimov compressed format. Multiple directories can be concatenated with ;.

NalimovCache

option name NalimovCache type spin ...

This is the size of the cache for the nalimov table bases in MB.

Ponder

option name Ponder type check ...

Engines that advertise this option are able to ponder. The GUI will send this whenever pondering is possible or not. Note: The engine should not start pondering on its own if this is enabled, this option is merely a hint if pondering is to be expected at all.

OwnBook

option name OwnBook type check ...

This means that the engine has its own book which is accessed by the engine itself. if this is true, the engine takes care of the opening book. If set to false, the engine should not access its own book.

MultiPV

option name MultiPV type spin default 1 ...

The engine supports multi best line or k-best mode.

UCI_ShowCurrLine

option name UCI_ShowCurrLine type check default false

The engine can show the current line it is calculating.

UCI_ShowRefutations

option name UCI_ShowRefutations type check default false

The engine can show a move and its refutation in a line.

UCI_LimitStrength

option name UCI_LimitStrength type chekc default false

The engine is able to limit its strength to a specific Elo number. This should always be implemented together with UCI_Elo.

UCI_Elo

option name UCI_Elo type spin ...

The engine can limit its strength in Elo within this interval. This should always be implemented together with UCI_LimitStrength

UCI_AnalyseMode

option name UCI_AnalyseMode type check ...

The engine wants to behave differently when analysing or playing a game. if this is set to false, the engine is playing a game.

UCI_Opponent

option name UCI_Opponent type string ...

With this, the GUI can send the name, title, elo and if the engine is playing against a human or a computer to the engine. REGEX: (?'title'GM|IM|FM|WGM|WIM|none) (?'elo'[1-9][0-9]*|none) (?'type'computer|human) (?'name'[ -~]+|none) More readable: (GM | IM | FM | WGM | WIM | none) (<elo> | none) (computer | human) (<name> | none)