dorkhub
show your thing

binbo

Chess representation written in Erlang using Bitboards, ready for use on game servers

DOBRO
Erlang★ 135⑂ 16 forksApache-2.0updated 3 months ago
binbobitboardschesschess-gamechess-pgnchess-ucichessboardchessboard-representation
git clone https://github.com/DOBRO/binbo.gitDOBRO/binbo
README.mdfork it — it’s yours

Binbo

Binbo on Hex.pm CI Status Code coverage Erlang License

Binbo is a full-featured Chess representation written in pure Erlang using Bitboards. It is basically aimed to be used on game servers where people play chess online.

It’s called Binbo because its ground is a binary board containing only zeros and ones (0 and 1) since this is the main meaning of Bitboards as an internal chessboard representation.

Binbo also uses the Magic Bitboards approach for a blazing fast move generation of sliding pieces (rook, bishop, and queen).

Note: it’s not a chess engine but it could be a good starting point for it. It can play the role of a core (regarding move generation and validation) for multiple chess engines running on distributed Erlang nodes, since Binbo is an OTP application itself.

In addition, the application is able to communicate with chess engines that support UCI protocol (Universal Chess Interface) such as Stockfish, Shredder, Houdini, etc. You can therefore write your own client-side or server-side chess bot application on top of Binbo, or just play with engine right in Erlang shell. TCP connections to remote chess engines are also supported.

Binbo is part of the Awesome Elixir list.

Binbo sample
Table of Contents

Features

  • Blazing fast move generation and validation.

  • No bottlenecks. Every game is an Erlang process (gen_server) with its own game state.

  • Ability to create as many concurrent games as many Erlang processes allowed in VM.

  • Support for PGN loading.

  • All the chess rules are completely covered including:

  • Unicode chess symbols support for the board visualization right in Erlang shell:
    ♙ ♘ ♗ ♖ ♕ ♔    ♟ ♞ ♝ ♜ ♛ ♚

  • UCI protocol support.

  • Support for TCP connections to remote UCI chess engines.

  • Passes all perft tests.

  • Cross-platform application. It can run on Linux, Unix, Windows, and macOS.

  • Ready for use on game servers.

Requirements

Installation

For Erlang projects

Add Binbo as a dependency to your rebar.config file:

{deps, [
  {binbo, "4.0.3"}
]}.

For Elixir projects

Add Binbo as a dependency to your mix.exs file:

defp deps do
  [
    {:binbo, "~> 4.0"}
  ]
end

Quick start

Clone repository, change directory to binbo and run rebar3 shell (or make shell):

$ git clone https://github.com/DOBRO/binbo.git
$ cd binbo
$ rebar3 shell

Common example

In the Erlang shell: 
%% Start Binbo application first:
binbo:start().

%% Start new process for the game:
{ok, Pid} = binbo:new_server().

%% Start new game in the process:
binbo:new_game(Pid).

%% Or start new game with a given FEN:
binbo:new_game(Pid, <<"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1">>).

%% Look at the board with ascii or unicode pieces:
binbo:print_board(Pid).
binbo:print_board(Pid, [unicode]).

%% Make move for White and Black:
binbo:move(Pid, <<"e2e4">>).
binbo:move(Pid, <<"e7e5">>).

%% Have a look at the board again:
binbo:print_board(Pid).
binbo:print_board(Pid, [unicode]).

Play with engine on local machine

In the Erlang shell: 
%% Start Binbo application first:
> binbo:start().
{ok,[compiler,syntax_tools,uef,binbo]}

%% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.157.0>}

%% Set full path to the engine's executable file:
> EnginePath = "/usr/local/bin/stockfish".
"/usr/local/bin/stockfish"

%% Start new game in the process:
> binbo:new_uci_game(Pid, #{engine_path => EnginePath}).
{ok,continue}

%% Which side is to move?
> binbo:side_to_move(Pid).
{ok,white}

%% Say, you want to play Black. Tell the engine to make move for White.
> binbo:uci_play(Pid, #{}).
{ok,continue,<<"e2e4">>}

%% Make your move for Black and get the engine's move immediately:
> binbo:uci_play(Pid, #{}, <<"e7e5">>).
{ok,continue,<<"g1f3">>}   % the engine's move was "g1f3"

%% Make your next move for Black and, again, get the engine's move at once:
> binbo:uci_play(Pid, #{}, <<"b8c6">>).
{ok,continue,<<"b1c3">>}   % the engine's move was "b1c3"

%% Look at the board with ascii or unicode pieces.
%% Flip the board to see Black on downside:
binbo:print_board(Pid, [flip]).
binbo:print_board(Pid, [unicode, flip]).

%% It's your turn now. Let the engine search for the best move for you with default options.
%% No move actually done, just hint:
> binbo:uci_bestmove(Pid, #{}).
{ok,<<"g8f6">>}

%% Tell the engine to search for the best move at depth 20:
> binbo:uci_bestmove(Pid, #{depth => 20}).
{ok,<<"g8f6">>}

%% To make the gameplay more convenient, introduce new function:
> Play = fun(Move) -> Result = binbo:uci_play(Pid, #{}, Move), binbo:print_board(Pid, [unicode, flip]), Result end.

%% Now, with this function, go through three steps at once:
%%   - make move "g8f6",
%%   - get the engine's move,
%%   - see how the position was changed.
> Play("g8f6").

… engine’s move was "d2d4":

   +---+---+---+---+---+---+---+---+
 1 | ♖ |   | ♗ | ♔ | ♕ | ♗ |   | ♖ |
   +---+---+---+---+---+---+---+---+
 2 | ♙ | ♙ | ♙ |   |   | ♙ | ♙ | ♙ |
   +---+---+---+---+---+---+---+---+
 3 |   |   | ♘ |   |   | ♘ |   |   |
   +---+---+---+---+---+---+---+---+
 4 |   |   |   | ♙ | ♙ |   |   |   |
   +---+---+---+---+---+---+---+---+
 5 |   |   |   | ♟ |   |   |   |   |
   +---+---+---+---+---+---+---+---+
 6 |   |   | ♞ |   |   | ♞ |   |   |
   +---+---+---+---+---+---+---+---+
 7 | ♟ | ♟ | ♟ |   | ♟ | ♟ | ♟ | ♟ |
   +---+---+---+---+---+---+---+---+
 8 | ♜ |   | ♝ | ♚ | ♛ | ♝ |   | ♜ |
   +---+---+---+---+---+---+---+---+
     H   G   F   E   D   C   B   A

  Side to move: Black
  Lastmove: d2-d4, WHITE_PAWN
  Fullmove: 4
  Halfmove: 0
  FEN: "r1bqkb1r/pppp1ppp/2n2n2/4p3/3PP3/2N2N2/PPP2PPP/R1BQKB1R b KQkq d3 0 4"
  Status: continue

{ok,continue,<<"d2d4">>}

Connect to remote engine over TCP

The examples below assume that Stockfish is used as the chess engine and its path is /usr/local/bin/stockfish, change it according to your environment. TCP service starts on local machine on port 9010.

If you are on Linux, install socat and start TCP service. On macOS just use file org.stockfish.x86.plist (for Intel-based devices) or org.stockfish.arm.plist (for Apple silicon) provided in the test folder (see below).

On Ubuntu/Debian: 
$ apt install socat -y
$ socat TCP-LISTEN:9010,reuseaddr,fork EXEC:/usr/local/bin/stockfish &
$ git clone https://github.com/DOBRO/binbo.git
$ cd binbo
$ rebar3 shell
On Centos/Fedora: 
$ dnf install socat -y
$ socat TCP-LISTEN:9010,reuseaddr,fork EXEC:/usr/local/bin/stockfish &
$ git clone https://github.com/DOBRO/binbo.git
$ cd binbo
$ rebar3 shell
On macOS (Intel x86 Architecture): 
$ git clone https://github.com/DOBRO/binbo.git
$ cd binbo
$ launchctl load test/helper-files/org.stockfish.x86.plist
$ rebar3 shell
On macOS (Apple silicon): 
$ git clone https://github.com/DOBRO/binbo.git
$ cd binbo
$ launchctl load test/helper-files/org.stockfish.arm.plist
$ rebar3 shell
Now in the Erlang shell: 
%% Start Binbo application first:
> binbo:start().
{ok,[compiler,syntax_tools,uef,binbo]}

%% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.282.0>}

%% Set path to the remote engine as tuple {Host, Port, Timeout}:
> EnginePath = {"localhost", 9010, 5000}.
{"localhost",9010,5000}

%% Start new game in the process:
> binbo:new_uci_game(Pid, #{engine_path => EnginePath}).
{ok,continue}

%% UCI-over-TCP connection made, start playing:
> binbo:uci_play(Pid, #{movetime => 100}, <<"e2e4">>).
{ok,continue,<<"c7c5">>} % the engine's move was "c7c5"

Interface

There are three steps to be done before making game moves:

  1. Start Binbo application.

  2. Create process for the game.

  3. Initialize game state in the process.

Note: process creation and game initialization are separated for the following reason: since Binbo is aimed to handle a number of concurrent games, the game process should be started as quick as possible leaving the supervisor doing the same job for another game. It’s important for high-load systems where game creation is a very frequent event.

Starting application

To start Binbo, call:

binbo:start().

Creating game process

binbo:new_server() -> {ok, Pid} | {error, Reason}.
binbo:new_server(Options) -> {ok, Pid} | {error, Reason}.
where:

  • Pid - pid of the created process;

  • Options - options for the game process (see bellow).

So, to start one or more game processes: 
{ok, Pid1} = binbo:new_server(),
{ok, Pid2} = binbo:new_server(),
{ok, Pid3} = binbo:new_server().

Options for the game process

binbo:set_server_options(Pid, Options) -> ok | {error, Reason}.

Pid is the pid of the game process.

Options: 
#{
  idle_timeout => timeout(),
  onterminate  => {fun my_callback/4, Arg}
}
where:

  • idle_timeout - time in milliseconds with no messages received before the game process exits. Defaults to infinity.

  • onterminate - tuple where the first element is a callback function that performs when process exits. This function must be of arity 4 with argumnents Pid, Reason, GameState, and Arg where:

    • Pid - pid of the game process;

    • Reason - the reason why the game process exited;

    • GameState - the whole game state;

    • Arg - the argument you want to pass to the callback function.

Example: 
-module(on_terminate).

-export([run/0]).

run() ->
    binbo:start(),
    {ok, Pid} = binbo:new_server(),
    binbo:new_game(Pid),
    binbo:set_server_options(Pid, #{
        idle_timeout => 1000,
        onterminate => {fun onterminate_callback/4, "my argument"}
    }),
    % 'onterminate_callback/4' will be called after 1000 ms
    ok.

onterminate_callback(GamePid, Reason, Game, Arg) ->
    io:format("GamePid: ~p~n", [GamePid]),
    io:format("Reason: ~p~n", [Reason]),
    io:format("Game: ~p~n", [Game]),
    io:format("Arg: ~p~n", [Arg]),
    ok.
To reset options, call: 
binbo:set_server_options(Pid, #{
    idle_timeout => infinity,
    onterminate => undefined
})

Initializing new game

binbo:new_game(Pid) -> {ok, GameStatus} | {error, Reason}.

binbo:new_game(Pid, Fen) -> {ok, GameStatus} | {error, Reason}.
where:

It is possible to reinitialize game in the same process. For example:

binbo:new_game(Pid),
binbo:new_game(Pid, Fen2),
binbo:new_game(Pid, Fen3).
Example: 
%% In the Erlang shell.

> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% New game from the starting position:
> binbo:new_game(Pid).
{ok,continue}

% New game with the given FEN:
> binbo:new_game(Pid, <<"rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1">>).
{ok,continue}

Making moves

API

binbo:move(Pid, Move) -> {ok, GameStatus} | {error, Reason}.

binbo:san_move(Pid, Move) -> {ok, GameStatus} | {error, Reason}.

binbo:index_move(Pid, FromIndex, ToIndex) -> {ok, GameStatus} | {error, Reason}.

binbo:index_move(Pid, FromIndex, ToIndex, PromotionType) -> {ok, GameStatus} | {error, Reason}.

where:

  • Pid is the pid of the game process;

  • Move is of binary() or string() type;

  • GameStatus is the game status.

  • FromIndex - index of square a piece moves from.

  • ToIndex - index of square a piece moves to.

  • PromotionType - piece that a pawn should be promoted to, one of the atoms: q, r, b, n (queen, rook, bishop, knight). Defaults to q (queen).

Function binbo:move/2 supports only strict square notation with respect to argument Move, for example: <<"e2e4">>, <<"e7e5">>, etc.

Function binbo:san_move/2 is intended to handle various formats of argument Move including standard algebraic notation (SAN), for example: <<"e4">>, <<"Nf3">>, <<"Qxd5">>, <<"a8=Q">>, <<"Rdf8">>, <<"R1a3">>, <<"O-O">>, <<"O-O-O">>, <<"e1e8">>, etc.

Function binbo:index_move/3,4 takes only square indices for the second and third parameter. For example, binbo:index_move(Pid, 12, 28) is the same as binbo:move(Pid, <<"e2e4">>).

Examples for binbo:move/2: 
%% In the Erlang shell.

% New game from the starting position:
> {ok, Pid} = binbo:new_server().
{ok,<0.190.0>}
> binbo:new_game(Pid).
{ok,continue}

% Start making moves
> binbo:move(Pid, <<"e2e4">>). % e4
{ok,continue}

> binbo:move(Pid, <<"e7e5">>). % e5
{ok,continue}

> binbo:move(Pid, <<"f1c4">>). % Bc4
{ok,continue}

> binbo:move(Pid, <<"d7d6">>). % d6
{ok,continue}

> binbo:move(Pid, <<"d1f3">>). % Qf3
{ok,continue}

> binbo:move(Pid, <<"b8c6">>). % Nc6
{ok,continue}

% And here is checkmate!
> binbo:move(Pid, <<"f3f7">>). % Qf7#
{ok,{checkmate,white_wins}}
Examples for binbo:san_move/2: 
%% In the Erlang shell.

% New game from the starting position:
> {ok, Pid} = binbo:new_server().
{ok,<0.190.0>}
> binbo:new_game(Pid).
{ok,continue}

% Start making moves
> binbo:san_move(Pid, <<"e4">>).
{ok,continue}

> binbo:san_move(Pid, <<"e5">>).
{ok,continue}

> binbo:san_move(Pid, <<"Bc4">>).
{ok,continue}

> binbo:san_move(Pid, <<"d6">>).
{ok,continue}

> binbo:san_move(Pid, <<"Qf3">>).
{ok,continue}

> binbo:san_move(Pid, <<"Nc6">>).
{ok,continue}

% Checkmate!
> binbo:san_move(Pid, <<"Qf7#">>).
{ok,{checkmate,white_wins}}
Examples for binbo:index_move/3: 
%% In the Erlang shell.

% New game from the starting position:
> {ok, Pid} = binbo:new_server().
{ok,<0.190.0>}
> binbo:new_game(Pid).
{ok,continue}

% Start making moves
> binbo:index_move(Pid, 12, 28). % e2-e4
{ok,continue}

> binbo:index_move(Pid, 52, 36). % e7-e5
{ok,continue}

Castling

Binbo recognizes castling when:

  • White king moves from E1 to G1 (O-O);

  • White king moves from E1 to C1 (O-O-O);

  • Black king moves from E8 to G8 (O-O);

  • Black king moves from E8 to C8 (O-O-O).

Binbo also checks whether castling allowed or not acording to the chess rules.

Castling examples: 
% White castling kingside
binbo:move(Pid, <<"e1g1">>).
binbo:san_move(Pid, <<"O-O">>).

% White castling queenside
binbo:move(Pid, <<"e1c1">>).
binbo:san_move(Pid, <<"O-O-O">>).

% Black castling kingside
binbo:move(Pid, <<"e8g8">>).
binbo:san_move(Pid, <<"O-O">>).

% Black castling queenside
binbo:move(Pid, <<"e8c8">>).
binbo:san_move(Pid, <<"O-O-O">>).

Promotion

Binbo recognizes promotion when:

  • White pawn moves from square of rank 7 to square of rank 8;

  • Black pawn moves from square of rank 2 to square of rank 1.

Promotion examples: 
% White pawn promoted to Queen:
binbo:move(Pid, <<"a7a8q">>).
binbo:san_move(Pid, <<"a8=Q">>).
% or just:
binbo:move(Pid, <<"a7a8">>).
binbo:san_move(Pid, <<"a8">>).

% White pawn promoted to Knight:
binbo:move(Pid, <<"a7a8n">>).
binbo:san_move(Pid, <<"a8=N">>).

% Black pawn promoted to Queen:
binbo:move(Pid, <<"a2a1q">>).
binbo:san_move(Pid, <<"a1=Q">>).
% or just:
binbo:move(Pid, <<"a2a1">>).
binbo:san_move(Pid, <<"a1">>).

% Black pawn promoted to Knight:
binbo:move(Pid, <<"a2a1n">>).
binbo:san_move(Pid, <<"a1=N">>).

En passant

Binbo also recognizes the en passant capture in strict accordance with the chess rules.

Getting FEN

binbo:get_fen(Pid) -> {ok, Fen}.
Example: 
> binbo:get_fen(Pid).
{ok, <<"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1">>}.

PGN loading

binbo:load_pgn(Pid, PGN) -> {ok, GameStatus} | {error, Reason}.

binbo:load_pgn_file(Pid, Filename) -> {ok, GameStatus} | {error, Reason}.
where:

  • Pid is the pid of the game process;

  • PGN is a Portable Game Notation, its type is binary();

  • Filename is a path to the file from which PGN is to be loaded. Its type is binary() or string().

  • GameStatus is the game status.

Function binbo:load_pgn/2 loads PGN itself.

If PGN is pretty large and you are able to load it from local file, to avoid sending large data between processes, use binbo:load_pgn_file/2 since it’s highly optimized for reading local files.

To extract move list, Binbo takes into account various cases specific to PGN such as comments in braces, recursive annotation variations (RAVs) and numeric annotation glyphs (NAGs).

Examples: 
%% Binary PGN:
load_pgn() ->
  PGN = <<"1. e4 e5 2. Nf3 Nc6 3. Bb5 a6">>,
  {ok, Pid} = binbo:new_server(),
  binbo:load_pgn(Pid, PGN).

%% From file:
load_pgn_from_file() ->
  Filename = "/path/to/game.pgn",
  {ok, Pid} = binbo:new_server(),
  binbo:load_pgn_file(Pid, Filename).

Board visualization

binbo:print_board(Pid) -> ok.
binbo:print_board(Pid, [unicode|ascii|flip]) -> ok.

You may want to see the current position right in Elang shell. To do it, call:

% With ascii pieces:
binbo:print_board(Pid).

% With unicode pieces:
binbo:print_board(Pid, [unicode]).

% Flipped board:
binbo:print_board(Pid, [flip]).
binbo:print_board(Pid, [unicode, flip]).

Game status

binbo:game_status(Pid) -> {ok, GameStatus} | {error, Reason}.
where:

  • Pid is the the pid of the game process;

  • GameStatus is the game status itself;

  • Reason is the reason why the game status cannot be obtained (usually due to the fact that the game is not initialized via binbo:new_game/1,2).

The value of GameStatus:

  • continue - game in progress;

  • {checkmate, white_wins} - White wins, Black checkmated;

  • {checkmate, black_wins} - Black wins, White checkmated;

  • {draw, stalemate} - draw because of stalemate;

  • {draw, rule50} - draw according to the fifty-move rule;

  • {draw, insufficient_material} - draw because of insufficient material;

  • {draw, threefold_repetition} - draw according to the threefold repetition rule;

  • {draw, {manual, WhyDraw}} - draw was set manually for the reason of WhyDraw.

  • {winner, Winner, {manual, WinnerReason}} - winner Winner was set manually for the reason of WinnerReason.

List of legal moves

binbo:all_legal_moves(Pid) -> {ok, Movelist} | {error, Reason}.

binbo:all_legal_moves(Pid, Movetype) -> {ok, Movelist} | {ok, Number} | {error, Reason}.
where:

  • Pid is the pid of the game process;

  • Movelist is a list of all legal moves for the current position. Each element of Movelist is a tuple {From, To} or {From, To, Promo}, where:

    • From and To are starting and target square respectively.

    • Promo is one of the atoms: q, r, b, n (i.e. queen, rook, bishop, and knight respectively). Three-element tuple {From, To, Promo} occurs in case of pawn promotion.

  • Movetype can take on of the values: int, bin, str, or count.

The call binbo:all_legal_moves(Pid) is the same as binbo:all_legal_moves(Pid, int).

If Movetype is count, the function returns tuple {ok, Number} where Number is the number of legal moves.

The values of From and To depend on Movetype as follows:

  • int: the values of From and To are integers in range 0..63, namely, square indices. For example, the move from A1 to H8 corresponds to {0, 63}. Use int to get the fastest reply from the game process.

  • bin: the values of From and To are binaries. For example: {<<"e2">>, <<"e4">>}.

  • str: the values of From and To are strings. For example: {"e2", "e4"}.

Example: 
> {ok, Pid} = binbo:new_server().
{ok,<0.212.0>}

%% Start new game from FEN that corresponds to Position 5
%% from Perft Results: https://www.chessprogramming.org/Perft_Results
> binbo:new_game(Pid, <<"rnbq1k1r/pp1Pbppp/2p5/8/2B5/8/PPP1NnPP/RNBQK2R w KQ - 1 8">>).
{ok,continue}

%% Count legal moves
> binbo:all_legal_moves(Pid, count).
{ok,44}

> {ok, Movelist} = binbo:all_legal_moves(Pid).
{ok,[{51,58,q},
     {51,58,r},
     {51,58,b},
     {51,58,n},
     {26,53},
     {26,44},
     {26,40},
     {26,35},
     {26,33},
     {26,19},
     {26,17},
     {15,31},
     {15,23},
     {14,30},
     {14,22},
     {12,29},
     {12,27},
     {12,22},
     {12,18},
     {12,6},
     {10,18},
     {9,25},
     {9,17},
     {8,24},
     {8,16},
     {7,...},
     {...}|...]}

%% Count moves:
> erlang:length(Movelist).
44

> binbo:all_legal_moves(Pid, bin).
{ok,[{<<"d7">>,<<"c8">>,q},
     {<<"d7">>,<<"c8">>,r},
     {<<"d7">>,<<"c8">>,b},
     {<<"d7">>,<<"c8">>,n},
     {<<"c4">>,<<"f7">>},
     {<<"c4">>,<<"e6">>},
     {<<"c4">>,<<"a6">>},
     {<<"c4">>,<<"d5">>},
     {<<"c4">>,<<"b5">>},
     {<<"c4">>,<<"d3">>},
     {<<"c4">>,<<"b3">>},
     {<<"h2">>,<<"h4">>},
     {<<"h2">>,<<"h3">>},
     {<<"g2">>,<<"g4">>},
     {<<"g2">>,<<"g3">>},
     {<<"e2">>,<<"f4">>},
     {<<"e2">>,<<"d4">>},
     {<<"e2">>,<<"g3">>},
     {<<"e2">>,<<"c3">>},
     {<<"e2">>,<<"g1">>},
     {<<"c2">>,<<"c3">>},
     {<<"b2">>,<<"b4">>},
     {<<"b2">>,<<"b3">>},
     {<<"a2">>,<<"a4">>},
     {<<"a2">>,<<...>>},
     {<<...>>,...},
     {...}|...]}

> binbo:all_legal_moves(Pid, str).
{ok,[{"d7","c8",q},
     {"d7","c8",r},
     {"d7","c8",b},
     {"d7","c8",n},
     {"c4","f7"},
     {"c4","e6"},
     {"c4","a6"},
     {"c4","d5"},
     {"c4","b5"},
     {"c4","d3"},
     {"c4","b3"},
     {"h2","h4"},
     {"h2","h3"},
     {"g2","g4"},
     {"g2","g3"},
     {"e2","f4"},
     {"e2","d4"},
     {"e2","g3"},
     {"e2","c3"},
     {"e2","g1"},
     {"c2","c3"},
     {"b2","b4"},
     {"b2","b3"},
     {"a2","a4"},
     {"a2",[...]},
     {[...],...},
     {...}|...]}

Side to move

binbo:side_to_move(Pid) -> {ok, white | black} | {error, Reason}.

If White is to move, it returns {ok, white}. If Black is to move, it returns {ok, black}.

Example: 
> {ok, Pid} = binbo:new_server().
{ok,<0.232.0>}

> binbo:new_game(Pid).
{ok,continue}

> binbo:side_to_move(Pid). % White is to move
{ok,white}

> binbo:move(Pid, <<"e2e4">>).
{ok,continue}

> binbo:side_to_move(Pid). % Black is to move now
{ok,black}

Game state

binbo:game_state(Pid) -> GameState.
binbo:set_game_state(Pid, GameState) -> {ok, GameStatus} | {error, Reason}.
where:

  • Pid is the pid of the game process;

  • GameState is the whole game state.

  • GameStatus is the game status.

binbo:game_state/1 returns a raw game state, it may be useful when you want to save it somehow (e.g. into a database) and then restore it in the future with binbo:set_game_state(Pid, GameState). It’s much faster than restoring game move by move incrementally.

Example: 
> {ok, Pid} = binbo:new_server().
{ok,<0.194.0>}

> binbo:new_game(Pid).
{ok,continue}

> GameState = binbo:game_state(Pid).
#{12 => 1,4 => 6,38 => 0,16 => 0,53 => 17,46 => 0,28 => 0,
  23 => 0,lastmovepc => 0,59 => 21,58 => 19,bbenpa => 0,
  30 => 0,40 => 0,47 => 0,24 => 0,27 => 0,21 => 0,
  bbwp => 65280,29 => 0,22 => 0,31 => 0,61 => 19,18 => 0,
  54 => 17,5 => 3,14 => 1,51 => 17,57 => 18,...}

> BinGame = erlang:term_to_binary(GameState).
<<131,116,0,0,0,89,97,48,97,17,100,0,4,98,98,98,98,110,8,
  0,0,0,0,0,0,0,0,36,100,...>>

> binbo:set_game_state(Pid, erlang:binary_to_term(BinGame)).
{ok,continue}

Setting a draw

It is possible to set a draw via API:

binbo:game_draw(Pid) -> ok | {error, Reason}.
binbo:game_draw(Pid, WhyDraw) -> ok | {error, Reason}.
where:

  • Pid is the pid of the game process;

  • WhyDraw is the reason why a draw is to be set.

Calling binbo:game_draw(Pid) is the same as: binbo:game_draw(Pid, undefined).

Example: 
% Players agreed to a draw:
> binbo:game_draw(Pid, by_agreement).
ok

% Trying to set a draw for the other reason:
> binbo:game_draw(Pid, other_reason).
{error,{already_has_status,{draw,{manual,by_agreement}}}}

Setting game winner

binbo:set_game_winner(Pid, Winner) -> ok | {error, Reason}.
binbo:set_game_winner(Pid, Winner, WinnerReason) -> ok | {error, Reason}.
where:

  • Pid is the pid of the game process;

  • Winner is the winner, it can be any Erlang term (white, black, 'Bobby Fischer', etc.);

  • WinnerReason is the reason why winner is to be set.

Calling binbo:set_game_winner(Pid, Winner) is the same as: binbo:set_game_winner(Pid, Winner, undefined).

Example: 
% Black resigned
> binbo:set_game_winner(Pid, white, black_resigned).
ok

% Now the status of the game is: {winner,white,{manual,black_resigned}}
> binbo:game_status(Pid).
{ok,{winner,white,{manual,black_resigned}}}

% Trying to set the winner right after that (impossible):
> binbo:set_game_winner(Pid, white, black_lost_on_time).
{error,{already_has_status,{winner,white,
                                   {manual,black_resigned}}}}

Stopping game process

If, for some reason, you want to stop the game process and free resources, use:

binbo:stop_server(Pid) -> ok | {error, {not_pid, Pid}}.

Function terminates the game process with pid Pid.

Stopping application

To stop Binbo, call:

binbo:stop().

Using chess engines

You can write a chess bot application or play with engine using functions described in this section.

Please note:

  • Chess engine must support UCI protocol;

  • Chess engine must be installed on the same machine where Binbo runs on.

Read the description of the Universal Chess Interface (UCI) with examples for details.

Start new game with engine

binbo:new_uci_game(Pid, Options) -> {ok, GameStatus} | {error, Reason}.
Types: 
Pid :: pid().

Options :: #{
  engine_path := EnginePath,
  fen => Fen
}.

EnginePath :: binary() | string() | {TCPHost, TCPPort, timeout()}.
TCPHost :: inet:socket_address() | inet:hostname().
TCPPort :: inet:port_number().

Fen :: binary() | string().
where:

  • Pid is the pid of the process where the game is to be initialized;

  • EnginePath is the full path to the engine’s executable file (e.g. /usr/local/bin/stockfish) or tuple {Host, Port, Timeout} for TCP connection;

  • Fen is the Forsyth–Edwards Notation (FEN), defaults to initial if omitted;

  • GameStatus is the game status.

Example: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% New game from the starting position:
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).
{ok,continue}

% New game with the given FEN:
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish", fen => <<"rnbqkbnr/pppppppp/8/8/3P4/8/PPP1PPPP/RNBQKBNR b KQkq - 0 1">>}).
{ok,continue}

Search for the best move

binbo:uci_bestmove(Pid) -> {ok, BestMove} | {error, Reason}.
binbo:uci_bestmove(Pid, BestMoveOptions) -> {ok, BestMove} | {error, Reason}.
Types: 
Pid :: pid().
BestMove :: binary() % e.g. <<"e2e4">>, <<"a7a8q">>, ...

BestMoveOptions :: #{
  depth  => pos_integer(),     % depth <x> (search x plies only)
  wtime  => non_neg_integer(), % wtime <x> (white has x msec left on the clock)
  btime  => non_neg_integer(), % btime <x> (black has x msec left on the clock)
  winc  => pos_integer(),      % winc <x> (white increment per move in mseconds if x > 0)
  binc  => pos_integer(),      % binc <x> (black increment per move in mseconds if x > 0)
  movestogo => pos_integer(),  % movestogo <x> (there are x moves to the next time control, this will only be sent if x > 0, if you don't get this and get the wtime and btime it's sudden death)
  nodes  => pos_integer(),     % nodes <x> (search x nodes only)
  movetime => pos_integer()    % movetime <x> (search exactly x mseconds)
}.

binbo:uci_bestmove(Pid) is the same as binbo:uci_bestmove(Pid, #{movetime ⇒ 1000}), it sends command go to the engine. binbo:uci_bestmove(Pid, BestMoveOptions) sends command go …​ to the engine adding values associated with the keys of BestMoveOptions.

For example, calling binbo:uci_bestmove(Pid, #{movetime => 2000, depth => 10}) means sending command go movetime 2000 depth 10 to the engine.

Note: the very important option is movetime, it tells the engine how long (in milliseconds) to search for the best move. Defaults to 1000 milliseconds.

Functions binbo:uci_bestmove/2,3 do NOT change the position on the board, they return the bestmove as a hint. To make moves and play with engine, use functions binbo:uci_play/2,3.

Example: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% New game with the given FEN:
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish", fen => <<"r1bqkbnr/pp1ppp1p/2n3p1/1Bp5/4P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 0 4">>}).
{ok,continue}

% Search for the best move (no options given):
> binbo:uci_bestmove(Pid).
{ok,<<"e1g1">>}

% Search exactly 1000 milliseconds:
> binbo:uci_bestmove(Pid, #{movetime => 1000}).
{ok,<<"e1g1">>}

% Search for the best move at depth 10:
> binbo:uci_bestmove(Pid, #{depth => 10}).
{ok,<<"b5c6">>}

% Search exactly 5000 milliseconds at depth 30:
> binbo:uci_bestmove(Pid, #{depth => 30, movetime => 5000}).
{ok,<<"e1g1">>}

Play with engine, make moves

binbo:uci_play(Pid, BestMoveOptions) -> {ok, GameStatus, EngineMove} | {error, Reason}.
binbo:uci_play(Pid, BestMoveOptions, YourMove) -> {ok, GameStatus, EngineMove} | {error, Reason}.
where:

  • Pid - pid of the game process;

  • BestMoveOptions - options for the best move the engine should search for, same as options for binbo:uci_bestmove/2;

  • EngineMove - move that was done by the engine;

  • YourMove - your move to send to the engine before it makes its move, e.g. <<"e2e4">>, <<"a7a8q">>, …

  • GameStatus is the game status.

Function binbo:uci_play(Pid, BestMoveOptions) goes through the following steps:

  • the engine searches for the bestmove (EngineMove) from the current position;

  • the engine makes this move and changes its internal position;

  • tuple {ok, GameStatus, EngineMove} is returned.

The behaviour of function binbo:uci_play(Pid, BestMoveOptions, YourMove) is slightly different. Here are the steps it goes through:

  • your move YourMove is sent to the engine;

  • the engine receives YourMove and changes its internal position;

  • the engine searches for the bestmove (EngineMove) from the changed position;

  • the engine makes this move and changes its internal position;

  • tuple {ok, GameStatus, EngineMove} is returned.

See how to play with engine in the example from "Quick start" section.

Сhange position after the game is created

binbo:uci_set_position(Pid, Fen) -> {ok, GameStatus} | {error, Reason}.
where:

  • Pid - pid of the game process;

  • Fen is the Forsyth–Edwards Notation (FEN);

  • GameStatus is the game status.

Using this function you can change the position at any time. The game MUST be created before.

Example: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% Start new game from the initial position:
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).

% Set up new position with the given FEN:
> binbo:uci_set_position(Pid, <<"r1bqk1nr/ppppppb1/2n3p1/7p/2PP4/5NPP/PP2PP2/RNBQKB1R b KQkq - 2 5">>).
{ok,continue}

Synchronize positions

binbo:uci_sync_position(Pid) -> ok | {error, Reason}.
where:

  • Pid - pid of the game process.

It can be useful to call this function when the position of the game process was changed somehow and the engine wasn’t notified about that.

Example: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% Start new game from the initial position:
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).

% Make move (the engine knows nothing about it):
> binbo:move(Pid, "e2e4").
{ok,continue}

% Now synchronize the engine's position with the position of the game process:
> binbo:uci_sync_position(Pid).
ok

Send any command to engine

binbo:uci_command_call(Pid, Command) -> ok | {error, Reason}.
binbo:uci_command_cast(Pid, Command) -> ok.
where:

  • Pid - pid of the game process;

  • Command - UCI command to send to the engine.

You can send any command to the engine with functions binbo:uci_command_call/2 and binbo:uci_command_cast/2.

binbo:uci_command_call/2 is a synchronous function, it calls gen_server:call/2 inside. Returns ok if Command is sent, or tuple {error, no_uci_connection} if the engine’s process is not connected to the game process.

binbo:uci_command_cast/2 is an asynchronous function, it calls gen_server:cast/2 inside. Returns ok. It also checks if the engine’s process is connected to the game process before sending message and, if not connected, returns ok anyway.

Example: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% Start new game:
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).
{ok,continue}

% Set hash to 32 MB (synchronous):
> binbo:uci_command_call(Pid, "setoption name Hash value 32").
ok

% Set hash to 32 MB (asynchronous):
> binbo:uci_command_cast(Pid, "setoption name Hash value 32").
ok

Handling messages from engine

binbo:set_uci_handler(Pid, Handler) -> ok.
Types: 
Pid :: pid().
Handler :: undefined | default | fun().
where:

  • Pid - pid of the game process;

  • Handler - what to do with the message received from the engine.

If Handler is undefined, no operations are performed (the initial behaviour).

If Handler is set to default, function binbo_uci_protocol:default_handler/1 from module binbo_uci_protocol is performed. It just prints the message to the Erlang shell.

If Handler is a function of arity 1, this function is performed. The only argument the function takes is the message received from the engine.

Note: all the messages received from the engine are of binary() type.

Example with default handler: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% Start new game (no message handler):
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).
{ok,continue}

% Set default message handler:
> binbo:set_uci_handler(Pid, default).
ok

% Now start new game (with default message handler):
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).
{ok,continue}
… and get the messages from the engine: 
--- UCI LOG BEGIN ---
Stockfish 10 64 POPCNT by T. Romstad, M. Costalba, J. Kiiski, G. Linscott
--- UCI LOG END ---

--- UCI LOG BEGIN ---
id name Stockfish 10 64 POPCNT
id author T. Romstad, M. Costalba, J. Kiiski, G. Linscott

option name Debug Log File type string default
option name Contempt type spin default 24 min -100 max 100
option name Analysis Contempt type combo default Both var Off var White var Black var Both
option name Threads type spin default 1 min 1 max 512
option name Hash type spin default 16 min 1 max 131072
option name Clear Hash type button
option name Ponder type check default false
option name MultiPV type spin default 1 min 1 max 500
option name Skill Level type spin default 20 min 0 max 20
option name Move Overhead type spin default 30 min 0 max 5000
option name Minimum Thinking Time type spin default 20 min 0 max 5000
option name Slow Mover type spin default 84 min 10 max 1000
option name nodestime type spin default 0 min 0 max 10000
option name UCI_Chess960 type check default false
option name UCI_AnalyseMode type check default false
option name SyzygyPath type string default <empty>
option name SyzygyProbeDepth type spin default 1 min 1 max 100
option name Syzygy50MoveRule type check default true
option name SyzygyProbeLimit type spin default 7 min 0 max 7
uciok
--- UCI LOG END ---
Example with custom message handler: 
%% In the Erlang shell.

% Start new process for the game:
> {ok, Pid} = binbo:new_server().
{ok,<0.185.0>}

% Start new game (no message handler):
> binbo:new_uci_game(Pid, #{engine_path => "/usr/local/bin/stockfish"}).
{ok,continue}

% Remember pid of the calling process:
> SomePid = self().
<0.411.0>

% Set custom message handler as a function that resends messages to the process with pid SomePid:
> binbo:set_uci_handler(Pid, fun(Message) -> SomePid ! Message end).
ok

% Tell the engine to search for the bestmove:
> binbo:uci_bestmove(Pid).
{ok,<<"e2e4">>}

% Get the messages received:
> flush().
Shell got <<"info depth 1 seldepth 1 multipv 1 score cp 116 nodes 20 nps 20000 tbhits 0 time 1 pv e2e4\n">>
Shell got <<"info depth 2 seldepth 2 multipv 1 score cp 112 nodes 54 nps 54000 tbhits 0 time 1 pv e2e4 b7b6\n">>
Shell got <<"info depth 3 seldepth 3 multipv 1 score cp 148 nodes 136 nps 136000 tbhits 0 time 1 pv d2d4 d7d6 e2e4\n">>
Shell got <<"info depth 4 seldepth 4 multipv 1 score cp 137 nodes 247 nps 123500 tbhits 0 time 2 pv d2d4 e7e6 e2e4 c7c6\n">>
Shell got <<"info depth 5 seldepth 5 multipv 1 score cp 77 nodes 1157 nps 385666 tbhits 0 time 3 pv c2c3 d7d5 d2d4 b8c6 c1g5\n">>
Shell got <<"info depth 6 seldepth 6 multipv 1 score cp 83 nodes 2250 nps 562500 tbhits 0 time 4 pv e2e4 b8c6 d2d4 d7d6 f1c4 g8f6\n">>
Shell got <<"info depth 7 seldepth 7 multipv 1 score cp 67 nodes 4481 nps 746833 tbhits 0 time 6 pv e2e4 e7e5 d2d4 e5d4 d1d4 b8c6 d4d1\n">>
Shell got <<"info depth 8 seldepth 8 multipv 1 score cp 60 nodes 7849 nps 981125 tbhits 0 time 8 pv e2e4 e7e5 g1f3 d7d5 d2d4 b8c6 f3e5\n">>
Shell got <<"info depth 9 seldepth 11 multipv 1 score cp 115 nodes 11846 nps 1184600 tbhits 0 time 10 pv e2e4 e7e5 g1f3 g8f6 b1c3\n">>
Shell got <<"info depth 10 seldepth 10 multipv 1 score cp 106 upperbound nodes 14951 nps 1245916 tbhits 0 time 12 pv e2e4 d7d5\nbestmove e2e4 ponder d7d5\n">>
ok

% Now turn the message handler off:
> binbo:set_uci_handler(Pid, undefined).
ok

Other helper functions

more like this

cc65-Chess

Portable chess game in C. Commodore 64, Apple 2, Atari, Oric, Commander X16, curses terminal, etc.

C★ 50
@StewBC

search

search projects, people, and tags