CECP/WB2 protocl extension suggestion: feature metainfo=1

[elliechess]

Sorry to barge in with this as my first post, but I noticed something I find worth addressing:

E.g. Arena Chess GUI ships with the author name, country, and a nice logo for some engines, but has an apparently brittle matching of engine name to entry (supposedly to allow matching for future versions, it can lead to false positives). Also, obviously that info can be outdated for other reasons too. This made me wonder, there is myname="..." already, so why isn't there some way to specify more than just an engine's name through the protocol?

Therefore I propose the feature metainfo extension to allow a GUI to query an engine for name, logo, author,...:

Addition to "Initial Handshake" specs section:

Code: Select all

Initial Handshake
[...]

feature NAME1=VALUE1 NAME2=VALUE2 ...
    Feature commands are mostly used to control the commands the GUI [...]

    * metainfo (0) This specifies that the engine understands the "metainfo" command.
      This command allows an engine to provide more info about itself like name, author, etc.


Addition to "Frills" specs section:

Code: Select all

Frills
[...]

metainfo
   Can be sent from the GUI to the engine to ask for the metainfo fields it supports.
   This metainfo can be displayed by the GUI in some way during an engine tournament,
   or in advanced engine info dialogs, or other ways it sees fit.
   The engine must either ignore this, or answer with:
       Available info: KEY1,KEY2,KEY3
   Every such key must be ascii and without space characters,
   and any key refers to a metadata field name the engine makes available for query.

   Suggested metainfo fields to implement are:
   name (the engine's canonical name), author (name of the engine's creator),
   license (a short description of the engine's licensing situation, or the full license text),
   logo (base64 encoded image that should be JPEG and have aspect ratio 2:1),
   country (country of origin of the engine's creator fully spelled out),
   elo (the engine's supposed full playing strength as integer ELO number),
   website (an URL specifying the engine's website starting with http:// or https://).
   This is a non-exhaustive list, and any engine author may add more fields at their discretion.

metainfo KEY
   Sent by the GUI to query the given metadata field from the engine.
   The GUI must have checked through a generic "metainfo" query the field exists.
   The engine may send "Error (...some reason...): metainfo" if it cannot answer.
   Otherwise, it must respond with the field contents which may contain line breaks,
   and terminate the field contents with a line containing just a dot.
   Please note this means no metainfo response may ever contain a line with just a
   dot anywhere other than at the end of the output, since this is the designated end of output.
   A metainfo response may also never start with "Error " unless there was an error.
   Example response to request: metainfo license
           Copyright (C) All Rights Reserved.
           .
   (Please note the empty line with dot to terminate the output)
   The engine should avoid sending overly long lines.
   This applies especially for the logo metadata field when it responds base64:
   an engine should break up too long lines into multiple ones to ease processing
   for the GUI.

   If a GUI expects a certain format, like base64 JPG for the logo,
   then it must NOT crash if it's not met and is suggested to find other ways
   to display the metainfo field data to the user, e.g. as plain text.

   If the GUI doesn't get a well-formed response back with an
   empty line with dot at the end, then it is STRONGLY encouraged to fully ignore it.
   This shall encourage engine authors to always terminate their output properly.


Full usage example:

Code: Select all

theGUI: metainfo
engine: Available info: name, author, country, license
theGUI: metainfo author
engine: John Doe
engine: .
theGUI: metainfo license
engine: Copyright (C) John Doe 2018-2020
engine: All Rights Reserved.
engine: .


Maybe this is a bad idea for reasons I don't see, or really overkill - but I would like it if future engine releases more often came with more extensive info about themselves built-in, or even the logos. Wouldn't that be nice? I dunno, I can't help but like the idea

PS: I don't care for copyright or attribution for the text suggestions above in any way

[H.G.Muller]

This seems needlessly complex. CECP already allows the engine to send the 'metainfo' directly, through 'feature' commands similar to 'myname':

feature myname="Fairy-Max" author="H.G.Muller" version="5.0" country="Netherlands" date="24-12-2016"

CECP puts no restriction on the feature names an engine can use in reply to a "protover 2" command; for features not defined in the specs the GUI is likely to react to them with

accepted myname
rejected author
rejected version
rejected country
rejected date

and then happily continues in blissful ignorance of all this metainfo. Current WinBoard/XBoard would certainly do that. But GUIs that are designed to display such infos are free to use it (and then probably would respond with "accepted author", etc.

I don't think it a good idea for an engine to send actual image data to a GUI (such as logos). This violates the basic design that engines should have a text-based interface, and leave graphics to the GUI. Besides, engines would not have such image info as initialized data in their program, but would likely have to read it from an image file before relaying it to the GUI. In that case it would be much simpler if the GUI itself read the image file. The engine could of course just relay the name of the image file to the GUI, but it would only be able to do that if it would know where that file is, i.e. when the logo was part of the engine install. But by adopting a convention where in the engine install the logo should be this would be redundant, as the GUI could know this convention too. WinBoard, for instance, would look for files named "logo.bmp" in the engine directory, and if it finds one, use that image as logo.

[elliechess]

Thanks for responding, and aww, a shame you don't like it! Sadly the main point to me is indeed the embedding of images:

Besides, engines would not have such image info as initialized data in their program, but would likely have to read it from an image file before relaying it to the GUI.

I test-implemented this for my engine and it's pretty easy to compile an image into the binary, so yes my engine would have the image data initialized like that. (And I wrote this spec suggestion under the assumption engines would indeed not commonly read it from a separate file!)

The reason I think a properly baked-in image useful is that it appears to me people share engines just as .exe commonly, especially in obscure engine collections all over the web, and then the logo often gets lost which I find pretty sad. Humans have faces, I just thought it'd be nice if engines could have their logo shown in tournaments too with no extra effort for the organizers/end-user of the GUI in a more reliable way. (I say more reliable since WinBoard & Arena offer logos already, but only in this separate file way many don't seem to bother with. I found my own super old engine also archived on the web - cool! - but with its logo file missing...)

I don't know, maybe it's just me. But I basically saw the cool logos thing, was sad it wasn't more used and not more inherently provided with engines, and hence this suggestion. And putting metadata info like author name etc inthe feature string just seemed a bit chaotic to me, so that is why I added this in with it to solve two things at once basically. But of course it's not deeply important or anything, so I get if you want to pass on it

Edit: additional note:

This violates the basic design that engines should have a text-based interface, and leave graphics to the GUI

I kinda get this, but for engine logos this is just kind of inherent to what they are. And I think they are a worthwhile exception for the otherwise quite text-based world of chess for some spots of color and cheering when recognizing a familiar logo in a tournament, but yeah maybe just me interested in that I dunno

[H.G.Muller]

What you seem to overlook is this: when authors do not even bother to provide a logo in a separate file, they will certainly not be going to bother to include it in the engine's executable as initialized data. Designing a more complex way to distribute logos than the one already in use will not make that more people are going to do it.

I also think you are wrong about sharing of .exe engine files only. There are many engines for which the bare .exe would not work, but require some kind of .ini file for configuring it. Engines are typically distributed as archives (e.g. .zip, .rar or .tar.gz), containing many files. Even many .exe files, as nowadays people make many different compiles for the various CPUs (for which standardization is sadly fading away), to use sse, bmi, popcnt and all those instruction-set extensions which might or might not be supported by the user's CPU.

For engine authors that care about logos it would be by far the easiest to just pack the bitmap with the engine.exe in a zip file, and just have the engine exit with an error message if it does not find a file with that name in its current directory. That is much less work than including it in their source code as initialized data, and implementing a metainfo command for printing that info. And the less work it is, the more likely it is that some of them are going to do it.

It also would bring a lot of platform-dependence to the engine: WinBoard needs logos in .bmp format, but XBoard needs .png, and who knows what other GUIs would want. When authors make compiles for various platforms, they could distribute each compile with a logo in the image format that is in common use on that platform, without any additional hassle.

The point is that things like this can only work if there is a standard, and enough people are willing to embrace that standard. And the latter strongly correlates with the simplicity of the standard. Creating a logo image would in all cases be a necessary step. The way I envision it, it would be the only step, as people would zip their engine distros anyway. What you propose would require them to do a whole lot more, that in addition would not work at all on most GUIs. (Where including the logo as a separate file already does work!)

[elliechess]

What you seem to overlook is this: when authors do not even bother to provide a logo in a separate file, they will certainly not be going to bother to include it in the engine's executable as initialized data. Designing a more complex way to distribute logos than the one already in use will not make that more people are going to do it.

This could just be me again, but personally I am not sure i will include one now since it's more inconvenient and in the past people lost it anyway. Because as for people sharing of .exe engine files only when there was other stuff like a logo image available, I have seen it.

I wonder since you say XBoard can't parse the simple & common .bmp, maybe that could be worth adding/patching? (Independently of this feature suggestion)

The point is that things like this can only work if there is a standard, and enough people are willing to embrace that standard.

I suppose, but it takes just one GUI to support it to allow people to get started, because there is not really a downside to implementing this for an engine author. (Unlike adding in an additional file and offer a .zip instead of distributing a plain .exe which increases the complexity of passing it around.)

Maybe making my proposal include other metadata too makes it indeed to complicated, I find that a fair point, but a simpler one could provide a nice starting point maybe? I could think up something that does the image thing only, that could be a lot simpler to spec out.

Edit:

maybe something like that?

Code: Select all

Frills
[...]

logoimage
   Can be sent from the GUI to the engine to ask for a logo image
   to represent the engine in tournaments and similar.

   The engine may either ignore this, or respond with either a file name to be
   checked by the GUI in the engine directory like this:

   Logo: mylogo.bmp

   or respond with a base64 image data for a .BMP image like this:

   Logo: Qk2K8isAAAAAAIoA...

   (ellipsis indicating more data following)

   The GUI must first assume the returned value is a filename, and only
   if no such file is found on disk it should try to parse it as base64.

   The engine should only offer images in the common BMP format if
   it wants to ensure the GUI is able to display the image on any platform.


[H.G.Muller]

This could just be me again, but personally I am not sure i will include one now since it's more inconvenient and in the past people lost it anyway.

You can prevent people from losing it by having the engine test for its presence, and exiting if it is not there. This would still require less code than including the image in the source.

I wonder since you say XBoard can't parse the simple & common .bmp, maybe that could be worth adding/patching? (Independently of this feature suggestion)

The point is that this format is not common at all. It only exists in Windows. Formats like GIF, JPEG and PNG are universal. So it would be much better to patch WinBoard for using PNG. But that cannot be done without making WinBoard dependable on large 3rd-party libraries that are not automatically available on Windows machines.

I suppose, but it takes just one GUI to support it to allow people to get started, because there is not really a downside to implementing this for an engine author. (Unlike adding in an additional file and offer a .zip instead of distributing a plain .exe which increases the complexity of passing it around.)

So you say, but this is simply not true. If we would both start from the same point, where we have the source code of an engine in NotePad and an open MS Paint in which we just designed a logo, it would take you at least 100 times as long to add source code to handle the metainfo command, and convert the image to text you could include in your source code, as it would take me to save the logo in the engine folder and zip the latter. Because the whole thing would take me perhaps 5 sec at most. For someone that doesn't know yet how to include images as initialized data, a slowdown of a factor 1000 seems a more realistic estimate.

Maybe making my proposal include other metadata too makes it indeed to complicated, I find that a fair point, but a simpler one could provide a nice starting point maybe? I could think up something that does the image thing only, that could be a lot simpler to spec out.

Edit:

maybe something like that?

Code: Select all

Frills
[...]

logoimage
   Can be sent from the GUI to the engine to ask for a logo image
   to represent the engine in tournaments and similar.

   The engine may either ignore this, or respond with either a file name to be
   checked by the GUI in the engine directory like this:

   Logo: mylogo.bmp

   or respond with a base64 image data for a .BMP image like this:

   Logo: Qk2K8isAAAAAAIoA...

   (ellipsis indicating more data following)

   The GUI must first assume the returned value is a filename, and only
   if no such file is found on disk it should try to parse it as base64.

   The engine should only offer images in the common BMP format if
   it wants to ensure the GUI is able to display the image on any platform.


You could also have the engine .exe just save the bitmap included in its source code as a file in the current folder (when that file doesn't exist yet), rather than print it on its standard output. Then no one can lose it, you won't have to zip anything, you will stay fully compatible with the large group of engine authors that would prefer zipping a folder over meddiling with base64 data in their source code, and there already exists a GUI for which it works...

[elliechess]

Huh, an engine writing out an image file without asking? I don't know, that seems quite hackish to me. Good point on the time investment needed, but I meant no downsides for those who choose it is worth their time. After all a logo in itself also needs quite some time and could be considered useless, but if it needs an additional separate file that just adds to the downsides which I find a bit unfortunate & worth fixing, personally

You can prevent people from losing it by having the engine test for its presence, and exiting if it is not there. This would still require less code than including the image in the source.

This still seems to me like the most feasible way. But also way less elegant than just not needing a file in the first place, but I get that you don't want to pollute the protocol too much for something rarely ever used. I'd still implement a logo protocol function for sure (including the shorter alternative variant I suggested) but maybe I'd be the only one after all, it's not like I can tell

I personally think especially the shorter "logoimage" variant wouldn't hurt among other also somewhat obscure but neat functions (like chatting on ICC, I love that this is at least a possibility even though I never used it) so I can only hope maybe one day you'll change your mind

Edit: https://docs.microsoft.com/en-us/archiv ... ent-basics could this help for loading PNG under windows maybe? looks like a pretty ugly API but it should be available on all windows machines, so maybe that might be worth a look

[H.G.Muller]

Huh, an engine writing out an image file without asking? I don't know, that seems quite hackish to me.

This is called a 'self-extracting archive'. Your proposal basically is equivalent to
* designing your own archive format for storing multiple files (engine executable + logo image) as one
* Writing your own extractor for this archive format to retrieve the logo
* Implement a set of commands to activate this function

Good point on the time investment needed, but I meant no downsides for those who choose it is worth their time. After all a logo in itself also needs quite some time and could be considered useless, but if it needs an additional separate file that just adds to the downsides which I find a bit unfortunate & worth fixing, personally

Yeah, ignoring the price everything is free! It is of course your right to prefer whatever you want, personally. But in my assessment there would be virtually no other engine author in the world that would have the slightest interest in doing this if they can just zip the logo file with the engine.

Edit: https://docs.microsoft.com/en-us/archiv ... ent-basics could this help for loading PNG under windows maybe? looks like a pretty ugly API but it should be available on all windows machines, so maybe that might be worth a look

Thank you for the hint. I will take a look at it. It would be really nice if WinBoard could use PNG instead of BMP, as PNG is a compressed format, and the piece images (especially the large ones) should be highly compressible, as they are basically black & white, with gray scales occuring only near the outline due to anti-aliasing. The WinBoard-AA package, which uses external BMP (with transparency) images, in bloated enormously by the size of the latter.

[elliechess]

This is called a 'self-extracting archive'. Your proposal basically is equivalent to
* designing your own archive format for storing multiple files (engine executable + logo image) as one
* Writing your own extractor for this archive format to retrieve the logo
* Implement a set of commands to activate this function

I think there might be a misunderstanding here: to implement my logoimage proposal, all I did was just copy the binary base64 image string into a C header as a static array, and output that array to any "logoimage" command at runtime. Pretty easy and about 5 lines of code + a short python script I used to get the base64, and done. Not sure what you are suggesting but it sounds like something else that is way too complicated, and there is definitely no need to implement a new archive format.

In any case, it's not zero effort of course so I can see how you would think almost nobody will ever use this, and/or it's too much bloat for something not really that important. It was just an idea after all

[H.G.Muller]

Well, that is about what an archive program like tar does too, isn't it? Just concatenating all files in the archive, with some markers at the boundary so that it can later take them apart again.

[elliechess]

I mean I didn't really use a marker or anything, just `unsigned char base64_image[] = "...";` and that can be printed out with printf+fflush(stdout) and that's kinda it. I would find implementing a more complex archive format somewhat an overkill personally, but I guess developer preferences do differ. Reading/writing a file would also seem somewhat more cumbersome to me compared to just a built-in string printed out like that, both to code and for the user later to use. I really think the hardcoded base64 char array is pretty elegant and easy