UCIChessEngineProtocol

Source: UCI - Universal Chess Interface

Description of the universal chess interface (UCI)    August 2021
=================================================================

* The specification is independent of the operating system. For Windows,
  the engine is a normal exe file, either a console or "real" windows application.

* All communications are done via standard input and output with text commands.

* The engine should boot and wait for input from the GUI,
  the engine should wait for the "isready" or "setoption" command to set up its internal parameters
  as the boot process should be as quick as possible.

* The engine must always be able to process input from stdin, even while thinking.

* All command strings the engine receives will end with '\n',
  also all commands the GUI receives should end with '\n',
  Note: '\n' can be 0x0d or 0x0a0d or any combination depending on your OS.
  If you use Engine and GUI in the same OS this should be no problem if you communicate in text
  mode, but be aware of this when for example running a Linux engine in a Windows GUI.

* Arbitrary white space between tokens is allowed
  Example: "debug on\n" and  "   debug     on  \n" and "\t  debug \t  \t\ton\t  \n"
  all set the debug mode of the engine on.

* The engine will always be in forced mode which means it should never start calculating
  or pondering without receiving a "go" command first.

* Before the engine is asked to search on a position, there will always be a position command
  to tell the engine about the current position.

* By default all the opening book handling is done by the GUI,
  but there is an option for the engine to use its own book ("OwnBook" option, see below).

* If the engine or the GUI receives an unknown command or token it should just ignore it and try to
  parse the rest of the string in this line.
  Examples: "joho debug on\n" should switch the debug mode on given that joho is not defined,
            "debug joho on\n" will be undefined however.

* If the engine receives a command which is not supposed to come, for example "stop" when the
  engine is not calculating, it should also just ignore it.



Move format:
------------

The move format is in long algebraic notation without piece symbol in the beginning of the move,
and without "-" and "x" symbols between "from" and "to" squares.
A nullmove from the Engine to the GUI should be sent as 0000.
Examples:  e2e4, e7e5, e1g1 (white short castling), e7e8q (for promotion)



GUI to engine:
--------------

These are all the command the engine gets from the interface.

* uci
	Tells the engine to use the uci (universal chess interface),
	this will be sent once as a first command after program boot
	to tell the engine to switch to uci mode.
	After receiving the uci command the engine must identify itself with the "id" command
	and send the "option" commands to tell the GUI which engine settings the engine supports if
	any. After that the engine should send "uciok" to acknowledge the uci mode. If no uciok is sent
	within a certain time period, the engine task will be killed by the GUI.

* debug [ on | off ]
	Switches the debug mode of the engine on and off.
	In debug mode the engine should send additional infos to the GUI, e.g. with the "info string"
	command, to help debugging, e.g. the commands that the engine has received etc. This mode
	should be switched off by default and this command can be sent any time, also when the engine
	is thinking.

* isready
	This is used to synchronize the engine with the GUI. When the GUI has sent a command or
	multiple commands that can take some time to complete,
	this command can be used to wait for the engine to be ready again or
	to ping the engine to find out if it is still alive.
	E.g. this should be sent after setting the path to the tablebases as this can take some time.
	This command is also required once before the engine is asked to do any search
	to wait for the engine to finish initializing.
	This command must always be answered with "readyok" and can be sent also when the engine is
	calculating in which case the engine should also immediately answer with "readyok" without
	stopping the search.

* setoption name <id> [value <x>]
	This is sent to the engine when the user wants to change the internal parameters
	of the engine. For the "button" type no value is needed.
	One string will be sent for each parameter and this will only be sent when the engine is
	waiting. The name and value of the option in <id> should not be case sensitive and can inlude
	spaces. The substrings "value" and "name" should be avoided in <id> and <x> to allow
	unambiguous parsing, for example do not use <name> = "draw value".
	Here are some strings for the example below:
	   "setoption name Nullmove value true\n"
	   "setoption name Selectivity value 3\n"
	   "setoption name Style value Risky\n"
	   "setoption name Clear Hash\n"
	   "setoption name NalimovPath value c:\chess\tb\4;c:\chess\tb\5\n"

* register
	This is the command to try to register an engine or to tell the engine that registration
	will be done later. This command should always be sent if the engine has sent "registration
	error" at program startup.
	The following tokens are allowed:
	* later
	   The user doesn't want to register the engine now.
	* name <x>
	   The engine should be registered with the name <x>.
	* code <y>
	   The engine should be registered with the code <y>.
	Example:
	   "register later"
	   "register name Stefan MK code 4359874324"

* ucinewgame
	This is sent to the engine when the next search (started with "position" and "go") will be from
	a different game or position. This can be a new game that the engine should play or a new game
	that it should analyse. It can also be a new position from a test suite.
	If the GUI has not sent a "ucinewgame" before the first "position" command, the engine should
	not expect any further ucinewgame commands as the GUI is probably not supporting it. Although
	new GUIs are required to support it, the engine should not rely on this command.
	As the engine's reaction to "ucinewgame" might take some time, the GUI should always send
	"isready" after "ucinewgame" to make sure that the engine will be ready to execute the
	next command.
   
* position [fen <fenstring> | startpos ]  moves <move1> .... <movei>
	Set up the position described in fenstring on the internal board and
	play the moves on the internal chess board.
	If the game was played  from the start position the string "startpos" will be sent
	Note: no "new" command is needed. However, if this position is from a different game than
	the last position sent to the engine, the GUI should have sent a "ucinewgame" inbetween.

* go
	Allows the engine to start calculating on the current position. This command shall be followed
	by other command or commands and all will be sent in the same string. Examples:
	"go wtime 10000 btime 10000"
	"go movetime 1000 depth 10"
	Any commands that are not sent, the info or purpose of such commands should not influence the
	engine's search.
	* searchmoves <move1> .... <movei>
		Restrict search to this moves only.
		Example: After "position startpos" and "go infinite searchmoves e2e4 d2d4"
		the engine should only search the two moves e2e4 and d2d4 in the initial position.
	* ponder
		Engine may start searching in pondering mode.
		Do not exit the search in ponder mode, even if it's mate!
		This means that the last move sent in the position string is the ponder move.
		The engine can do what it wants to do, but after a "ponderhit" command
		it should execute the suggested move to ponder on. This means that the ponder move sent by
		the GUI can be interpreted as a recommendation about which move to ponder. However, if the
		engine decides to ponder on a different move, it should not display any mainlines as they
		are likely to be misinterpreted by the GUI because the GUI expects the engine to ponder on
		the suggested move.
	* wtime <x>
		The white side has x msec (milliseconds) left on the clock.
	* btime <x>
		The black side has x msec left on the clock.
	* winc <x>
		This is the white side increment per move in msec if x > 0.
	* binc <x>
		This is the black side increment per move in msec if x > 0.
	* movestogo <x>
		There are x moves to the next time control, this will only be sent if x > 0.
		If you don't get this and get the wtime and btime it's sudden death.
	* depth <x>
		Search x plies only.
	* nodes <x>
		Search x nodes only.
	* mate <x>
		Search for a mate in x moves.
	* movetime <x>
		Search exactly x msec.
	* infinite
		Search until the "stop" command. Do not stop the search without being told to do so in this mode!
    
* stop
	Stop calculating as soon as possible, don't forget the "bestmove" and possibly the "ponder"
	token when finishing the search.

* ponderhit
	The user has played the expected move. This will be sent if the engine was told to ponder on
	the same move the user has played. The engine should continue searching but switch from
	pondering to normal search.

* quit
	Quit the program as soon as possible.



Engine to GUI:
--------------

* id
	* name <x>
		This must be sent after receiving the "uci" command to identify the engine.
		e.g. "id name Shredder X.Y\n"
	* author <x>
		This must be sent after receiving the "uci" command to identify the engine.
		e.g. "id author Stefan MK\n"

* uciok
	Must be sent after the id and optional options to tell the GUI that the engine
	has sent all infos and is ready in uci mode.

* readyok
	This must be sent when the engine has received an "isready" command and has
	processed all input and is ready to accept new commands now.
	It is usually sent after a command that can take some time to be able to wait for the engine,
	but it can be used anytime, even when the engine is searching,
	and must always be answered with "isready".

* bestmove <move1> [ ponder <move2> ]
	The engine has stopped searching and f