# gobblet-rl
[](https://github.com/elliottower/gobblet-rl/actions/workflows/pages/pages-build-deployment)
[](https://results.pre-commit.ci/latest/github/elliottower/gobblet-rl/main)
[](https://github.com/psf/black)
[](https://badge.fury.io/py/gobblet-rl)
Interactive Multi-Agent Reinforcement Learning Environment for the [Gobblet](https://themindcafe.com.sg/wp-content/uploads/2018/07/Gobblet-Gobblers.pdf) board game using [PettingZoo](https://github.com/PettingZoo-Team/PettingZoo) and [Pygame](https://github.com/pygame/pygame).
Allows for users to play in the same environment, and even play against RL agents trained with [Tianshou](https://github.com/thu-ml/tianshou).
<h1 style="text-align: center;width: 80%">
<img alt="Gobblet board game" src="./assets/gobblet.jpg" width="45%">
<img alt="Gobblet-rl game rendered with Pygame" src="./assets/gobblet_pygame.gif" width="45%">
</h1>
## Installation
### Using pip (recommended)
```bash
pip install gobblet-rl
```
### Local
```bash
git clone hhttps://github.com/elliottower/gobblet-rl.git
cd gobblet-rl
pip install -e .
```
## Usage
### Setting up a basic environment
In a Python shell, run the following:
```python
from gobblet_rl import gobblet_v1
env = gobblet_v1.env()
```
### Play against a greedy agent
In the terminal, run the following:
```
python gobblet/example_tianshou_greedy.py --cpu-players 1
```
This will launch a game vs a greedy agent, which is a very strong baseline. This agent considers all possible moves with a depth of 2, winning if possible, blocking enemy wins, and even forcing the enemy to make losing moves.
Note: this policy exploits domain knowledge to reconstruct the internal game board from the observation (perfect information) and directly uses functions from `board.py`. Tianshou policies do not get direct access to the environment, only observations/action masks. So the greedy agent should not be directly compared with other RL agents.
### Play against a DQN agent trained with Tianshou
In the terminal, run the following:
```
python gobblet/example_tianshou_DQN.py --epoch 50 --player 1 --cpu-players 2
```
This will train a [DQN](https://tianshou.readthedocs.io/en/master/tutorials/dqn.html) model from Tianshou for 50 epochs, and launch an interactive game against the pre-trained agent.
Use the argument ``--cpu-player`` to determine the number of CPU agents (1 or 2) and ``--player`` to choose which agent goes first (human first: 0, CPU first: 1)
Use the argument ``--self-play`` to train agents using self-play.
### Play an interactive game
In the terminal, run the following:
```
python gobblet/examples/example_user_input.py"
```
Note: Interactive play can be enabled in other scripts using the argument `--num-cpu 1`
To select a piece size, press a number key `1`, `2`, or `3`, or press `space` to cycle through pieces. Placing a piece is done by clicking on a square on the board. A preview will appear showing legal moves with the selected piece size. Clicking on an already placed piece will pick it up and prompt you to place it in a new location (re-placing in the same location is an illegal move).
### Create screen recording of a game
In the terminal, run the following:
```
python gobblet/examples/example_record_game.py"
```
This will save a screen recording of a game to `gobblet/examples/game.gif`
### Watch a game between two basic CPU agents
In the terminal, run the following:
```
python gobblet/examples/example_basic.py"
```
This will launch a game with two basic agents choosing random actions. This file can be used as a starting point for prototyping future methods.
### Command Line Arguments
#### Game Modes
All scripts besides`example_basic.py` (no support for interactive play) take the following arguments:
The default game mode is human vs CPU, with the human playing as red and CPU as yellow.
``--player 1`` sets the human player as yellow, with the CPU moving first as red.
``--cpu-players 1`` will launch a game with one CPU agent and one human agent. (default)
``--cpu-players 0`` will launch a game with no CPU agents, taking interactive input for both agents.
``--cpu-player 2`` will launch a game with two CPU agents, and takes no interactive input.
#### Display Modes
`example_basic.py` takes the following arguments to change display mode:
``--render_mode="human" `` will render the game board visually using pygame. Player 1 plays red and goes first, while player 2 plays yellow.
<img alt="Example using render_mode='human'" src="./assets/gobblet_pygame.png" width=30% height=30%>
When playing interactively, possible moves can be previewed by hovering the mouse over each square. To move a piece which is already placed, simply click on it.
``--render_mode="text"`` will render a 3x3 board only showing the topmost pieces (pieces which are covered by others, or 'gobbled', are hidden):
```
TURN: 2, AGENT: player_1, ACTION: 51, POSITION: 6, PIECE: 3
| |
- | - | -3
_______|_______|_______
| |
- | - | +2
_______|_______|_______
| |
- | - | -
| |
```
``--render_mode="text_full"`` will render three different 3x3 boards representing the small, medium and large pieces. This gives full information about pieces which are covered or 'gobbled' by other pieces. :
```
TURN: 3, AGENT: player_0, ACTION: 42, POSITION: 6, PIECE: 5
SMALL MED LARGE
| | | | | |
- | - | - - | - | - - | - | +5
_______|_______|_______ _______|_______|_______ _______|_______|_______
| | | | | |
- | - | -2 - | - | - - | - | -
_______|_______|_______ _______|_______|_______ _______|_______|_______
| | | | | |
- | - | - - | - | - - | - | -6
| | | | | |
```
## Testing
Testing can be done via [pytest](http://doc.pytest.org/):
```bash
git clone https://github.com/elliottower/gobblet-rl.git
cd gobblet-rl
pytest
```
Raw data
{
"_id": null,
"home_page": "https://github.com/elliottower/gobblet-rl/",
"name": "gobblet-rl",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "gobblet,board game,multiagent-reinforcement-learning,pettingzoo,gymnasium,interactive,pygame",
"author": "elliottower",
"author_email": "elliot@elliottower.com",
"download_url": "https://files.pythonhosted.org/packages/23/d4/5f39334856abf21643eb99611cf58414fe25cf7f384e2b90037d5f03b16f/gobblet_rl-1.3.5.tar.gz",
"platform": null,
"description": "# gobblet-rl\n\n\n[](https://github.com/elliottower/gobblet-rl/actions/workflows/pages/pages-build-deployment)\n[](https://results.pre-commit.ci/latest/github/elliottower/gobblet-rl/main)\n[](https://github.com/psf/black)\n[](https://badge.fury.io/py/gobblet-rl) \n\nInteractive Multi-Agent Reinforcement Learning Environment for the [Gobblet](https://themindcafe.com.sg/wp-content/uploads/2018/07/Gobblet-Gobblers.pdf) board game using [PettingZoo](https://github.com/PettingZoo-Team/PettingZoo) and [Pygame](https://github.com/pygame/pygame).\n\nAllows for users to play in the same environment, and even play against RL agents trained with [Tianshou](https://github.com/thu-ml/tianshou).\n\n<h1 style=\"text-align: center;width: 80%\">\n <img alt=\"Gobblet board game\" src=\"./assets/gobblet.jpg\" width=\"45%\">\n \n <img alt=\"Gobblet-rl game rendered with Pygame\" src=\"./assets/gobblet_pygame.gif\" width=\"45%\">\n\n</h1>\n \n## Installation\n\n### Using pip (recommended)\n\n```bash\npip install gobblet-rl\n```\n\n### Local\n\n```bash\ngit clone hhttps://github.com/elliottower/gobblet-rl.git\ncd gobblet-rl\npip install -e .\n```\n\n## Usage\n\n### Setting up a basic environment\n\nIn a Python shell, run the following:\n\n```python\nfrom gobblet_rl import gobblet_v1\n\nenv = gobblet_v1.env()\n```\n\n### Play against a greedy agent\n\nIn the terminal, run the following:\n```\npython gobblet/example_tianshou_greedy.py --cpu-players 1\n```\n\nThis will launch a game vs a greedy agent, which is a very strong baseline. This agent considers all possible moves with a depth of 2, winning if possible, blocking enemy wins, and even forcing the enemy to make losing moves.\n\nNote: this policy exploits domain knowledge to reconstruct the internal game board from the observation (perfect information) and directly uses functions from `board.py`. Tianshou policies do not get direct access to the environment, only observations/action masks. So the greedy agent should not be directly compared with other RL agents.\n\n### Play against a DQN agent trained with Tianshou\n\nIn the terminal, run the following:\n```\npython gobblet/example_tianshou_DQN.py --epoch 50 --player 1 --cpu-players 2\n```\n\nThis will train a [DQN](https://tianshou.readthedocs.io/en/master/tutorials/dqn.html) model from Tianshou for 50 epochs, and launch an interactive game against the pre-trained agent. \n\nUse the argument ``--cpu-player`` to determine the number of CPU agents (1 or 2) and ``--player`` to choose which agent goes first (human first: 0, CPU first: 1)\n\nUse the argument ``--self-play`` to train agents using self-play.\n\n\n### Play an interactive game\n\nIn the terminal, run the following:\n```\npython gobblet/examples/example_user_input.py\"\n```\n\nNote: Interactive play can be enabled in other scripts using the argument `--num-cpu 1`\n\nTo select a piece size, press a number key `1`, `2`, or `3`, or press `space` to cycle through pieces. Placing a piece is done by clicking on a square on the board. A preview will appear showing legal moves with the selected piece size. Clicking on an already placed piece will pick it up and prompt you to place it in a new location (re-placing in the same location is an illegal move).\n\n### Create screen recording of a game\n\nIn the terminal, run the following:\n```\npython gobblet/examples/example_record_game.py\"\n```\nThis will save a screen recording of a game to `gobblet/examples/game.gif`\n\n\n### Watch a game between two basic CPU agents\n\nIn the terminal, run the following:\n```\npython gobblet/examples/example_basic.py\"\n```\nThis will launch a game with two basic agents choosing random actions. This file can be used as a starting point for prototyping future methods.\n\n\n### Command Line Arguments\n\n\n#### Game Modes\n\nAll scripts besides`example_basic.py` (no support for interactive play) take the following arguments:\n\nThe default game mode is human vs CPU, with the human playing as red and CPU as yellow. \n\n ``--player 1`` sets the human player as yellow, with the CPU moving first as red.\n\n``--cpu-players 1`` will launch a game with one CPU agent and one human agent. (default) \n\n``--cpu-players 0`` will launch a game with no CPU agents, taking interactive input for both agents. \n\n``--cpu-player 2`` will launch a game with two CPU agents, and takes no interactive input.\n\n\n\n#### Display Modes\n\n`example_basic.py` takes the following arguments to change display mode:\n\n``--render_mode=\"human\" `` will render the game board visually using pygame. Player 1 plays red and goes first, while player 2 plays yellow. \n\n<img alt=\"Example using render_mode='human'\" src=\"./assets/gobblet_pygame.png\" width=30% height=30%>\n\nWhen playing interactively, possible moves can be previewed by hovering the mouse over each square. To move a piece which is already placed, simply click on it.\n\n\n``--render_mode=\"text\"`` will render a 3x3 board only showing the topmost pieces (pieces which are covered by others, or 'gobbled', are hidden):\n```\nTURN: 2, AGENT: player_1, ACTION: 51, POSITION: 6, PIECE: 3\n | | \n - | - | -3 \n_______|_______|_______\n | | \n - | - | +2 \n_______|_______|_______\n | | \n - | - | - \n | | \n```\n\n``--render_mode=\"text_full\"`` will render three different 3x3 boards representing the small, medium and large pieces. This gives full information about pieces which are covered or 'gobbled' by other pieces. :\n```\nTURN: 3, AGENT: player_0, ACTION: 42, POSITION: 6, PIECE: 5\n SMALL MED LARGE \n | | | | | | \n - | - | - - | - | - - | - | +5 \n_______|_______|_______ _______|_______|_______ _______|_______|_______\n | | | | | | \n - | - | -2 - | - | - - | - | - \n_______|_______|_______ _______|_______|_______ _______|_______|_______\n | | | | | | \n - | - | - - | - | - - | - | -6 \n | | | | | | \n```\n\n\n## Testing\n\nTesting can be done via [pytest](http://doc.pytest.org/):\n\n```bash\ngit clone https://github.com/elliottower/gobblet-rl.git\ncd gobblet-rl\npytest\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Interactive Multi-Agent Reinforcement Learning Environment for the board game Gobblet using PettingZoo.",
"version": "1.3.5",
"split_keywords": [
"gobblet",
"board game",
"multiagent-reinforcement-learning",
"pettingzoo",
"gymnasium",
"interactive",
"pygame"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "07a5246ff88669ef5817bbeafa19c956fb42e6f003025649edc4c29795f0591a",
"md5": "4401577c12b5d6e324c3ad6571827ca1",
"sha256": "10e32b18ab17b6c0510ecb42123b0a7e2af9df841e3ce4867c3d0ab953ab8a25"
},
"downloads": -1,
"filename": "gobblet_rl-1.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4401577c12b5d6e324c3ad6571827ca1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 59930,
"upload_time": "2023-03-10T18:01:29",
"upload_time_iso_8601": "2023-03-10T18:01:29.389083Z",
"url": "https://files.pythonhosted.org/packages/07/a5/246ff88669ef5817bbeafa19c956fb42e6f003025649edc4c29795f0591a/gobblet_rl-1.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "23d45f39334856abf21643eb99611cf58414fe25cf7f384e2b90037d5f03b16f",
"md5": "9acabc078214209fa6e00804a5a18add",
"sha256": "3202864ef58d910703d2eba7d7f5eb0d49ef9a91429d0df7aec2cf3287276e7c"
},
"downloads": -1,
"filename": "gobblet_rl-1.3.5.tar.gz",
"has_sig": false,
"md5_digest": "9acabc078214209fa6e00804a5a18add",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 44379,
"upload_time": "2023-03-10T18:01:31",
"upload_time_iso_8601": "2023-03-10T18:01:31.300778Z",
"url": "https://files.pythonhosted.org/packages/23/d4/5f39334856abf21643eb99611cf58414fe25cf7f384e2b90037d5f03b16f/gobblet_rl-1.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-10 18:01:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "elliottower",
"github_project": "gobblet-rl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gobblet-rl"
}
JSON
