Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/evanofslack/pyminion
dominion game engine and simulator
https://github.com/evanofslack/pyminion
ai bot dominion dominion-card-game python
Last synced: about 1 month ago
JSON representation
dominion game engine and simulator
- Host: GitHub
- URL: https://github.com/evanofslack/pyminion
- Owner: evanofslack
- License: mit
- Created: 2021-10-05T04:20:40.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-09-03T03:30:53.000Z (5 months ago)
- Last Synced: 2024-12-06T07:35:24.255Z (about 2 months ago)
- Topics: ai, bot, dominion, dominion-card-game, python
- Language: Python
- Homepage: https://pypi.org/project/pyminion/
- Size: 897 KB
- Stars: 20
- Watchers: 2
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pyminion
[](https://github.com/evanofslack/pyminion/actions/workflows/python-app.yml)
[](https://codecov.io/gh/evanofslack/pyminion)
Pyminion is a library for executing and analyzing games of [Dominion](https://www.riograndegames.com/games/dominion/).
At its core, pyminion implements the rules and logic of Dominion and provides
an API to interact with the game engine. In addition, it enables interactive
games through the command line and simulation of games between bots.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Support](#support)
- [Contributing](#contributing)
## Installation
Pyminion requires at least Python 3.10 and can easily be installed through pypi
```bash
python3 -m pip install pyminion
```
## Usage
### Setting up a game
To play an interactive game through the command line against a bot, initialize
a human and a bot and assign them as players. Alternatively, games can be
created between multiple humans or multiple bots.
```python
from pyminion.expansions import base, intrigue, seaside, alchemy
from pyminion.game import Game
from pyminion.bots.examples import BigMoney
from pyminion.human import Human
# Initialize human and bot
human = Human()
bot = BigMoney()
# Setup the game
game = Game(players=[human, bot], expansions=[base.base_set, intrigue.intrigue_set, seaside.seaside_set, alchemy.alchemy_set])
# Play game
game.play()
```
### Creating Bots
Defining new bots is relatively straightforward. Inherit from the
`BotDecider` class and implement play and buy strategies in the
`action_priority` and `buy_priority` methods respectively.
For example, here is a simple big money + smithy bot:
```python
from pyminion.bots.bot import Bot, BotDecider
from pyminion.expansions.base import gold, province, silver, smithy
from pyminion.player import Player
from pyminion.game import Game
class BigMoneySmithyDecider(BotDecider):
"""
Big money + smithy
"""
def action_priority(self, player: Player, game: Game):
yield smithy
def buy_priority(self, player: Player, game: Game):
money = player.state.money
if money >= 8:
yield province
if money >= 6:
yield gold
if money == 4:
yield smithy
if money >= 3:
yield silver
class BigMoneySmithy(Bot):
def __init__(
self,
player_id: str = "big_money_smithy",
):
super().__init__(decider=BigMoneySmithyDecider(), player_id=player_id)
```
To see other bot implementations with more advanced decision trees, see [/bots](https://github.com/evanofslack/pyminion/tree/master/pyminion/bots)
### Running Simulations
Simulating multiple games is good metric for determining bot performance.
To create a simulation, pass a pyminion game instance into the `Simulator`
class and set the number of iterations to be run.
```python
from pyminion.bots.examples import BigMoney, BigMoneySmithy
from pyminion.expansions.base import base_set, smithy
from pyminion.game import Game
from pyminion.simulator import Simulator
bm = BigMoney()
bm_smithy = BigMoneySmithy()
game = Game(players=[bm, bm_smithy], expansions=[base_set], kingdom_cards=[smithy], log_stdout=False)
sim = Simulator(game, iterations=1000)
result = sim.run()
print(result)
```
with the following terminal output:
```console
~$ python simulation.py
Simulation Result: ran 1000 games
big_money won 110, lost 676, tied 214
big_money_smithy won 676, lost 110, tied 214
```
Please see [/examples](https://github.com/evanofslack/pyminion/tree/master/examples) to see demo scripts.
## Support
Please [open an issue](https://github.com/evanofslack/pyminion/issues/new) for support.
## Contributing
Install this library, test it out, and report any bugs. A welcome contribution
would be to create new bots, especially an implementation that uses machine
learning to determine optimal play.
If you would like to contribute, please create a branch, add commits, and
[open a pull request](https://github.com/evanofslack/pyminion/pulls).