Enum UciCommand

pub enum UciCommand {
    Uci,
    Debug(bool),
    IsReady,
    SetOption {
        name: String,
        value: Option<String>,
    },
    Register {
        name: Option<String>,
        code: Option<String>,
    },
    UciNewGame,
    Position {
        fen: Option<String>,
        moves: Vec<String>,
    },
    Go(UciSearchOptions),
    Stop,
    PonderHit,
    Quit,
}

A command sent from a GUI to an engine.

Variants

Uci

Command structure:

uci

Protocol Description

Tell 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(bool)

Command structure:

debug [on | off]

where on = true

Protocol Description

Switch 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

Command structure:

isready

Protocol Description

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 table bases 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

Command structure:

setoption name <id> [value <x>]

Protocol Description

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 include 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.

Examples

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

Fields

name: String

The name of the engine parameter to modify.

value: Option<String>

If provided, the new value for the specified parameter option.

Register

Command structure:

registration [name <name> code <code> | later]

If called with later, then the name and code parameters will be None. Otherwise, they are likely to both be Some, though they are parsed independently, and it is up to you(r engine) to determine whether your registration process requires both values.

Protocol Description

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

Fields

name: Option<String>

If provided, the name to use during registration.

code: Option<String>

If provided, the code to use during registration.

UciNewGame

Command structure:

ucinewgame

Protocol Description

This is sent to the engine when the next search (started with position and go) will be from a different game. This can be a new game the engine should play or a new game it should analyze but also the next position from a test suite with positions only.

If the GUI hasn’t sent a ucinewgame before the first position command, the engine shouldn’t expect any further ucinewgame commands as the GUI is probably not supporting the ucinewgame command. So the engine should not rely on this command even though all new GUIs should support it.

As the engine’s reaction to ucinewgame can take some time the GUI should always send isready after ucinewgame to wait for the engine to finish its operation.

Position

Command structure:

position [fen <string> | startpos] [moves <move_1> [<move_2> ...]]

If called with startpos, then the fen field will be None.

Protocol Description

Set up the position described in FEN string 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 in between.

Fields

fen: Option<String>

If provided, the FEN string of the position to start with.

If startpos was provided, this will be None.

moves: Vec<String>

Go(UciSearchOptions)

Command structure:

go [searchmoves <move_1> [<move_2> ...]] [ponder] [wtime <x>] [btime <x>] [winc <x>] [binc <x>] [movestogo <x>] [depth <x>] [nodes <x>] [mate <x>] [movetime <x>] [infinite]

If no parameters are received, this should will be treated as go infinite and the infinite field will be set to true.

Protocol Description

Start calculating on the current position set up with the position command.

There are a number of commands that can follow this command, all will be sent in the same string. If one command is not sent its value should be interpreted as it would not influence the search.

Arguments

searchmoves <move_1> [<move_2> ... <move_i>]

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

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 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>

White has x milliseconds left on the clock.

btime <x>

Black has x milliseconds left on the clock.

winc <x>

White increment per move in milliseconds if x > 0.

binc <x>

Black increment per move in milliseconds 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 milliseconds.

infinite

Search until the stop command. Do not exit the search without being told so in this mode!

Stop

Command structure:

stop

Protocol Description

Stop calculating as soon as possible.

Don’t forget the bestmove and possibly the ponder token when finishing the search.

PonderHit

Command structure:

ponderhit

Protocol Description

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

Command structure:

quit

This does not necessarily need to immediately exit, but should make sure it performs any necessary clean-up before exiting.

It is likely that you want this command to be a special case in your engine’s event handler.

Protocol Description

Quit the program as soon as possible.

Implementations

impl UciCommand

pub fn new(input: &str) -> Result<Self, String>

Attempt to parse input into a valid UciCommand.

If this function fails, Err will contain an error message as to why.

Trait Implementations

impl Clone for UciCommand

fn clone(&self) -> UciCommand

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UciCommand

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for UciCommand

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats this UciCommand using the given formatter.

The formatted string will almost always be identical to the source it was parsed from, with the following exceptions:

1. Parameters to commands like UciCommand::Go will have a fixed order, regardless of how they were originally supplied.
2. Leading/trailing/excessive whitespace is parsed out.

impl FromStr for UciCommand

fn from_str(s: &str) -> Result<Self, Self::Err>

Alias for UciCommand::new.

type Err = String

The associated error which can be returned from parsing.

impl PartialEq for UciCommand

fn eq(&self, other: &UciCommand) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for UciCommand

impl StructuralPartialEq for UciCommand