gonggi

A die game of risk and reward.

You will find here the rules and the implementation of a simulator for a 2-player dice game.

Note that this game has nothing to do with the game of gonggi, which is a traditional Korean game.

We do not know the actual name of the game implemented here though.

Usage

Run the game using poetry run play_game, or alternatively without Poetry: python3 scripts/play_game.py (this project is actually pure Python as detailed here).

Doing so will run the game with the policies defined in gonggi.policies.__init__.py.

See poetry run play_game --help for more information on the script options.

📜 Rules of the game

• The game is played on a board made of two n x n grids, one for each player.
• A player's score is the total of all the dice currently placed on his side of the board.
• The players take turn by rolling a die and placing it on one of the n columns of his side of the board.
• The game ends when one of the two boards is full, the winner is the player with the highest score.

The game was initially designed to be played with a six-sided dice and with n equal to 3.

There are two additional behaviors to this game that are described below.

🎲 Match dice

When dice of the same number are placed in the same column, multiply their values.

More precisely, k similar dices in the same column amount to k ** 2 the value of the dice.

♟️ Destroy opponent

Destroy your opponent's dice by matching yours to theirs.

If a player places a die of value x in column j of his side of the board, all dice with the same value are removed from column j of his opponent's side of the board.

Implementation

This project is written in pure Python (no heavy computation is performed, no need for efficient NumPy-based operations) and supports Python >= 3.9. Therefore, the dependencies only contain development tools, and there is no particular need to install a dedicated venv.

📦 Dependency management and packaging

Dependencies are managed using poetry: https://python-poetry.org/.

To install poetry follow the steps in: https://python-poetry.org/docs/.

• The dependencies are listed in a pyproject.toml alongside supported ranges of versions for each dependency.
• The exact versions used can be frozen using poetry lock, which generated a snapshot in the form of the poetry.lock file.
• The dependencies can then be installed in a virtualenv (cached under ~/.cache/pypoetry) by running poetry install.

🔨 Adding a policy

You can add your own policies in file policies.py and choose which one to use in gonggi.policies.__init__.py

Make sure your policy respects the typing defined in gonggi.simulation.data_structures.