Skip to content

First Card Game

This tutorial walks through running a demo game of The Forest of Humbaba and a quick tournament — no LLM required.

Prerequisites

Complete the installation first. Make sure your venv is active: source venv_py_bdpd/bin/activate

1. Run a Demo Game

The card game simulation pits two archetype decks against each other:

python3 agents/cards_ai_play.py \
  --deck1 warrior --deck2 temple \
  --cards cards/cards_v03.json \
  --demo --games 1

What does this do?

--demo enables verbose output showing every turn's play. --games 1 runs a single match. Increase for statistical results.

2. Read the Output

The output logs each turn:

══════════════════════════════════════════════════════════════════
Turn 1 — Forest Health: ●●●●●●○○○○ (6/10)
══════════════════════════════════════════════════════════════════
  Warrior-King plays: Harvest (harvest 3)
  Temple Keeper plays: Heal (restore 1 Forest Health)

  Harvest phase: Warrior-King collects 3 tokens
  Temple Keeper collects 0 tokens

  End of turn — Forest regenerates +1
══════════════════════════════════════════════════════════════════

At the end, you see:

Metric Meaning
Result p1_wins / p2_wins / tie / collapse
Final stockpiles Each player's accumulated cedars
Turns played Game length
Collapse trigger What caused collapse (if any) — empty Forest Deck, failed Forest Die roll, Box Reserve drained

Try different deck matchups:

# Aggressive vs Aggressive — fastest collapse
python3 agents/cards_ai_play.py \
  --deck1 warrior --deck2 warrior \
  --cards cards/cards_v03.json --demo --games 1

# Conservative + Adaptive vs Aggressive
python3 agents/cards_ai_play.py \
  --deck1 temple --deck2 merchant \
  --cards cards/cards_v03.json --demo --games 1

3. Run a Quick Tournament

Tournaments run multiple matches across deck pairings and produce aggregate statistics:

python3 experiments/sweep_card_tournaments.py \
  --cards cards/cards_v03.json \
  --demo --sweep ct1

This runs the CT1 tournament (collapse-rate matrix across all 4 × 4 archetype matchups). Demo collapse rates at 200 games per cell (see card_tournaments.md for the canonical published table):

CT1 — Collapse-rate matrix
            warrior  stranger  merchant  temple
warrior      81.5%    69.5%     71.5%     54.5%
stranger     69.5%    56.0%     39.5%      0.0%
merchant     71.5%    39.5%      0.0%      0.0%
temple       54.5%     0.0%      0.0%      0.0%

Key takeaway: Warrior-King is the dominant driver of collapse — matchups excluding the Warrior collapse 0% of the time. Stranger-King shows a dual nature: 0% vs Temple, ~70% vs Warrior.

4. Run with an LLM

To run the card game with an LLM opponent, you need either a local llama-server or an OpenAI-compatible API key. See LLM Agents for setup, then:

LLM_MODE=local MODEL_PATH=/path/to/model.gguf \
  python3 agents/cards_ai_play.py \
    --deck1 stranger --deck2 warrior \
    --cards cards/cards_v03.json --games 5

LLM_MODE=api BDPD_API_KEY=sk-... \
  python3 agents/cards_ai_play.py \
    --deck1 stranger --deck2 warrior \
    --cards cards/cards_v03.json --games 5

5. Generate Physical Cards

To generate print-ready PNG cards from SVG templates:

python3 tools/card_generator/generate_cards.py \
  --cards-json cards/cards_v03.json \
  --dpi 300 \
  --out-dir my_cards/

See Card Generator for full options.

The Four Archetypes

Archetype Strategy Platform Equivalent
Warrior-King Maximises harvest every turn Aggressive
Temple Keeper Conservative extraction, can heal the forest Conservative
River Merchant Adapts harvest to forest trend Adaptive
Stranger-King Starts cooperative, can defect late The Mule (strategy_override)

Next Steps