Winboard Forum

As the discussion in the WB protocol thread seems to focus on developing new protocol for configuring the engine through the GUI interface, rather than on discussing the extended / clarified protocol as I posted (and implemented in WinBoard 4.3.14), I decided to create a new thread for it.

The situation we were slowly converging on was something like this:

There will be a distinction between standard options, which describe properties and limitations of the system we are running on. This includes information on were we put standard files like books and end-game tables, and maximum allowed resource usage, like memory size and number of cores.

The second type of options are those specific to the engine, like playing style, and even if other engines have such an option as well, the allowed values for the option will vary from engine to engine. To WinBoard such engines mean nothing; it will merely act as a passive medium to pass along the options and their settings btween engine and user.

For standard options the engine will merely have to tell WinBoard if it understands them (or not). In WB protocol the 'feature' command is used for such things, and I see no reason to change that. So the engine can send things like

feature egt="nalimov,scorpio"
feature book=1
feature processors=4
feature memory=160

during the normal WB startup handshaking, and WinBoard would reply with

accepted egt
accepted book
accepted processors
accepted memory

(older versions, or other WB-compatible GUIs might of course send 'rejected' in stead of 'accepted', but this is not very interesting to the engine, and just means that it will not receive any commands for setting the correspondng options later on.)

The sequence above would tell WinBoard that the engine would accept the commands

processors N
memory M

to set the number of cores and the memory the engine will be allowed to use. For the cores, WinBoard will know that the maximum number of cores the engine can use is 4, so that WinBoard can relay this information to the user in the configuration dialog for this engine. It will not be considered an error, though, for the user to set a number of cores larger than this in the settings menu for standard options (as the other engine might support the larger number of cores), the value there is merely the maximum the engine can use. Likewise, the engine should not consider it an error when the 'processors' command passes a number larger than the specified maximum; it should simply use the maximum it does support in that case. We might have a menu item in the engine-specific configuration dialog that can limit the number of cores further.

For the memory option it works slightly differently; the number specified here is the engine default.

The feature egt enables the GUI->engine commands

egtpath nalimov PATHNAME
egtpath scorpio PATHNAME

which will always be sent if WinBoard is aware of the location of the respective end-game tables. It will also enable sending of the command

egtcache M

when the user requests this from the engine-specific configuration menu. Engines are allowed to ignore this command, if they want, as long as they do not exceed the total memory allocation specified in the 'memory' command.

Similarly, the feature book=1 will prompt WinBoard to send

bookpath PATHNAME

of an openingbook that the engine could use, provided it is aware of the existence of one.

For the engine-specific options, the engine would have to specify both the name of the option, and the values it can take. A natural way to do it would be to have the engine send a feature command like

feature options="style:*patzer/karpov,resign:boolean,pawn hash:3MB"

for convenience, it would be allowed to divide the list over several feature commands:

feature options="style:patzer*/karpov"
feature options="resign:ON"
feature options="pawn hash:3MB"
feature options="LMR moves:5"
feature options="piece-value file:{C:\engines\master\pieces.ini}"

Everything before the ':' would be taken as the opton name. This name would appear in the engine-specific configuration dialog, and if the user would alter it through this dialog, it would cause WinBoard to send comamnd to the engine like

option style karpov
option resign on
option pawn hash 8
option LMR moves 3
option piece-value file .\alternatevalues.ini

The engine would be responsible for the parsing of everything after 'option'.

Everything after the ':' would describe the values an option could take, which will have implications for the type of control element that will appear in the configure dialog box.

An ON or OFF value would imply a check box, and at the same time relay the current (default) state.

Something that starts with a digit would imply a numeric argument, and causes a numeric type-in field in the dialog box. Again, the value given is the current setting. Any characters appended to the number would be units, that can be displayed next to the input field, to remind the user of the meaning of the number. This could also be used to specify a range, by writing something like 5(2-8). The (2-8) would appear behind the input field lik any other text.

Something within braces {} would be a filename, and would cause a type-in box with browse button.

A list of identifiers separated by / would be an 'enumeration type', that would appear as a list of options where you can choose from by ticking one. An * behind one of them would indicate the current setting.

H.G.Muller wrote:As the discussion in the WB protocol thread seems to focus on developing new protocol for configuring the engine through the GUI interface, rather than on discussing the extended / clarified protocol as I posted (and implemented in WinBoard 4.3.14), I decided to create a new thread for it.

The situation we were slowly converging on was something like this:

There will be a distinction between standard options, which describe properties and limitations of the system we are running on. This includes information on were we put standard files like books and end-game tables, and maximum allowed resource usage, like memory size and number of cores.

The second type of options are those specific to the engine, like playing style, and even if other engines have such an option as well, the allowed values for the option will vary from engine to engine. To WinBoard such engines mean nothing; it will merely act as a passive medium to pass along the options and their settings btween engine and user.

For standard options the engine will merely have to tell WinBoard if it understands them (or not). In WB protocol the 'feature' command is used for such things, and I see no reason to change that. So the engine can send things like

feature egt="nalimov,scorpio"
feature book=1
feature processors=4
feature memory=160

during the normal WB startup handshaking, and WinBoard would reply with

accepted egt
accepted book
accepted processors
accepted memory

(older versions, or other WB-compatible GUIs might of course send 'rejected' in stead of 'accepted', but this is not very interesting to the engine, and just means that it will not receive any commands for setting the correspondng options later on.)

The sequence above would tell WinBoard that the engine would accept the commands

processors N
memory M

to set the number of cores and the memory the engine will be allowed to use. For the cores, WinBoard will know that the maximum number of cores the engine can use is 4, so that WinBoard can relay this information to the user in the configuration dialog for this engine. It will not be considered an error, though, for the user to set a number of cores larger than this in the settings menu for standard options (as the other engine might support the larger number of cores), the value there is merely the maximum the engine can use. Likewise, the engine should not consider it an error when the 'processors' command passes a number larger than the specified maximum; it should simply use the maximum it does support in that case. We might have a menu item in the engine-specific configuration dialog that can limit the number of cores further.

For the memory option it works slightly differently; the number specified here is the engine default.

The feature egt enables the GUI->engine commands

egtpath nalimov PATHNAME
egtpath scorpio PATHNAME

which will always be sent if WinBoard is aware of the location of the respective end-game tables. It will also enable sending of the command

egtcache M

when the user requests this from the engine-specific configuration menu. Engines are allowed to ignore this command, if they want, as long as they do not exceed the total memory allocation specified in the 'memory' command.

Similarly, the feature book=1 will prompt WinBoard to send

bookpath PATHNAME

of an openingbook that the engine could use, provided it is aware of the existence of one.

No objection about options of this type.

H.G.Muller wrote:For the engine-specific options, the engine would have to specify both the name of the option, and the values it can take. A natural way to do it would be to have the engine send a feature command like

feature options="style:*patzer/karpov,resign:boolean,pawn hash:3MB"

for convenience, it would be allowed to divide the list over several feature commands:

feature options="style:patzer*/karpov"
feature options="resign:ON"
feature options="pawn hash:3MB"
feature options="LMR moves:5"
feature options="piece-value file:{C:\engines\master\pieces.ini}"

Everything before the ':' would be taken as the opton name. This name would appear in the engine-specific configuration dialog, and if the user would alter it through this dialog, it would cause WinBoard to send comamnd to the engine like

option style karpov
option resign on
option pawn hash 8
option LMR moves 3
option piece-value file .\alternatevalues.ini

The engine would be responsible for the parsing of everything after 'option'.

Everything after the ':' would describe the values an option could take, which will have implications for the type of control element that will appear in the configure dialog box.

An ON or OFF value would imply a check box, and at the same time relay the current (default) state.

Something that starts with a digit would imply a numeric argument, and causes a numeric type-in field in the dialog box. Again, the value given is the current setting. Any characters appended to the number would be units, that can be displayed next to the input field, to remind the user of the meaning of the number. This could also be used to specify a range, by writing something like 5(2-8). The (2-8) would appear behind the input field lik any other text.

Something within braces {} would be a filename, and would cause a type-in box with browse button.

A list of identifiers separated by / would be an 'enumeration type', that would appear as a list of options where you can choose from by ticking one. An * behind one of them would indicate the current setting.

This proposal is too inferior, compared with the easy way UCI handles all this.
My proposal is to send a single "feature options=" per line with a syntax like that of UCI.

Well, I do not know UCI syntax. Could you give an example of how you would combine it with the WB 'feature' command?

H.G.Muller wrote:Well, I do not know UCI syntax. Could you give an example of how you would combine it with the WB 'feature' command?

All 4 types (check, spin, combo, string) for Engine to GUI :

feature option=LazyEval type check default false
feature option=Secret Value type spin default 60 min -17 max 100
feature option=Combinations type combo default All var All var Most var Some var None
feature option=Private Path type string default <empty>

GUI to Engine :

option LazyEval value true
option Secret Value value 73
option Combinations value Most
option Private Path value c:\MyPath

These options are sent and received one per line (ending with a '\n')
All option features are sent without features of a different type in-between.
I left out type button because rarely used and tougher for GUI to handle.
Details in UCI specification.

H.G.Muller wrote:Well, I do not know UCI syntax. Could you give an example of how you would combine it with the WB 'feature' command?

Snippet of UCI spec. :

* option
This command tells the GUI which parameters can be changed in the engine.
This should be sent once at engine startup after the "uci" and the "id" commands
if any parameter can be changed in the engine.
The GUI should parse this and build a dialog for the user to change the settings.
If the user wants to change some settings, the GUI will send a "setoption" command to the engine.
For all allowed combinations see the example below, as some combinations of this tokens don't make sense.
One string will be sent for each paramter.
* name <id>
The option has the name id.
This can be sent in any language, the GUI will take care of the translation.
Certain options have a fixed value for <id>, which means that the semantics of this option is fixed
* type <t>
The option has type t.
There are 5 different types of options the engine can send
* check
a checkbox that can either be true or false
* spin
a spin wheel that can be an integer in a certain range
* combo
a combo box that can have different predefined strings as a value
* button
a button that can be pressed to send a command to the engine
* string
a text field that has a string as a value,
an empty string has the value "<empty>"
* default <x>
the default value of this parameter is x
* min <x>
the minimum value of this parameter is x
* max <x>
the maximum value of this parameter is x
* var <x>
a predefined value of this paramter is x


Example: Here are 5 strings for each of the 5 possible types of options
"option name Nullmove type check default true\n"
"option name Selectivity type spin default 2 min 0 max 4\n"
"option name Style type combo default Normal var Solid var Normal var Risky\n"
"option name NalimovPath type string default c:\\n"
"option name Clear Hash type button\n"

Matthias Gemuh wrote:

H.G.Muller wrote:Well, I do not know UCI syntax. Could you give an example of how you would combine it with the WB 'feature' command?

All 4 types (check, spin, combo, string) for Engine to GUI :

feature option=LazyEval type check default false
feature option=Secret Value type spin default 60 min 17 max 100
feature option=Combinations type combo default All var All var Most var Some var None
feature option=Private Path type string default <empty>

GUI to Engine :

option LazyEval value true
option Secret Value value 73
option Combinations value Most
option Private Path value c:\MyPath

These options are sent and received one per line (ending with a '\n')
All option features are sent without features of a different type in-between.
I left out type button because rarely used and tougher for GUI to handle.
Details in UCI specification.

I do not see the need to merge functionalities of different "options". That removes the reserve word "Type". But, maybe it is not important.

However, I think it will be much better to precede every reserve word with underscore or something to make sure it does not interfere with the options. For instance, it starts to be awkward if some of your options or word are type, default min etc. For instance:

Engine to GUI

feature option_check= LazyEval --default false
feature option_spin = Secret_Value --default 60 --min 17 --max 100
feature option_combo = Combinations --default All --var All --var Most --var Some --var None
feature option_string = Private_Path --default <empty>

or if you want to keep option as one

feature option = LazyEval --type check --default false
feature option = Secret_Value --type spin --default 60 --min 17 --max 100
feature option = Combinations --type combo --default All --var All --var Most --var Some --var None
feature option = Private_Path --type string --default <empty>


GUI to Engine

option_check checkLazyEval --value true
option_spin Secret_Value --value 73
option_combo Combinations --value Most
option_string Private_Path --value c:\MyPath

alternatively
option checkLazyEval --value true
option Secret_Value --value 73
option Combinations --value Most
option Private_Path --value c:\MyPath

the prefixx "--" mimicks the conventions of linux commnad lines, so it could also be possible to be parsed by library functions (getop(), getoplong() etc). I have seen windows open source replacement for those too. This will help GUI developers.

Also, I think that the name or ID of the option should be kept one word. If we want the GUI to display a specific title with spaces, it should be send as "title". If no title is sent, the ID can be used by the GUI.


feature option_spin = Secret_Value --title "Secret Value" --default 60 --min 17 --max 100
feature option_string = Private_Path --title "Private Path" --default <empty>

Note that separating the "title" ("Private Path") from the "id" (Private_Path) will help for translations.

Miguel

Miguel A. Ballicora wrote:I do not see the need to merge functionalities of different "options". That removes the reserve word "Type". But, maybe it is not important.

However, I think it will be much better to precede every reserve word with underscore or something to make sure it does not interfere with the options. For instance, it starts to be awkward if some of your options or word are type, default min etc. For instance:

Engine to GUI

feature option_check= LazyEval --default false
feature option_spin = Secret_Value --default 60 --min 17 --max 100
feature option_combo = Combinations --default All --var All --var Most --var Some --var None
feature option_string = Private_Path --default <empty>

or if you want to keep option as one

feature option = LazyEval --type check --default false
feature option = Secret_Value --type spin --default 60 --min 17 --max 100
feature option = Combinations --type combo --default All --var All --var Most --var Some --var None
feature option = Private_Path --type string --default <empty>


GUI to Engine

option_check checkLazyEval --value true
option_spin Secret_Value --value 73
option_combo Combinations --value Most
option_string Private_Path --value c:\MyPath

alternatively
option checkLazyEval --value true
option Secret_Value --value 73
option Combinations --value Most
option Private_Path --value c:\MyPath

the prefixx "--" mimicks the conventions of linux commnad lines, so it could also be possible to be parsed by library functions (getop(), getoplong() etc). I have seen windows open source replacement for those too. This will help GUI developers.

Also, I think that the name or ID of the option should be kept one word. If we want the GUI to display a specific title with spaces, it should be send as "title". If no title is sent, the ID can be used by the GUI.


feature option_spin = Secret_Value --title "Secret Value" --default 60 --min 17 --max 100
feature option_string = Private_Path --title "Private Path" --default <empty>

Note that separating the "title" ("Private Path") from the "id" (Private_Path) will help for translations.

Miguel

You may be right about somehow distinguishing keywords.
I made no distinctions because the UCI protocol is successfully conquering the chess scene without the distinctions.

It is OK to somehow distinguish.

Matthias.

I think the distinction between reserved words and option names is important. I don't think we should emulate the UCI protocol just for the sake of making the protocols similar. We should improve it if there are deficiencies, which in this case there are IMO. I think the best way would be to separate the options, like: keyword name keyword name.

This is similar to commandline options, but it avoids the --. Whenever the engine provides a multi-word name, just enclose it in quotes. Having a different ID and display name for an option is interesting. It allows for pretty printing but makes the parsing for the engine a bit easier.

I also think we should come up with some better terms: check, spin, combo, var, they aren't very descriptive to me. It makes it clear that the protocol was designed by non-native English speakers.

So it could look like this:

feature option_bool = name "Lazy Eval" default false
feature option_int = name "Secret Value" default 60 min 17 max 100
feature option_list = name "Combinations" default "All" opts "All, Pretty much all of them, Most, Some, None"
feature option_string = name "Private Path"

There are a couple of issues here though, syntax-wise: having the underscore in the feature name isn't very WB-like, more natural would be optionstring, but less readable; and that features with string arguments are typically enclosed entirely with quotes. The first could be avoided by making the type an argument, but I'm not sure about the second. Perhaps we should just go with it, and the GUI writers can take care of it (shouldn't be too hard anyway...)

Zach Wegner wrote:I also think we should come up with some better terms: check, spin, combo, var, they aren't very descriptive to me. It makes it clear that the protocol was designed by non-native English speakers.

So it could look like this:

feature option_bool = name "Lazy Eval" default false
feature option_int = name "Secret Value" default 60 min 17 max 100
feature option_list = name "Combinations" default "All" opts "All, Pretty much all of them, Most, Some, None"
feature option_string = name "Private Path"

Code: Select all

 check, spin, combo, ... it clear that the protocol was designed by non-native English speakers.

It is Microsoft who introduced the terms into Windows, not SMK.
As a Windows programmer, those terms make more sense to me than anything else.

Anyway, I would go with:

feature option_bool = name "Lazy Eval" default false
feature option_int = name "Secret Value" default 60 min -17 max 100
feature option_list = name "Combinations" default "All" opts "All, Pretty much all of them, Most, Some, None"
feature option_string = name "Private Path" default ""

Matthias.

OK, I see what you mean now. Let me summarize.

There were three issues addressed above, in which we could deviate from the UCI syntax:

1) We could encode the data type of the option in the keyword for defining the option feature, or we could have it implied by a 'type' field.
2) We could make the keywords distinguishable by a reserved character, rather than making them reserved words.
3) We could require quoting of arguments containing spaces.

Without having formed an opinion yet, I want to point out that 2 and 3 more or less achieve the same thing. The special character that starts keywors, and the quotes around the values would have the same function.

My first worry is that the requirement of one option per line breaks more or less the current syntax of the feature command, whih allows multiple features to be specified. This might cause unnecessary complication in the feature parser.

Why not stick to the current feature syntax of space-delimited keyword=value elements in the feature list? Something like

feature option="/name hash size /spin /min 1 /max 256 /default 128"

One could in principle specify as many options per feature command as one wants, but in practice specifying even two will make the line too long, so it will not be done. The protocol will not really be interested what is in the string argument. It will simply be passed to the GUI front-end as a string, and the front-end can do with it whatever it wants to create pop-up dialgs, and restrict input given in them.

The fact that the engine has defined one or more option features, now allows the GUI to send a command

option hash size /value <value>

The /name keyword in the 'feature' command seems a bit redundant; everything from the start of the string upto the next keyword could be taken as the name, as a name would always have to be present. It would only be useful if you want to allow shufflling of the various fields. In the same way, when setting the option, the /value keyword seems redundant: the name has been defined, and I don't see how anything else than a value could follow it. Or do we want to allow an engine to define things like

feature option="/name hash size /combo /var for pawns 32 /var for EGTB"
feature option="/name hash size for pawns /spin /default 32"

so that it becomes imprtant to know if

option hash size for pawns 32

means

option hash size for pawns /value 32
or
option hash size /value for pawns 32

? Anyway, I am kind of neutral on the issue of requiring the /name and /value keywords. They are silly, for sure, but I do think similarity to UCI is a valid argument that should not be entirely discounted.

I would prefer to have keyword recognition for delimiting values rather than explicit quoting, mainly because the entire option feature value would already be a quoted string, and I dislike recursive quoting. As to the necessity to recognize keywords by their first character, as to recognizing the entire word, I am also kind of neutral. In practice each keyword in the string would have to be searched in a table. You might as well search every word.

Code: Select all

My first worry is that the requirement of one option per line breaks more or less the current syntax of the feature command, whih allows multiple features to be specified. This might cause unnecessary complication in the feature parser.

OK, let us put the whole option feature in one giant string that may even exceed 10000 characters. The reply to the engine is of course in chunks.

Code: Select all

feature option="/name hash size for pawns /spin /default 32"

Spin always has min,max,default.

Code: Select all

I would prefer to have keyword recognition for delimiting values rather than explicit quoting, mainly because the entire option feature value would already be a quoted string, and I dislike recursive quoting. As to the necessity to recognize keywords by their first character, as to recognizing the entire word, I am also kind of neutral. In practice each keyword in the string would have to be searched in a table. You might as well search every word.

A delimiter is welcome.

Matthias.

Matthias Gemuh wrote:OK, let us put the whole option feature in one giant string that may even exceed 10000 characters. The reply to the engine is of course in chunks.

Yes, the setting of the options would go with on option per 'option' command.

Code: Select all

feature option="/name hash size for pawns /spin /default 32"

Spin always has min,max,default.

Why is that? It would only cause the problem of representing infinity if there was no limit. Anyway, it is the engine that determines what to send. I would not consider it an error in WinBoard if it did not recieve a /max or /min with a /spin option. In fact I see little use for these parameters, and WinBoard would most likely just ignore them. The /spin would ask for an input field where the user could type a number. This field would be filled initially with the /default value, if any was given, and blank otherwise. When the user types something there, and OKs it, it would simply be sent to the engine.

H.G.Muller wrote:

Code: Select all

Spin always has min,max,default.


Why is that? It would only cause the problem of representing infinity if there was no limit. Anyway, it is the engine that determines what to send. I would not consider it an error in WinBoard if it did not recieve a /max or /min with a /spin option. In fact I see little use for these parameters, and WinBoard would most likely just ignore them. The /spin would ask for an input field where the user could type a number. This field would be filled initially with the /default value, if any was given, and blank otherwise. When the user types something there, and OKs it, it would simply be sent to the engine.

A spin allows typing a number just as an alternative.
Usually the user will scroll up/down to set the value, with no possibility of setting a value that the engine considers out of bounds.
min,max limit what the spin can offer.

My Borland compiler calls the thing "SpinEdit".
The Microsoft compiler has it but uses maybe a different name for it.

This fine Windows element is very useful for users, as the users are never left in doubt about allowed ranges of parameters.

Matthias.

H.G.Muller wrote:OK, I see what you mean now. Let me summarize.

There were three issues addressed above, in which we could deviate from the UCI syntax:

1) We could encode the data type of the option in the keyword for defining the option feature, or we could have it implied by a 'type' field.
2) We could make the keywords distinguishable by a reserved character, rather than making them reserved words.
3) We could require quoting of arguments containing spaces.

Without having formed an opinion yet, I want to point out that 2 and 3 more or less achieve the same thing. The special character that starts keywors, and the quotes around the values would have the same function.

My first worry is that the requirement of one option per line breaks more or less the current syntax of the feature command, whih allows multiple features to be specified. This might cause unnecessary complication in the feature parser.

Why not stick to the current feature syntax of space-delimited keyword=value elements in the feature list? Something like

feature option="/name hash size /spin /min 1 /max 256 /default 128"

I see your point. The problem is that the original designed is flawed, IMHO. Why allow unnecessary grammar flexibility? That grammar flexibility killed the flexibility for expansion. It should have never been allowed to include more than one feature per line. That's done though.

What you propose, using the whole command packed into a quoted string is a clever workaround of the flaw, but it is still a workaround. It limits the future possibilities substantially (as you say, double quotes will start to be a mess).

I think that we should fix the flaw rather than work around it. To do this, I think that we could expand the syntax of feature introducing a keyword. I do not know which one, but let's assume it is "multi". Multi will mean that feature is providing a feature with multiple values. "feature multi" can provide only one by line.

feature multi option = /name hash size /spin /min 1 /max 256 /default 128

Note that feature multi could be feature_multi, it does not matter to me.

After "=" you can have now whatever you want, quotes, etc. etc. and treat it as a regular command line if we or future developers want it.

If fact, it may be a good idea to treat that line with whatever parser winboard/xboard has already for its own command lines and keep the same type of syntax. It allow quotes, by the way, so no extra code writing will be necessary.

Miguel

One could in principle specify as many options per feature command as one wants, but in practice specifying even two will make the line too long, so it will not be done. The protocol will not really be interested what is in the string argument. It will simply be passed to the GUI front-end as a string, and the front-end can do with it whatever it wants to create pop-up dialgs, and restrict input given in them.

The fact that the engine has defined one or more option features, now allows the GUI to send a command

option hash size /value <value>

The /name keyword in the 'feature' command seems a bit redundant; everything from the start of the string upto the next keyword could be taken as the name, as a name would always have to be present. It would only be useful if you want to allow shufflling of the various fields. In the same way, when setting the option, the /value keyword seems redundant: the name has been defined, and I don't see how anything else than a value could follow it. Or do we want to allow an engine to define things like

feature option="/name hash size /combo /var for pawns 32 /var for EGTB"
feature option="/name hash size for pawns /spin /default 32"

so that it becomes imprtant to know if

option hash size for pawns 32

means

option hash size for pawns /value 32
or
option hash size /value for pawns 32

? Anyway, I am kind of neutral on the issue of requiring the /name and /value keywords. They are silly, for sure, but I do think similarity to UCI is a valid argument that should not be entirely discounted.

I would prefer to have keyword recognition for delimiting values rather than explicit quoting, mainly because the entire option feature value would already be a quoted string, and I dislike recursive quoting. As to the necessity to recognize keywords by their first character, as to recognizing the entire word, I am also kind of neutral. In practice each keyword in the string would have to be searched in a table. You might as well search every word.