UCI

Home * Protocols * UCI

UCI, (Universal Chess Interface) an open communication protocol for chess engines to play games automatically, that is to communicate with other programs including Graphical User Interfaces. UCI was designed and developed by Rudolf Huber and Stefan Meyer-Kahlen, and released in November 2000. It has, by-in-large, replaced the older Chess Engine Communication Protocol (WinBoard/XBoard).

=Design Philosophy= The UCI capable GUI is not only View and Controller of a chess MVC, but also keeps the Model with its internal game states. It is also an "arbiter" instance to decide about the outcome of the game, for instance in declaring a game to be drawn after a threefold repetition has occurred. The UCI GUI may choose and play moves from an opening book and endgame tablebase.

=Critique= While the UCI design makes it simple for engine programmers to integrate a "stateless" chess engine, it was also disputed by various chess programmers, since it subsumes engine control parameters and delegates possibly game decisive stuff to the GUI.

Contra

 * GUIs may send very long commands (for chess positions) to chess engines
 * It is hard for chess engines to process input/output without an extra thread for that duty
 * Missing some useful commands/info: inform chess engines the results, no information about after movestogo GUIs will reset clock or not

Excerpt concerning UCI from a Robert Hyatt interview by Frank Quisinsky in 2002 : I simply don't like UCI. It subsumes all engine control parameters. It tells the engine when to ponder, when to search, when to stop, etc. That is contrary to my design and I have no interest in hacking Crafty to support something that is so different from the WinBoard/XBoard protocol that has been around for a long time and which works perfectly.

It removes several critical engine-decisions that are best made by the engine, not the GUI.

Harm Geert Muller wrote on a Talkchess thread

IMO statelessness w.r.t. the game state (including clocks) in UCI was a very bad idea. It is not only that it makes the communication unnecessarily verbose, but w.r.t. clocks there is a real problem: in classical TC the timing info accompanying the 'go' command does not specify how much time will be added after the 'movestogo' have been played. With movestogo=1 and wtime/btime=59000 you could be in a 40moves/hour game, at the brink of receiving another hour for the next 40 moves, in which case it would be wise to completely spend the remaining 59 sec on the upcoming move, as this is already below average. But you could also be in a 40moves/min game, where you got out of book after 39 moves, and receive only 1 new minute for the next 40. Wasting the 59 sec on a single move now effectively reduces your time for the second session by a factor 2, which would be very sub-optimal. The time management in this case should act like you have 1:59 for 41 moves (but be aware of a 'cold-turkey deadline' for the upcoming move). There is no way a UCI engine could know this.

Pro

 * Statelessness. That reduces unsynchronised problems between chess GUIs and engines
 * Chess systems (chess GUIs and chess engines) may work more stably
 * Remove the need of having extra configuration/init files for engines
 * Easier for chess engine developers to support: easy to parse, create commands, almost no ambiguous, straight/simple code since it is almost not required automatic algorithms
 * Easier for debugging: easy to start a match from the middle of a game (using various opening types); easy to pick up a position from long logs (for debugging purposes)
 * Almost all new and/or strong chess engines support UCI
 * Almost all chess GUIs support

Fabien Letouzey emphasize the ease of implementation in a Quisinsky interview, April 05, 2005 : The choice of UCI is based on software-design principles that are not easy to explain. It's a programmer's thing really, I don't expect engine users to understand. Let me give you a clue though: think about young WinBoard engines that you have tried; how many handled pondering ... without bugs??? Another clue might be that surely, Stefan Meyer-Kahlen knows a lot about good programming, right? So trust him if not me, UCI is good for programmers because it leads to fewer bugs in the code ... Fabien wrote a protocol translation program, PolyGlot to allow use of the new protocol on Linux, though this is now supported natively by the powerful Scid vs. PC toolkit. Scid vs. PC itself includes Polyglot code to enable support for Polyglot opening books.

Marco Costalba replied Robert Hyatt on a Talkchess thread

The protocol is brilliant (and you can clearly realize it was designed by a very good programmer) because allows the code needed to handle it to be: - Straightforward - Simple (meaning with the minimal number of 'if' branches and logic) - General (meaning the same algorithm can handle all the different cases in an uniform fashion). The aim of the UCI protocol is to make the code simple, that's why I think it was made for programmers by a (great) programmer.

Nguyen Pham replied Harm Geert Muller on a Talkchess thread

UCI's statelessness is surely not a bad idea. Your example did not prove that (it is a bad idea) but just point out a flawed detail on UCI design. A stateless protocol means a chess GUI must provide enough information each time an engine starts thinking. In your example, it cannot send enough information about the timer since the protocol does not mention it. It is not a big deal since programmers can solve that issue easily by adding some assumes. Of course, it is better one day we can fix those flawed details in the protocol (version 2?).

I have written engines with both protocols (UCI, WB) and now support them all in my own chess GUI. Thus I have my own ideas about the strong points of each. Both are so good and can do so well their jobs. The stateless idea is the central point of UCI, which makes it a bit more suitable for modern computers and programming - that is why recently it becomes very popular.

=Engines= =GUIs=
 * UCI Engines
 * Linux UCI Engines
 * Aquarium
 * Arena
 * Banksia
 * Banksia GUI
 * Chess Assistant
 * ChessBase (Database)
 * Chess for Android
 * ChessPartner
 * Chess Wizard
 * Cute Chess
 * Fritz GUI
 * HIARCS Chess Explorer
 * Jerry
 * jose
 * Kvetka
 * LittleBlitzer
 * PyChess
 * SCID
 * Scid vs. PC
 * Scidb
 * Shredder GUI
 * Tarrasch

=CLIs=
 * Cutechess-cli
 * c-chess-cli

=Utilities=
 * InBetween
 * JSUCI
 * PolyGlot
 * Wb2UCI
 * UCI2WB

=See also=
 * Chess Engine Communication Protocol
 * CPW-Engine_com
 * Engine Testing
 * USI - Universal Shogi Interface
 * Vice UCI-Videos
 * WinBoard
 * XBoard

=Forum Posts=

2000 ...

 * UCI (=universal chess interface) by Stefan Meyer-Kahlen, CCC, November 28, 2000
 * UCI Issues by Peter McKenzie, CCC, February 25, 2001
 * UCI - a good idea? by David Rasmussen, CCC, December 15, 2001
 * Delphi and the UCI Protokoll by Martin Bauer, CCC, April 18, 2002 » Delphi
 * One more time Delphi and UCI by Martin Bauer, CCC, April 21, 2002
 * UCI versus Winboard by Bas Hamstra, CCC, August 21, 2002
 * UCI - Worth Implementing? by David Rasmussen, CCC, December 07, 2002
 * UCI-protocoll and engines. score cp (x) by Juergen Wolf, CCC, April 01, 2003
 * Extension of the UCI protocol by Stefan Meyer-Kahlen, CCC, April 15, 2004

2005 ...

 * How to implement the UCI command "currline" by Josué Forte, Winboard Forum, April 24, 2005
 * UCI protocol question by Jon Dart, CCC, October 04, 2005
 * UCI protocol and SMP by Aart Bik, CCC, November 13, 2008 » Parallel Search, SMP
 * Appeal to SMP-engines programmers using UCI by Harm Geert Muller, CCC, January 09, 2009
 * UCI protocol in winboard by Engin Üstün, Winboard Forum, September 24, 2009 » Chess Engine Communication Protocol, WinBoard

2010 ...
2011 2012 2013 2014
 * Handling UCI protocol and Stockfish / Glaurung behavior by Pascal Georges, CCC, January 10, 2010 » Stockfish, Glaurung
 * UCI extensions for kibitzing by Aaron Becker, CCC, March 05, 2010
 * UCI issues by Miguel A. Ballicora, CCC, May 24, 2010
 * UCI-compatible interface for 10x8 chess? by Norbert Raimund Leisner, CCC, December 17, 2010
 * some UCI protocol issues/questions by Jon Dart, CCC, December 17, 2010
 * SMP for Android UCI engines by Aart Bik, CCC, April 14, 2011 » Android, SMP
 * UCI multipv question by Martin Sedlak, CCC, June 11, 2011 » Multi-PV
 * UCI nullmove by Marco Costalba, CCC, August 03, 2011
 * UCI Engine Tuning by Steven Atkinson, CCC, August 20, 2011
 * About UCI multipv by Fermin Serrano, CCC, January 17, 2012 » Multi-PV
 * good macintosh guy for UCI engine development by Sam Hamilton, CCC, January 25, 2012 » GUI, Macintosh, Mac OS
 * Remote UCI engines and port forwarding by itias, OpenChess Forum, August 01, 2012
 * Ponder and UCI by geko, OpenChess Forum, November 19, 2012 » Pondering
 * Problem with UCI engines hash in Arena by Carl Langan, CCC, December 26, 2012 » Arena
 * UCI Programming by CDaley11, OpenChess Forum, January 15, 2013
 * UCI protocol not working by CDaley11, OpenChess Forum, January 27, 2013
 * UCI Interfacing question by epideath, OpenChess Forum, July 05, 2013
 * UCI protocol issue by Jon Dart, CCC, July 27, 2013 » Repetitions
 * uci ponder protocol by Marco Belli, CCC, August 17, 2013 » Pondering
 * UCI variants support by Balint Pfliegel, CCC, December 15, 2013
 * JSUCI 1.0 - connect javascript chess engines to UCI by Edmund Moshammer, CCC, March 28, 2014 » JavaScript
 * MadChess UCI_LimitStrength Algorithm by Erik Madsen, CCC, April 12, 2014 » MadChess, Playing Strength
 * UCI, ownbooks, and a potential problem by Miguel A. Ballicora, CCC, June 16, 2014 » Opening Book
 * UCI exclude move by Steven Atkinson, CCC, July 30, 2014
 * UCI Protocol by jay dee, CCC, August 31, 2014
 * PV after stop/readyok by Steven Atkinson, CCC, October 20, 2014
 * UCCI2WB by Harm Geert Muller, CCC, October 27, 2014 » Chinese Chess
 * UCI protocol for chess variants by Evert Glebbeek, CCC, October 28, 2014
 * How does input console for UCI work ? by Piotr Lopusiewicz, CCC, December 20, 2014

2015 ...

 * UCI request answers all time..... how to do it? by Luis Babboni, CCC, March 14, 2015
 * UCI way to communications. Wich kind of inputs? by Luis Babboni, CCC, March 15, 2015
 * UCI extension: nodestime by Marco Costalba, CCC, March 22, 2015
 * UCI extension: nps NODE_RATE by Marco Costalba, CCC, March 23, 2015
 * ponder engine-gui interaction by Alexandru Mosoi, CCC, June 25, 2015 » Pondering
 * Crafty UCI version by Marek Soszynski, July 10, 2015 » Crafty
 * UCI OwnBook shim? by Ian Osgood, CCC, November 07, 2015 » PolyGlot
 * Ugly UCI by Fermin Serrano, CCC, November 27, 2015
 * Re: Ugly UCI by Marcel van Kervinck, CCC, November 27, 2015

2016 2017 2018 2019
 * stateless UCI by Marco Belli, CCC, February 13, 2016 » Pondering
 * Question to UCI engine authors by Harm Geert Muller, CCC, December 01, 2016
 * UCI protocol: letting the engine know the game result by Folkert van Heusden, CCC, January 19, 2017
 * UCI: Console Play Mode? by Matthew Hull, CCC, February 20, 2017
 * Novag UCB drivers (Winboard and UCI) by Graham O'Neill, CCC, February 24, 2017 » Novag Universal Electronic Chess Board
 * Reporting a draw in UCI by Vince Sempronio, CCC, May 05, 2017 » Draw
 * UCI, What command should the engine expect while it's searching by Mahmoud Uthman, CCC, June 09, 2017
 * UCI on another thread, programming help ! by Mahmoud Uthman, CCC, June 11, 2017
 * UCI error codes? by Rasmus Althoff, CCC, July 21, 2017
 * Regarding UCI Pondering by Manik Charan, CCC, September 28, 2017 » Pondering
 * Loading opening book and tablebases (xboard vs uci) by Pedro Castro, CCC, October 15, 2017 » Chess Engine Communication Protocol
 * UCI pondering or infinite search by Lucas Braesch, CCC, November 10, 2017 » Pondering
 * Regarding options ponder flag by Jürgen Précour, CCC, December 06, 2017 » Pondering
 * UCI vs Winboard question by Michael Sherwin, CCC, March 05, 2018 » Chess Engine Communication Protocol, WinBoard
 * UCI Pondering workaround by Andrew Grant, CCC, July 13, 2018 » Pondering
 * ExaChess interface UCI to program by Stuart Cracraft, CCC, October 20, 2018
 * UCI pondering done right 	by lucasart, CCC, December 16, 2018 » Pondering
 * UCI question by Ed Schröder, CCC, January 28, 2019
 * Ambiguous: UCI and option Clear Hash by Nguyen Pham, CCC, June 20, 2019
 * Sending pure comments using UCI protocol by Vivien Clauzon, CCC, August 21, 2019
 * Re: PGN standard, its improvement and standardization by Nguyen Pham, CCC, October 14, 2019 » from Portable Game Notation to Protocols
 * UCI Win/Draw/Loss reporting by Gian-Carlo Pascutto, CCC, October 22, 2019 » Pawn Advantage, Win Percentage, and Elo
 * UCI pondering and time management by Vivien Clauzon, CCC, December 30, 2019 » Pondering, Time Management

2020 ...
2021
 * UCI to CECP by Fulvio, CCC, April 07, 2020 » CECP
 * UCI Options, clarifation by Alan Cooper, CCC, April 10, 2020
 * Remote UCI by Daniel José Queraltó, CCC, September 26, 2020
 * UCI wrapper? by Kurt Lanc, CCC, November 13, 2020
 * UCI Gui to remote Linux Engine by Joshua Shriver, CCC, December 05, 2020 » GUI, Linux
 * Uci "go" command without other parameters by Vivien Clauzon, CCC, January 17, 2021
 * Missing input in ponder by Fabio Gobbato, CCC, April 15, 2021 » Pondering
 * Listening for GUI input when searching by Niels Abildskov, CCC, April 27, 2021 » GUI, Search, Thread
 * Reporting errors in UCI by Niels Abildskov, CCC, June 03, 2021

=External Links=
 * The UCI Specification from Shredder Chess
 * UCI protocol hosted by WBEC Ridderkerk
 * Universal Chess Interface From Wikipedia
 * Interview with SOS programmer Rudolf Huber in German language! by Frank Quisinsky, Arena Chess GUI 3.0 - Archive 9, 132, May 10, 2005 (Wayback Machine)

Implementations

 * UCI Engine Support for Android by Aart Bik
 * Back to the 80's with UCI by Ed Schröder » Mephisto
 * Senjo C++ UCI Adapter by Shawn Chidester » Clubfoot, C++
 * GitHub - freeeve/uci: a UCI (Universal Chess Interface) API for golang by Eve Freeman » Go (Programming Language)
 * nionita/chessNet · GitHub by Nicu Ionita » Haskell

JavaScript

 * Javascript Universal Chess Interface | Free software downloads at SourceForge.net by Edmund Moshammer
 * GitHub - ebemunk/node-uci: UCI Protocol for node.js - talk to chess engines painlessly by Buğra Fırat
 * node-uci Documentation


 * GitHub - imor/uci: A thin wrapper on a uci chess engine

=Video Tutorials=
 * An overview of the UCI protocol from a programmer's perspective by Jonathan Warkentin, YouTube Video


 * Implementing the UCI protocol in your engine (pseudo code) by Jonathan Warkentin, YouTube Video

=References= Up one Level