Binbo

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.

---

Table of Contents

• Features
• Requirements
• Installation
  • For Erlang projects
  • For Elixir projects
• Quick start
  • Common example
  • Play with engine on local machine
  • Connect to remote engine over TCP
• Interface
  • Starting application
  • Creating game process
    • Options for the game process
  • Initializing new game
  • Making moves
    • API
    • Castling
    • Promotion
    • En passant
  • Getting FEN
  • PGN loading
  • Board visualization
  • Game status
  • List of legal moves
  • Side to move
  • Game state
  • Setting a draw
  • Setting game winner
  • Stopping game process
  • Stopping application
  • Using chess engines
    • Start new game with engine
    • Search for the best move
    • Play with engine, make moves
    • Сhange position after the game is created
    • Synchronize positions
    • Send any command to engine
    • Handling messages from engine
  • Other helper functions
    • binbo:get_pieces_list/2
• Building and testing
  • Building
  • Dialyzer
  • Testing
  • Code coverage
  • Generating Edoc files
• Binbo and Magic Bitboards
• Changelog
• Contributing
• License

---

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:

  • En-passant move;

  • Castling;

  • Fifty-move rule;

  • Threefold repetition;

  • Draw by insufficient material:

    • King versus King,

    • King and Bishop versus King,

    • King and Knight versus King,

    • King and Bishop versus King and Bishop with the bishops on the same color;

• 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

• Erlang/OTP 20.0 or higher.

• rebar3

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:

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

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

• GameStatus is the game status.

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

binbo:get_pieces_list/2

binbo:get_pieces_list(Pid, SquareType) -> {ok, PiecesList} | {error, Reason}.

where:

• Pid - pid of the game process;

• SquareType is one of the atoms: index or notation;

• PiecesList - list of tuples {Square, Color, PieceType}:

  • Square - square index (0 .. 63) or notation (binary: <<"a1">>, …​, <<"h8">>) depending on SquareType;

  • Color - white | black;

  • PieceType - pawn | knight | bishop | rook | queen | king.

Example:

> binbo:get_pieces_list(Pid, index).
{ok,[{63,black,rook},
     {62,black,knight},
     {61,black,bishop},
     {60,black,king},
     {59,black,queen},
     {58,black,bishop},
     {57,black,knight},
     {56,black,rook},
     {55,black,pawn},
     {54,black,pawn},
     {53,black,pawn},
     {52,black,pawn},
     {51,black,pawn},
     {50,black,pawn},
     {49,black,pawn},
     {48,black,pawn},
     {15,white,pawn},
     {14,white,pawn},
     {13,white,pawn},
     {12,white,pawn},
     {11,white,pawn},
     {10,white,pawn},
     {9,white,pawn},
     {8,white,pawn},
     {7,white,...},
     {6,...},
     {...}|...]}

> binbo:get_pieces_list(Pid, notation).
{ok,[{<<"h8">>,black,rook},
     {<<"g8">>,black,knight},
     {<<"f8">>,black,bishop},
     {<<"e8">>,black,king},
     {<<"d8">>,black,queen},
     {<<"c8">>,black,bishop},
     {<<"b8">>,black,knight},
     {<<"a8">>,black,rook},
     {<<"h7">>,black,pawn},
     {<<"g7">>,black,pawn},
     {<<"f7">>,black,pawn},
     {<<"e7">>,black,pawn},
     {<<"d7">>,black,pawn},
     {<<"c7">>,black,pawn},
     {<<"b7">>,black,pawn},
     {<<"a7">>,black,pawn},
     {<<"h2">>,white,pawn},
     {<<"g2">>,white,pawn},
     {<<"f2">>,white,pawn},
     {<<"e2">>,white,pawn},
     {<<"d2">>,white,pawn},
     {<<"c2">>,white,pawn},
     {<<"b2">>,white,pawn},
     {<<"a2">>,white,pawn},
     {<<"h1">>,white,...},
     {<<...>>,...},
     {...}|...]}

Building and testing

Two possible ways are presented here for building and testing the application (with make and rebar3).

Building

$ make

$ rebar3 compile

Dialyzer

$ make dialyze

$ rebar3 dialyzer

Testing

$ make test

$ export BINBO_UCI_ENGINE_PATH="/path/to/engine"
$ export BINBO_UCI_ENGINE_HOST=localhost
$ export BINBO_UCI_ENGINE_PORT=9010
$ make test

$ rebar3 ct --verbose

$ export BINBO_UCI_ENGINE_PATH="/path/to/engine"
$ export BINBO_UCI_ENGINE_HOST=localhost
$ export BINBO_UCI_ENGINE_PORT=9010
$ rebar3 ct --verbose

Code coverage

$ make cover

$ rebar3 cover

Generating Edoc files

$ make docs

$ rebar3 edoc

Binbo and Magic Bitboards

As mentioned above, Binbo uses Magic Bitboards, the fastest solution for move generation of sliding pieces (rook, bishop, and queen). Good explanations of this approach can also be found here and here.

The main problem is to find the index which is then used to lookup legal moves of sliding pieces in a preinitialized move database. The formula for the index is:

in C/C++:

magic_index = ((occupied & mask) * magic_number) >> shift;

in Erlang:

MagicIndex = (((Occupied band Mask) * MagicNumber) bsr Shift).

where:

• Occupied is the bitboard of all pieces.

• Mask is the attack mask of a piece for a given square.

• MagicNumber is the magic number, see "Looking for Magics".

• Shift = (64 - Bits), where Bits is the number of bits corresponding to attack mask of a given square.

All values for magic numbers and shifts are precalculated before and stored in binbo_magic.hrl.

To be accurate, Binbo uses Fancy Magic Bitboards. It means that all moves are stored in a table of its own (individual) size for each square. In C/C++ such tables are actually two-dimensional arrays and any move can be accessed by a simple lookup:

move = global_move_table[square][magic_index]

If detailed:

moves_from = global_move_table[square];
move = moves_from[magic_index];

The size of moves_from table depends on piece and square where it is placed on. For example:

• for rook on A1 the size of moves_from is 4096 (2^12 = 4096, 12 bits required for the attack mask);

• for bishop on A1 it is 64 (2^6 = 64, 6 bits required for the attack mask).

There are no two-dimensional arrays in Erlang, and no global variables which could help us to get the fast access to the move tables from everywhere.

So, how does Binbo beat this? Well, it’s simple :).

Erlang gives us the power of tuples and maps with their blazing fast lookup of elements/values by their index/key.

Since the number of squares on the chessboard is the constant value (it’s always 64, right?), our global_move_table can be constructed as a tuple of 64 elements, and each element of this tuple is a map containing the key-value association as MagicIndex => Moves.

If detailed, for moves:

GlobalMovesTable = { MoveMap1, ..., MoveMap64 }

where:

MoveMap1  = #{
  MagicIndex_1_1 => Moves_1_1,
  ...
  MagicIndex_1_K => Moves_1_K
},
MoveMap64 = #{
  MagicIndex_64_1 => Moves_64_1, ...
  ...
  MagicIndex_64_N => Moves_64_N
},

and then we lookup legal moves from a square, say, E4 (29th element of the tuple):

E4 = 29,
MoveMapE4   = erlang:element(E4, GlobalMovesTable),
MovesFromE4 = maps:get(MagicIndex, MovesMapE4).

To calculate magic index we also need the attack mask for a given square. Every attack mask generated is stored in a tuple of 64 elements:

GlobalMaskTable = {Mask1, Mask2, ..., Mask64}

where Mask1, Mask2, …​, Mask64 are bitboards (integers).

Finally, if we need to get all moves from E4:

E4 = 29,
Mask = erlang:element(E4, GlobalMaskTable),
MagicIndex = ((Occupied band Mask) * MagicNumber) bsr Shift,
MoveMapE4   = erlang:element(E4, GlobalMovesTable),
MovesFromE4 = maps:get(MagicIndex, MovesMapE4).

Next, no global variables? We make them global!

How do we get the fastest access to the move tables and to the attack masks from everywhere?

ETS? No! Using ETS as a storage for static terms we get the overhead due to extra data copying during lookup.

And now we are coming to the fastest solution.

When Binbo starts up, all move tables are initialized. Once these tables (tuples, actually) initialized, they are "injected" into dynamically generated modules compiled at Binbo start. Then, to get the values, we just call a getter function (binbo_global:get/1) with the argument as the name of the corresponding dynamic module.

This awesome trick is used in MochiWeb library, see module mochiglobal.

Using persistent_term (since OTP 21.2) for storing static data is also a good idea. But it doesn’t seem to be a better way for the following reason with respect to dynamic modules. When Binbo stops, it gets them unloaded as they are not necessary anymore. It should do the similar things for persistent_term data, say, delete all unused terms to free memory. In this case we run into the issue regarding scanning the heaps in all processes.

So, using global dynamic modules with large static data seems to be more reasonable in spite of that fact that it significantly slows down the application startup due to the run-time compilation of these modules.

Changelog

See CHANGELOG for details.

Contributing

Want to contribute? Really? Awesome!

Please refer to the CONTRIBUTING file for details.

License

This project is licensed under the terms of the Apache License, Version 2.0.

See the LICENSE file for details.