Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dobro/binbo
Chess representation written in Erlang using Bitboards, ready for use on game servers
https://github.com/dobro/binbo
binbo bitboards chess chess-game chess-pgn chess-uci chessboard chessboard-representation erlang erlang-chess erlang-library magic-bitboards otp-library pgn uci uci-protocol universal-chess-interface
Last synced: about 16 hours ago
JSON representation
Chess representation written in Erlang using Bitboards, ready for use on game servers
- Host: GitHub
- URL: https://github.com/dobro/binbo
- Owner: DOBRO
- License: apache-2.0
- Created: 2019-07-10T13:22:31.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-05-19T16:04:41.000Z (over 1 year ago)
- Last Synced: 2023-12-07T10:21:52.213Z (about 1 year ago)
- Topics: binbo, bitboards, chess, chess-game, chess-pgn, chess-uci, chessboard, chessboard-representation, erlang, erlang-chess, erlang-library, magic-bitboards, otp-library, pgn, uci, uci-protocol, universal-chess-interface
- Language: Erlang
- Homepage:
- Size: 401 KB
- Stars: 114
- Watchers: 6
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
= Binbo
:toc: macro
:toclevels: 4
image:https://img.shields.io/hexpm/v/binbo.svg?color=yellow["Binbo on Hex.pm", link="https://hex.pm/packages/binbo"]
image:https://github.com/DOBRO/binbo/actions/workflows/main.yml/badge.svg?branch=master["CI Status", link="https://github.com/DOBRO/binbo/actions?query=workflow%3ABuild+branch%3Amaster"]
image:https://codecov.io/gh/DOBRO/binbo/branch/master/graph/badge.svg["Code coverage", link="https://codecov.io/gh/DOBRO/binbo"]
image:https://img.shields.io/badge/erlang-%3E%3D%2020.0-0d6e8c.svg["Erlang", link="https://www.erlang.org/"]
image:https://img.shields.io/badge/license-Apache%202.0-blue.svg["License", link="LICENSE"]
Binbo is a full-featured Chess representation written in pure Erlang using https://www.chessprogramming.org/Bitboards[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 **bin**ary **bo**ard 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 https://www.chessprogramming.org/Magic_Bitboards[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 https://www.chessprogramming.org/Category:UCI[chess engines that support UCI protocol] (https://www.chessprogramming.org/UCI[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 https://github.com/h4cc/awesome-elixir[Awesome Elixir] list.
image::https://user-images.githubusercontent.com/296845/61208986-40792d80-a701-11e9-93c8-d2c41c5ef00d.png[Binbo sample]
'''
toc::[]
'''
== 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:
** https://en.wikipedia.org/wiki/En_passant[En-passant move];
** https://en.wikipedia.org/wiki/Castling[Castling];
** https://en.wikipedia.org/wiki/Fifty-move_rule[Fifty-move rule];
** https://en.wikipedia.org/wiki/Threefold_repetition[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: +
♙{nbsp}♘{nbsp}♗{nbsp}♖{nbsp}♕{nbsp}♔{nbsp}{nbsp}{nbsp}{nbsp}♟{nbsp}♞{nbsp}♝{nbsp}♜{nbsp}♛{nbsp}♚
* UCI protocol support.
* Support for TCP connections to remote UCI chess engines.
* Passes all https://www.chessprogramming.org/Perft_Results[perft] tests.
* Cross-platform application. It can run on Linux, Unix, Windows, and macOS.
* Ready for use on game servers.
== Requirements
** https://www.erlang.org/[Erlang/OTP] 20.0 or higher.
** https://www.rebar3.org/[rebar3]
== Installation
=== For Erlang projects
Add Binbo as a dependency to your `rebar.config` file:
[source,erlang]
----
{deps, [
{binbo, "4.0.3"}
]}.
----
=== For Elixir projects
Add Binbo as a dependency to your `mix.exs` file:
[source,elixir]
----
defp deps do
[
{:binbo, "~> 4.0"}
]
end
----
== Quick start
Clone repository, change directory to `binbo` and run `rebar3 shell` (or `make shell`):
[source,bash]
----
$ git clone https://github.com/DOBRO/binbo.git
$ cd binbo
$ rebar3 shell
----
=== Common example
.In the Erlang shell:
[source,erlang]
----
%% 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]).
----
[[quickstart-play-with-engine]]
=== Play with engine on local machine
.In the Erlang shell:
[source,erlang]
----
%% 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":
[source]
----
+---+---+---+---+---+---+---+---+
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">>}
----
[[quickstart-uci-over-tcp]]
=== 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:
[source,bash]
----
$ 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:
[source,bash]
----
$ 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):
[source,bash]
----
$ 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):
[source,bash]
----
$ 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:
[source,erlang]
----
%% 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:
. Start Binbo application.
. Create process for the game.
. 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 http://erlang.org/doc/design_principles/sup_princ.html[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:
[source,erlang]
----
binbo:start().
----
=== Creating game process
[source,erlang]
----
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 link:#server-options[bellow]).
.So, to start one or more game processes:
[source,erlang]
----
{ok, Pid1} = binbo:new_server(),
{ok, Pid2} = binbo:new_server(),
{ok, Pid3} = binbo:new_server().
----
[[server-options]]
==== Options for the game process
[source,erlang]
----
binbo:set_server_options(Pid, Options) -> ok | {error, Reason}.
----
`Pid` is the `pid` of the game process.
.`Options`:
[source,erlang]
----
#{
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 link:#game-state[game state];
** `Arg` - the argument you want to pass to the callback function.
.Example:
[source,erlang]
----
-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:
[source,erlang]
----
binbo:set_server_options(Pid, #{
idle_timeout => infinity,
onterminate => undefined
})
----
[[initializing-new-game]]
=== Initializing new game
[source,erlang]
----
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 https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation[Forsyth–Edwards Notation] (FEN);
* `GameStatus` is the link:#game-status[game status].
It is possible to reinitialize game in the same process. For example:
[source,erlang]
----
binbo:new_game(Pid),
binbo:new_game(Pid, Fen2),
binbo:new_game(Pid, Fen3).
----
.Example:
[source,erlang]
----
%% 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
[source,erlang]
----
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 link:#game-status[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 https://en.wikipedia.org/wiki/Algebraic_notation_(chess)[_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`:
[source,erlang]
----
%% 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`:
[source,erlang]
----
%% 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`:
[source,erlang]
----
%% 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 https://en.wikipedia.org/wiki/Castling[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:
[source,erlang]
----
% 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 https://en.wikipedia.org/wiki/Promotion_(chess)[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:
[source,erlang]
----
% 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 https://en.wikipedia.org/wiki/En_passant[en passant capture] in strict accordance with the chess rules.
=== Getting FEN
[source,erlang]
----
binbo:get_fen(Pid) -> {ok, Fen}.
----
.Example:
[source,erlang]
----
> binbo:get_fen(Pid).
{ok, <<"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1">>}.
----
=== PGN loading
[source,erlang]
----
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 https://en.wikipedia.org/wiki/Portable_Game_Notation[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 link:#game-status[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_,
https://chess.stackexchange.com/questions/18214/valid-pgn-variations[_recursive annotation variations_] (RAVs) and
https://en.wikipedia.org/wiki/Numeric_Annotation_Glyphs[_numeric annotation glyphs_] (NAGs).
.Examples:
[source,erlang]
----
%% 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
[source,erlang]
----
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:
[source,erlang]
----
% 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]]
=== Game status
[source,erlang]
----
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 link:#initializing-new-game[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 link:#setting-a-draw[manually] for the reason of `WhyDraw`.
* `{winner, Winner, {manual, WinnerReason}}` - winner `Winner` was set link:#setting-game-winner[manually] for the reason of `WinnerReason`.
=== List of legal moves
[source,erlang]
----
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:
[source,erlang]
----
> {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
[source,erlang]
----
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:
[source,erlang]
----
> {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]]
=== Game state
[source,erlang]
----
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 link:#game-status[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:
[source,erlang]
----
> {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]]
=== Setting a draw
It is possible to set a draw via API:
[source,erlang]
----
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:
[source,erlang]
----
% 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]]
=== Setting game winner
[source,erlang]
----
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:
[source,erlang]
----
% 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:
[source,erlang]
----
binbo:stop_server(Pid) -> ok | {error, {not_pid, Pid}}.
----
Function terminates the game process with pid `Pid`.
=== Stopping application
To stop Binbo, call:
[source,erlang]
----
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 https://gist.github.com/DOBRO/2592c6dad754ba67e6dcaec8c90165bf[description of the Universal Chess Interface (UCI)] with examples for details.
[[start-new-game-with-engine]]
==== Start new game with engine
[source,erlang]
----
binbo:new_uci_game(Pid, Options) -> {ok, GameStatus} | {error, Reason}.
----
.Types:
[source,erlang]
----
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 link:#game-status[game status].
.Example:
[source,erlang]
----
%% 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]]
==== Search for the best move
[source,erlang]
----
binbo:uci_bestmove(Pid) -> {ok, BestMove} | {error, Reason}.
binbo:uci_bestmove(Pid, BestMoveOptions) -> {ok, BestMove} | {error, Reason}.
----
.Types:
[source,erlang]
----
Pid :: pid().
BestMove :: binary() % e.g. <<"e2e4">>, <<"a7a8q">>, ...
BestMoveOptions :: #{
depth => pos_integer(), % depth (search x plies only)
wtime => non_neg_integer(), % wtime (white has x msec left on the clock)
btime => non_neg_integer(), % btime (black has x msec left on the clock)
winc => pos_integer(), % winc (white increment per move in mseconds if x > 0)
binc => pos_integer(), % binc (black increment per move in mseconds if x > 0)
movestogo => pos_integer(), % movestogo (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 (search x nodes only)
movetime => pos_integer() % movetime (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 link:#binbo-uci-play-docs[binbo:uci_play/2,3].
.Example:
[source,erlang]
----
%% 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">>}
----
[[binbo-uci-play-docs]]
==== Play with engine, make moves
[source,erlang]
----
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 link:#search-for-the-best-move[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 link:#game-status[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 link:#quickstart-play-with-engine[example] from _"Quick start"_ section.
==== Сhange position after the game is created
[source,erlang]
----
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 link:#game-status[game status].
Using this function you can change the position at any time. The game MUST be link:#start-new-game-with-engine[created] before.
.Example:
[source,erlang]
----
%% 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
[source,erlang]
----
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:
[source,erlang]
----
%% 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
[source,erlang]
----
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 https://erlang.org/doc/man/gen_server.html#call-2[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 https://erlang.org/doc/man/gen_server.html#cast-2[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:
[source,erlang]
----
%% 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
[source,erlang]
----
binbo:set_uci_handler(Pid, Handler) -> ok.
----
.Types:
[source,erlang]
----
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 link:src/binbo_uci_protocol.erl[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:
[source,erlang]
----
%% 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:
[source]
----
--- 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
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:
[source,erlang]
----
%% 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
[source,erlang]
----
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:
[source,erlang]
----
> 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
[source,bash]
----
$ make
----
[source,bash]
----
$ rebar3 compile
----
=== Dialyzer
[source,bash]
----
$ make dialyze
----
[source,bash]
----
$ rebar3 dialyzer
----
=== Testing
[source,bash]
----
$ make test
$ export BINBO_UCI_ENGINE_PATH="/path/to/engine"
$ export BINBO_UCI_ENGINE_HOST=localhost
$ export BINBO_UCI_ENGINE_PORT=9010
$ make test
----
[source,bash]
----
$ 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
[source,bash]
----
$ make cover
----
[source,bash]
----
$ rebar3 cover
----
=== Generating Edoc files
[source,bash]
----
$ make docs
----
[source,bash]
----
$ rebar3 edoc
----
== Binbo and Magic Bitboards
As mentioned above, Binbo uses https://www.chessprogramming.org/Magic_Bitboards[Magic Bitboards], the fastest solution for move generation of sliding pieces
(rook, bishop, and queen). Good explanations of this approach can also be found https://stackoverflow.com/questions/16925204/sliding-move-generation-using-magic-bitboard/30862064#30862064[here]
and http://vicki-chess.blogspot.com/2013/04/magics.html[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++:_
[source,c]
----
magic_index = ((occupied & mask) * magic_number) >> shift;
----
._in Erlang:_
[source,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 "https://www.chessprogramming.org/Looking_for_Magics[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 https://www.chessprogramming.org/Magic_Bitboards#Fancy[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:
[source,c]
----
move = global_move_table[square][magic_index]
----
._If detailed:_
[source,c]
----
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:_
[source,erlang]
----
GlobalMovesTable = { MoveMap1, ..., MoveMap64 }
----
._where:_
[source,erlang]
----
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_):
[source,erlang]
----
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:
[source,erlang]
----
GlobalMaskTable = {Mask1, Mask2, ..., Mask64}
----
where `Mask1`, `Mask2`, ..., `Mask64` are _bitboards_ (integers).
Finally, if we need to get all moves from `E4`:
[source,erlang]
----
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**?
http://erlang.org/doc/man/ets.html[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 https://github.com/mochi/mochiweb/blob/master/src/mochiglobal.erl[mochiglobal].
Using http://erlang.org/doc/man/persistent_term.html[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 link:CHANGELOG.md[CHANGELOG] for details.
== Contributing
Want to contribute? Really? Awesome!
Please refer to the link:CONTRIBUTING.md[CONTRIBUTING] file for details.
== License
This project is licensed under the terms of the Apache License, Version 2.0.
See the link:LICENSE[LICENSE] file for details.