CECP ('WB protocol') specs

[Evert]

A few comments on the latest iteration of the document:

• The original document says to follow "xboard" with a carriage return (but doesn't say why). The current version says nothing like this. The reason for the carriage return is to clear away the prompt if the engine shows one. This might be good to mention as a possible "gotcha".
• I find it inconvenient that the different feature options are no longer listed in one place. Perhaps include such a list in an(other) appendix?
• Would it be possible to document if and how "setboard" affects the side the engine is playing? I understand Xboard always switches the engine to force mode before sending "setboard", but perhaps this could be documented?

EDIT: something else that occurred to me: is the document equally useful for authors of engines as it is for authors of GUIs? This isn't immediately obvious to me; I can imagine the list of do/don't's is different for those two cases.

[hgm]

Off-topic @Evert: did you see the PM I sent you?

I did not! For some reason the link said "you have no new messages" when in fact I had one. Odd.

I'll try to find a moment to test the variant description with the current version; it looks like it should work correctly.

Well, actually when I tried self-play with it, games always ended rather quickly in an illegal move, which then always was a repeat of the previous move for that side. So it looks like there is something thouroughly wrong with this Feb 15 version. But I was not able to find a more recent Windows-API binary. A version from January I had around seemed to completely ignore the variants.txt file.

[hgm]

Would it be possible to document if and how "setboard" affects the side the engine is playing? I understand Xboard always switches the engine to force mode before sending "setboard", but perhaps this could be documented?

As I understand it, 'setboard' or 'edit' should not change the engine 'mode'; it just stays playing for whatever side it was playing. That it would be only issued in 'force' mode is not guaranteed in the v2 protocol, and should be considered just an implementation peculiarity of XBoard. There has been a draft for a v3 spec, which would limit the use of many commands to force-mode only, but in fact the v2 spec explicitly contradicts this by appointing 'setboard' as one of the commands that can be used in analyze mode. (Something XBoard would never do, btw.)

It would have been better if 'setboard' was modeled on the 'white/black' commands rather than 'edit', setting the engine to play the side not on move. Its admissibility in analysis mode is doubtful, like that of the 'new' command (another thing XBoard would never do), and the requirement that 'new' works different in analyze mode (not setting the mode to 'play black') seems idiotic in view of the fact that XBoard will never use it in this mode. It sounds like uncritically importing an existing engine implementation that was not thought through very well is responsible for this.

[Evert]

Off-topic @Evert: did you see the PM I sent you?

I did not! For some reason the link said "you have no new messages" when in fact I had one. Odd.

I'll try to find a moment to test the variant description with the current version; it looks like it should work correctly.

Well, actually when I tried self-play with it, games always ended rather quickly in an illegal move, which then always was a repeat of the previous move for that side. So it looks like there is something thouroughly wrong with this Feb 15 version. But I was not able to find a more recent Windows-API binary. A version from January I had around seemed to completely ignore the variants.txt file.

At the moment I can confirm that there is a bug related to castling rights: they're never actually set, so castling moves are not generated. I don't know why that is (yet), but it might be that there's an assumption somewhere that the king starts on the back rank (which is an unnecessary assumption that should be fixed if so). PVs look normal in the current development version; I haven't tried promotions yet.
It's possible that the version you have that ignores variants.txt is looking for it in the wrong place; you can always list it explicitly on the commandline ("sjaakii path/to/variants.txt") to make sure it is loaded, or specify the location in the options dialog.

[Evert]

As I understand it, 'setboard' or 'edit' should not change the engine 'mode'; it just stays playing for whatever side it was playing.

That's what Sjaakii/Jazz/etc do: setboard only changes the current position (and game history), but not the engine side to move (in XBoard mode; when not in XBoard mode setboard also switches to force mode simply because I tend to forget doing that by hand). Either way, this would already be good to state explicitly even if the default assumption should be that nothing is changed unless stated explicitly.

That it would be only issued in 'force' mode is not guaranteed in the v2 protocol, and should be considered just an implementation peculiarity of XBoard. There has been a draft for a v3 spec, which would limit the use of many commands to force-mode only, but in fact the v2 spec explicitly contradicts this by appointing 'setboard' as one of the commands that can be used in analyze mode. (Something XBoard would never do, btw.)

It would have been better if 'setboard' was modeled on the 'white/black' commands rather than 'edit', setting the engine to play the side not on move. Its admissibility in analysis mode is doubtful, like that of the 'new' command (another thing XBoard would never do), and the requirement that 'new' works different in analyze mode (not setting the mode to 'play black') seems idiotic in view of the fact that XBoard will never use it in this mode. It sounds like uncritically importing an existing engine implementation that was not thought through very well is responsible for this.

For these, I would suggest listing these things as recommendations to GUI authors because it seems more robust to do it that way. Unless there are no GUIs that do it differently at the moment, in which case I would say to just document the desired behaviour as correct and deprecate other uses.

[hgm]

BTW, isn't it strange that the old CECP specs recommend that on reception of an invalid position the engine would throw up an error message with a 'tellusererror' command? It seems to me that this delegates a responsibility that should be the GUI's to the engine. Normally I would expect that the engine would respond to an invalid position with

Error (too many knights): setboard
Error (unkown piece 'A'): edit

A GUI could for instance use this to prevent the user exits setup mode (or return to it, like it returns to the previous position on reception of an 'Illegal move' command).

The recommendation seems inspired by laziness of the GUI designer to implement special handling for errors in setboard/edit.

[Ferdy]

Perhaps I should re-formulate that. It would have been simpler to just say the default of the variants feature for v2 engines is "normal". Except that there seems to be a wide-spread misunderstanding that "normal" need not be mentioned (perhaps because many people believe that FIDE Chess isn't a variant, but the "real thing"), so that when they add FRC support to their engine they only add variants="fischerandom" where they did not emit a variants feature before, so that the point needs to be stressed.

And I see now that XBoard actually implements it differently: the default variants list is a user-configurable option, (namely the same as that requests the actual variant: -variant), and it is the default value of the option that is "normal". This to allow v1 engines, which cannot emit a variants feature, to play variants, as they would be automatically assumed to play what the user requests on the XBoard command line.

So perhaps it would be better to just say:

"
Note that not mentioning "normal" in the variant list implies the engine is not capable of playing orthodox Chess. The GUI determines what the default value of the variants feature will be; this should be "normal" unless the GUI is not designed for Chess or the user reconfigured it to suit the engine.
"

This is my suggestion.

Code: Select all

variant VARIANT
Only used with VARIANTs that the engine announced it could play in the 
'feature variants="VARIANT1,VARIANT2,..."' command at startup.
This is sent to the engine immediately after the "new" command.
The engine stays playing for the side that does not have the move, 
but should not start pondering on this position. 
Note that by default the GUI is set to play variant normal or FIDE chess. This default
can be reconfigured by the user thru the command line option -variant VARIANT.
If VARIANT is not an XBoard standard variant (see appendix B), 
the engine should reply with a "setup" and possibly "piece" commands to define it:

[Evert]

This is my suggestion.

Code: Select all

variant VARIANT
Only used with VARIANTs that the engine announced it could play in the 
'feature variants="VARIANT1,VARIANT2,..."' command at startup.
This is sent to the engine immediately after the "new" command.
The engine stays playing for the side that does not have the move, 
but should not start pondering on this position. 
Note that by default the GUI is set to play variant normal or FIDE chess. This default
can be reconfigured by the user thru the command line option -variant VARIANT.
If VARIANT is not an XBoard standard variant (see appendix B), 
the engine should reply with a "setup" and possibly "piece" commands to define it:

The bit about GUI defaults and commandline options is out of place in a document describing a protocol.

The "variant" command is functionally an optional argument of the "new" command: without it "new" defaults to "normal". It has no other effect.
The default value for "feature variants" is 'normal'. Engines that override the default need to explictly list 'normal' if they support it. I think formulating it along those lines is easiest to follow.

[Ferdy]

This is my suggestion.

Code: Select all

variant VARIANT
Only used with VARIANTs that the engine announced it could play in the 
'feature variants="VARIANT1,VARIANT2,..."' command at startup.
This is sent to the engine immediately after the "new" command.
The engine stays playing for the side that does not have the move, 
but should not start pondering on this position. 
Note that by default the GUI is set to play variant normal or FIDE chess. This default
can be reconfigured by the user thru the command line option -variant VARIANT.
If VARIANT is not an XBoard standard variant (see appendix B), 
the engine should reply with a "setup" and possibly "piece" commands to define it:

The bit about GUI defaults and commandline options is out of place in a document describing a protocol.

Why not? protocol is about GUI (at least Winboard GUI) and engines. It does not hurt describing like that if the purpose is to make it more understandable.

The "variant" command is functionally an optional argument of the "new" command: without it "new" defaults to "normal". It has no other effect.

Read again, the one with the note, and even at the start the one with the "Only used ..."

[Evert]

The bit about GUI defaults and commandline options is out of place in a document describing a protocol.

Why not? protocol is about GUI (at least Winboard GUI) and engines. It does not hurt describing like that if the purpose is to make it more understandable.

It's out of place because the protocol description isn't the right place to discuss implementation details and idiosyncrasies of a particular GUI (even if it is X/WinBoard, which is arguably the reference implementation):

Note that by default the GUI is set to play variant normal or FIDE chess.

So a GUI specifically designed for playing Shogi is non-compliant because it's not set to play "variant normal" by default? Of course not, but that's what the text implies.
What you mean is that without "variant X" the assumed variant is "variant normal", but if that is what you mean to say, then say that directly.

This default can be reconfigured by the user thru the command line option -variant VARIANT.

This is irrelevant to an engine that needs to communicate through the protocol, and it suggests that a GUI needs to support such a command-line option to be compliant, which is again not true.
It's also misleading because it doesn't actually change the variant that is set when you receive a "new" command.

The "variant" command is functionally an optional argument of the "new" command: without it "new" defaults to "normal". It has no other effect.

Read again, the one with the note, and even at the start the one with the "Only used ..."

I see nothing that contradicts in any way what I just said.
Also,

Note that not mentioning "normal" in the variant list implies the engine is not capable of playing orthodox Chess. The GUI determines what the default value of the variants feature will be; this should be "normal" unless the GUI is not designed for Chess or the user reconfigured it to suit the engine.

to me is just a more complicated way of saying

The default value for "feature variants" is 'normal'. Engines that override the default need to explictly list 'normal' if they support it. I think formulating it along those lines is easiest to follow.