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

Hex was invented in the 1940s by Piet Hein and, independently, by John Nash. Please read the Wikipedia page for more information.

§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

// Or use human-readable coordinates
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: Board represents the Hex board and all placed stones.
Coords: Coordinates of a single cell of the board. hexgame uses a zero-based (row, column)-format analogous to matrix-indices.
Game: Game holds the full state of a game of Hex and allows to manipulate this state by playing valid moves.

Enums§

Color: This enum represents the two players. The first player is always Black.
CoordsOrEdge: 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).
Edge: Represents the four edges of the board.
InvalidBoard: This error may be returned by methods that load a board from serialized data.
InvalidMove: This enum is returned by game.play when the given move is invalid.
Status: Status of a game.

Constants§

MAX_BOARD_SIZE: Maximal supported board size
MIN_BOARD_SIZE: Minimal supported board size

Traits§

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

Type Aliases§

CoordValue: The type of a single coordinate (row or column).
StoneMatrix: This type represents the board as a matrix of Option<Color>. It may be used to serialize/deserialize boards.

Crate hexgameCopy item path