Usage¶

As a Library¶

Quick start — generate a random setup¶

from dominion_setup import load_card_database, generate_game

# Load the bundled card database (all sets, all editions)
db = load_card_database()

# Generate a random game — by default draws from ALL sets and editions
game = generate_game(db)

# Inspect the result
for pile in game.kingdom_piles:
    marks = f" [{', '.join(str(m) for m in pile.marks)}]" if pile.marks else ""
    print(f"  {pile.card.name} ({pile.card.cost}){marks}")

Choosing specific sets and editions¶

from dominion_setup import load_card_database, generate_game
from dominion_setup.models import CardSet, CardSetEdition, KingdomSortOrder

db = load_card_database()

game = generate_game(
    db,
    sets_editions={
        (CardSet.BASE, CardSetEdition.SECOND_EDITION),
        (CardSet.INTRIGUE, CardSetEdition.SECOND_EDITION),
        (CardSet.PROSPERITY, CardSetEdition.SECOND_EDITION),
    },
    sort_order=KingdomSortOrder.NAME,  # sort kingdom by name
    use_colony=True,  # always include Colony/Platinum
    use_shelters=False,  # never use Shelters
    max_landscapes=1,  # at most 1 landscape card
)

Exploring the `Game` object¶

from dominion_setup import load_card_database, generate_game

db = load_card_database()
game = generate_game(db)

# Sets used in this game
print("Sets:", ", ".join(str(s) for s in game.sets_used))

# Kingdom piles (always 10, plus any special extras such as Bane)
for pile in game.kingdom_piles:
    print(
        f"  {pile.card.name:25s} {str(pile.card.cost):>5}  {', '.join(pile.card.types)}"
    )

# Landscape cards (Events, Landmarks, Projects, Ways, Traits)
if game.landscapes:
    print("Landscapes:")
    for card in game.landscapes:
        print(f"  {card.name}")

# Ally (present when any Liaison card is in the Kingdom)
if game.ally:
    print("Ally:", game.ally.name)

# Prophecy (present when any Omen card is in the Kingdom)
if game.prophecy:
    print("Prophecy:", game.prophecy.name)

# Druid Boons (present when Druid is in the Kingdom)
if game.druid_boons:
    print("Druid Boons:", ", ".join(b.name for b in game.druid_boons))

# Non-supply piles (Prizes, Rewards, Traveller chains, Spirits, …)
if game.non_supply_piles:
    print("Non-Supply:")
    for pile in game.non_supply_piles:
        print(f"  {pile.card.name}")

# Basic supply (Copper, Silver, Gold, Estate, Duchy, Province, Curse,
#               + conditional Colony/Platinum, Potion, Ruins, Shelters, Heirlooms)
for pile in game.basic_piles:
    print(f"  {pile.card.name}")

# Required mats and tokens
if game.materials:
    print("Materials:", ", ".join(str(m) for m in game.materials))

# Per-card setup instructions
for instruction in game.setup_instructions:
    print(f"  • {instruction}")

Querying the card database¶

from dominion_setup import load_card_database
from dominion_setup.models import CardSet, CardSetEdition, CardType, CardCost

db = load_card_database()

# All kingdom cards in Nocturne
nocturne_cards = db.get_cards_by_set_edition(
    CardSet.NOCTURNE, CardSetEdition.FIRST_EDITION
)
print(f"Nocturne has {len(nocturne_cards)} kingdom cards")

# All Action–Attack cards
attack_actions = [
    card
    for card in db.kingdom_cards.values()
    if CardType.ACTION in card.types and CardType.ATTACK in card.types
]

# All kingdom cards that cost $5
five_cost = db.get_cards_by_cost(CardCost(coins=5))

# Look up a card by name
village = db.get_card_by_name("Village")
print(village.name, village.cost, village.instructions)

As a CLI Tool¶

The dominion-setup command groups three sub-commands. Running it with no arguments is equivalent to dominion-setup generate.

`dominion-setup generate` — generate a random setup¶

Generate a random game from the Base 2nd edition (the default):

dominion-setup generate

Mix Intrigue 2e and Seaside 2e, sorted by name:

dominion-setup generate --set intrigue_2e --set seaside_2e --sort name

Use all cards from Dark Ages (always include Shelters, never Colony):

dominion-setup generate --set dark_ages --shelters --no-colony

Allow up to three landscape cards, mix Base 2e with Adventures:

dominion-setup generate --set base_2e --set adventures --max-landscapes 3

Force Colony/Platinum on when playing with a Prosperity mix:

dominion-setup generate --set base_2e --set prosperity_2e --colony

`dominion-setup list-cards` — browse the card database¶

List all kingdom cards sorted by cost (default):

dominion-setup list-cards

List only Base 2e cards:

dominion-setup list-cards --set base_2e

List all Attack cards across Base 2e and Intrigue 2e:

dominion-setup list-cards --set base_2e --set intrigue_2e --type attack

List all Action–Duration cards that cost exactly $4:

dominion-setup list-cards --type action --type duration --cost 4

List all Nocturne Night cards, sorted by name:

dominion-setup list-cards --set nocturne --type night --sort name

`dominion-setup list-sets` — list available sets¶

dominion-setup list-sets

This prints a table of every supported set (and edition, where applicable) together with its kingdom card count:

              Sets
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
 ┃ Set                            ┃ Kingdom Cards ┃
 ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
 │ Base, 1E                       │            26 │
 │ Base, 2E                       │            26 │
 │ Intrigue, 1E                   │            26 │
 │ ...                            │           ... │
 └────────────────────────────────┴───────────────┘