UCI Protocol

Date: 2020-12-08 03:39:06

You can also download the original document from Shredder Chess. This document will contain any updates and examples for my own notes.

Skill levels

There are 3 things to adjust. Skill, move times, and depths. See some source at lichess.

Description of the universal chess interface (UCI) April 2006

Move format:

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

GUI to engine:

These are all the command the engine gets from the interface.

Engine to GUI:


This is how the communication when the engine boots can look like:

GUI engine

// tell the engine to switch to UCI mode uci

// engine identify
id name Shredder id author Stefan MK

// engine sends the options it can change // the engine can change the hash size from 1 to 128 MB option name Hash type spin default 1 min 1 max 128

// the engine supports Nalimov endgame tablebases option name NalimovPath type string default option name NalimovCache type spin default 1 min 1 max 32

// the engine can switch off Nullmove and set the playing style option name Nullmove type check default true option name Style type combo default Normal var Solid var Normal var Risky

// the engine has sent all parameters and is ready uciok

// Note: here the GUI can already send a "quit" command if it just wants to find out // details about the engine, so the engine should not initialize its internal // parameters before here. // now the GUI sets some values in the engine // set hash to 32 MB setoption name Hash value 32

// init tbs setoption name NalimovCache value 1 setoption name NalimovPath value d:\tb;c\tb

// waiting for the engine to finish initializing // this command and the answer is required here! isready

// engine has finished setting up the internal values readyok

// now we are ready to go

// if the GUI is supporting it, tell the engine that is is // searching on a game that it hasn't searched on before ucinewgame

// if the engine supports the "UCI_AnalyseMode" option and the next search is supposed to // be an analysis, the GUI should set "UCI_AnalyseMode" to true if it is currently // set to false with this engine setoption name UCI_AnalyseMode value true

// tell the engine to search infinite from the start position after 1.e4 e5 position startpos moves e2e4 e7e5 go infinite

// the engine starts sending infos about the search to the GUI // (only some examples are given)

    info depth 1 seldepth 0
    info score cp 13  depth 1 nodes 13 time 15 pv f1b5 
    info depth 2 seldepth 2
    info nps 15937
    info score cp 14  depth 2 nodes 255 time 15 pv f1c4 f8c5 
    info depth 2 seldepth 7 nodes 255
    info depth 3 seldepth 7
    info nps 26437
    info score cp 20  depth 3 nodes 423 time 15 pv f1c4 g8f6 b1c3 
    info nps 41562

// here the user has seen enough and asks to stop the searching stop

// the engine has finished searching and is sending the bestmove command // which is needed for every "go" command sent to tell the GUI // that the engine is ready again bestmove g1f3 ponder d8f6


UCI could easily be extended to support Chess960 (also known as Fischer Random Chess).

The engine has to tell the GUI that it is capable of playing Chess960 and the GUI has to tell the engine that is should play according to the Chess960 rules. This is done by the special engine option UCI_Chess960. If the engine knows about Chess960 it should send the command 'option name UCI_Chess960 type check default false' to the GUI at program startup. Whenever a Chess960 game is played, the GUI should set this engine option to 'true'.

Castling is different in Chess960 and the white king move when castling short is not always e1g1. A king move could both be the castling king move or just a normal king move. This is why castling moves are sent in the form king "takes" his own rook. Example: e1h1 for the white short castle move in the normal chess start position.

In EPD and FEN position strings specifying the castle rights with w and q is not enough as there could be more than one rook on the right or left side of the king. This is why the castle rights are specified with the letter of the castle rook's line. Upper case letters for white's and lower case letters for black's castling rights. Example: The normal chess position would be: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w AHah -

Copyright © 2020, Lee Patterson