WB protocol specs

[hgm]

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.

I guess there is an important distinction between protocol specs, and a guide for engine authors on how to implement WB protocol. In the latter case it would be acceptable, and perhaps even desirable to make a selection of the protocol, and only present the alternatives we recommend. If we want to simplify the presentation, there is a whole lot of commands that seem almost useless to anyone that only wants to make a regular engine, rather than (say) a bot that directly interacts with an ICS to give commands and chat with people there. Basically all commands I grouped under 'frills' fall in this category, plus the features to switch them on. So we could prescribe the use of

feature ping=1 memory=1 smp=1 setboard=1 usermove=1 debug=1 draw=1 colors=0 sigint=0 sigterm=0 done=1

as fixed final response to 'protover', (which could be preceded by more feature commands), and remove discussion of these features (except done=0) from the description, as well as the 'edit', 'white', 'black' and 'playother' command, and the Linux signals. When we then also kick out the commands 'ics', 'name', 'rating', and their associated features, as well as all the ICS tell commands (tellall, tellother, tellopponent, tellics, tellicsnoalias) and feature san.

The 'variant', 'setup' and 'piece' commands, and 'feature variants', as well as the highlight protocol could be kept in a separate section which most people would not read, of which the Bughouse stuff could then be made a sub-section.

Some things I am not sure about how we should handle them:

* is there any point in restricting the set of commands that must be received in analyze mode? The old specs give a list, which already contains some commands that XBoard would never send in analyze mode (like 'new' and 'setboard'). In any case 'option' would have to be
added to the list, as it is desirable to be able to change the multi-PV setting during analysis. But personally I don't see any reason why commands like 'go' and 'force' should be forbidden. None of my engines that support analysis would have any problem with those. ('exit' seems to be a synonym for 'force' anyway...)

* should we encourage the use of the 'usermove' prefix, or rather discourage it? The prefix makes it easier to distinguish unknown commands from illegal moves (to give the proper error response, which is important). But it makes it very annoying to use the engine from the command line.

* I adopted the policy to always request sending 'memory' and 'cores' commands; engines that have no use for them can always ignore them, or respond to them with Error (unknown comand). There seems no reason to complicate things by switching off commands you have no use for. (In this respect it is inconsistent to send feature colors=0. I am not even sure why GUIs would ever want to send 'white' or 'black' commands when they do not use 'edit', but apparently XBoard does (at least for 'white'). Is this one of those silly work-arounds for badly non-compliant engines that people have long since stopped using, and now puts a burdon on all compliant engines to switch it off or suffer the silliness?

[Evert]

* is there any point in restricting the set of commands that must be received in analyze mode?

For backward compatibility reasons, yes.

The old specs give a list, which already contains some commands that XBoard would never send in analyze mode (like 'new' and 'setboard'). In any case 'option' would have to be
added to the list, as it is desirable to be able to change the multi-PV setting during analysis. But personally I don't see any reason why commands like 'go' and 'force' should be forbidden. None of my engines that support analysis would have any problem with those. ('exit' seems to be a synonym for 'force' anyway…)

All my engines use a separate input loop during analysis (or ponder) mode, rather than dropping back to the main command loop when they receive input. The reason is I don't want to interrupt the analysis if I don't have to; this is mainly a cosmetic thing of course, but changing the code so it could handle "go" while in analysis mode would be a relatively major change for me. I'd rather not.

* should we encourage the use of the 'usermove' prefix, or rather discourage it? The prefix makes it easier to distinguish unknown commands from illegal moves (to give the proper error response, which is important). But it makes it very annoying to use the engine from the command line.

Well, one can always keep track of whether the engine is in "xboard" mode or not and base appropriate behaviour on that. SjaakII, for instance, behaves slightly differently in xboard mode than in its normal mode: it suppresses "setup" or "piece" output in normal mode (it's just noise to the user), it normally prints a board and a prompt, and prints moves as SAN (each of these can be disabled separately though). It also normally catches SIGINT to interrupt a search, but in xboard mode it doesn't (so SIGINT terminates the program).
EDIT: forgot a major one: when not in xboard mode, "new" does not reset the variant to "normal".

In this respect it is inconsistent to send feature colors=0. I am not even sure why GUIs would ever want to send 'white' or 'black' commands when they do not use 'edit', but apparently XBoard does (at least for 'white'). Is this one of those silly work-arounds for badly non-compliant engines that people have long since stopped using, and now puts a burdon on all compliant engines to switch it off or suffer the silliness?

I never really understood why you'd need to send colors=0, it's not like the commands are particularly nasty or confusing to implement. On the other hand, I also never really saw the point of the commands, except when using "edit".
Perhaps the recommended value for "colors" should depend on what's done for setboard: "feature colors=0 setboard=0" leads to a problem where you can no longer specify the side to move in a setup position. Conversely, when "feature colors=1 setboard=1" the colour commands should be redundant (which should probably result in xboard not sending them).

[Michel]

But what do you think of the pseudo-code description I gave above?

I think it is indeed a good idea to present (parts of) the specification in pseudo code. The advantage of pseudo code is that it is unambiguous.

[hgm]

Well, one can always keep track of whether the engine is in "xboard" mode or not and base appropriate behaviour on that.

I guess not even that is needed; people that want to meke the engine usable from the command line could make it understand both plain moves and moves prefixed by "usermove". There is no reason not to accept "usermove" in non-xboard mode, and you don't have to worry on what to do on plain moves, as in xboard mode you would never get those.

I also never really saw the point of the commands, except when using "edit".

I checked the old specs, and it seems they are used to work around non-compliant implementations of the time and otim commands. This is why they are sent by XBoard even when 'edit' is never used. They are always sent then in combinations that are no-ops, though. So even completely ignoring them would not hurt (although I agree that the compliant implementation is pretty trivial too).

The pseudo-code I have now is this:

Code: Select all

<pre>enum &#123; &#40;PLAY&#41;WHITE, &#40;PLAY&#41;BLACK, FORCE_MODE, ANALYZE &#125; mode;
enum &#123; WHITE&#40;TO MOVE&#41;, BLACK&#40;TO MOVE&#41; &#125; stm;
enum &#123; OFF, ON &#125; ponder; 

while&#40;1&#41; &#123;
  if&#40;mode == ANALYZE&#41; AnalyzeUntilInput&#40;);
  if&#40;mode == stm&#41; &#123;
    move = ThinkUntilTimeUp&#40;);
    if&#40;move == NONE&#41; mode = FORCE_MODE; // game ended
    else stm = Opponent&#40;stm&#41;; // make move &#40;and send it to GUI&#41;
  &#125;
  if&#40;mode == Opponent&#40;stm&#41; && ponder == ON&#41; PonderUntilInput&#40;);
  command = ReadLine&#40;);
  ASSERT&#40;mode != ANALYZE || command in &#123;"new", "setboard", "usermove", "undo", "exit", ".", "bk", "hint" &#125; ); // annoy user by not doing it for no reason
  switch&#40;command&#41; &#123;
    case "force"&#58; mode = FORCE_MODE;
    case "new"&#58;   if&#40;mode != ANALYZE&#41; mode = BLACK; stm = WHITE;
    case "white"&#58; mode = BLACK; stm = WHITE;
    case "black"&#58; mode = WHITE; stm = BLACK;
    case "go"&#58;    mode = stm;
    case "playother"&#58; mode = Opponent&#40;stm&#41;;
    case "usermove"&#58;  if&#40;Illegal&#40;)) print&#40;"Illegal move"); else stm = Opponent&#40;stm&#41;; // make move
    case "setboard"&#58;  stm = SideToMoveFromFEN&#40;);
    case "result"&#58;    mode = FORCE_MODE;
    case "analyze"&#58;   mode = ANALYZE;
    case "exit"   mode = FORCE_MODE;
    case "easy"&#58;  ponder = OFF;
    case "hard"&#58;  ponder = ON;
    case "quit"&#58;  exit&#40;);
    case "pause"&#58; while&#40;( command = ReadLine&#40;)) != "resume") print&#40;"Error &#40;paused&#41;&#58;", command&#41;;
    case "edit"&#58;  ;
  &#125;
&#125; 
</pre>

[Evert]

I guess not even that is needed; people that want to meke the engine usable from the command line could make it understand both plain moves and moves prefixed by "usermove". There is no reason not to accept "usermove" in non-xboard mode, and you don't have to worry on what to do on plain moves, as in xboard mode you would never get those.

True, but there probably is a case to not handle plain moves in xboard mode in that case: by doing that you can assume that whatever input you don't understand is actually a command and not a move (I'm still a bit sloppy with that, admittedly - it's a lot harder to decide if something looks like a move that just happens to be illegal or is an unknown command if you can parse a number of different move formats; improving this is on the list).

I checked the old specs, and it seems they are used to work around non-compliant implementations of the time and otim commands. This is why they are sent by XBoard even when 'edit' is never used.

It must be nice to be able to cull such crap from XBoard itself too. I'd imagine most current (maintained) engines don't have these problems (and if they do they should be fixed). Perhaps this could be phased out by first making this a compatibility option and then removing it further down the line.

Of course it's not good to deliberately break programs that used to work, but at the same time, nice clean and maintainable GUI code is important too.

[hgm]

by doing that you can assume that whatever input you don't understand is actually a command and not a move (I'm still a bit sloppy with that, admittedly - it's a lot harder to decide if something looks like a move that just happens to be illegal or is an unknown command if you can parse a number of different move formats; improving this is on the list).

True, but if you are not in XBoard mode it doesn't matter much if you reject it as an unknown command or as an illegal move; the user will understand in both cases that what he typed was ignored. In xboard mode it is important, because an illegal move causes a discrepancy between GUI and engine (game) state, as the GUI would not have sent the move if it had not accepted it by itself. And this needs to be corrected. The usermove prefix used by the GUI can guarantee you always can give the correct error response to have the GUI make that correction.