Skip to main content

A Python implementation of the board game intended to be played by artificial intelligence

Project description

Abalone BoAI GitHub Stars GitHub Forks

License Pipenv locked Python version Codecov

This is a Python implementation of the board game Abalone.

It is primarily intended to be played by artificial intelligence, but also offers the option to play as a human player.


Command Line Usage

A minimal command line interface for running a game is provided by abalone/ From the abalone directory run:

$ ./ <black player> <white player>

Replace <black player> and <white player> each with an artificial intelligence (or human player if you want to play yourself).

For instance, play against an AI that makes random moves:

$ ./ human_player.HumanPlayer random_player.RandomPlayer

Loading your own AI works analogously with <module>.<class>.

Abalone Rules

From Wikipedia (CC BY-SA):

Abalone is an award-winning two-player abstract strategy board game designed by Michel Lalet and Laurent Lévi in 1987. Players are represented by opposing black and white marbles on a hexagonal board with the objective of pushing six of the opponent's marbles off the edge of the board.
The board consists of 61 circular spaces arranged in a hexagon, five on a side. Each player has 14 marbles that rest in the spaces and are initially arranged as shown below, on the left image. The players take turns with the black marbles moving first. For each move, a player moves a straight line of one, two or three marbles of one color one space in one of six directions. The move can be either broadside / arrow-like (parallel to the line of marbles) or in-line / in a line (serial in respect to the line of marbles), as illustrated below.

Initial position Black opens with a broadside move White counters with an in-line move
Abalone Standard Abalone Broadside Abalone Inline

A player can push their opponent's marbles (a "sumito") that are in a line to their own with an in-line move only. They can only push if the pushing line has more marbles than the pushed line (three can push one or two; two can push one). Marbles must be pushed to an empty space (i.e. not blocked by a marble) or off the board. The winner is the first player to push six of the opponent's marbles off of the edge of the board.

Write Your Own Artificial Intelligence

In order to write your own AI, create a python file with a class that inherits from abstract_player.AbstractPlayer and implement the turn method:

from abstract_player import AbstractPlayer

class MyPlayer(AbstractPlayer):
    def turn(self, game, moves_history):
        pass  # TODO: implement

Have a look at for a sample implementation.

Refer to the documentation for details about the parameters and the return type.

A particularly useful method is game.generate_legal_moves(). It yields all legal moves that the AI can perform. The turn method can simply return one of the yielded values.

A "move"

The return value of the turn method is called a move. This is a tuple, which consists firstly of the marbles to be moved and secondly of the direction of movement.
The marbles are specified by the space where they are located on the board (see the image at the beginning of this document for the notation of the spaces). All spaces are listed in the Space enum. For an inline move only the trailing marble ("caboose") of the line to be moved is specified. For a broadside move only the two outermost marbles are given in a tuple.
The second element of the tuple is the direction of movement. These are all listed in the Direction enum. Therefore the two example moves from the images above (see Abalone Rules) would look like this:

from enums import Direction, Space

# Black opens with a broadside move
# (returned from the turn method of the black player)
return (Space.C3, Space.C5), Direction.NORTH_WEST

# White counters with an in-line move
# (returned from the turn method of the white player)
return Space.I8, Direction.SOUTH_WEST


All contributions are welcome. See for details.

See Also

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

abalone-boai-1.0.0.tar.gz (16.2 kB view hashes)

Uploaded Source

Built Distribution

abalone_boai-1.0.0-py3-none-any.whl (20.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page