Debian Codegraph @

doc/Universal Chess Interface

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