Quick Start

Installation

pip install pyscoundrel

Play the game

# Basic game
python -m pyscoundrel

# Reproducible game with a fixed seed
python -m pyscoundrel --seed 42

# Skip title screen
python -m pyscoundrel --no-title

# Custom dungeon
python -m pyscoundrel --dungeon my_dungeon.yaml

Game mechanics

Card type	Effect
Monster	Deals damage equal to its value (2–14)
Weapon	Reduces monster damage; can only kill monsters ≤ last kill value
Potion	Heals up to 20 HP; one per turn

Each turn:

1. Draw 4 cards → Room

2. Face 3 of 4 (1 carries to the next room)

3. You may avoid a room once (cards go to bottom of deck), but not twice in a row

4. Win: clear all cards — Lose: health reaches 0

Programmatic usage

from pyscoundrel import GameEngine

engine = GameEngine(seed=42)
engine.start_game()

while not engine.is_game_over:
    engine.draw_room()
    # face the first card in the room
    result = engine.face_card(0)
    # handle monsters, potions, weapons via result.metadata ...

print(f"Victory: {engine.state.victory}, Score: {engine.state.score}")

Running an agent

python -m pyscoundrel --agent examples/smart_agent.py --headless

See Writing Agents for the Agent base class API.