Details on how to use belofte

This is the belofte manual. Belofte is a promising chess program released under GNU - GPL v2.0. This file references belofte versions 2.x. For the manual of the older release, please refer to the belofte 0.x manual.

Using Belofte

Belofte can be used in different ways. The program interfaces according to the UCI protocol or the Xboard protocol (also known as the CECP or Winboard protocol). It works fine as well with any interace implementing the UCI or Xboard protocol. See the about belofte file for an introduction and the list of supported programs.

Using it in a program

Belofte expects one of the following commands after launching:

uci for getting into uci mode, or passing --uci as a parameter;
xboard followed by protover 2 for getting into xboard mode (or passing --xboard or -xboard as a parameter).

If no command is issued, belofte will work more or less like a winboard 1 compatible program while accepting all UCI and CECP commands.

On the command line

Belofte can be launched without any parameters from a console on any platform. Please refer to the commands section to understand how to play. Please make sure not to double-click in a file explorer but launch from a console. On certain platforms, double-clicking will not open a console but run the application silently.

It is recommended to use bash. If you do use another shell, please make sure to verify the scripts before running.

Command line parameters

Belofte uses following command line parameters. It is launched with following parameters as shown below:

belofte [--command1] [--command2] [--commandn] [[@]rcfilename]

Use the help command to have a list of available commands. Most common commands are below.

Command            Description
--xboard / -xboard Switch to xboard mode
--uci              Switch to UCI mode
--help             Execute help command and exit
--version          Execute about command and exit
--bench / bench    Run benchmark and exit
--<command>        Execute <command>, type help in belofte for list
[@]rcfilename      Execute script identified by the filename

Note: belofte needs to be replaced by belofte.exe on windows.

Other use-cases

Testing positions, benchmarking, finding mates. See the about belofte file for some examples.
Belofte can be run from a script that will launch XBoard using the engine;
Belofte can be used to learn to program C++ in a cross platform way;
Belofte can be run from a script that will launch an inter-engine automated tournament, some scripts for cutechess-cli based tournaments are included in the release. See the about belofte file for more details.

Supported commands

This section applies for using the program from the command line or when integrating the program with a Xboard, Winboard or UCI compatible application.

The application supports most Xboard/Winboard commands;
The application supports most UCI commands;
Allmost all commands can also be passed on the command line if preceded by by a double dash '–';
The supported commands can be found when giving the help command. More information below.

Commands

d2d4 Any coordinate move e.g. d2d4, e1g1, ... no capture information nor check or checkmate information. Promotion is done by adding extra character, e.g. d2d1q. Please note that in higher versions of the protocol, the usermove command is preferred. See usermove command. belofte> d2d4 belofte> d7d8q
? | stop Abort thinking as soon as possible and move now. If computer is not thinking, no-op.
@ <inputfilename.rc> Read and execute all commands from file in parameter. Please note that passing inputfilename.rc when launching the application will have the same effect.
again Evaluate the previous position again and see if the same result is obtained. Most useful is issuing this command when there are multiple moves that can be selected because they are all considered equal. Possibly another move will be selected. Another use is when analysing the game, to make sure that a search is performed with different parameters that can be set before issuing this command. It is an equivalent for: 'undo' and 'go'.
alg [Random|StaticEval|BruteForce|SearchIterativeBF|AB|ABFS|ABFH] Set search algorithm.
analyze Enter analyze mode.
belofte Swith to belofte mode, used when in uci or xboard mode.
draw Draw offer. {X, currently unimplemented}
easy Set pondering off. It is working but pondering is not being used afterwards. {X, WB1, WB2, B1}
epd file [-sts|-perf] <filename> | epd pos [-sts|-perf] <EPD-position> Parse an epd file or position. Please refer to the section on epd files for more information.
eval Show the static position evaluation of the current position.
evaltype [PiecesOnly|StaticBoard|PositionalBoard] Set position evaluation algorithm.
exec <inputfilename.rc> Alternative for the @ command.
fd <n> Set fixed depth. No iterative deepening, no break possible.
force Set computer engine off for both black and white. Turn ponder off.
game Show the game history on the command line.
go Set computer engine for current player to move, start thinking.
In UCI, the engine will always return with a bestmove answer. Furthermore, in uci, following parameters are accepted: depth, nodes, movetime, movestogo, binc, winc, btime, wtime, infinite.
help [<command>|–all] It will list all sensible commands that can be used in the version of the interface. Only a few commands are depending on the version of the interface however. Even if in a certain version of the interface a certain command is not listed through the help command, it does not mean that it cannot be used.
Passing --all will list all available commands, even those irrelevant in the current context.
info Display current configuration, including compile options.
isready Allow engine to finish initialization. Also needs to be sent after sending ucinewgame command. You should wait until you receive the readyok feedback.
level <n> <n>[:<n>] <n> Indicates a level.
ls [<pattern>|<subdir>] It will list all files except hidden files in current or specified folder. When given an extension, will list all files matching the extension. No wildcards supported. The matching pattern is litteral (no regex). belofte> ls .rc belofte> ls epd/
name <username> Set player name.
new Start a new game. Reset some parameters.
nopost Turn off pondering output.
nps {X, currently unimplemented}
otim <n> Indicates time available to the adversary. Implemented but unused at this moment.
perft <0|1|2|3|4|5|..>
Do perft test. High values will block the engine until the test has been finished, no break possible. Start with lower numbers first to measure your machines performance before using higher values. Changes game level for next go command.
ping <n> Keepalive message, engine responds with pong <n>.
playother Set computer engine for opponent player to move, start pondering.
ponderhit {currently unimplemented}
position [fen <fenstring> | startpos ] moves <move1> .... <movei>
Set position.
post Turn on pondering output. At this moment, not much is output.
protover <n>
Winboard/xboard will issue the protover 2 command when initialising the engine. Please note that the command does not form part of the winboard 1 version standard but is mandatory to bring the engine to another standard.
quit Exit program.
random Toggle random mode, off by default. Type info to get current status.
rating <n> <n> Set players rating. {X, currently unimplemented}
remove Undo move twice, computer remains with same colour.
save [<filename>] It will save the file as a pgn file until the current position. If no parameter is given, the name chosen will be belofte-<version>.pgn. belofte> save belofte> save mybestgame.pgn
sd <n>
Search to a fixed depth. Sets absolute search depth, except for quiescence extension that is still possible beyond that. If used in uci mode, will set go depth parameter permanently.
setboard <fen> Initialise the board with a FEN position. Please refer to the specific section on FEN strings for more information.
setoption Set belofte configurable option.
st <n> Search to a maximum time.
time <n> Indicates time avaible to the program for move calculation. At this moment, this is converted into a sd command with an estimated depth that will correspond approximately to the time being used. Beware, on slower machines, this calculation might not be correct.
rejected {X, currently unimplemented}
result 1-0|0-1|1/2-1/2|* Store game result. {X, WB1, WB2, B1}
resume {X, currently unimplemented}
uci Bring engine into UCI mode. The engine will respond with uciok if ready. Please note that the UCI executable will accept most uci commands without issuing the uci command. The uci command is provided for strict adherance to the uci specification and for interfacing with UCI programs.
ucinewgame Start new game. Needs to be followed by isready command.
usermove <move> Move is in position notation. e.g. e2e4, e1g1, promotion is denoted by adding a lowercase symbol to the move e.g. e2f1q
undo Undo last move. Assumes a preceding force command was received. Belofte will return an error if force mode is not in effect.
variant {X, currently unimplemented}
verbose <n> Indicates verbosity level, active only if post command has been issued before. Allowed values: 0-99, default off.
xboard Change to xboard mode. No prompt nor board output.
Please note that this command can be omitted if belofte is launched with -xboard parameter as explained above.

Belofte startup sequence

Belofte will parse all parameters passed on the command line.
After that, it will parse a command file passed as argument. If none is present, it will try to load an .rc file based on its name. (.exe suffix on windows is not considered)
Thereafter, it expects the following initialisation commands:

UCI initialisation command uci

id name Belofte 2.1.4
id author Yves De Billoëz
option name alg type combo default BruteForce var Random var StaticEval var BruteForce
option name evaltype type combo default StaticBoard var PiecesOnly var StaticBoard

Winboard/Xboard initialisation command protover 2

feature done=0
feature ping=0 setboard=1 playother=1
feature usermove=1 time=0 draw=0 sigint=1 sigterm=1
feature analyze=0 debug=1
feature done=1

Obsolete commands

Following commands are deemed obsolete, and whilst implemented partially, they should not be used.

black
Set engine to play white, assuming player plays black. Use setboard instead. {X, WB1, WB2, B1}
edit
Start edit mode. Use setboard instead. {X, unimplemented}
pause {X, currently unimplemented}
register
As belofte is a free program, this command will never be implemented. {unimplemented}
white
Set engine to play black, assuming player plays white. Use setboard instead. {X, WB1, WB2, B1}

Testing

Testing scripts

The test directory contains a number of testscripts.

tour-bottomlist.sh
tour-nextversion.sh
testsuite-uciinterface.rc

Belofte will read a resource file with the same name as the program executable with an .rc suffix. This is a way of reconfiguring it.

Test commands

debug [fenhistory|hashhistory|on|off|filename.ext]
Activate debug, stop debug, show FEN strings in history, show HASH strings in history, spool debug to file.
debug autosave will turn on autosave. debug logging will turn on logging.
fd <n>
Only search at fixed depth, quiescence extension.
perft <0|1|2|3|4|5>
Do perft test. Do not use high figures, no break possible.
epd file [-sts|-perf] filename | epd pos [-perf] EPD-position
Execute epd test.
@**filename | **@** filename Execute command file.
**exec filename Execute command file, alternative to @ command.
info
Display current configuration, including compile options.
bench [<n>] Run a benchmark.
ls pattern|subdir/
List files on disk.
load
Load PGN file from disk. {B1}
save
Save PGN file to disk. {B1}

Formats used in the application.

FEN strings

Please refer to the Forsyth-Edwards Notation information on Wikipedia.

RC file

Contains a list of commands in a file. The file can start with a # or = or ; character to indicate a comment. Comments are ignored. Please refer to the standard belofte.rc file in the distribution, content of which is listed below.

If the file contains a line with just __END__, parsing is ended immediately (see perl).

# commands in this file will be executed on launch of program
# comments need to be preceded by the hash symbol
# belofte will seek the file belofte-2.1.4.rc located in following
# location ./
xboard
protover 2
new
bd

A file with execute mark could have the following first line:

#!/usr/bin/env -S belofte --xboard

The file does not require to end with .rc.

SAN move

Standard algebraic notation. As a picture shows more than a thousand words, here some chess pictures taken from different games to explain what a SAN move means.

f3 e5 2. g4 Qh4# 0-1
e4 e5 2. d4 exd4 3. c4 dxc3 {as one can notice, e.p. move is not marked as such} 4. Nxc3
O-O O-O-O 21. Bxb7+ *

San moves can contain comments and decorations i.e. +, # but no glyphs or annotations yet.

PGN file

All played games will also be stored in a PGN file. The format of this file conforms to the same rules as the above. Use the save command to save the current game in PGN format. When starting a new game with the new command, the current game is automatically saved.

Please refer to the PGN specification (1, 2) for full details.

Reading PGN files

Lines starting with the % character are ignored. Lines starting with [ will be considered to contain a PGN tag.

Writing PGN files

Belofte will write at the end of each game the game in a PGN file. In case of protover 1 & 2, only tags from the STR will be written. (see specification) In protover 4, additional tags will be used. When issuing the command save, the program will save the game immediately according to specification.
When issuing the command game, the program will print the game to screen, it will not print the PGN tags.

EPD files

Extended Position Description (EPD) files can best be compared to computer readable files of chess problems as printed in the press. EPD files contain a number of test positions and their expected results. The result for each test position is listed next to the problem. The format of the file is very well defined. Not all options might be implemented. The format of the file is as such that if a certain option is not implemented, the option will be ignorable. It depends on the implementation whether this unsupported option will be ignored. A missing option might render an EPD test file worthless for the given implementation.

Using EPD files

From within the command line option, enter epd file followed by the fully qualified filename including extension.

belofte> epd file epd/matein1.epd
belofte> epd file -perf epd/oldperftsuite.epd
belofte> epd file -sts epd/perftsuite.epd

ALl files are relative to the current folder. The path information should be compatible with the platform the program is run on. The program will output for each test in the EPD file whether a result has been found or not. The normal log-levels of the program will be used during the parsing of the file. At the end of the test, the total number of correct results and the total number of tests will be printed.

The command epd filename is supported for backwards compatibility.

Supported options

Belofte supports comments started with the hash '#' and semi-column ';' character at the beginning of a line. The op-codes 'acs', am', 'bm', c[n], 'dm', Dn' and 'id' are supported. The op-code 'dm [1-99]' will set a search depth. The op-code 'acs [1-9999]' will set the maximum time to search. The op-code 'D[1-99]' will trigger a perf test. All other opcodes are being ignored.

Passing the -perf option will force running perftsuite. Useful if the position does not contain a D[1-99] tag. Passing the -sts option will force calculating scores in a test suite.

EPD files and test results

Given the result is stored with the test, EPD files are not suited for human tests. They are very well suited to computerised tests, given the program does not cheat by reading the result. Given most programs implement epd when they want to integrate an automated test suite, we can assume programs do not cheat but use the EPD test suite to measure itself against predefined tests.

EPD result interpretation

Belofte will parse the EPD file given with the current level setting, except if the 'dm' or 'acs' options are being used. Belofte will output the number of solutions found and the total number of test positions scanned. Most test-sets are based around a certain level and a score of a certain % can be translated into a certain elo level. See the -sts option for more information.

Strategic test results

When running an EPD file or EPD position with the -sts option, a strategic test will be run.

Using EPD positions

From within the command line option, enter epd pos followed by a single EPD position line.

belofte> epd pos r1bqkb1r/ppp1pppp/2n4B/3p4/3P4/5N2/PPP1PPPP/RN1QKB1R w KQkq - bm Bxh6
belofte> epd pos -sts 1kr5/3n4/q3p2p/p2n2p1/PppB1P2/5BP1/1P2Q2P/3R2K1 w - - bm f5; c0 "f5=10, Be5+=2, Bf2=3, Bg4=2";
belofte> epd pos -perf rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -,20,400,8902,197281,4865609,119060324

The program will validate a single EPD position.

The -sts option is only useful for debugging as it is meant to run on a complete file.

The command epdpos is supported for backwards compatibility.

Other information

Terminology

Term    Description
CR LF   Carriage return and linefeed character. Represented as hexadecimal
        characters 0x13 0x10.
EARS    Engine Analysis Reliability Score
EPD     Extended Position Description
ELO     The Elo rating system is a method for calculating the relative skill of players.
FEN     Forsyth-Edwards Notation
FICS    Free Internet Chess Server
GNU     GNU's Not UNIX
ICS     Internet Chess Server
PERFT   PERFormance Test, move path enumeration
PGN     Portable Game Notation
SAN     Standard Algebraic Notation
SIGINT  The SIGINT signal is sent to a process by its controlling terminal when
        a user wishes to interrupt the process.
SIGTERM The SIGTERM signal is sent to a process to request its termination.
UCI     Universal chess interface. Interface being used on most modern
        chess engines such as Stockfish and Fruit. 

Translations

Language            Native translation      Name of application.
English             English                 Belofte - A promising chess program
Flemish / Dutch     Vlaams / Nederlands     Belofte schaak
French              Français                Promesse échecs
German              Deutsch                 Schach
Spanish             Español                 Ajedrez
Russian             Русский                 Шахматьі

Alternative chess-piece identifier letters

Currently listed for information only, not implemented.

Language     Piece letters
             (pawn knight bishop rook queen king)  
----------   ------------------------------------
Czech        P J S V D K
Danish       B S L T D K
Dutch        - P L T D K
English      P N B R Q K
Estonian     P R O V L K
Finnish      P R L T D K
French       P C F T D R
German       B S L T D K
Hungarian    G H F B V K
Icelandic    P R B H D K
Italian      P C A T D R
Norwegian    B S L T D K
Polish       P S G W H K
Portuguese   P C B T D R
Romanian     P C N T D R
Spanish      P C A T D R
Swedish      B S L T D K

eof