About

This format has two main purposes:

• Lets the client know which chess engines are installed, and where to look for them.
• Cache and work as data model for engine information that would otherwise slow client at run time to discover.

For difficulty handling, the client should as default put some lines in each box, depending on the supported features of the engine, like depth for cecp engines and UCI_LimitStrength for uci engines.

How it works

Two files exist. Both sharing the same format.

• First one file exists. It is not writable to the user and is very general, and rudimentary. It contains all the information which cannot be discovered otherwise. At the moment only the binary name and the protocol needs to be included. (Look in the bottom of the example to see how this looks)
• When the client starts up, it looks in the first file for binary names, and compares them to the files in PATH. For those found, it creates a new file (writable for the user) with all the info it can find out about the engine. This includes the name, the UCI options and the md5 sum.
• If that the second file already exists, it looks if it can find any new engines, and if the found ones still has the same md5sum. If not, it does discovering again.
• When user configures the engines, the second file is updated.

Example

<engines>
    <engine protocol="cecp" binname="gnuchess">
        <path>/usr/bin/gnuchess</path>
        <md5>bee39e0ac125b46a8ce0840507dde50e</md5>
        <meta>
            <name>GNU Chess 5.07</name>
        </meta>
        <variants>normal,bughouse,crazyhouse,suicide,giveaway,losers</variants>
        <callname>GnuChess</callname>
        <cecp-features>
            <feature command="setboard" value="true" />
            <feature command="analyze" value="true" />
            <feature command="ping" value="true" />
            <feature command="draw" value="false" />
            <feature command="signint value="false" />
            <feature command="variants" value="normal" />
            
            <!-- The following features aren't told by the engines, but has to be
                 discovered manually (or read from an engine database).
                 
                 It is my experience that the commands should be tried both before and
                 after "xboard" being sent, as some engines will ignore the commands in
                 either their own or in xboard mode.
                 
                 We can know the the command isn't supported, when we get a response like
                 "Illegal move: edit" or
                 "tellusererror command 'edit' not implemented"
                 
                 However there is no perfect mode to find out, and we might end up with
                 "Illegal move" errors, because we tried to set a new board, but the
                 engine simply ignored it. In those errors an "Engine crashed" dialog
                 should be shown, allowing users to restart the engine or choose a new
                 one. -->
            
            <feature command="edit" supports="false" />
            <feature command="protover 2" supports="true" />
            <feature command="sd" supports="false" />
            <feature command="depth" supports="true" />
        </cecp-features>
        <options>
            <check-option name="Ponder" default="false" />
            <check-option name="Random" default="false" />
            
            <spin-option name="Depth" min="1" max="-1" default="-1" />
            <!-- The value -1 is interpreted as infinity, which in pracsis means that the
                 depth or sd option is not sent -->

            <custom-option name="book off" default="false" />
            <!-- Custom options are used to enable engine specific features.
                 They work like check options, but when they are enabled, their name is
                 simply sent to the engine as a command -->
        </option>
        <difficulty id="easy">
            <option name="Depth" value="1" />
            <option name="Random" value="true" />
            <option name="book off" value="true" />
        </difficulty>
        <difficulty id="advanced">
            <option name="Depth" value="4" />
            <option name="Random" value="true" />
        </difficulty>
        <difficulty id="expert">
            <option name="Ponder" value="true" />
        </difficulty>
    </engine>
    
    <engine protocol="uci" binname="fruit_21_static">
        <path>/usr/bin/fruit_21_static</path>
        <md5>34378c3de14d16f92ca30c34ed4fa5ca</md5>
        <meta>
            <name>Fruit 2.1</name>
            <author>Fabien Letouzey</author>
            <about>Shredder Classic 1.3 by Stefan Meyer-Kahlen, www.shredderchess.com</about>
            <!-- Copied from Shredder as Fruit doesn't use UCI_EngineAbout -->
            <country>USA</country>
        </meta>
        <options>
            <spin-option name="Hash" min="4" max="1024" default="16" />
            <check-option name="Ponder" default="false" />
            <combo-option name="NullMove Pruning" default="Fail High">
                <var value="Always" />
                <var value="Fail High" />
                <var value="Never" />
            </combo-option>
            <string-option name="BookFile" default="book_small.bin" />
            <button-option name="Fruit has no buttons" />
        </options>
        <difficulty id="easy">
            <option name="Hash" value="5" />
        </difficulty>
        <difficulty id="expert">
            <option name="Ponder" value="true" />
        </difficulty>
    </engine>
</engines>

<!-- Minimal version -->
<engines>
    <engine protocol="cecp" binname="gnuchess" />
    <engine protocol="cecp" binname="crafty" />
    <engine protocol="cecp" binname="faile" />
    <engine protocol="cecp" binname="phalanx" />
    <engine protocol="cecp" binname="sjeng" />
    <engine protocol="uci" binname="ShredderClassicLinux" />
    <engine protocol="uci" binname="fruit_21_static" />
</engines>

Document Type Definition (DTD)

TODO