Extensible Chess Interface (XCI)

1 Introduction

2 Design Goals

• standardized output from engine
• proper separation of work between GUI and engine
• synchronization between GUI and engine
• support for FRC and 10x8 variants
• no modes
• some game state
• easy for programmer
• easy for user
• extensible

3 Key Differences From XBoard/WinBoard

• no modes (like force, go)
• never start computation until directed by GUI
• easy to tell what state engine is in
• standardized output
• extended level command
• GUI checks for legality
• GUI checks for end of game

4 Key Differences From UCI

• not stateless with respect to game state
• whole move list not sent to engine
• descriptions of parameters/options
• engine gets game result
• engine can display book info
• engine controls pondering
• engine controls draw offers
• engine knows full time control
• engine doesn't handle registration through the protocol (would be done during installation or other utility?)

5 Engine States

• WAIT/READY : engine is waiting for next command from GUI (and not consuming cpu time)
• THINK : engine is computing best move for current position
• ANALYZE : engine is analyzing current position
• PONDER : engine is pondering in current position

6 Commands From GUI to Engine

6.x xci

• Description : start Simple Chess Interface (xci) session
• Usage : xci
• Responses :
  • id name [x]
  • id author [x]
  • id about [x]
  • id about [x]
  • option name1 type values
  • option name2 type values
  • info name1 description blah1
  • info name2 description blah2
  • readyok

6.x position

• Description : start new game or set up position
• Usage : position [fen] | startpos
  • fen : fen string
  • startpos : starting position (for variants with unique starting position)
• Notes :
  • engine can infer (totally) new game by looking at half move counter (and position of pawns)

6.x move

• Description : make move on internal board
• Usage : move [move1]
• Notes :
  • engine doesn't start thinking after receiving move command

6.x level

• Description : give time control information
• Usage : level (x/y)* [z+inc]
  • (x/y)* : zero or more time controls of the form x moves in y seconds (tournament)
  • z+inc : z seconds for rest of game plus inc second increment per move (sudden death)
• Examples :
  • level 40/300 (40 moves in 5 minutes, repeating)
  • level 300+5 (game in 5 minutes plus 5 seconds per move)
  • level 40/300 60/300 300+0 (40 moves in 5 minutes, then 60 moves in 5 minutes, then rest of game in 5 minutes)
• Notes :
  • at least one time control type will be given, i.e., either x/y or z+inc
  • if no z+inc is provided, the last tournament time control will be repeated
  • engine is not forced to use this information since go command will provide moves to go and remaining time
  • remaining time from a previous time control carries over to the next
  • under sudden death z+inc, inc is added to remaining time before the current move (e.g., 0+3 does not immediately result in a loss on time)

6.x setoption

• Description : set option in engine
• Usage : setoption name [id] value [x]
  • name : name/label of option
  • value : value/setting of option
• Examples :
  • setoption name King Safety value 110
  • setoption name History Pruning value 3
  • setoption name Clear Hash
• Notes :
  • button type options do not require a value
  • setoption is only sent when engine is in WAIT state

6.x go

• Description : start an operation
• Usage : go (cmd)*
  • searchmoves [move1] ... [movei] : restrict search to these moves only
  • ponder : start pondering
  • wtime [x] : white has x ms left
  • btime [x] : black has x ms left
  • winc [x] : white increment per move in ms (if x > 0)
  • binc [x] : black increment per move in ms (if x > 0)
  • movestogo [x] : moves till next time control
  • depth [x] : limit search to depth x
  • nodes [x] : limit search to x nodes
  • mate [x] : search for mate in x moves
  • movetime [x] : limit search time to x ms
  • infinite : start analyzing (i.e., enter ANALYZE state); note that existing level (time control) doesn't apply
  • -----
  • drawoffer : engine can accept opponent's draw offer during this think
• Responses :
• Notes :

6.x getbook

• Description : get book information
• Usage : getbook
• Responses :
  • info book ... (see Section X)
  • info book null (if no book moves in current position)

6.x getstartpos

• Description : get starting position
• Usage : getstartpos
• Responses :
  • info startpos ... (see Section X)
  • info startpos null (if engine cannot provide this)
• Notes :
  • this command is useful when engine supports a variant that is not officially supported by the GUI
  • an important assumption is that all engines that support this variant agree on syntax of positions, moves, and results

6.x getmovelist

• Description : get list of legal moves in current position
• Usage : getmovelist
• Responses :
  • info movelist ... (see Section X)
  • info movelist null (if engine cannot provide this)
• Notes :
  • this command is useful when engine supports a variant that is not officially supported by the GUI
  • an important assumption is that all engines that support this variant agree on syntax of positions, moves, and results

6.x getresult

• Description : get result of current position
• Usage : getresult
• Responses :
  • info result ... (see Section X)
  • info result null (if engine cannot provide this)
• Notes :
  • this command is useful when engine supports a variant that is not officially supported by the GUI
  • an important assumption is that all engines that support this variant agree on syntax of positions, moves, and results

6.x stop

• Description : stop calculating as soon as possible
• Usage : stop
• Responses :
  • bestmove [move1] (if engine in THINK or ANALYZE state)
  • readyok (if engine in PONDER state)

6.x isready

• Description : synchronize engine with GUI
• Usage : isready
• Responses : readyok
• Notes :

6.x result

• Description : tell engine the result of the current game (sequence of moves since last position command)
• Usage : result [result] [{comment}]
  • result : 1-0, 0-1, 1/2-1/2, *
  • {comment} : optional comment such as {White mates}, {Black resigns}, {Stalemate}, {White loses on time}

6.x quit

• Description : shut down engine as soon as possible
• Usage : quit

7 Commands From Engine to GUI

7.x id

• Description : provide engine and author information
• Usage : id [name|author|country|about] [x]
• Examples :
  • id name Simple Engine 1.0
  • id author Michael Yee
• Notes :
  • must be sent by engine after receiving the xci command

7.x acceptdraw

• Description : accept draw offer from opponent
• Usage : acceptdraw
• Notes :
  • only applicable when engine received drawoffer as part of go command
  • engine must keep thinking and reply with bestmove, however, since draw offer could have been retracted

7.x bestmove

• Description : best move in current position
• Usage : bestmove [move1]
• Notes :
  • only applicable when engine received drawoffer as part of go command
  • engine must keep thinking and reply with bestmove, since draw offer could have been retracted
  • after sending bestmove, engine enters WAIT state
  • engine does not make this move on its internal board; instead it waits for GUI to send make command

7.x info

• Description : provide thinking (or other) information
• Usage : info ([type] [x])*
  • depth [x] : search depth in plies
  • seldepth [x] : selective search depth in plies
  • time [x] : elapsed time in ms
  • nodes [x] : nodes searched
  • pv [move1] ... [movei] : principle variation (best line)
  • multipv [num] : for multi pv mode, send multipv 1 followed by best move (and pv) followed by rest of k best moves and pvs
  • score [scoretype] lowerbound | upperbound
    • cp [x] : score from engines point of view in centipawns
    • mate [x] : mate in x moves (not plies); if engine is being mated, use negative x
    • lowerbound : score is just a lower bound
    • upperbound : score is just an upper bound
  • currmove [move] : currently searching move
  • currmovenumber [x] : currently searching move number x (numbering of move list starts at 1)
  • hashfull [x] : hash table is x percent full
  • nps [x] : nodes per second
  • tbhits [x] : number of positions found in egtbs
  • cpuload [x] : cpu usage by engine is x percent
  • string [str] : any string
  • refutation [move1] [move2] ... [movei] : move [move1] is refuted by line [move2] ... [movei]
  • currline [cpunr] [move1] ... [movei] : current line being searched
  • --------
  • name [label] value [x] : a custom piece of information, e.g., info name MoveOrdering value 93% (sent during thinking)
  • name [label] description [x] : alerts GUI about custom information during initialization (after xci command)
  • --------
  • book ([move] percent [x] frequency [y] annotation [z])* : book information/statistics for current position; note that percent/frequency/annotation are optional
  • startpos [pos] : a valid starting position for the current variant or null if engine cannot provide this
  • movelist [move1] ... [movei] : list of legal moves in current position or null if engine cannot provide this
  • result [res] : result of game (win|loss|draw|inprogress) or null if engine cannot provide this
• Notes :
  • all info related to a particular pv should be sent together
  • custom information must be pre-declared during initialization phase (after xci command) so GUI can make extra columns in output display if necessary

7.x option

• Description : tell GUI options that can be changed in engine
• Usage : option name [id] type [t] default [x] min [x] max [x] var [x] description [x]
  • id : name of option
  • t : check | spin | combo | button | string
    • check : checkbox that can be either true or false
    • spin : spin wheel that can be an integer in a certain range
    • combo : combo box that can have different strings as a value
    • button : button that can be pressed to send a command to engine
    • string : text field that has a string as a value; empty string has value "" (?)
  • default : default value of parameter
  • min : minimum value of parameter
  • max : maximum value of parameter
  • var : a predefined value of parameter (i.e., an element of the discrete set of the combo box)
  • description : string (to end of line) describing meaning of option
• Options with predefined/standard meanings :
  • NalimovPath, type string
  • NalimovCache, type spin
  • Ponder, type check
  • OwnBook, type check
  • MultiPV, type spin
  • UCI_ShowCurrLine, type check, default false
  • UCI_ShowRefutations, type check, default false
  • UCI_LimitStrength, type check, default false
  • UCI_Elo, type spin
  • UCI_Opponent, type string (format [GM|IM|FM|WGM|WIM|none] [elo|none] [computer|human] name)
  • --------
  • XCI_Variant, type combo, vars Standard, FRC (Chess960?), Shuffle, Capablanca, CRC, etc.

7.x offerdraw

• Description : offer draw to opponent
• Usage : offerdraw
• Notes :
  • engine can only send offerdraw while in THINK state
  • engine must keep thinking and reply with bestmove, since opponent may not accept
  • offerdraw command can be sent anytime before bestmove

7.x resign

• Description : resign in the current position
• Usage : resign
• Notes :
  • engine can only send resign while in THINK state
  • after sending resign, engine stops computation and enters WAIT state

7.x readyok

• Description : part of mechanism for synchronization with GUI
• Usage : readyok
• Notes :
  • engine must send readyok in response to isready
  • if engine receives isready while in THINK, PONDER, or ANALYZE states, it should reply with readyok and continue computation
  • if engine receives isready while in WAIT state, it should reply with readyok after processing all previous commands
  • engine sends readyok after xci command
  • engine sends readyok after receiving stop while in PONDER state

7.x error

• Description : engine encountered an unrecoverable error
• Usage : error [msg]
• Notes :
  • this should almost never happen (since GUI only sends legal moves, etc.)
  • however, an illegal move could happen if a buggy engine was chosen to be the "referee" for an non-GUI-supported variant
  • after sending the error command, engine enters the WAIT state

8 Move Format (for Standard and FRC/CRC)

• e2e4 (regular move)
• e7e8q (pawn promotion)
• e1g1 (kingside castling)
• e1f1k (h-side castling in FRC, disambiguated)
  • note : this is backwards compatible with normal coordinate notation
  • note : it is also similar in spirit to pawn promotion notation--indicating a special operation by appending a character

9 Position Format (for Standard and FRC/CRC)

• Reinhard Scharnagl's suggestion for FRC-FEN and CRC-FEN (i.e., that KQkq field can be disambiguated with rook column if necessary, e.g., Kfkq)
• note : this is backwards compatible with normal FEN

10 Sample Sessions