Dungeon Configuration

Dungeons are defined as YAML files. You can create custom card pools to build themed experiences instead of using the default card set.

YAML format

version: "1.0"

cards:
  - id: "rat"           # unique identifier
    name: "Giant Rat"   # display name
    type: monster       # monster | weapon | health_potion
    value: 2            # damage / healing / weapon power
    count: 4            # copies in deck
    description: "..."  # optional

Example dungeon

version: "1.0"

cards:
  - { id: rat,       name: "Giant Rat",     type: monster,       value: 2,  count: 4 }
  - { id: zombie,    name: "Zombie",        type: monster,       value: 5,  count: 3 }
  - { id: vampire,   name: "Vampire Lord",  type: monster,       value: 12, count: 2 }
  - { id: stick,     name: "Wooden Stick",  type: weapon,        value: 3,  count: 2 }
  - { id: hammer,    name: "War Hammer",    type: weapon,        value: 7,  count: 2 }
  - { id: potion_s,  name: "Small Potion",  type: health_potion, value: 4,  count: 3 }
  - { id: potion_l,  name: "Large Potion",  type: health_potion, value: 8,  count: 2 }

Using a custom dungeon

python -m pyscoundrel --dungeon path/to/dungeon.yaml

from pathlib import Path
from pyscoundrel import Dungeon, GameEngine

dungeon = Dungeon(config_path=Path("my_dungeon.yaml"))
errors = dungeon.validate()
if errors:
    raise ValueError(errors)

engine = GameEngine(dungeon=dungeon, seed=42)

Balance guidelines

  • Total cards: 40–50 recommended

  • Monsters: ~60% — mix of low (2–5), mid (6–10), high (11–13) values

  • Weapons: ~20% — values 2–10

  • Potions: ~20% — values 2–10

Validation

dungeon.validate() returns a list of error strings. It checks for:

  • Duplicate card IDs

  • Non-positive values or counts

  • Invalid card types

  • Fewer than 20 total cards