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
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.
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
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
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
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
Keyword InfoPrefix
Default
Keyword EngineInfoTabs
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.
|
