\input macros.tex %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \beginruby WIDTH = 210 HEIGHT = 297 HMARGIN = 50 VMARGIN = 50 \endruby% \pdfpagewidth⟦WIDTH⟧mm \pdfpageheight=⟦HEIGHT⟧mm \hoffset=⟦(HMARGIN-25.4).round(3)⟧mm \voffset=⟦(VMARGIN-25.4).round(3)⟧mm \hsize=⟦( WIDTH-HMARGIN*2).round(3)⟧mm \vsize=⟦(HEIGHT-VMARGIN*2).round(3)⟧mm %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \currentfamily={Alegreya Sans}% \currentweight={}% \currentsize=11% \syncfonts% \hangpun% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \pretolerance=1000 \baselineskip=16pt \parskip=8pt \parindent=0pt \raggedbottom \nopagenumbers \setbox0=\lastbox %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \def\comment#1{\ltgrey{#1}}% \newcount\majorcount \newcount\minorcount \def\major{\advance\majorcount by 1\minorcount=0\leavevmode\llap{\ltgrey{\the\majorcount}\hem}}% \def\minor{\advance\minorcount by 1\leavevmode\llap{\ltgrey{\the\majorcount·\the\minorcount}\hem}}% \def\fw{% \advance\currentsize by -1 \currentfamily={Operator}% \currentweight={ Book}% \syncfonts }% \def\sup#1{{% \currentsize=8 \currentfamily={Operator}% \currentweight={ Book}% \syncfonts \raise0.8ex\hbox{#1}% }}% \def\n{\hfil\penalty-10000}% \long\def\item#1{% \par \vskip-\parskip \leavevmode {\leftskip=0.9em\llap{\hbox to 0.9em{▶\hfil}}#1\par}% }% \def\inset#1{% \par \vskip-\parskip \leavevmode {\leftskip=0.9em #1\par}% }% \def\noskip{\vskip-\parskip}% \def\uni#1{{\caps u+#1}}% \def\cmd#1{\teal{#1}}% \def\tok#1{\teal{\fw #1}}% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \centerline{\letterspace{8}\caps UNIVERSAL CHESS INTERFACE} \centerline{\letterspace{4}\caps 2022 dec 29 • draft} \vskip2\baselineskip \major{\bf Introduction}\par \minor This specification governs the interaction between two processes named the \purple{client} and the \purple{engine}. \comment{Graphical interfaces, terminals, and scripts or utilities are examples of clients.} \minor The engine's stdin, stdout, and stderr must all be open file descriptors. \minor The sequence of bytes that the client sends to the engine (via the engine's stdin) must be valid {\caps utf-8}, and the Unicode scalar values that the client sends must be \uni{000a line feed}, \uni{000d carriage return}, or in the range \uni{0020} to \uni{007e} inclusive \comment{(in other words, printable {\caps ascii} characters and space)}. When the scalar value \uni{000d} appears it must be immediately followed by \uni{000a}. \minor The sequence of bytes that the engine sends to the client (via the engine's stdout) must be valid {\caps utf-8}. \comment{Non-{\caps ascii} characters are permitted so that the engine name, author names, and info messages can be represented.} When the scalar value \uni{000d} appears it must be immediately followed by \uni{000a}. \minor No requirements are placed upon the engine's stderr \comment{(for example, the engine's stderr may be directed to a null file, to the client's stdout or stderr, or to a log file)}, and there are no restrictions on the sequence of bytes that the engine writes to its stderr. \minor When the client or engine violate the requirements of this specification, a \purple{violation} is said to have occurred. When a violation occurs, or when the requirements of this specification are otherwise not met, this specification imposes no further requirements on the behavior of the client or engine. \minor There are conditions that resemble violations but that the client and engine are expected to handle; these are called \purple{errors}. \vskip\parskip \major{\bf Other Definitions}\par \minor A \purple{message} is a sequence consisting of \item{zero or more scalar values that are not \uni{000a}}\noskip followed by \item{the scalar value \uni{000a}.} \minor The scalar value \uni{000a} (or, if the scalar value \uni{000a} is preceded by the scalar value \uni{000d}, the sequence \uni{000d} \uni{000a}) is the message \purple{termination}. \comment{Note that both client and engine are required to handle both Unix- and Windows-style line endings.} \minor The sequence of scalar values in a message before the message termi\-nation is the message \purple{body}. \minor A \purple{token} is a maximally contiguous sequence of scalar values that are not \uni{0020 space} in the message body. \comment{Tokens are separated by whitespace. White\-space is any contiguous sequence of \uni{0020} in the message body.} \minor An \purple{algebraic} token is a token of the form [\tok{a}−\tok{h}][\tok{1}–\tok{8}][\tok{a}−\tok{h}][\tok{1}–\tok{8}][\tok{qrbn}]?. \minor A message whose body does not contain any tokens is \purple{empty}. \minor The first token of a message from the client to the engine is a \purple{command}. For any token \tok{\it cmd}, a message whose command is \tok{\it cmd} is a \purple{{\it cmd} message}. \minor The first token of a message from the engine to the client is a \purple{remark}. For any token \tok{\it rmk}, a message whose remark is \tok{\it rmk} is an \purple{{\it rmk} message}. \vskip\parskip \major{\bf States and Transitions} \minor At every point in time, given the history of messages between the client and engine, there is a corresponding \purple{state}. When the client or engine sends a message (that is, writes a message to the engine's stdin or stdout), the state may change; this is a \purple{transition}. \comment{Note that transitions occur when messages are written, not read.} \minor Empty messages may always be sent and must be ignored by the client and engine. Empty messages never cause a transition. \minor This specification begins to govern the interaction between the client and the engine when the client sends a well-formed \cmd{uci} message. %\comment{An empty history (when no messages have yet been sent) does not %correspond to any state.} \minor In the initial state, the client may not send a non\-empty message to the engine. The engine may send any message. If the engine sends a message that is not a well-formed \cmd{id}, \cmd{option}, \cmd{protocol}, \cmd{info}, or \cmd{uciok} message, the message must be ignored by the client. When the engine sends a well-formed \cmd{uciok} message, the state changes to \purple{idle}. \minor In the idle state, the client may send any message. If the client sends a non\-empty message that is not a well-formed \cmd{setoption}, \cmd{ucinewgame}, \cmd{isready}, \cmd{position}, \cmd{go}, \cmd{stop}, \cmd{debug}, or \cmd{quit} message, an error has occurred, and the engine may respond by sending an \cmd{info} message indicating that a client error has occurred; besides sending an \cmd{info} message, the engine must ignore the client message \comment{(in other words, the engine must behave as if no message was sent)}. When the client sends a well-formed \cmd{isready} message, the state changes to \purple{sync}. When the client sends a well-formed \cmd{go} message, the state changes to \purple{active}. \comment{Note that the engine cannot assume that a go message will be preceded by an isready message.} \minor In the idle state, the engine may send any message. If the engine sends a message that is not a well-formed \cmd{info} message, the message must be ignored by the client. \comment{In the idle state, the engine should be asleep or minimally utilize processing resources unless, for example, it is reconfiguring itself in response to a setoption message.} \minor In the sync state, the client may not send a non\-empty message to the engine. The engine may send any message. If the engine sends a message that is not a well-formed \cmd{info} or \cmd{readyok} message, the message must be ignored by the client. When the engine sends a well-formed \cmd{readyok} message, the state changes to idle. \minor In the active state, the client may send any message. If the client sends a non\-empty message that is not a well-formed \cmd{isready} or \cmd{stop} message, an error has occurred, and the engine may respond by sending an \cmd{info} message indicating that a client error has occurred; besides sending an \cmd{info} message, the engine must ignore the client message. When the client sends a well-formed \cmd{isready} message, the state changes to \purple{ping}. When the client sends a well-formed \cmd{stop} message, the state changes to \purple{halt}. \minor In the active state, the engine may send any message. If the engine sends a message that is not a well-formed \cmd{info} or \cmd{bestmove} message, the message must be ignored by the client. When the engine sends a well-formed \cmd{bestmove} message, the state changes to idle. \minor In the ping state, the client may not send a non\-empty message to the engine. The engine may send any message. If the engine sends a message that is not a well-formed \cmd{info}, \cmd{readyok}, or \cmd{bestmove} message, the message must be ignored by the client. When the engine sends a well-formed \cmd{readyok} message, the state changes to active. When the engine sends a well-formed \cmd{bestmove} message, the state changes to idle. \minor In the halt state, the client may not send a non\-empty message to the engine. If the engine sends a message that is not a well-formed \cmd{info} or \cmd{bestmove} message, the message must be ignored by the client. When the engine sends a well-formed \cmd{bestmove} message, the state changes to idle. \minor This specification stops governing the interaction between the client and the engine when the client sends a well-formed \cmd{quit} message in the idle state. Engines are recommended to shut down and terminate themselves. Clients are recommended to provide a grace period not less than 5 seconds before killing the engine. \comment{There is an interesting invariant that the state and transition rules should satisfy due to the nature of stdin and stdout.} \comment{The time that a message is read and processed necessarily occurs some duration after the time that the message is written ({\it sending a message} is merely {\it enqueuing,} not invoking a subroutine of the recipient's) and it impossible to atomically perform both a read and a write. More particularly, it is impossible for a process to guarantee that a write to stream {\caps f} is not preceded by a write to stream {\caps g} by some other process. Even if the process attempts to read {\caps g}, finds it empty, and immediately writes to {\caps f}, it is possible for an intervening write to {\caps g} to occur before the write to {\caps f} occurs.} \comment{As a result, if the transition from state {\caps a} to state {\caps b} is caused by the client sending a message, it is impossible to guarantee that a message sent by the engine in state {\caps a} can actually be read by the client in state {\caps a} (and not in state {\caps b}). Therefore, any message that the engine is allowed to send in state {\caps a} should be allowed in state {\caps b}. The same idea holds for transitions caused by the engine sending a message, so we can state the invariant generally as follows:} \comment{\it For distinct processes 1 and 2, for all pairs of states {\capsit a} and {\capsit b}, if a transition from {\capsit a} to {\capsit b} can be caused by process 1 sending a message, every messages that process 2 is allowed to send in state {\capsit a} must also be allowed in state {\capsit b}.} \vskip\parskip \major{\bf Timeouts} \minor The time between the client sending a well-formed \cmd{uci} message and the client reading a well-formed \cmd{uciok} message may not exceed an implementation-defined duration. \comment{For example, this may be caused by transmission latency, by the client or engine failing to read data or flush their writes, or by the engine performing excessive operations at startup.} This duration (the \purple{initialization timeout}) must not be less than 5 seconds. \minor The time between the client sending a well-formed \cmd{isready} message in the idle state and the client reading a well-formed \cmd{readyok} message may not exceed an implementation-defined duration. This duration (the \purple{reconfiguration timeout}) must not be less than 5 seconds. \minor The time between the client sending a well-formed \cmd{isready} message in the active state and the client reading a well-formed \cmd{readyok} message may not exceed an implementation-defined duration. This duration (the \purple{ping timeout}) must not be less than 1 second. \minor The time between the client sending a well-formed \cmd{stop} message in the active state and the client reading a well-formed \cmd{bestmove} message may not exceed an implementation-defined duration. This duration (the \purple{halt timeout}) must not be less than 1 second. \vskip\parskip \major{\bf Engine Remarks} \minor An \cmd{id} message is well-formed when its body is a sequence of three or more tokens. It is recommended that engines notify the client of \item{the engine's name using \tok{id name ...}\dt,} \item{any authors' names using \tok{id author ...}\dt,}\noskip where \tok{...}\ is any non\-empty sequence of tokens. \comment{Recall that, in all states, a message sent by the engine that is not well-formed must be ignored. All id messages that are long enough are considered to be well-formed, then, so that implementation-defined id messages besides engine and author names can be added.} \minor An \cmd{option} message is well-formed when its body is of the form \inset{\tok{option name ...¹ type ...² ...³}}\noskip where \item{\tok{...¹} is any non\-empty sequence of tokens that does not contain the token \tok{type} or the token \tok{value} (the \purple{option name}),} \item{\tok{...²} is \tok{check}, \tok{spin}, \tok{combo}, \tok{button}, or \tok{string} (the \purple{option type}),} \item{\tok{...³} is a well-formed \purple{option schema} given the option type.} A well-formed option schema is a sequence of tokens of the form \item{\tok{default true} or \tok{default false} when the option type is \tok{check},} \item{\tok{default ...\sup{a} min ...\sup{b} max ...\sup{c}} when the option type is \tok{spin}, where \tok{...\sup{a}}, \tok{...\sup{b}}, and \tok{...\sup{c}} are decimal integers in the range 0 to 2⁶³\ot−\pt1 inclusive,} \item{\tok{default ...\sup{a} }(\pt\tok{var ...\sup{b}}\pt)+ when the option type is \tok{combo}, where \tok{...\sup{a}} and \tok{...\sup{b}} are non\-empty sequences of tokens that do not contain the token \tok{var},} \item{the empty sequence when the option type is \tok{button},} \item{\tok{default ...\sup{a}} when the option type is \tok{string}, where \tok{...\sup{a}} is any non\-empty sequence of tokens. The one-token sequence \tok{<empty>} must be interpreted by the client as if it were the empty sequence.} It is recommended that engines use the option name \tok{Hash} (with option type \tok{spin}) for cache size in megabytes and the option name \tok{Threads} (with option type \tok{spin}) for number of worker threads. \minor A \cmd{protocol} message is well-formed when its body is of the form \inset{\tok{protocol ...}}\noskip where \tok{...}\ is a single token that is the \purple{protocol identifier} of a version of this specification that the engine will conform to. The protocol identifier of this version of the specification (in other words, the version described in this particular document) is \tok{2}. Clients should interpret the protocol identifier \tok{1} as a indication that the engine will behave informally (in other words, as a warning that the engine may cause a violation). \minor The only well-formed \cmd{uciok} message body is the single-token sequence \tok{uciok}. \minor The only well-formed \cmd{ready} message body is the single-token sequence \tok{readyok}. \minor An \cmd{info} message is well-formed when its body is of the form \inset{\tok{info} (\pt\tok{string}\pt|\pt\tok{error}\pt) \tok{...}}\noskip where \tok{...}\ is any non\-empty sequence of tokens, or is of the form \inset{\tok{info ...}}\noskip where \tok{...}\ is a non\-empty sequence (\purple{search information}) of well-formed \purple{fields}. \comment{Engines should only send info messages beginning with {\fw info error} when a client error has occurred. Info messages beginning with {\fw info string} may be sent by the engine for any purpose. Both kinds of info messages may be interpreted by the client in any implementation-defined manner; in fact, a conforming client may simply ignore all such info messages (although it is recommended that clients do not do this).} A~field is a sequence of two or more tokens. \item{Any number of fields may be omitted (subject to the aforementioned constraint that at least one field must be present).} \item{Each field may appear only once.} \item{Fields may appear in any order, subject to the constraint that the \tok{pv} field, if present, must be last.}\noskip In the field descriptions below, the metatoken \tok{\it int} is any decimal integer in the range 0 to 2⁶³\ot−\pt1 inclusive. The meaning of each field is implementation-defined\comment{, but recommended use is given after an equals sign as a comment}. The fields are: \item{\tok{depth \it int} \comment{= for traditional α/β engines, the nominal length in ply of the principal variation before extensions and reductions have been applied and not including plies examined in a quiescing search},} \item{\tok{seldepth \it int} \comment{= for traditional α/β engines, the length in ply of the principal variation after extensions and reductions have been applied, possibly including plies explored in a quiescing search, or the length in ply of the longest line examined by the engine},} \item{\tok{nodes \it int} \comment{= the number of positions (counted with multiplicity) examined by the engine since the most recent go message was read},} \item{\tok{time \it int} \comment{= the time in milliseconds since the most recent go message was read},} \item{\tok{nps \it int} \comment{= the mean number of positions (counted with multiplicity) examined per second since the most recent go message was read},} \item{\tok{hashfull ...}, where \tok{...}\ is a decimal integer in the range 0 to 1000 inclusive \comment{= for traditional α/β engines, the number of unique cache entries per mille written by the engine since the most recent go message was read},} \item{\tok{tbhits \it int} \comment{= the number of tablebase accesses since the most recent go message was read},} \item{\tok{currmove ...}, where \tok{...}\ is an algebraic token \comment{= for traditional engines, when interpreted as long algebraic notation, the first move of the lines currently being examined by the representative worker (the thread that will determine which move is reported with the bestmove message)},} \item{\tok{currmovenumber \it int} \comment{= for traditional engines, an index associated with the move given by {\fw currmove} in the same message, assigned in order that those moves and their continuations are examined, where {\fw 1} indicates the first move},} \item{\tok{multipv \it int} \comment{= the rank of the line given in the {\fw pv} field of the same message, where {\fw 1} indicates the principal variation, {\fw 2} indicates the principal variation if the first move of line 1 were disallowed as the first move of the principal variation, {\fw 3}~indicates the principal variation if the first moves of lines 1 and 2 were disallowed as the first move of the principal variation, and so on},} \item{\tok{score cp ...¹} (\pt\tok{...²}\pt)?\ or \tok{score mate ...¹}, where \tok{...¹} is a decimal integer in the range −2⁶³\ot+\pt1 to 2⁶³\ot−\pt1 inclusive (which may be written with a leading \tok{+}) and \tok{...²} is either \tok{lowerbound} or \tok{upperbound} \comment{= when {\fw cp}, an estimate of the advantage in centipawn for the side-to-move, where negative values of {\fw ...¹} indicate that the side-to-move is disadvantaged; when {\fw mate}, an indication that a forced mate in this many full moves exists, where positive values of {\fw ...¹} indicate that the side-to-move can deliver mate so that the game is over after {\fw ...¹}\pt×\pt2 − 1 additional plies have been played (including the move that the side-to-move is about to make) and negative values of {\fw ...¹} indicate that the side-waiting can deliver mate so that the game is over after {\fw ...¹}\pt×\pt2 additional plies have been played (including the move that the side-to-move is about to make); when {\fw lowerbound} is present, an indication that {\fw ...¹} is an estimated bound in centipawn for the advantage for the side-to-move and the advantage is estimated to be {\fw ...¹} or greater; when {\fw upperbound} is present, an indication that {\fw ...¹} is a likewise an estimated bound and the advantage is estimated to be {\fw ...¹} or less},} \item{\tok{pv ...}, where \tok{...}\ is a sequence of algebraic tokens \comment{= the principal variation, or when the {\fw currmove} field is present, the principal variation if the move given by the {\fw currmove} field in the same message were required to be the first move of the principal variation}.} Additional implementation-defined fields besides those listed above may be included in search information. Implementation-defined fields must not have any contiguous subsequence of tokens matching the fields listed above. \comment{The second token of the {\fw currmove} field, when interpreted as long algebraic notation, should correspond to a legal move for the side-to-move in the position defined by the last well-formed position message sent by the client in the idle state (or in the starting position if no such position messages have been sent), but the field is still well-formed even when this is not the case (although clients may then ignore the field, since the meaning of the field is implementation-defined).} \comment{Likewise, the tokens of the {\fw pv} field following the token {\fw pv}, when interpreted as long algebraic notation, should correspond to a sequence of legal moves from the position defined by the last well-formed position message sent by the client in the idle state (or from the starting position if no such position messages have been sent), but the field is still well-formed even when this is not the case (although clients may then ignore the field, since the meaning of the field is implementation-defined).} \comment{Many legacy clients require the {\fw multipv} field whenever the {\fw pv} field is present, regardless of engine configuration. This behavior is strongly discouraged.} \minor A \cmd{bestmove} message is well-formed when its body is of the form \inset{\tok{bestmove 0000}}\noskip or is of the form \inset{\tok{bestmove ...}}\noskip where \tok{...}\ is an algebraic token that, when interpreted as long algebraic notation, corresponds to a legal move for the side-to-move in the position defined by the last well-formed position message sent by the client in the idle state (or in the starting position if no such position messages have been sent). \comment{The token {\fw 0000} (or {\it null move}) should generally be used to indicate that the engine was unable or is not willing to recommend a move.} All bestmove messages sent in the active, ping, and halt states must be well-formed. \comment{In other words, when the engine sends a bestmove message in these states that is not well-formed, a violation has occurred.} \vskip\parskip \major{\bf Client Commands} \minor The only well-formed \cmd{uci} message body is the one-token sequence \tok{uci}. \minor A \cmd{setoption} message is well-formed when its body is of the form \inset{\tok{setoption name ...¹ value ...²}}\noskip where \item{\tok{...¹} is a non\-empty sequence of tokens that match an option name that has been advertised by the engine whose option type is \tok{check}, \tok{spin}, \tok{combo}, or \tok{string},} \item{\tok{...²} is \tok{true} or \tok{false} when the option type is \tok{check},} \item{\tok{...²} is a decimal integer not less than the minimum value nor greater than the maximum value advertised by the engine when the option type is \tok{spin},} \item{\tok{...²} is one of the token sequences advertised by the engine when the option type is \tok{combo},} \item{\tok{...²} is any non\-empty sequence of tokens when the option type is \tok{string},}\noskip or is of the form \inset{\tok{setoption name ...}}\noskip where \tok{...}\ is a non\-empty sequence of tokens that match an option name that has been advertised by the engine whose option type is \tok{button}. When the option type is \tok{string}, the single-token sequence \tok{<empty>} must be interpreted by the engine as if it were the empty sequence. \minor The only well-formed \cmd{debug} message bodies are the sequences \tok{debug on} and \tok{debug off}. \minor The only well-formed \cmd{ucinewgame} message body is the single-token sequence \tok{ucinewgame}. \minor The only well-formed \cmd{isready} message body is the single-token sequence \tok{isready}. \minor A \cmd{position} message is well-formed when its body is of the form \inset{\tok{position ...¹} (\pt\tok{moves ...²}\pt)?}\noskip where \item{\tok{...¹} is the token \tok{startpos} or the seven-token sequence \tok{fen ...\sup{f}}, where \tok{...\sup{f}} is the description of a position in Forsyth-Edwards Notation,} \item{\tok{...²} is a sequence of algebraic tokens that, when interpreted as long algebraic notation, correspond to a sequence of legal moves from the position described by \tok{...¹}.} In the final position (the position described by the entirety of the \cmd{position} message) there must be at least one legal move available for the side-to-move \comment{(in other words, the game must not be over)}, otherwise the message is not well-formed. \comment{Recall that position messages sent in idle state that are not well-formed must be ignored by the engine, so engines may not partially apply position updates.} \minor A \cmd{go} message is well-formed when its body is of the form \inset{\tok{go infinite} (\pt\tok{...}\pt)?}\noskip where \tok{...}\ is a non\-empty sequence of well-formed \purple{search modifiers}, or of the form \inset{\tok{go} (\pt\tok{...})?}\noskip where \tok{...}\ is a non\-empty sequence of well-formed \purple{search limits}, \purple{search context}, and/or modifiers. Modifiers, limits, and context items are sequences of two or more tokens. \item{Each limit, context item, or modifier may appear only once.} \item{Limits, context items, and modifiers may appear in order, subject to the constraint that the \tok{searchmoves} modifier, if present, must be last.} The meaning of search modifiers, search limits, and search context is implementation-defined\comment{, but recommended use is given after an equals sign as a comment}. In the descriptions below, the metatoken \tok{\it int16} is any decimal integer in the range 1 to 2¹⁵\ot−\pt1 inclusive, the metatoken \tok{\it int32} is any decimal integer in the range 0 to 2³¹\ot−\pt1 inclusive, and the metatoken \tok{\it int64} is any decimal integer in the range 0 to 2⁶³\ot−\pt1 inclusive. \comment{Note that, unlike {\fw\it int32} and {\fw\it int64}, an {\fw\it int16} {\weight{Medium}cannot} be zero.} \vfill\break The search modifiers are: \item{\tok{searchmoves ...}, where \tok{...}\ is a non\-empty sequence of algebraic tokens that, when interpreted as long algebraic notation, each correspond to a legal move for the side-to-move in the position defined by the last well-formed position message sent by the client in the idle state (or in the starting position if no such position messages have been sent) \comment{= a collection of moves to which the engine should restrict its consideration (in other words, the move reported with the bestmove message should be one of the moves in this collection)},} \item{\tok{mate \it int16} \comment{= an indication that the engine should attempt to prove a mate in this many full moves (or twice this many plies) and may assume that it does not need to examine lines beyond this many full moves (or twice this many plies)}.} The search context items are: \item{\tok{wtime \it int32} \comment{= the number of milliseconds that the white side has on their clock},} \item{\tok{btime \it int32} \comment{= the number of milliseconds that the black side has on their clock},} \item{\tok{winc \it int32} \comment{= the number of milliseconds that will be added to white's clock after each move by white},} \item{\tok{binc \it int32} \comment{= the number of milliseconds that will be added to black's clock after each move by black},} \item{\tok{movestogo \it int16} \comment{= an indication that when the side-to-move has played this many additional moves (including the move that the side-to-move is about to make) a new time control will begin}.} The search limits are: \item{\tok{depth \it int16} \comment{= for traditional α/β engines, the maximum length in ply of the principal variation (before extensions and reductions have been applied, and not including plies examined in a quiescing search) that the engine should explore},} \item{\tok{nodes \it int64} \comment{= for traditional engines, the maximum number of positions (counted with multiplicity) that the engine should examine},} \item{\tok{movetime \it int32} \comment{= the maximum time in milliseconds that the engine should spend after reading this message before sending a bestmove message}.} \comment{When more than one limit is given, the halting condition should be the logical {\caps or} of the limits rather than the logical {\caps and}. In other words, the engine should stop and send a bestmove message when any of the limiting conditions are met.} \comment{Since the meaning of search modifiers, search limits, and search context are implementation-defined, engines may ignore them (for example, node limits). However, disregard or lack of support for search context and the {\fw depth} and {\fw movetime} limits is strongly discouraged.} \minor The only well-formed \cmd{stop} message body is the single-token sequence \tok{stop}. \minor The only well-formed \cmd{quit} message body is the single-token sequence \tok{quit}. \vskip\parskip %\vfill\break {\bf Revision Notes}\par \def\uci{{\caps uci}}% \def\spec{{\caps spec}}% \def\hmk{{\caps hmk}}% This specification (or \purple{\spec}) is primarily a formalization of the {\it Description of the universal chess interface} (or \purple{\hmk}) by Rudolf Huber and Stefan Meyer-Kahlen, but it differs in the following ways: ▶\hem\hmk\ states that, when the client sends the message \tok{go infinite}, the engine must ``not exit the search'' until it is sent a following \cmd{stop} message, whereas in the active state \spec\ always allows engines to return a \cmd{bestmove} message. \comment{This is meant to simplify the specification and allow engines to signal that they have reached their maximum depth and will make no further progress.} ▶\hem\spec\ allows the client to send the engine a \cmd{go} message without a corresponding \cmd{position} message, whereas \hmk\ requires the client to send a \cmd{position} message before it sends the first \cmd{go} message and in between every pair of \cmd{go} messages. ▶\hem\hmk\ states that clients and engines should attempt to skip unknown or malformed tokens and continue parsing the remainder of a message, whereas \spec\ states that clients and engines should ignore the message. ▶\hem\hmk\ includes \uni{0009 character tabulation} in its definition of white\-space (and possibly other scalar values as well), whereas \spec \ implicitly defines white\-space as contiguous sequences of \uni{0020} only. ▶\hem\spec\ does not include the \cmd{register} command or \cmd{registration} and \cmd{copyprotection} remarks. \comment{The effect of a register message may be emulated with a setoption message, and registration and copyprotection messages may be emulated with info messages.} ▶\hem\hmk\ allows search information to end with a \tok{string} field, whereas \spec\ does not. {\caps Hmk} also disallows the \tok{seldepth} field when the \tok{depth} field is not present, but \spec\ does not impose this restriction. ▶\hem\spec\ introduces the \cmd{protocol} remark. Although \spec\ is designed so that conforming engines will be usable with nonconforming, legacy clients (and vice versa), some configurations may be incompatible. In future versions of this specification, this section will also list changes that have been made from prior versions. \vskip\parskip {\bf Outstanding Issues}\par ▶\hem The transition diagram needs to show that when the engine sends a \cmd{bestmove} message in the active, ping, and halt states that is not well-formed, a violation has occurred. ▶\hem Pondering still needs to be incorporated. ▶\hem Should \tok{refutation} and \tok{currline} be included in the list of governed fields? or left as implementation-defined additions? ▶\hem Should this specification introduce {\caps wdl} scoring (or something similar) in addition to centipawn-advantage scoring? ▶\hem Should \tok{upperbound} and \tok{lowerbound} not be required to come after the score? ▶\hem Should the client be allowed to queue up messages in the halt state? ▶\hem Should the client be allowed to send a \cmd{quit} message anytime? ▶\hem Should a \cmd{stop} message in the idle state be considered an error? In other words, should the engine notify the client with \tok{info error ...}\ that it received a \cmd{stop} message in the idle state, rather than with a generic \cmd{info} message? ▶\hem Should the value for \tok{string}-type options be a sequence of bytes rather than a seqence of tokens? – since (\pt1\pt) file system paths may contain \uni{0020}, where it's not a separator and the number of contiguous \uni{0020} values is significant, and (\pt2\pt) file system paths are often just byte sequences. This latter fact means that it'd be insufficient to relax the {\caps ascii} restriction on client messages; the {\caps utf-8} restriction needs to be relaxed as well. (In fact, it's worse than that: file system paths can also include \uni{000a}, so an escape sequence would need to be devised.) ▶\hem Should this formalization of {\caps uci} be given a name? If so, what? ▶\hem There should be a set of conformance tests that client and engine developers can use to find ways in which their programs do not adhere to specification. (Help writing these would be welcome.) \vfill %\centerline{\purple{\fw *\pt\raise0.5ex\hbox{*}\pt*}} %\vskip-\parskip {\caps copyright 2022}\ \kern1pt\comment{\fw uci@expositor.dev} \vskip-\parskip Although interfaces are not copyrightable, this particular document is protected by copyright. However, this work is licensed for use under the Creative Commons Attribution-NoDerivatives license (\ot{\caps cc by-nd 4·0}\ot). Informally, this means you are free to copy and redistribute this work so long as you give appropriate attribution and notice of the license, but you are not allowed to distribute modified copies or derivative works. \eject\bye