WB protocol specs

[Michel]

I am not sure this is the right approach to a stateful protocol.

I would think the protocol should be described as a list of states, with in each state the list messages that are legal for the GUI and the engine, together with a definition on how they change the state....

I am not saying this would be easy. But it would make the description unambiguous.

[michiguel]

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.

I think commands like edit should not even be discussed in a new description. When there are two ways of doing things (edit v setboard, for instance) the one that is preferred should be described and the one that is obsolete should be given a link to an appendix (in this case, the appendix could be the old protocol description). Description of obsolete commands are distracting and should be discouraged.

Whenever I have time I will go through it, but in general, I believe that thew new description should be written like the old "vices" of xboard do not exist. This has been the reason why xboard got a bad name of "being difficult" when in reality it is no so. One needed to go through paragraphs explaining things only relevant for the old gnuchess... that should be archived. I am not saying it should not be supported, but it should get out of the way.

Miguel

[Evert]

I think commands like edit should not even be discussed in a new description. When there are two ways of doing things (edit v setboard, for instance) the one that is preferred should be described and the one that is obsolete should be given a link to an appendix (in this case, the appendix could be the old protocol description). Description of obsolete commands are distracting and should be discouraged.

One would first need to reach a consensus on what the preferred command is. I agree with the principle, but I think HGM for one prefers edit (he'll correct me if I'm wrong). The main problem with it anyway is that the protocol allows you to disable the "white" and "black" commands, leaving you with no way to specify the side to move.

[Evert]

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.

Probably true. There is a work-around for that particular problem, of course, which is to start a new process for each game. This is just working around the problem rather than fixing it, of course.

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 don't see why you'd ever send SAN=1. I mean, my programs understand SAN, but I see no reason to request that the GUI sends the moves in the same format.

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.

Probably a good idea.

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.

So they're not following the protocol description accurately.

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.

I would argue that this is, in fact, a GUI bug. One that may be unlikely to bite (since the circumstances where it would are fairly specific and perhaps contrived) but a bug all the same.

Let's not forget that the reason edit is defined the way it is, and the reason XBoard uses it the way it does (and gets away with this) is because that's how GNUChess originally behaved. It wasn't implemented as a special "send list of pieces" command, but as an "edit the board" mode, which is useful in a chess program but not so much in a chess engine.

If you were to design the "edit" command from scratch, you would probably design it as a command that clears the board, sends a list of white pieces, a separator character, and a list of black pieces, followed by a termination character. I would.
On the GUI side you can certainly realise this using edit by defining the command as "edit\n#\n", the piece-separator as "\n", "c\n" as the separator between white and black and the termination character as ".\n"

However, this is not how "edit" was originally described. It isn't defined as a way to send a list of pieces, but as a mode for editing the board and there is nothing in the protocol spec that says you have to treat it any particular way, and engines that expect exactly this form may break when used with a GUI that doesn't behave the same as XBoard. I'm not saying that's likely, just that the protocol allows for it.

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 disagree with this on principle, but I would say existing GUIs are non-conformant in this particular respect rather than broken. The distinction being that "broken" suggests that it doesn't work and "non-conformant" meaning that it may well work, but it cannot be relied on (and should be fixed in some future version, which may be in the indefinite future if the non-conformity doesn't cause problems in practice). Mentioning the non-conformity as something to be aware of may be a good idea though (in some sort of appendix, probably).
Note that I think future GUIs shouldn't implement "edit" at all.

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

I would go one further: sending "setboard=1" implies "edit=0", regardless of whether "san=1" or not. Does anything really break when the engine interprets an edit piece-placement as a move? The engine wouldn't have the correct position on the board whether it ignored anything in edit-mode or not. You're just delaying the moment where the problem comes to light (one potential problem is that the engine may start thinking if it encounters what it thinks is a legal move, but switching it to force mode first takes care of that danger).

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

Well, as I said: does it really change anything in practice? The engine will have the wrong position on its internal board if it did not process "edit" anyway.

[Evert]

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.

I think that's exactly what it should be considered as. It looks like an extremely ugly hack that tries to work around a problem that would not exist if the protocol didn't allow you to disable the commands that allow you to specify the side-to-move to begin with (ie, colors=0).

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.

colors=0 is pretty stupid (I actually send "colors=0" because I was in a lazy mood back in the day and you don't actually need "white" and "black" if you don't support "edit"). However, time=0 has to take the cake for deliberately trying to break things. How else are you supposed to keep the engine and GUI clocks synchronised?

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.

That's hilarious.
Never really saw the point of that one either.

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

You mean it doesn't work that way? It seems like the most natural way to keep track of this.

[hgm]

The only sensible GUI reaction to an "Error (unkown command): edit" message would be to perform a 'New Game' action, and informing the user (e.g. through a popup) that this engine only supports setting up the standard opening, and whether he would please play the moves needed to transform that to the position he wants. (Too bad for him if it isn't reachable.) To design such a sequence of moves by itself goes well beyond the duty of a GUI, imo. (XBoard also pops up an error box when the engine refuses an analyze command.)

It doesn't make any difference if the engine performed some random moves in response to edit. The point is that it did not set up the requested position, and all other actions would be 'equally wrong'. GUIs should simply not expect the game-state to be defined after a failed 'edit'.

If the engine-intf.html document suggest otherwise, in particular that the GUI should realize that the Error response only meant the 'edit' line was ignored, so that it in principle can figure out how the individual piece placements changed the game state, I think it was in error, and needs to be corrected. I don't think specs should be considered to be above error, when thet require something crazy, especially not in this case, where half of the document is not true specs but a description of the behavior of a particular implementation.

I think everyone takes setboard=1 to imply edit=0. But I also think that setboard=0 (explicit or implied) should imply edit=1. I don't agree that a program that prints "Error (unknown command): INPUT" in response to any INPUT is a CECP implementation, anymore than that someone who has learned to say the single sentence "No hablo español" can claim to speak Spanish (and if he could, he would still be lying! ). There is a core set of commands you must support before you can claim to implement CECP, and a command to set up a position is one of those.

[Evert]

The only sensible GUI reaction to an "Error (unkown command): edit" message would be to perform a 'New Game' action, and informing the user (e.g. through a popup) that this engine only supports setting up the standard opening, and whether he would please play the moves needed to transform that to the position he wants. (Too bad for him if it isn't reachable.) To design such a sequence of moves by itself goes well beyond the duty of a GUI, imo.

Certainly.

I think everyone takes setboard=1 to imply edit=0. But I also think that setboard=0 (explicit or implied) should imply edit=1.

Yes, this is probably true. I guess the interpretation is that "edit = !setboard".

I don't agree that a program that prints "Error (unknown command): INPUT" in response to any INPUT is a CECP implementation,

To any input, probably not. But it is responding correctly according to the protocol.

There is a core set of commands you must support before you can claim to implement CECP, and a command to set up a position is one of those.

It's an interesting point. I agree that a program that doesn't have the ability to set up a position is next to useless, but even so: it may still be able to play a game from the starting position using CECP protocol. Clearly not a limitation that needs to be defined in the protocol spec.

[hgm]

I am not sure this is the right approach to a stateful protocol.

I would think the protocol should be described as a list of states, with in each state the list messages that are legal for the GUI and the engine, together with a definition on how they change the state....

I am not saying this would be easy. But it would make the description unambiguous.

I never found a complete state diagram of a CECP engine particularly illuminating. The problem is that the full state is really a product of a number of nearly independent state machines: one for the engine mode, one for the game state, one for each option setting (where in particular ponder on/off is important). And even in these underlying state machines, the effect of commands is usually independent of the state in which they are received (e.g. "force" always puts you in force mode, "analyze" always put you in analyze mode, etc.). That also makes that the description of the state machine just gets needlessly complex with duplications.

It could be good to stress that there is an engine state { (PLAY)WHITE, (PLAY)BLACK, FORCE_MODE, ANALYZE } and a game state { WHITE(TO MOVE), BLACK(TO MOVE) }. And then describe the state machine with pseudo-code like

Code: Select all

while(1) {
  if(mode == ANALYZE) AnalyzeUntilInput(); else
  if(mode == stm) {
    move = ThinkUntilTimeUp();
    if(move == NONE) mode = FORCE_MODE; // game ended
    else stm = Opponent(stm); // make move
  }
  if(mode == Opponent(stm) && ponder == ON) PonderUntilInput();
  command = ReadLine();
  switch(command) {
    case "force": mode = FORCE_MODE;
    case "new":   mode = BLACK; stm = WHITE;
    case "white": mode = BLACK; stm = WHITE;
    case "black": mode = WHITE; stm = BLACK;
    case "go":    mode = stm;
    case "playother": mode = Opponent(stm);
    case "usermove":  if(Illegal()) print("Illegal move"); else stm = Opponent(stm); // make move
    case "setboard":  stm = SideToMoveFromFEN();
    case "result":    mode = FORCE_MODE;
    case "analyze":   mode = ANALYZE;
    case "exit"   mode = FORCE_MODE;
    case "easy":  ponder = OFF;
    case "hard":  ponder = ON;
    case "quit":  exit();
    case "pause": while(( command = ReadLine()) != "resume") print("Error (paused):", command);
    case "edit":  ;
  }
}

[Michel]

force" always puts you in force mode,

Even this is not totally clear. One could argue that one should first send "exit" in analyze mode (this is what the old protocol description seemed to say).

The point is that an informal description of a stateful protocol inevitability contains ambiguities. A state diagram forces one in principle to think about every possible transition (no matter how weird).

I seem to recall there is also an ambiguity about the state after the engine startup before new. It may be meaningful to say that in that case the state is "undefined" so that the GUI is not allowed to rely on it.

[hgm]

Even this is not totally clear. One could argue that one should first send "exit" in analyze mode (this is what the old protocol description seemed to say).

The specs say indeed that sending 'force' in analysis mode is illegal. But it also says that 'exit' should put you in force mode, making 'exit' do what 'force' should have been expected to do. There seems to be a completely unnecessary ban on most commands in force mode. But I am not sure that a state diagram would be the best way to get that info across. IMO it would be better to state GUIs should limit what they send in analyze mode for no reason that the specs say so.

The point is that an informal description of a stateful protocol inevitability contains ambiguities. A state diagram forces one in principle to think about every possible transition (no matter how weird).

I am not convinced this is 'inevitable'. But what do you think of the pseudo-code description I gave above?

I seem to recall there is also an ambiguity about the state after the engine startup before new. It may be meaningful to say that in that case the state is "undefined" so that the GUI is not allowed to rely on it.

Indeed, this I remarked upon already above. Of course the fact that the informal description contains an ambiguity could already be taken to imply the state is undefined. But it should be made clear that it should not be undefined to the extent that the engine could spontaneously start printing and moving. In paractice engines do spontaneously start printing stuff, and consuming lots of CPU (e.g. initializing tablebases).