WB protocol specs

[hgm]

I have made an attempt to re-write the CECP specs ('WB protocol') from scratch. It can be seen at http://hgm.nubati.net/newspecs.html .

Please let me know if this is an improvement over the old document.

[Janne Kokkala]

The old version says:

Mate scores should be indicated as 100000 + N for "mate in N moves", and -100000 - N for "mated in N moves".

This seems to be removed; is this intentional?. The GUIs I use don't seem to have implemented this feature, so I don't know if it's ever used.

The new version does not specify precisely what MPS actually means. From the old version, I understood that (a) a "level 40 5 0" command followed by 8 forced moves for each side means that the engine gets more time when it has played 32 moves, and (b) a "setboard" command specifying the move number to be 9 followed by "level 40 5 0" command means that the engine gets more time when it has played 40 moves. The new version seems to leave case (b) ambiguous.

Does a "new" command have to be sent before the start of the first game after the initial handshake? IcsDrone does not do that, which resulted in an interesting bug in my engine, as I had assumed that. The old version suggests

At the beginning of each game, xboard sends an initialization string. This is currently "new\nrandom\n" unless the user changes it with the initString or secondInitString option.

but the new version does not seem to answer this explicitly.

All in all, even though in the old version it was nice to see how different protocol versions differ, it was a bit difficult to read. The new rewritten version seems to be much easier to read. I'll probably read it thoroughly and comment more later.

[Evert]

My first overall impression is that I like it, since it simplifies things and removes a lot of the cruft in the old version. I'm not entirely sure I like the loss of the clean break between GUI->Engine and Engine->GUI communication, but I do like the new grouping and in the end of the day you can't have both (well, you could - a list of Engine->GUI and GUI->Engine commands as an appendix is possible and would cover that; not sure it's really needed). There is one change in phrasing I take issue with, you can probably guess which one, but I'll come to that in a bit.

There actually is a use for being able to tell when a particular feature was added, but it doesn't need to be colour-coded the way the old document was. A short appendix listing the major additions per XBoard version would be enough for that. The use-case is that you may want to check that certain features are available on a particular version of XBoard.

I did find the "recommended" value listed for features quite useful, as they help identify the newer features that the engine should try to support (say, ping). There is a measure of arbitraryness to this, of course, so we don't necessarily need it for all of them.

In general, be very careful that you do not change the protocol by rephrasing things, because that will lead to incompatibilities and buggy behaviour. Commands should still have the same documented behaviour.
The change in phrasing I referred to above is, of course,

The edit command puts the chess engine into a special mode, where it accepts the following subcommands

to

The edit command is a multi-line command, that ends with a line containig only a period.

These are not equivalent: the old description makes edit similar to analyze in that it changes how the engine behaves. The difference is that according to the old spec I can respond to edit as a command (in particular one I don't implement) by "Error (unknown command): edit" whereas in the new spec I have to wait for "." before I can do that.
The old protocol description certainly allows one to implement "edit" as a multi-line command, but it doesn't require it and that is the main difference.
I know we don't fully agree on correct behaviour in this case (although we seem to agree that sending "feature setboard=1" implies I should never have to deal with "edit", even after "rejected setboard", but that is not stated explicitly in the new text), but I do think this is effectively a protocol change that should be avoided if the goal is just to clarify the specs.

I'll check later if I think there are other places where this sort of change in meaning is present. What we don't want is "CECP original protocol" and "CECP rewrite protocol" which are subtly different.

[hgm]

(well, you could - a list of Engine->GUI and GUI->Engine commands as an appendix is possible and would cover that; not sure it's really needed).

Yes, this sounds like a good idea. I can make two main columns, for engine->GUI and GUI->engine, and vertically keep the same distribution in sections (where possble putting the command and its reply in the same row).

There actually is a use for being able to tell when a particular feature was added, but it doesn't need to be colour-coded the way the old document was. A short appendix listing the major additions per XBoard version would be enough for that. The use-case is that you may want to check that certain features are available on a particular version of XBoard.

The old document was a strange mixture between protocol specs and description of XBoard behavior, and I tried to cleanse it as much as possible from the latter. It would not do any harm to devote an appendix table to XBoard. Or perhaps just an extra column in the command overview table to list the 'introduction version' of the command.

I did find the "recommended" value listed for features quite useful, as they help identify the newer features that the engine should try to support (say, ping). There is a measure of arbitraryness to this, of course, so we don't necessarily need it for all of them.

As far as I am concerned this really only applies to 'ping'. It cannot be stressed enough how important 'ping' is; without it the protocol sucks, and causes problems with moves from one game flowing over into the next. Whether people implement 'analyze', 'draw' or 'setboard' is really just a personal preference. Perhaps using san=1 deserves to be strongly recommended against. (What if a GUI rejects it?)

I guess I could point out the essential importace of 'ping' in the general text on the handshaking, where it is now only said the engine should print done=1.

In general, be very careful that you do not change the protocol by rephrasing things, because that will lead to incompatibilities and buggy behaviour. Commands should still have the same documented behaviour.

I agree of course about the genral principle. But on the patricular case of 'edit', if the descriptions are different, then what is actually the difference? If you expect the wording in terms of a 'mode' to allow an immediate Error response to 'edit' to prevent the remaining lines of the command to be sent, than this would definitely be the wrong description. Because despite the fact that this is the wording used in the original specs, there exists not a single GUI on the planet that would behave that way. The de-facto standard is that GUIs, and certainly all XBpard/WinBoard versions, just dump the command plus all the lines upto the period, before starting to process input again. Engines can respond immediately to 'edit' with an 'Error', but this reply will just sit in the pipe untill the GUI is done.

If there is a discrepancy between the de-facto standard and the specs, I think it is better to change the specs. It would be in no one's interest to retroactively declare all existing GUIs broken, and put unreasonable demands on future GUIs, just to rescue the exact meaning of the old description.

I guess there is a fundamental flaw here in the protocol, that can only be repaired here by an extra rule:a GUIs must not send 'edit' to an engine that has sent 'setboard=1' in combination with 'san=1', even when they reject 'setboard'. (Or, more drastically, require that any v2 GUI must support setboard. Which is probably more in line with what existing engines expect: no engine I know of that sends setboard=1 would be able to understand the edit command.) For v1 GUIs, which never get to see the features because they don't send 'protover', so they will also never send SAN. So we could add the remark that when running on a v1 GUI engines should never parse input lines as if they were SAN.

[xmas79]

Hi HGM,
the document still doesn't say that setboard command specifies also what color the engine (and not the position) plays.

[Evert]

Hi HGM,
the document still doesn't say that setboard command specifies also what color the engine (and not the position) plays.

As far as I know it doesn't. Certainly all my programs will start thinking immediately if they play black and you setboard a black to move position.

I would actually prefer it if setboard would automatically set the engine to force mode, but of course the GUI can just send force\nsetboard instead, so there is no need to specify this in the protocol.

[hgm]

Actually I have been thinking setboard would put the engine in force mode for a long time, and most of my engines implemented setboard that way. It never gave rise to any problems, because XBoard always does put the engine in force mode, before using setboard. There has been a proposal for a v3 version of the protocol, which would make the latter an official requirement (for setboard as well as many other commands). But I did not see much benefit in this.

I am not sure what to make of this silly work-around for the 'black' command. For one, it is broken in Xiangqi and Shogi, where the initial position does not have a Pawn on a2. The old document present it as an XBoard peculiarity, rather than a protocol requirement.

Features like colors=0, draw=0, time=0 also seem unholy inventions. What is the point of instructing a GUI not to send a 'draw' command? If you were foolish enough to make your engine such that it would choke on a draw command (which means it is non-compliant, as there the protocol prescribes how to handle unknown commands, and how would you manage to do that anyway?), it would require a change to make it so. And changing it such that it would ignore 'draw' (silently or with an Error reply) would be much more logical than having it print 'feature draw=0'. Having a feature to switch off the use of a command that would be used by default is imo a completely non-sensical solution. For sigterm and sigint there is some justification, as these use a system resource that might be inefficient, and would otherwise not be needed.

That it is recommended to have 'playother=1' is a joke, as XBoard does not even support playother, so that an engine would only send it to be rejected. It is true that I am often annoyed that I cannot set the engine to play black when white is on move (e.g. after recovering from an operator error in an OTB tournament), but if a GUI would have wanted to support that, it would have been quite easy to do it without 'playother', by just having a flag to indicate the engine is currently in force mode and the GUI wants it to be in black mode, and send a 'go' in that case whenever black gets on move. (Or more general and less error prone: let the GUI keep track of what the engine thinks it is playing, as well as what the GUI thinks it should play, and take corrective action whenever possible and needed by sending 'force' or 'go'. One day I might re-write the GUI-book code that way.)

[xmas79]

Hi HGM,
the document still doesn't say that setboard command specifies also what color the engine (and not the position) plays.

As far as I know it doesn't. Certainly all my programs will start thinking immediately if they play black and you setboard a black to move position.

I would actually prefer it if setboard would automatically set the engine to force mode, but of course the GUI can just send force\nsetboard instead, so there is no need to specify this in the protocol.

I know this because we already had a discussion about it (from this post on):

http://www.talkchess.com/forum/viewtopi ... 78&t=51761

[hgm]

The conclusion of that discussion also was that the 'setboard' command would not make the engine play any particular side.

I don't think there is any ambiguity about this in the original specs. It does not mention any effect of the command on the side the engine plays. This must be taken to imply there is no such effects. For commands that do have an effect, (new, white, black) it is always mentioned explicitly. The specs never explicitly point out thing the command does not do. E.g. it also doesn't say that the engine should not quit after receiving setboard, or that it should not switch pondering off, and that doesn't mean it is ambiguous whether the engine should in fact quit or alter ponder state.

It seems my sample WB-protocol driver is in error, as for 'setboard' it actually says "engineSide = NONE;", meaning it switches to force mode. This is wrong. You only end up in force mode after 'setboard' because XBoard always put you there before it sent 'setboard'. The assymmetry between edit/white/black on the one hand and setboard on the other is of course regretable.

[hgm]

The old version says:

Mate scores should be indicated as 100000 + N for "mate in N moves", and -100000 - N for "mated in N moves".

This seems to be removed; is this intentional?. The GUIs I use don't seem to have implemented this feature, so I don't know if it's ever used.

Thank you for your remarks. No, this was not intentional, but an oversight. It was a recent addition to the specs (it seemed desirable to have a standard for this), and the latest XBoard/WinBoard (4.8.0) implements it. (Which means that to would print M6 in stead of 1000.06 in the Engine-Output window or embedded PGN.) The only engine I know that implements it is Joker. (I even forgot to adapt Fairy-Max to support it...). But I think I did implement it in Polyglot, so implicitly all UCI engines running under WinBoard should support it now.

The new version does not specify precisely what MPS actually means. From the old version, I understood that (a) a "level 40 5 0" command followed by 8 forced moves for each side means that the engine gets more time when it has played 32 moves, and (b) a "setboard" command specifying the move number to be 9 followed by "level 40 5 0" command means that the engine gets more time when it has played 40 moves. The new version seems to leave case (b) ambiguous.

OK, I will make that more explicit too. Many engines are defective in this respect.

Does a "new" command have to be sent before the start of the first game after the initial handshake? IcsDrone does not do that, which resulted in an interesting bug in my engine, as I had assumed that.

My understanding is that it must be sent. The specs do not define the state of the engine or game after the handshake. (Which is strange, because there seems the implicit requirement for the protocol to work that the engine must not consider itself on move, and produce a move as a result.)

The old version suggests

At the beginning of each game, xboard sends an initialization string. This is currently "new\nrandom\n" unless the user changes it with the initString or secondInitString option.

but the new version does not seem to answer this explicitly.

This is a description of XBoard behavior, and not of the protocol. Whether GUIs send random, and during which stage of the game (e.g. only after the engine leaves GUI book) is up to the GUI designer.