Evert wrote:Sure, I know that the current variant is MyAwesomeNewChessVariant357, because I defined that in my options list, XBoard placed it on a button and the user selected that, which prompted XBoard to send me "variant MyAwesomeNewChessVariant357". It's now up to me to tell XBoard what that means.
If I understand correctly, that would require me to keep track of whatever the previously selected variant was, ...
No. In this case the variant is unknown/invalid/engine-defined, and leaving it like that will cause an error for sure. Another way of thinking about it is that the variant is 'undefined' at this point, so that anything can happen when you leave it like that.
... as well as understand what that means in terms of pieceToChar - which is tricky because these aren't actually documented anywhere as far as I can tell
If the variant is not defined, the pieceToCharTable isn't either.
(this would be a good thing to have in the documentation, along with the startup FEN, although you can get that one by just selecting the variant without an engine loaded and copying the current position). Apart from that, Sjaak actually doesn't "know" what a pieceToChar table is. All it knows are a startup FEN and possibly a "setup" string that have to be sent to XBoard.
A pieceToCharTable has two aspects: the letters that occur in it, and the position of these letters in the table. The latter has no meaning for the engine, and is a pure GUI thing. (Except that in the case of + and ~ the engine should be able to match the promoted with the unpromoted pieces.)
It is true that this isn't documented anywhere, but in most cases it is pretty obvious (if you know the variant). And even if there is controversy over what the standard is, you can fire up XBoard, select the variant, select 'Copy Position', and you get the FEN of the opening position. Which in almost all cases contains all participating pieces (or at least all participating pieces that have letters associated with them). So in a sense XBoard is self-documenting here.
It just seems to me that "knowing" these things requires knowing a great deal about understanding something about the inner workings of XBoard. From my perspective, it shouldn't be necessary to understand the intricacies and quirks of one particular GUI beyond what's specified in the protocol.
That is debatable. The rules of Chess, for instance, are not specified in the protocol. Yet if you would not know how to play Chess at all, you would not get very far writing an engine for it, even if you are allowed to consult the CECP specs as often as you like. And knowing the names of the pieces or their ID can be considered (a very minor) part of the game rules.
The information that is in the ordering (i.e. which images to associate with a piece of a given name) is indeed a very troublesome aspect of the pieceToChar info. It is totally GUI dependent, and except for the orthodox Chess pieces there are no standard symbols. In an ideal world the pieceToChar info would be superfluous, and all info could be sent as 'piece' commands. The GUI could interpret the piece move, and decide what symbol best fits that move. (Or decide that globally for the entire piece set, if multiple pieces would compete for the same symbol.)
On the other hand, XBoard is clearly the only game in town when it comes to this particular niche, so it's not too bad to just target XBoard specifically. It also does a fantastic job of what it does, especially considering that it was never designed for playing half of what it can do now.
As another example of what I'd call an XBoard quirk that's not very well documented, I just got bitten (again) by the problem that if you specify holdingsize 1, you can only store pawns there. I realised what the problem was because I remembered you mentioned you needed to change the pieceToChar table for Mini Shogi.
Well, holdings are another 'open nerve'. One can specify holdingsSize, but not what the holdings are used for. E.g. whether captured pieces should go into their own holdings, or (after color flipping) into those of the opponent. Or, indeed, not at all (as in Seirawan).
I started with internal piece numbers (the pieceToChar ordinals) mapping 1:1 on holdings positions, which is why I had to squirm to get Shogi working, as it required all the held pieces to be contiguous in the low part of the table. This is why the Shogi Lance is really a Queen. (But promoted pieces needed special representation anyway, not useful for other variants, so that was not a big deal.)
Now this has been improved by at least ignoring pieces not present in the pieceToChar. But it still means I need an unnaturally large holdings size in Seirawan, because it also needs space for PNBRQ, while it only wants to store H and E.
Perhaps the 'piece' commands can be used to improve the matter. They can indicate which pieces can be dropped, and for pieces that cannot be dropped no place needs to be reserved in the holdings.