# Option The `option` command is sent during initialisation to enumerate[^enum] and define the custom configurable parameters the engine supports. Most of these options should be used to construct a per-engine-instance menu for the user, but certain options should be controlled differently. The standard specifies a few options which have predefined behaviour, all other options should be documented by implementations or "unofficial" standards. --- ## Subcommands The `option` command has no parameters of it's own, only subcommands. Certain combinations of subcommands to `option` do not make any sense. Examples are provided to help clarify the form of the different kinds of options. ### Name `option name ExampleOptionName ...` The name of the option being defined. Certain names are reserved by the standard, see [[#Predefined Options]]. ### Type `option name ExampleOptionName type [ check | spin | combo | button | string ] ...` The type of the option being defined. - `check` can be either `true` or `false`, typically displayed as a checkbox. - `spin` is an integer in a certain range. - `combo` can have one of a predefined list of strings as a value, typically displayed as a dropdown menu. These strings should not contain spaces, otherwise parsing can become a nightmare. A GUI may decide to replace certain characters, such as \@, \#, \$, \%, or \_ with spaces in the menu displayed to the user. - `button` has no values. It is typically displayed as a clickable button. When the button `ExampleOptionName` is clicked, [[setoption]] should be called as `setoption name ExampleOptionName`. - `string` can be any arbitrary string of characters, typically displayed as a text box. Spaces can be used in these, unlike `combo`, because no additional parameters need to follow a default string value. ### Default - `option name ExampleOptionName type check default [ true | false ]` - `option name ExampleOptionName type spin default <x> ...` - `option name ExampleOptionName type combo default <variant> ...` - `option name ExampleOptionName type string default <string>` ### Minimum & Maximum `option name ExampleOptionName type spin default <x> min <y> max <z>` The minimum and maximum values for the `spin` type option. ### Variation `option name ExampleOptionName type combo default <variant1> var <variant2> var <variant3> ... var <varianti>` Enumerates[^enum] the variants for the `combo` type option. --- ## Predefined Options The following option names have a predefined behaviour set by the UCI standard. Engines are not required to implement any of them, but GUIs must at minimum recognize and treat [[#Hash]] as special, and should ensure [[#Ponder]] is set to false if it does not support it. If an engine does implement one, there may be restrictions on alloweable default values. ### Hash `option name Hash type spin ...` The value in [[Units of Data|MB]] for the maximum allowed size of the engine's hash tables in memory. GUIs should set this with [[setoption]] as soon as possible after initialisation, even if the user does not manually change it, as the GUI is assumed to be more knowledgeable about the resources available to the system than the engine. Engines should set the `default` value of `Hash` as low as possible, and wait for the GUI to tell it how much memory it can use. --- ### NalimovPath `option name NalimovPath type string default ` (Note the lack of `...`, the default should in most cases be the empty string). The path to the [Nalimov Compressed Format Tablebases](https://www.chessprogramming.org/Nalimov_Tablebases). Multiple paths can be concatenated with `;` as a separator. --- ### NalimovCache `option name NalimovCache type spin ...` Like [[#Hash]], but for the engine's in-memory cache . --- ### Ponder `option name Ponder type check default [ true | false ]` If the engine exposes this option, this indicates that the engine supports pondering (see [[go#Ponder|go ponder]], [[ponderhit]]). This option being `true` *does not* mean that the engine may ponder automatically. It simply indicates to the engine that the GUI also supports pondering, so that the engine can act accordingly. The engine may use either `true` or `false` as the default value for this parameter, but note that GUIs which do not support pondering are not strictly required to automatically set this option to `false`. --- ### OwnBook `option name OwnBook type check default [ true | false ]` The presence of this option indicates that the engine has it's own opening book. If set to `true`, the GUI should not play opening book moves for the engine, instead simply using [[go]] and allowing the engine to decide whether to look in it's opening book. If this option is set to `false`, the engine must not use it's own opening book. The engine may use it's own opening book if it does not expose this option at all. --- ### MultiPV `option name MultiPV type spin default 1 min 1 max ...` The presence of this option indicates that the engine supports MultiPV mode. If the value of this option is some integer k, and k is not `1`, MultiPV mode is active, specifically k-best mode. In k-best mode, the engine should keep track of k different preferred lines. See [[UCI Docs/Commands/Engine/info#PV|info: PV]] and [[UCI Docs/Commands/Engine/info#MultiPV|info: MultiPV]]. --- ### UCI_ShowCurrLine `option name UCI_ShowCurrLine type check default false` If this option is `true`, the engine should regularly send the current line it is calculating with [[UCI Docs/Commands/Engine/info#Currline|info currline]]. --- ### UCI_ShowRefutations `option name UCI_ShowRefutations type check default false` If this option is `true`, the engine should regularly send refutations with [[UCI Docs/Commands/Engine/info#Refutation|info refutation]]. --- ### UCI_LimitStrength `option name UCI_LimitStrength type check default false` If this is set to `true`, the engine should attempt to limit itself to a specific [Elo rating](https://www.chess.com/terms/elo-rating-chess) determined by the [[#UCI_Elo]] option. --- ### UCI_Elo `option name UCI_Elo type spin ...` If [[#UCI_LimitStrength]] is `true`, the engine should attempt to limit itself to this Elo rating. --- ### UCI_AnalyseMode `option name UCI_AnalyseMode type check ...` Should (not must, hence why it's not in the above example) default to `false`. The presence of this option indicates that the engine wants to behave differently when analysing a game than when playing a game. If this option is `false`, the engine is playing a game. If it is `true`, the engine is analysing a game. --- ### UCI_Opponent `option name UCI_Opponent type string default ` (Note the lack of `...`, the default should be the empty string). This command can be used to send information about the engine's opponent to the engine using [[setoption]]. The format of this option's value is: `[GM|IM|FM|WGM|WIM|none] [<elo>|none] [computer|human] <name>`. For example: - `GM 2882 human Magnus Carlsen` - `none 1 human Lily McCabe` (I like programming chess, I never said I was any good at playing it myself) - `none 3120 computer Stockfish` > [!info] > Note that the standard doesn't specify Elo ratings according to anyone in particular. So it does not need to correspond to FIDE or chess.com or lichess ratings, and the scale may be different to what you expect. --- ### UCI_EngineAbout `option name UCI_EngineAbout type string default ...` The default value of this option is used to tell the GUI about the engine. It doesn't really make sense to set this option with [[setoption]], but if a GUI does not recognise this option and make it immutable, and the user does try to change it, the engine should simply ignore this. --- ### UCI_ShredderbasesPath `option name UCI_ShredderbasesPath type string default ` (Note the lack of `...`, the default should be the empty string). Much like [[UCI Docs/Commands/Engine/info#SBHits|info: SBHits]], this seems unnecessarily specific to Shredder Chess. This option should be a path to a folder containing the Shredder Endgame Databases, or the path to the file containing one Shredder Endgame Database. --- ### UCI_SetPositionValue `option name UCI_SetPositionValue type string default ` (Note the lack of `...`, the default should be the empty string). This option is used to override the engine's evaluation of a specific position. Setting the value of this option does not change the value of this option, `setoption name UCI_SetPositionValue value` is effectively just the name of an optional command. The value set for this option can must be formatted as: `[<value> <fen> | clear <fen> | clearall]`. [^enum]: The word "enumerate" has two subtly different common uses in software development. In this context, to enumerate a set of options simply means to systematically list all of the options in detail.