Crate hexgame

Expand description

This is a simple and performant implementation of the Hex board game.

While it was mainly written to be used in Monte-Carlo Tree Search bots for Hex, it aims to be a general-purpose library for Hex.

Features:

• rules of the game (without swap rule, see below),
• serialize/deserialize to/from JSON,
• some analysis functions that may be helpful when writing bots: `get_neighbors`, `get_empty_cells`, `find_attacked_bridges`. See the `Board` struct for more information.

The Game of Hex

The rules of Hex are very simple: Hex is played by two players (Black and White) on a board of hexagons. The size is variable, typical sizes are 11x11 or 19x19. Starting with Black, the players take turns to place stones of their color on an empty space. The task of Black is to connect the top and bottom edges. White needs to connect left and right edges. The first player to connect their edges wins the game.

In the following example, Black (●) has won the game after connecting the top edge to the bottom edge.

`````` a  b  c  d  e
1\.  .  .  ○  ●\1
2\.  .  ○  ●  .\2
3\.  .  ●  ●  .\3
4\.  .  ○  ●  .\4
5\.  ○  ●  ○  .\5
a  b  c  d  e``````

The Swap Rule

As starting player, Black has a huge advantage. In real games, this advantage is circumvented by the so-called swap rule: After Black has placed the first Stone, the second player can choose to either continue the game normally or to swap colors.

This library does not yet implement the swap rule, mostly because it was not necessary for the MCTS-research using this library.

How to use this library

The most important struct is `Game`. To play the game, you also need `Coords`. The game keeps track of the current player automatically.

``````use hexgame::{Coords, Game};

let mut game = Game::new(19); // size of the board

game.play(Coords::new(3, 5));  // (row, column) and zero-based, i.e. f4

game.play("d5".parse().unwrap());``````

`game.board` can be used to access the cells of the board (e.g. `get_color(coords)`).

Serialization

Serialization functionality requires `use hexgame::Serialization;`.

To serialize a game, use `game.save_to_string()` or `game.save_to_json()`, which serializes to a Serde value. `Game::load_from_str` or `Game::load_from_json` can be used to create a game from a JSON string or value.

Playing Hex on CLI

While this package is mostly a library, it also contains a small command-line interface to player Hex.

``cargo run``

Then type the coordinates of the space where you would like to place your next stone, e.g. “c2” and press Enter.

Optionally, you can specify the size of the board like in `cargo run 7`.

Structs

`Board` represents the Hex board and all placed stones.

Coordinates of a single cell of the board. `hexgame` uses a zero-based (row, column)-format analogous to matrix-indices.

`Game` holds the full state of a game of Hex and allows to manipulate this state by playing valid moves.

Enums

This enum represents the two players. The first player is always `Black`.

Represents either a cell of the board or an edge. This type is used in a few places that may return both coords and edges (e.g. get_neighbors).

Represents the four edges of the board.

This error may be returned by methods that load a board from serialized data.

This enum is returned by `game.play` when the given move is invalid.

Status of a game.

Constants

Maximal supported board size

Minimal supported board size

Traits

This trait is implemented by Game and can be used to serialize/deserialize Hex games to/from strings or JSON.

Type Definitions

The type of a single coordinate (row or column).

This type represents the board as a matrix of `Option<Color>`. It may be used to serialize/deserialize boards.