Belofte  version 2.1.5
A promising chess program using the UCI or Winboard interface
old Manual for version 0.9.x

Details on how to use belofte - older versions 0.x only

This is the belofte 0.x manual covering the previous releases. Belofte is a promising chess program released under GNU - GPL v2.0. For the manual for the most recent version, please check the belofte 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.

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 [--command] [[@]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
[@]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.
  • Belofte can be run from a script that will launch XBoard using the engine;
  • Belofte can be run from a script that will launch XBoard using the zippy interface (0.x only) and the engine to connect to ICS;
  • 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.

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 a few UCI commands;

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. {X, WB1}
    belofte> d2d4 belofte> d7d8q
  • ? Move now if computer is thinking. If computer is not thinking, no-op. {X, WB1, WB2, B}
  • @ <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.{B}
  • 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'. {B}
  • bk Show all book moves. Attention, in the specification, bk is implemented differently. Belofte differs from the standard by not implementing the standard. {X, B}
  • computer Indicate opponent is a computer. Changes random setting. {X, WB2, B}
  • createbook <inputfilename.pgn> This command will create an opening book based on the pgn file supplied. Please refer to the section on opening books for more details. {B}
  • easy Set pondering off. It is working but pondering is not being used afterwards. {X, WB1, WB2, B}
  • epd <filename> Parse an epd file. Please refer to the section on epd files for more information. {B}
  • epdpos <EPD-position> Parse an epd position. Please refer to the section on epd files for more information. {B}
  • eval Show the static position evaluation of the current position. {B}
  • exec <inputfilename.rc> Alternative for the @ command. {B}
  • fd <n> Set fixed depth. No iterative deepening, no break possible. {B}
  • force Set computer engine off for both black and white. Turn ponder off. {X, WB1, WB2, B}
  • game Show the game history on the command line. {B}
  • go Set computer engine for current player to move, start thinking. {X, WB1, WB2, B, UCI}
  • 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.{X, WB1, WB2, B, UCI}
  • ics <hostname> Set hostname for ics server. {X, WB2, B}
  • info Display current configuration, including compile options. {B}
  • isready Allow engine to finish initialization. Also needs to be sent after sending ucinewgame command. You should wait until you receive the readyok feedback. {UCI}
  • level <n> <n>[:<n>] <n> Indicates a level. {X, WB2, B}
  • ls [<pattern>] It will list all files except hidden files. When given an extension, will list all files matching the extension. No wildcards supported. The matching pattern is litteral (no regex). {B}
    belofte> ls .rc
  • name <username> Set player name. {X, WB1, WB2, B}
  • new [nobd] Start a new game. Reset some parameters. If nobd is given, the board is not printed. {X, WB1, WB2, B}
  • nopost Turn off pondering output. {X, WB2, B}
  • otim <n> Indicates time available to the adversary. Implemented but unused at this moment. {X, WB2, B}
  • pause {X, currently unimplemented}
  • 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. {B}
  • pgn Print pgn, same format as save command. {B}
  • ping <n> Keepalive message, engine responds with pong <n>. {X, WB2, B}
  • playother Set computer engine for opponent player to move, start pondering. {X, WB2, B}
  • post Turn on pondering output. At this moment, not much is output. {X, WB2, B}
  • protover <n>
    Accepts parameters 1, 2, 4. The list of commands below available depends on which protover is selected. By default, protover 1 is active. 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. {X, WB1, WB2, B}
  • quit Exit program. {X, WB1, WB2, B, UCI}
  • random Toggle random mode, off by default. Type info to get current status. {X, WB1, WB2, B}
  • rating <n> <n> Set players rating. {X, currently unimplemented}
  • remove Undo move twice, computer remains with same colour. {WB1, WB2, B}
  • 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 {B} 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. {X, WB2, B}
  • setboard <fen> Initialise the board with a FEN position. Please refer to the specific section on FEN strings for more information. {X, WB2, B}
  • st <n> Search to a maximum time. {X, WB2, B}
  • stop Abort thinking as soon as possible. {UCI}
  • 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. {X, WB2, B}
  • result 1-0|0-1|1/2-1/2|* Store game result. {X, WB1, WB2, B}
  • 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. It disables all B commands. {UCI, B}
  • ucinewgame Start new game. Needs to be followed by isready command. {UCI}
  • 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 {WB2, B}
  • undo Undo last move. Assumes a preceding force command was received. Belofte will return an error if force mode is not in effect. {WB1, WB2, B}
  • verbose <n> Indicates verbosity level, active only if post command has been issued before. Default off. {B}
  • 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. In belofte 0.x, it is not possible to undo this command. {X, WB1, WB2, B}

X: xboard/winboard protocol specification WB1: supported on Winboard and Xboard 1 WB2: supported on Winboard and Xboard 2 WB4: Winboard 4.4 specific commands B: belofte after protover 4 command UCI: UCI protocol (version 04-2006)

Belofte startup sequence

  1. Belofte will parse all parameters passed on the command line.
  2. 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)
  3. Thereafter, it expects the following initialisation commands:

Winboard/Xboard initialisation command sequence xboard followed by 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

UCI initialisation command uci

id name Belofte 0.9.20
id author Yves De Billoëz

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, B}
  • edit
    Start edit mode. Use setboard instead. {X, 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, B}

Testing

Testing scripts

The test directory contains a number of testscripts.

  • 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. {B, UCI}
  • fd <n>
    Only search at fixed depth, quiescence extension. {B}
  • perft <0|1|2|3|4|5>
    Do perft test. Do not use high figures, no break possible. {B}
  • epd filename | epdpos EPD-position
    Execute epd test. {B}
  • **@** filename Execute command file. {B}
  • exec filename Execute command file, alternative to @ command. {B}
  • info
    Display current configuration, including compile options. {B}
  • ls pattern List files on disk. {B}
  • load
    Load PGN file from disk. {B}
  • save
    Save PGN file to disk. {B}

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-0.9.20.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

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.

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

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.

Opening book

Belofte will try to read an opening book when starting a game. Only one opening book can be used at any time.

The opening book is an ASCII file with following data:

  • Each position starts with a FEN string excluding the last ply indicators;
  • On each next line, the SAN move is listed, together with its statistics. All data is separated by a space. The statistics are in following order:
  • The number of times this move is played, the number of times white won, the number of times black won, the number of times a draw was concluded, the number of total moves after this move in the games analysed;
  • When there are no more opening moves available, there is a blank line.

Only the first 10 moves will be read from the opening book. All other moves will be skipped. The book generation process is a slow process. Please reserve sufficient time to create your books.

Creating a book

Please refer to the createbook command for the PGN format of the file needed for creating the opening book. If you have a PGN file with all your games, you can use it to create a customized opening book.

The pgn file needs to be conform to some pgn standards:

  • The notation needs to be very strict. Only correct abbreviated SAN notation is supported. This is the SAN export notation. There must not be any from field character added when this is not required. Please refer to the SAN manual for more information on this notation.
  • The game tag needs to have a header tag with the result filled in. If the result is not filled in, the game is skipped and the next game is read.
  • The game must not have annotations.
  • The space in between the move number and the move itself is optional. (In order to allow the GNUchess book 1.00 to be read.)

The program will create a cache version of the opening book. This version will be used if available instead of the ASCII book for speed reasons.

A script for creating a book is included in the test folder. The script will convert the included file fide_wch_2001.pgn into an opening book compatible with the program.
./createbook.sh

Alternatively, run following command from the belofte prompt.
belofte> @createbook.rc

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 matein1.epd
belofte> 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.

Supported options

Belofte supports comments started with the hash '#' and semi-column ';' character at the beginning of a line. The op-codes am', 'bm' and 'id' are supported. All other opcodes are being ignored.

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. Belofte will output the number of solutions found and the total number of test positions scanned.

Using EPD positions

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

belofte> epdpos r1bqkb1r/ppp1pppp/2n4B/3p4/3P4/5N2/PPP1PPPP/RN1QKB1R w KQkq - bm Bxh6

The program will validate a single EPD position.

eof