{"id":13576801,"url":"https://github.com/evanofslack/pyminion","last_synced_at":"2025-08-20T16:31:28.331Z","repository":{"id":45361795,"uuid":"413671427","full_name":"evanofslack/pyminion","owner":"evanofslack","description":"dominion game engine and simulator","archived":false,"fork":false,"pushed_at":"2024-09-03T03:30:53.000Z","size":919,"stargazers_count":20,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-06T07:35:24.255Z","etag":null,"topics":["ai","bot","dominion","dominion-card-game","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pyminion/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evanofslack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-05T04:20:40.000Z","updated_at":"2024-09-03T03:30:56.000Z","dependencies_parsed_at":"2024-05-06T19:32:34.300Z","dependency_job_id":"dcf593a5-3884-4dd8-9248-3e37af93afb3","html_url":"https://github.com/evanofslack/pyminion","commit_stats":{"total_commits":362,"total_committers":4,"mean_commits":90.5,"dds":0.05524861878453036,"last_synced_commit":"d594a5d888475414777f75f8f91dc24841602228"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanofslack%2Fpyminion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanofslack%2Fpyminion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanofslack%2Fpyminion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanofslack%2Fpyminion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evanofslack","download_url":"https://codeload.github.com/evanofslack/pyminion/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230438185,"owners_count":18225870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bot","dominion","dominion-card-game","python"],"created_at":"2024-08-01T15:01:14.326Z","updated_at":"2024-12-19T13:07:22.153Z","avatar_url":"https://github.com/evanofslack.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Pyminion\n\n[![tests](https://github.com/evanofslack/pyminion/actions/workflows/python-app.yml/badge.svg)](https://github.com/evanofslack/pyminion/actions/workflows/python-app.yml)\n[![codecov](https://codecov.io/gh/evanofslack/pyminion/branch/master/graph/badge.svg?token=5GW65KFEL5)](https://codecov.io/gh/evanofslack/pyminion)\n\n\u003cimg width=\"800\" alt=\"pyminion-logo\" src=\"https://github.com/evanofslack/pyminion/assets/51209817/85e6ed9f-8cbf-4781-9c0b-f29c1d0a2162\"\u003e\n\u003cbr\u003e\u003c/br\u003e\n\nPyminion is a library for executing and analyzing games of [Dominion](https://www.riograndegames.com/games/dominion/).\nAt its core, pyminion implements the rules and logic of Dominion and provides\nan API to interact with the game engine. In addition, it enables interactive\ngames through the command line and simulation of games between bots.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Support](#support)\n- [Contributing](#contributing)\n\n## Installation\n\nPyminion requires at least Python 3.10 and can easily be installed through pypi\n\n```bash\npython3 -m pip install pyminion\n```\n\n## Usage\n\n### Setting up a game\n\nTo play an interactive game through the command line against a bot, initialize\na human and a bot and assign them as players. Alternatively, games can be\ncreated between multiple humans or multiple bots.\n\n```python\nfrom pyminion.expansions import base, intrigue, seaside, alchemy\nfrom pyminion.game import Game\nfrom pyminion.bots.examples import BigMoney\nfrom pyminion.human import Human\n\n# Initialize human and bot\nhuman = Human()\nbot = BigMoney()\n\n# Setup the game\ngame = Game(players=[human, bot], expansions=[base.base_set, intrigue.intrigue_set, seaside.seaside_set, alchemy.alchemy_set])\n\n# Play game\ngame.play()\n\n```\n\n### Creating Bots\n\nDefining new bots is relatively straightforward. Inherit from the\n`BotDecider` class and implement play and buy strategies in the\n`action_priority` and `buy_priority` methods respectively.\n\nFor example, here is a simple big money + smithy bot:\n\n```python\nfrom pyminion.bots.bot import Bot, BotDecider\nfrom pyminion.expansions.base import gold, province, silver, smithy\nfrom pyminion.player import Player\nfrom pyminion.game import Game\n\nclass BigMoneySmithyDecider(BotDecider):\n    \"\"\"\n    Big money + smithy\n\n    \"\"\"\n\n    def action_priority(self, player: Player, game: Game):\n        yield smithy\n\n    def buy_priority(self, player: Player, game: Game):\n        money = player.state.money\n        if money \u003e= 8:\n            yield province\n        if money \u003e= 6:\n            yield gold\n        if money == 4:\n            yield smithy\n        if money \u003e= 3:\n            yield silver\n\nclass BigMoneySmithy(Bot):\n    def __init__(\n        self,\n        player_id: str = \"big_money_smithy\",\n    ):\n        super().__init__(decider=BigMoneySmithyDecider(), player_id=player_id)\n```\n\nTo see other bot implementations with more advanced decision trees, see [/bots](https://github.com/evanofslack/pyminion/tree/master/pyminion/bots)\n\n### Running Simulations\n\nSimulating multiple games is good metric for determining bot performance.\nTo create a simulation, pass a pyminion game instance into the `Simulator`\nclass and set the number of iterations to be run.\n\n```python\nfrom pyminion.bots.examples import BigMoney, BigMoneySmithy\nfrom pyminion.expansions.base import base_set, smithy\nfrom pyminion.game import Game\nfrom pyminion.simulator import Simulator\n\nbm = BigMoney()\nbm_smithy = BigMoneySmithy()\n\ngame = Game(players=[bm, bm_smithy], expansions=[base_set], kingdom_cards=[smithy], log_stdout=False)\nsim = Simulator(game, iterations=1000)\nresult = sim.run()\nprint(result)\n```\n\nwith the following terminal output:\n\n```console\n~$ python simulation.py\nSimulation Result: ran 1000 games\nbig_money won 110, lost 676, tied 214\nbig_money_smithy won 676, lost 110, tied 214\n```\n\nPlease see [/examples](https://github.com/evanofslack/pyminion/tree/master/examples) to see demo scripts.\n\n## Support\n\nPlease [open an issue](https://github.com/evanofslack/pyminion/issues/new) for support.\n\n## Contributing\n\nInstall this library, test it out, and report any bugs. A welcome contribution\nwould be to create new bots, especially an implementation that uses machine\nlearning to determine optimal play.\n\nIf you would like to contribute, please create a branch, add commits, and\n[open a pull request](https://github.com/evanofslack/pyminion/pulls).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanofslack%2Fpyminion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevanofslack%2Fpyminion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanofslack%2Fpyminion/lists"}