uci/uci_protocol.txt

   1 /* With friendly permission, to public this document,
   2  * of Stefan-Mayer Kahlen
   3  * For more information or newer versions of the
   4  * UCI protcol please visit
   5  * http://www.shredderchess.de/download.html
   6  */
   7
   8 Description of the universal chess interface (UCI)    April 2004
   9 ================================================================
  10
  11 * The specification is independent of the operating system. For Windows,
  12   the engine is a normal exe file, either a console or "real" windows application.
  13
  14 * all communication is done via standard input and output with text commands,
  15
  16 * The engine should boot and wait for input from the GUI,
  17   the engine should wait for the "isready" or "setoption" command to set up its internal parameters
  18   as the boot process should be as quick as possible.
  19
  20 * the engine must always be able to process input from stdin, even while thinking.
  21
  22 * all command strings the engine receives will end with '\n',
  23   also all commands the GUI receives should end with '\n',
  24   Note: '\n' can be 0x0c or 0x0a0c or any combination depending on your OS.
  25   If you use Engine und GUI in the same OS this should be no problem if you cummunicate in text mode,
  26   but be aware of this when for example running a Linux engine in a Windows GUI.
  27
  28 * The engine will always be in forced mode which means it should never start calculating
  29   or pondering without receiving a "go" command first.
  30
  31 * Before the engine is asked to search on a position, there will always be a position command
  32   to tell the engine about the current position.
  33
  34 * by default all the opening book handling is done by the GUI,
  35   but there is an option for the engine to use its own book ("OwnBook" option, see below)
  36
  37 * if the engine or the GUI receives an unknown command or token it should just ignore it and try to
  38   parse the rest of the string.
  39
  40 * if the engine receives a command which is not supposed to come, for example "stop" when the engine is
  41   not calculating, it should also just ignore it.
  42
  43
  44 Move format:
  45 ------------
  46
  47 The move format is in long algebraic notation.
  48 A nullmove from the Engine to the GUI should be send as 0000.
  49 Examples:  e2e4, e7e5, e1g1 (white short castling), e7e8q (for promotion)
  50
  51
  52
  53 GUI to engine:
  54 --------------
  55
  56 These are all the command the engine gets from the interface.
  57
  58 * uci
  59         tell engine to use the uci (universal chess interface),
  60         this will be send once as a first command after program boot
  61         to tell the engine to switch to uci mode.
  62         After receiving the uci command the engine must identify itself with the "id" command
  63         and sent the "option" commands to tell the GUI which engine settings the engine supports if any.
  64         After that the engine should sent "uciok" to acknowledge the uci mode.
  65         If no uciok is sent within a certain time period, the engine task will be killed by the GUI.
  66
  67 * debug [ on | off ]
  68         switch the debug mode of the engine on and off.
  69         In debug mode the engine should sent additional infos to the GUI, e.g. with the "info string" command,
  70         to help debugging, e.g. the commands that the engine has received etc.
  71         This mode should be switched off by default and this command can be sent
  72         any time, also when the engine is thinking.
  73
  74 * isready
  75         this is used to synchronize the engine with the GUI. When the GUI has sent a command or
  76         multiple commands that can take some time to complete,
  77         this command can be used to wait for the engine to be ready again or
  78         to ping the engine to find out if it is still alive.
  79         E.g. this should be sent after setting the path to the tablebases as this can take some time.
  80         This command is also required once before the engine is asked to do any search
  81         to wait for the engine to finish initializing.
  82         This command must always be answered with "readyok" and can be sent also when the engine is calculating
  83         in which case the engine should also immediately answer with "readyok" without stopping the search.
  84
  85 * setoption name <id> [value <x>]
  86         this is sent to the engine when the user wants to change the internal parameters
  87         of the engine. For the "button" type no value is needed.
  88         One string will be sent for each parameter and this will only be sent when the engine is waiting.
  89         The name of the option in <id> should not be case sensitive and can inludes spaces like also the value.
  90         The substrings "value" and "name" should be avoided in <id> and <x> to allow unambiguous parsing,
  91         for example do not use <name> = "draw value".
  92         Here are some strings for the example below:
  93            "setoption name Nullmove value true\n"
  94       "setoption name Selectivity value 3\n"
  95            "setoption name Style value Risky\n"
  96            "setoption name Clear Hash\n"
  97            "setoption name NalimovPath value c:\chess\tb\4;c:\chess\tb\5\n"
  98
  99 * register
 100         this is the command to try to register an engine or to tell the engine that registration
 101         will be done later. This command should always be sent if the engine    has send "registration error"
 102         at program startup.
 103         The following tokens are allowed:
 104         * later
 105            the user doesn't want to register the engine now.
 106         * name <x>
 107            the engine should be registered with the name <x>
 108         * code <y>
 109            the engine should be registered with the code <y>
 110         Example:
 111            "register later"
 112            "register name Stefan MK code 4359874324"
 113
 114 * ucinewgame
 115    this is sent to the engine when the next search (started with "position" and "go") will be from
 116    a different game. This can be a new game the engine should play or a new game it should analyse but
 117    also the next position from a testsuite with positions only.
 118    If the GUI hasn't sent a "ucinewgame" before the first "position" command, the engine shouldn't
 119    expect any further ucinewgame commands as the GUI is probably not supporting the ucinewgame command.
 120    So the engine should not rely on this command even though all new GUIs should support it.
 121    As the engine's reaction to "ucinewgame" can take some time the GUI should always send "isready"
 122    after "ucinewgame" to wait for the engine to finish its operation.
 123
 124 * position [fen <fenstring> | startpos ]  moves <move1> .... <movei>
 125         set up the position described in fenstring on the internal board and
 126         play the moves on the internal chess board.
 127         if the game was played  from the start position the string "startpos" will be sent
 128         Note: no "new" command is needed. However, if this position is from a different game than
 129         the last position sent to the engine, the GUI should have sent a "ucinewgame" inbetween.
 130
 131 * go
 132         start calculating on the current position set up with the "position" command.
 133         There are a number of commands that can follow this command, all will be sent in the same string.
 134         If one command is not send its value should be interpreted as it would not influence the search.
 135         * searchmoves <move1> .... <movei>
 136                 restrict search to this moves only
 137                 Example: After "position startpos" and "go infinite searchmoves e2e4 d2d4"
 138                 the engine should only search the two moves e2e4 and d2d4 in the initial position.
 139         * ponder
 140                 start searching in pondering mode.
 141                 Do not exit the search in ponder mode, even if it's mate!
 142                 This means that the last move sent in in the position string is the ponder move.
 143                 The engine can do what it wants to do, but after a "ponderhit" command
 144                 it should execute the suggested move to ponder on. This means that the ponder move sent by
 145                 the GUI can be interpreted as a recommendation about which move to ponder. However, if the
 146                 engine decides to ponder on a different move, it should not display any mainlines as they are
 147                 likely to be misinterpreted by the GUI because the GUI expects the engine to ponder
 148            on the suggested move.
 149         * wtime <x>
 150                 white has x msec left on the clock
 151         * btime <x>
 152                 black has x msec left on the clock
 153         * winc <x>
 154                 white increment per move in mseconds if x > 0
 155         * binc <x>
 156                 black increment per move in mseconds if x > 0
 157         * movestogo <x>
 158       there are x moves to the next time control,
 159                 this will only be sent if x > 0,
 160                 if you don't get this and get the wtime and btime it's sudden death
 161         * depth <x>
 162                 search x plies only.
 163         * nodes <x>
 164            search x nodes only,
 165         * mate <x>
 166                 search for a mate in x moves
 167         * movetime <x>
 168                 search exactly x mseconds
 169         * infinite
 170                 search until the "stop" command. Do not exit the search without being told so in this mode!
 171
 172 * stop
 173         stop calculating as soon as possible,
 174         don't forget the "bestmove" and possibly the "ponder" token when finishing the search
 175
 176 * ponderhit
 177         the user has played the expected move. This will be sent if the engine was told to ponder on the same move
 178         the user has played. The engine should continue searching but switch from pondering to normal search.
 179
 180 * quit
 181         quit the program as soon as possible
 182
 183
 184 Engine to GUI:
 185 --------------
 186
 187 * id
 188         * name <x>
 189                 this must be sent after receiving the "uci" command to identify the engine,
 190                 e.g. "id name Shredder X.Y\n"
 191         * author <x>
 192                 this must be sent after receiving the "uci" command to identify the engine,
 193                 e.g. "id author Stefan MK\n"
 194
 195 * uciok
 196         Must be sent after the id and optional options to tell the GUI that the engine
 197         has sent all infos and is ready in uci mode.
 198
 199 * readyok
 200         This must be sent when the engine has received an "isready" command and has
 201         processed all input and is ready to accept new commands now.
 202         It is usually sent after a command that can take some time to be able to wait for the engine,
 203         but it can be used anytime, even when the engine is searching,
 204         and must always be answered with "isready".
 205
 206 * bestmove <move1> [ ponder <move2> ]
 207         the engine has stopped searching and found the move <move> best in this position.
 208         the engine can send the move it likes to ponder on. The engine must not start pondering automatically.
 209         this command must always be sent if the engine stops searching, also in pondering mode if there is a
 210         "stop" command, so for every "go" command a "bestmove" command is needed!
 211         Directly before that the engine should send a final "info" command with the final search information,
 212         the the GUI has the complete statistics about the last search.
 213
 214 * copyprotection
 215         this is needed for copyprotected engines. After the uciok command the engine can tell the GUI,
 216         that it will check the copy protection now. This is done by "copyprotection checking".
 217         If the check is ok the engine should sent "copyprotection ok", otherwise "copyprotection error".
 218         If there is an error the engine should not function properly but should not quit alone.
 219         If the engine reports "copyprotection error" the GUI should not use this engine
 220         and display an error message instead!
 221         The code in the engine can look like this
 222       TellGUI("copyprotection checking\n");
 223            // ... check the copy protection here ...
 224            if(ok)
 225               TellGUI("copyprotection ok\n");
 226       else
 227          TellGUI("copyprotection error\n");
 228
 229 * registration
 230         this is needed for engines that need a username and/or a code to function with all features.
 231         Analog to the "copyprotection" command the engine can send "registration checking"
 232         after the uciok command followed by either "registration ok" or "registration error".
 233         Also after every attempt to register the engine it should answer with "registration checking"
 234         and then either "registration ok" or "registration error".
 235         In contrast to the "copyprotection" command, the GUI can use the engine after the engine has
 236         reported an error, but should inform the user that the engine is not properly registered
 237         and might not use all its features.
 238         In addition the GUI should offer to open a dialog to
 239         enable registration of the engine. To try to register an engine the GUI can send
 240         the "register" command.
 241         The GUI has to always answer with the "register" command        if the engine sends "registration error"
 242         at engine startup (this can also be done with "register later")
 243         and tell the user somehow that the engine is not registered.
 244         This way the engine knows that the GUI can deal with the registration procedure and the user
 245         will be informed that the engine is not properly registered.
 246
 247 * info
 248         the engine wants to send infos to the GUI. This should be done whenever one of the info has changed.
 249         The engine can send only selected infos and multiple infos can be send with one info command,
 250         e.g. "info currmove e2e4 currmovenumber 1" or
 251              "info depth 12 nodes 123456 nps 100000".
 252         Also all infos belonging to the pv should be sent together
 253         e.g. "info depth 2 score cp 214 time 1242 nodes 2124 nps 34928 pv e2e4 e7e5 g1f3"
 254         I suggest to start sending "currmove", "currmovenumber", "currline" and "refutation" only after one second
 255         to avoid too much traffic.
 256         Additional info:
 257         * depth <x>
 258                 search depth in plies
 259         * seldepth <x>
 260                 selective search depth in plies,
 261                 if the engine sends seldepth there must also a "depth" be present in the same string.
 262         * time <x>
 263                 the time searched in ms, this should be sent together with the pv.
 264         * nodes <x>
 265                 x nodes searched, the engine should send this info regularly
 266         * pv <move1> ... <movei>
 267                 the best line found
 268         * multipv <num>
 269                 this for the multi pv mode.
 270                 for the best move/pv add "multipv 1" in the string when you send the pv.
 271                 in k-best mode always send all k variants in k strings together.
 272         * score
 273                 * cp <x>
 274                         the score from the engine's point of view in centipawns.
 275                 * mate <y>
 276                         mate in y moves, not plies.
 277                         If the engine is getting mated use negativ values for y.
 278                 * lowerbound
 279               the score is just a lower bound.
 280                 * upperbound
 281                    the score is just an upper bound.
 282         * currmove <move>
 283                 currently searching this move
 284         * currmovenumber <x>
 285                 currently searching move number x, for the first move x should be 1 not 0.
 286         * hashfull <x>
 287                 the hash is x permill full, the engine should send this info regularly
 288         * nps <x>
 289                 x nodes per second searched, the engine should send this info regularly
 290         * tbhits <x>
 291                 x positions where found in the endgame table bases
 292         * cpuload <x>
 293                 the cpu usage of the engine is x permill.
 294         * string <str>
 295                 any string str which will be displayed be the engine,
 296                 if there is a string command the rest of the line will be interpreted as <str>.
 297         * refutation <move1> <move2> ... <movei>
 298            move <move1> is refuted by the line <move2> ... <movei>, i can be any number >= 1.
 299            Example: after move d1h5 is searched, the engine can send
 300            "info refutation d1h5 g6h5"
 301            if g6h5 is the best answer after d1h5 or if g6h5 refutes the move d1h5.
 302            if there is norefutation for d1h5 found, the engine should just send
 303            "info refutation d1h5"
 304                 The engine should only send this if the option "UCI_ShowRefutations" is set to true.
 305         * currline <cpunr> <move1> ... <movei>
 306            this is the current line the engine is calculating. <cpunr> is the number of the cpu if
 307            the engine is running on more than one cpu. <cpunr> = 1,2,3....
 308            if the engine is just using one cpu, <cpunr> can be omitted.
 309            If <cpunr> is greater than 1, always send all k lines in k strings together.
 310                 The engine should only send this if the option "UCI_ShowCurrLine" is set to true.
 311
 312
 313 * option
 314         This command tells the GUI which parameters can be changed in the engine.
 315         This should be sent once at engine startup after the "uci" and the "id" commands
 316         if any parameter can be changed in the engine.
 317         The GUI should parse this and build a dialog for the user to change the settings.
 318         Note that not every option needs to appear in this dialog as some options like
 319         "Ponder", "UCI_AnalyseMode", etc. are better handled elsewhere or are set automatically.
 320         If the user wants to change some settings, the GUI will send a "setoption" command to the engine.
 321         Note that the GUI need not send the setoption command when starting the engine for every option if
 322         it doesn't want to change the default value.
 323         For all allowed combinations see the example below,
 324         as some combinations of this tokens don't make sense.
 325         One string will be sent for each parameter.
 326         * name <id>
 327                 The option has the name id.
 328                 Certain options have a fixed value for <id>, which means that the semantics of this option is fixed.
 329                 Usually those options should not be displayed in the normal engine options window of the GUI but
 330                 get a special treatment. "Pondering" for example should be set automatically when pondering is
 331                 enabled or disabled in the GUI options. The same for "UCI_AnalyseMode" which should also be set
 332                 automatically by the GUI. All those certain options have the prefix "UCI_" except for the
 333                 first 6 options below. If the GUI get an unknown Option with the prefix "UCI_", it should just
 334                 ignore it and not display it in the engine's options dialog.
 335                 * <id> = Hash, type is spin
 336                         the value in MB for memory for hash tables can be changed,
 337                         this should be answered with the first "setoptions" command at program boot
 338                         if the engine has sent the appropriate "option name Hash" command,
 339                         which should be supported by all engines!
 340                         So the engine should use a very small hash first as default.
 341                 * <id> = NalimovPath, type string
 342                         this is the path on the hard disk to the Nalimov compressed format.
 343                         Multiple directories can be concatenated with ";"
 344                 * <id> = NalimovCache, type spin
 345                         this is the size in MB for the cache for the nalimov table bases
 346                         These last two options should also be present in the initial options exchange dialog
 347                         when the engine is booted if the engine supports it
 348                 * <id> = Ponder, type check
 349                         this means that the engine is able to ponder.
 350                         The GUI will send this whenever pondering is possible or not.
 351                         Note: The engine should not start pondering on its own if this is enabled, this option is only
 352                         needed because the engine might change its time management algorithm when pondering is allowed.
 353                 * <id> = OwnBook, type check
 354                         this means that the engine has its own book which is accessed by the engine itself.
 355                         if this is set, the engine takes care of the opening book and the GUI will never
 356                         execute a move out of its book for the engine. If this is set to false by the GUI,
 357                         the engine should not access its own book.
 358                 * <id> = MultiPV, type spin
 359                         the engine supports multi best line or k-best mode. the default value is 1
 360                 * <id> = UCI_ShowCurrLine, type check, should be false by default,
 361                         the engine can show the current line it is calculating. see "info currline" above.
 362                 * <id> = UCI_ShowRefutations, type check, should be false by default,
 363                         the engine can show a move and its refutation in a line. see "info refutations" above.
 364                 * <id> = UCI_LimitStrength, type check, should be false by default,
 365                         The engine is able to limit its strength to a specific Elo number,
 366                    This should always be implemented together with "UCI_Elo".
 367                 * <id> = UCI_Elo, type spin
 368                         The engine can limit its strength in Elo within this interval.
 369                         If UCI_LimitStrength is set to false, this value should be ignored.
 370                         If UCI_LimitStrength is set to true, the engine should play with this specific strength.
 371                    This should always be implemented together with "UCI_LimitStrength".
 372                 * <id> = UCI_AnalyseMode, type check
 373                    The engine wants to behave differently when analysing or playing a game.
 374                    For example when playing it can use some kind of learning.
 375                    This is set to false if the engine is playing a game, otherwise it is true.
 376                  * <id> = UCI_Opponent, type string
 377                    With this command the GUI can send the name, title, elo and if the engine is playing a human
 378                    or computer to the engine.
 379                    The format of the string has to be [GM|IM|FM|WGM|WIM|none] [<elo>|none] [computer|human] <name>
 380                    Example:
 381                    "setoption name UCI_Opponent value GM 2800 human Gary Kasparow"
 382                    "setoption name UCI_Opponent value none none computer Shredder"
 383
 384
 385         * type <t>
 386                 The option has type t.
 387                 There are 5 different types of options the engine can send
 388                 * check
 389                         a checkbox that can either be true or false
 390                 * spin
 391                         a spin wheel that can be an integer in a certain range
 392                 * combo
 393                         a combo box that can have different predefined strings as a value
 394                 * button
 395                         a button that can be pressed to send a command to the engine
 396                 * string
 397                         a text field that has a string as a value,
 398                         an empty string has the value "<empty>"
 399         * default <x>
 400                 the default value of this parameter is x
 401         * min <x>
 402                 the minimum value of this parameter is x
 403         * max <x>
 404                 the maximum value of this parameter is x
 405         * var <x>
 406                 a predefined value of this parameter is x
 407         Example:
 408     Here are 5 strings for each of the 5 possible types of options
 409            "option name Nullmove type check default true\n"
 410       "option name Selectivity type spin default 2 min 0 max 4\n"
 411            "option name Style type combo default Normal var Solid var Normal var Risky\n"
 412            "option name NalimovPath type string default c:\\n"
 413            "option name Clear Hash type button\n"
 414
 415
 416
 417 Example:
 418 --------
 419
 420 This is how the communication when the engine boots can look like:
 421
 422 GUI     engine
 423
 424 // tell the engine to switch to UCI mode
 425 uci
 426
 427 // engine identify
 428       id name Shredder
 429                 id author Stefan MK
 430
 431 // engine sends the options it can change
 432 // the engine can change the hash size from 1 to 128 MB
 433                 option name Hash type spin default 1 min 1 max 128
 434
 435 // the engine supports Nalimov endgame tablebases
 436                 option name NalimovPath type string default <empty>
 437                 option name NalimovCache type spin default 1 min 1 max 32
 438
 439 // the engine can switch off Nullmove and set the playing style
 440            option name Nullmove type check default true
 441                 option name Style type combo default Normal var Solid var Normal var Risky
 442
 443 // the engine has sent all parameters and is ready
 444                 uciok
 445
 446 // Note: here the GUI can already send a "quit" command if it just wants to find out
 447 //       details about the engine, so the engine should not initialize its internal
 448 //       parameters before here.
 449 // now the GUI sets some values in the engine
 450 // set hash to 32 MB
 451 setoption name Hash value 32
 452
 453 // init tbs
 454 setoption name NalimovCache value 1
 455 setoption name NalimovPath value d:\tb;c\tb
 456
 457 // waiting for the engine to finish initializing
 458 // this command and the answer is required here!
 459 isready
 460
 461 // engine has finished setting up the internal values
 462                 readyok
 463
 464 // now we are ready to go
 465
 466 // if the GUI is supporting it, tell the engine that is is
 467 // searching on a game that is hasn't searched on before
 468 ucinewgame
 469
 470 // if the engine supports the "UCI_AnalyseMode" option and the next search is supposted to
 471 // be an analysis, the GUI should set "UCI_AnalyseMode" to true if it is currently
 472 // set to false with this engine
 473 setoption name UCI_AnalyseMode value true
 474
 475 // tell the engine to search infinite from the start position after 1.e4 e5
 476 position startpos moves e2e4 e7e5
 477 go infinite
 478
 479 // the engine starts sending infos about the search to the GUI
 480 // (only some examples are given)
 481
 482
 483                 info depth 1 seldepth 0
 484                 info score cp 13  depth 1 nodes 13 time 15 pv f1b5
 485                 info depth 2 seldepth 2
 486                 info nps 15937
 487                 info score cp 14  depth 2 nodes 255 time 15 pv f1c4 f8c5
 488                 info depth 2 seldepth 7 nodes 255
 489                 info depth 3 seldepth 7
 490                 info nps 26437
 491                 info score cp 20  depth 3 nodes 423 time 15 pv f1c4 g8f6 b1c3
 492                 info nps 41562
 493                 ....
 494
 495
 496 // here the user has seen enough and asks to stop the searching
 497 stop
 498
 499 // the engine has finished searching and is sending the bestmove command
 500 // which is needed for every "go" command sent to tell the GUI
 501 // that the engine is ready again
 502                 bestmove g1f3 ponder d8f6