ENGINEEXT.INI file layout

This documentation is based on winboard adapter version 5.0.0.30 

The engine plug-in module allows the use of winboard compatible chess engines with ChessPartner. From the dropdown box you can select which engine to use.

Use the Edit profile button to modify the settings for the engine profile.

You may get an error message asking to edit the engine profile, responding yes

brings up the plug-in profile selection dialog. Select crafty or gnuchess, you must edit the profile for the location of crafty or gnuchess.

In this release the profile is store in a simple text file, each engine profile start with a line [name] where name is CRAFTY, GNUCHESS, etc.

The file is located in the windows directory and called: ENGINEEXT.INI

Make sure to save the settings !

Of course you first have to install the various winboard engines. It is recommended to install each engine in its own directory below the engines directory in the installation directory e.g.

C:\Program Files\Lokasoft\ChessPartner\Engines\Crafty

C:\Program Files\Lokasoft\ChessPartner\Engines\GNUCHESS

etc.

The ENGINEEXT.INI file contains a number of sections. There is one section for each engine. A section starts with the engine name inbetween square brackets e.g. [Crafty]

Each section can contain a number of lines with keyword=value pairs. Ommited keywords will have a default value.

Since adapter version 4.0.0.15 It is possible to have all the options for a single engine in a separate file which is named after the engines executable. The file extention must .cpeini

e.g. engine name: crafty.exe , then create a file called:

crafty.cpeini that contains all the options for that

engine. The file format must be:

[Engine]

key1=value1

key2=value2

etc.

Note that the section header must be [Engine]

Options set in this engine specific file takes priority over the options set in ENGINEEXT.INI. There is no need to specify the engine path and directory in the engine.cpeini file. This makes it aesy for engine authors to supply a properly configured configuration file with the engine.

Most keywords are optional except the EnginePath key

Furthermore there are some parameters to control what kind of commands are send to the engines. In most cases it is not neccesary to change any of these. A command string can contain \n which is the same as enter typed from the command line. In this way it is possible to send multiple commands to the engine.

General keywords

Keyword Protocol

Default 1

This keyword controls what kind of protocol to use, the protocol controls the default behaviour of the adapter which can be modified by some of the keywords below. Currenty the following protocols are defined:

1 ( Winboard I ) No special action apart from what is defined in the keywords is taken.

2 ( Winboard II ) This causes the adapter to send the protover command as part of its initialization sequence, also the adapter will handle the feature commands. For most winboard II engines you only need the EnginePath keyword.

16 ( UCI ) Full UCI support, causes most of the string keywords to be ignored.

Keyword Console

Default 0

If console is set to 1 all commands that are send to the engine are displayed in a console window. Set this to 0 to hide the console window.

Keyword Logfile

Default

If a filename is given all commands are also saved in this file, useful for debugging. Leave blank for no logging.

Keyword EngineDir

Default

EngineDir specifies the directory where the engine is to be started from. If left blank the directory of the chess engine is used.

Keyword EnginePath

Default

EnginePath is the command line used to start the engine, is may be an absolute or relative path. In case of a relative path the ChessPartner installation directory is used as base. If the pathname contains spaces include it in between quotes. In that case possible parameters must be outside the quoted string.

Keyword EngineParameters

Default

Additional parameters which are passed on the engine command line can be given here. Variable names can be used as well. See the Engine Variables section.

Keyword Options

Default 2

This keyword contains some bit option values, the following options are defined. Multiple options can be combined by adding up the given values.

1 Invert score when engine plays black. This is to support engines that always return the score as seen from white.

2 Sends time/otime just before move is send to engine.

4 Sends time/otime to engine anytime clocks are changed, either by user changing clocks or by Chess server. (version 4.0.0.15)

16 Special option for Rebel Century, adapter sends "getvar bookmoves\n" which gets answered by a special formatted list of bookmoves.

32 MultiPV special. Only used for UCI engines (version 5.0.0.16 )

64 Don�t send ucinewgame ( version 5.0.0.30 )

Keyword EditMode

Default 0

0 is use editstring, followed by the pieces e.g. GNUCHESS mode, 1 is use setboard + fen e.g. crafty mode.

Keyword InputMoveDelay

Default 30

This specifies the time in milliseconds to wait after a move has been received from engine but before passing it on to the GUI, is intended to receive possible end of game conditions like checkmate, resign etc.

Keyword OutputMoveDelay

Default 0

This is the minimum time to wait before sending another move

Keyword UCITimeout

Default 60

This is the time in seconds the adapter waits for uciok after sending a IsReady command. It is sometimes needed to increase this value, especially when the engine takes a long time to initialize. This can happen when there are many tablebases to load.

Mapping string keywords

Keyword ExitString

Default quit\n

This string is send to exit the engine.

Keyword EditEndString

Default .\n

String sent to end the edit board mode.

Keyword SwapColorString

Default c\n

This string is send in editboard mode to swap the colors.

Keyword EditString

Default edit\n#\n

This string is send to start the edit board mode. Is only used when the edit mode is 0

Keyword ForceString

Default force\n

The command is send to the engine to set the engine to play neither color ("force mode"). Stop clocks. The engine should check that moves received in force mode are legal and made in the proper turn, but should not think, ponder, or make moves of its own.

Keyword UndoMoveString

Default undo\n

If you have ChessPartner take back moves, it sends this string for each move to take back. Before sending this string it firsts sends the ForceString.

Keyword ColorStringw

Default white\n

Command send to have the engine play the white moves

Keyword ColorStringb

Default black\n

Command send to have the engine play the black moves.

Keyword ComputeString

Default go\n

Command send to start the engine thinking it's best move.

Keyword MoveNowString

Default ?\n

This command is send to the engine to force it to play a move right now.

Keyword NewGameString

Default new\nrandom\n

ChessPartner send this string of commands to the engine when a new game is started. You may want to modify this string to set some additional options. You make sure the engine is ready to start a new game.

Keyword InitString

Default xboard\nnew\nhard\npost\n

This string is send when the engine is first loaded. You may want to add some additional options, important is that the engine is working in a winboard compatible mode.

Keyword NameRev

Default name of executable

This string is displayed in the engine properties page and also show when you play the engine on the internet. Fill the name and version of the engine.

Keyword PonderOn

Default hard\n

This string is send to enable pondering, if this string is specified you must also have a PonderOff key.

Keyword PonderOff

Default easy\n

This string is send to disable pondering, if this string is specified you must also have a PonderOn key.

Keyword SetAnalyseMode

Default

This string is send to set the engine in analyze mode, if this string is specified you must also have a ExitAnalyseMode key. If the engine does not support the analyze mode leave these keys blank.

Keyword ExitAnalyseMode

Default

This string is send to leave the analyze mode, if this string is specified you must also have a SetAnalyseMode key.

Keyword BookOn

Default

This string is send when the GUI wants to enable use of the opening book. If this string is specified you must also have a BookOff string. If the engine does not support enabling and disabling the book, then leave these keys blank.

Keyword BookOff

Default

This string is send when the GUI wants to disable use of the opening book.

Level mapping keywords

There are a number of level strings, these are used to map the ChessPartner levels to the level commands understand by the engine.

ChessPartner has 7 kind of levels, each kind of level has some parameters with it. For each kind of level you can define a string with parameter replacement that is send to the engine.

The following parameters can be inserted:

%1 = First search depth in ply's

%2 = Second search depth in ply's

%3 = First time check in seconds

%4 = Number of moves until first time check

%5 = Second time check or time increment in seconds

%6 = Number of moves for 2nd time check

%7 = First time check in minutes (Same as %3 but then converted to minutes)

%8 = First time check remainder seconds (Use in combination with %7)

%9 = Second time check in minutes (Same as %5 but then converted to minutes)

%10 = Second time check remainder seconds (Use in combination with %9)

Keyword Level0

Default level 1 9999 0\ndepth %1\n

The Level0 string is send when ChessPartner has selected a fixed search depth level. The %1 parameter is the requested search depth in ply's.

Keyword Level1

Default depth 29\nlevel %4 %7 0\n

This string is send when a tournament level is selected. The %3 and %4 parameters are for the first time check, the %5 and %6 for the second time check.

Keyword Level2

Default depth 29\nlevel 1 %7 0\n

String is send when a fixed time per move is selected; the %3 or %7 and %8 parameters contain the selected time.

Keyword Level3

Default level 1 9999 0\nsd %1\n

This string is send when a search for checkmate level is selected. The %1 parameter is the selected depth.

Keyword Level4

Default depth 29\nlevel 1 %7 0\n

This is send when a level with a average time per move is selected.

The %3 or %7 and %8 parameters contain the selected time.

Keyword Level5

Default depth 29\nlevel 0 %7 %5\n

Level with a time increment after each move is made ("fisher clock")

The %3 or %7 is the base time, the %5 parameter the time increment.

Keyword Level6

Default level 1 9999 0\ndepth 29\n

This string is send if the infinite time level is selected.

Keyword Level7

Default

This string is send if a level whit a time for the whole game is selected. This is optional, when not present the Level1 string is used. In that case the number of moves is passed as zero.

Engine variables

Engine variables are introduced in adapter version 5.0.0.0. They provide a way to set all kind of engine parameters in a consistent way from within the ChessPartner GUI.

Variables can be used for things like setting hashtable size, playing style, selecting opening books, clearing hashtables etc.

The values of the variables are saved by the ChessPartner GUI and send to the engine on the next startup.

In order to support variables a small enhancement to the winboard protocol is suggested:

setvar

The setvar command is used to set various variables. The general syntax is:

setvar name value

where name is the name of the variable and value the value of the variable. The name should not contain spaces, the value may contain spaces and terminates at end of the line.

For a list of variables see further in this document.

If the variable is successfully changed its new value is output in the format as described in the getvar command. When the variable does not exist or there is an error setting the variable a standard winboard error messages is given.

getvar

This command is used to retrieve the current value of a variable, general syntax:

getvar name

When successful the engine returns the variable in the following format:

var:name=value or in case of array variables each array entry is returned as:

var:name[1/3]=value

var:name[2/3]=value

var:name[3/3]=value

When a non existing variable is specified then a standard winboard error messages is returned.

A asterix * may be used as wildcard, e.g. getvar * returns all variables, each variable is returned on its own line.

Type of variables

Basically variables are send as strings but for presenting them in a GUI the following types are defined:

Action This is not really a variable but merely causes some action to happen. This could be something like clearing hashtables etc.

Filename The variable represents a filename. Usefull to know for GUI.

Directory Variable represents a directory, also useful for GUI.

Integer A integer value.

String A ascii string

In addition to this basic types a variable may be an array, in that case append a pair of square brackets to the name of the variable. e.g. name[n] where n the array index. Note that 1 is the first element. When variables are returned a second parameter can be given that indicates the number of elements. e.g. name[n/m] here m is the number of elements.

For this release variables are defined in the [Variables] section of the .cpeini file. Later versions may retrieve the variable definitions from the engine itself.

Variable definitions in .cpeini file

Variables can be defined in a ini file which must be named:

engine.cpeini

where engine must be the same name as the engines executable filename.

The variables are defined in the [Variables] section.

General syntax is: name=type

name is the name of the variable, type is what kind of variable.

The following basic types are defined:

Integer is a simple integer value. when the integer can only take a range of values or even enumerated values this can be specified in brackets. e.g. (0-9) only values 0 to 9 allowed or (0,1,4) only 0, 1, and 4 are valid. The values may be given labels for display purposes. e.g. (0=Test1,2=Another test) etc. Optionally a * may be used to allow any value e.g. (MyVal1,Other,False,*) results in a dropdown box but still editable.

String is a simple string value, in between brackets predefined values may be given e.g. : Stringvar=String(t1=Test1,t2=Test2,t3=Test3)

Filename is a file, in brackets the file mask may be given, this can be used for display in a file dialog. e.g. personality=Filename(Rebel Personalities (*.eng)|*.ENG)

Directory is a directory selector, in brackets additional information may be given. e.g. NalimovPath=Directory(Select the directory where the tb files are stored)

In order to support existing engines it is also possible to map these variables to any desired set of engine commands or even to command line parameters. Of course in the latter case the engine needs to be reloaded.

The variable mappings are define in the [Varmap] section.

When not used the variables are send to the engine using the default setvar command.

The general syntax of the mapping section is:

variable=mode,commands

Where variable is the name of the variable to map, mode is the mapping mode and commands the optional commands to send.

mode 0 = pass as winboard command, 1=pass as engine command line option.

The mapping string may use %variable% to reference variables.

e.g. myvariable=0,setvar myvariable %myvariable% %othervariable%\n

Finally there is a [VarHelp] section defined where additional help text for each variable can be given. The help text can be shown in a popup window.

e.g.

[VarHelp]

myvariable=This is just a one line help text telling something about myvariable.

Engine info

The engine can send special strings which are show in the engine info window. To enable this the following keywords are defined:

Keyword InfoPrefix

Default

When this keyword is set all engine output that starts with this string is routed to the engine info window. e.g. InfoPrefix=info: then all engine output starting with info: goes into the engine infowindow.

Keyword EngineInfoTabs

Default

The engine info window can be further divided with tabs, where each tab represents a different category of information. .e.g. EngineInfoTabs=search|test this will create a engine info window with a search and a test tab. Engine output starting with info:search goes to the search window while output starting with info:test goes to the test window.

Known problems.

For a number of features ChessPartner relies on functions in the chess engine, e.g. the opening book display and some others. These functions are not present in other chess engines so these functions are disabled.

Testing has mainly been done using crafty.

On occasions the chess engine does not exit.

Not all ChessPartner levels are interpreted correctly.

DISCLAIMER

THE WINBOARD ADAPTER IS UNSUPPORTED SOFTWARE. WE HAVE INCLUDED IT IN THE HOPE SOMEONE FINDS IT USEFULL. AS ITS OPERATION RELIES ON SOFTWARE OUTSITE OUR CONTROL WE CAN NOT MAKE ANY WARRANTY OF ITS PROPER FUNCTIONING.