WB protocol for engine comments

Discussion of chess software programming and technical issues.

Moderator: Ras

User avatar
hgm
Posts: 28395
Joined: Fri Mar 10, 2006 10:06 am
Location: Amsterdam
Full name: H G Muller

WB protocol for engine comments

Post by hgm »

It is sometimes convenient to output engine debug information to the GUI, for inclusion in the debug file. The trick is to make sure the GUI will ignore these lines (except from writing them in the debug file), and not get upset by them.

From WinBoard 4.3.13 on, there is now an official mechanism provided to achieve this:

Any line sent by the engine that starts with a '#' character will be considered a comment by WinBoard. Engines can write anything in such lines without fearing they might be interpreted in an unintended way by WinBoard.

To switch on this option, you have to send 'debug=1' amongst the features. The default for this feature is debug=0, meaning that no special meaning s attached to the '#'. (This might mean WinBoard ignores the line anyway, but you can never be sure of that, e.g. if they would have the words 'draw' or 'move' in them.)

A little care is required for engines that want to use this: as 'debug' is a feature that is not in the protocol version 2 definition, not every protocol-2 GUI can be expected to support it. GUIs are supposed not to choke on featres they don't know, however: they should respond to such features by rejecting them, through a GUI->engine command:

rejected debug

An engine that wants to adhere stricty to protocol should thus switch off its debug output if, after requesting it through "feature debug=1" it receives the command "rejected debug". If it receive "accepted debug", it can savely output the comment lines.
User avatar
Zach Wegner
Posts: 1922
Joined: Thu Mar 09, 2006 12:51 am
Location: Earth

Re: WB protocol for engine comments

Post by Zach Wegner »

Well, what I do is just print it out anyways. If the engine is thinking, as long as the output can't be confused with a move or something, Xboard just ignores it, still printing it out in debug mode.

Not a bad idea though, I just don't think I'll implement it.
krazyken

Re: WB protocol for engine comments

Post by krazyken »

Are any of these changes to Winboard being ported to Xboard?
User avatar
hgm
Posts: 28395
Joined: Fri Mar 10, 2006 10:06 am
Location: Amsterdam
Full name: H G Muller

Re: WB protocol for engine comments

Post by hgm »

These are changes in the platform independent code, shared by xboard and WinBoard. (In backend.c, to be exact.) So those that compile . build an xboard version using those files, wil automatically have the option implemented as well.
F. Bluemers
Posts: 880
Joined: Thu Mar 09, 2006 11:21 pm
Location: Nederland

Re: WB protocol for engine comments

Post by F. Bluemers »

hgm wrote:It is sometimes convenient to output engine debug information to the GUI, for inclusion in the debug file. The trick is to make sure the GUI will ignore these lines (except from writing them in the debug file), and not get upset by them.

From WinBoard 4.3.13 on, there is now an official mechanism provided to achieve this:

Any line sent by the engine that starts with a '#' character will be considered a comment by WinBoard. Engines can write anything in such lines without fearing they might be interpreted in an unintended way by WinBoard.

To switch on this option, you have to send 'debug=1' amongst the features. The default for this feature is debug=0, meaning that no special meaning s attached to the '#'. (This might mean WinBoard ignores the line anyway, but you can never be sure of that, e.g. if they would have the words 'draw' or 'move' in them.)

A little care is required for engines that want to use this: as 'debug' is a feature that is not in the protocol version 2 definition, not every protocol-2 GUI can be expected to support it. GUIs are supposed not to choke on featres they don't know, however: they should respond to such features by rejecting them, through a GUI->engine command:

rejected debug

An engine that wants to adhere stricty to protocol should thus switch off its debug output if, after requesting it through "feature debug=1" it receives the command "rejected debug". If it receive "accepted debug", it can savely output the comment lines.
Looks usefull,I only hope that tlcv does not choke on it.
Some of george lyapko's tool might need to be updated too?
Best
Fonzy
User avatar
hgm
Posts: 28395
Joined: Fri Mar 10, 2006 10:06 am
Location: Amsterdam
Full name: H G Muller

Re: WB protocol for engine comments

Post by hgm »

Indeed, to remain maximally useful, these users of debug files would have to adapt to the new protocol as well. If they do , they would actually benifit from this a lot: currently engines just dump anything without warning, to see it included in the winboard.debug, suppsoing that WinBoard will ignore it. But even if WnBoard does, TLCV might not. And indeed, spurious engine output often makes TLCV crash.

There is not really an official protocol for debug files, but perhaps it would be a good idea to bring somewhat more order in this area.

Ideally all egines should refrain from spurious output, and use the comment mechanism described here, so programs like TLCV could ignore those lines. But of course many programs won't

The next best thing is that there could be a WinBoard option to not put any protocol-violating output of the engine into the debug. This would be bad for debugging, though. It is also a bit awkward to do, as copying the engine output to the debug file would have to be delayed until after the command parsing. Now fortunately there aren't so many commands the engine could send to WinBoard. I count only:

move ...
feature ...
offer draw
resign
1-0 {...}
0-1 {...}
1/2-1/2 {...}
Illegal move ...
Error (...): ...
tell...

(the latter in a lot of flavors). And of course lists of numbers + PV moves during thinking or pondering. So it might be possible to pre-screen the engine output for starting with one of the listed keywords, and not writing it to the debug if it doesn't match.

Of course once the matching is done, WinBoard could just as easily pre-pend the line with '#' itself, before writing it to the debug file, if it doesn't match. Then the debug-processing prgrams can ignore such lines after all. Perhaps this is the best way to go, adding an option /engineDebugOutput=N, where N could be 0, 1 or 2, where 0 would mean that such output is not written in the debug, 1 would mean anything is written as the engine gives it, and 2 that it would be 'auto-commented out'. The latter might then be default.
krazyken

Re: WB protocol for engine comments

Post by krazyken »

That sounds nice, where is the place to go for current versions of the source?
User avatar
hgm
Posts: 28395
Joined: Fri Mar 10, 2006 10:06 am
Location: Amsterdam
Full name: H G Muller

Re: WB protocol for engine comments

Post by hgm »

The current source still changes by the hour. The last reasonably stable version (4.3.13c, which includes the engine comments, but not yet the option to auto-comment or suppress protocol-violating engine output in the debug file) can be obtained from Fonzy's website.

I am close to releasing 4.3.14, though. All of the additions and fixes I had in mind seem to be working now, so it is just a matter of collecting the source files for this version and zipping the tree. I would like to see if I can include an xboard version as well, even if it might not yet allow the use of all options. There are xboard sources around that work with an earlier version of my WinBoard back-end files.