scoundrel 0.1.1

A Python implementation of the Scoundrel card game

A Python implementation of the Scoundrel card game

---

📋 Table of Contents

• The Game
• Quick Start
• Setup
• Agent Approaches
• Development

---

🎮 The Game

Scoundrel is a dungeon-crawling card game where players navigate through rooms, collect cards, and battle monsters.

📖 Official Scoundrel Rules PDF

🎯 Playing the Game

play [--seed SEED]

Play interactively in the terminal. Use --seed for deterministic deck shuffling (same seed = same game sequence).

---

🚀 Quick Start

# Clone the repository
git clone https://github.com/Lizzard1123/scoundrel.git
cd scoundrel

# Create conda environment
conda env create -f environment.yml
conda activate scoundrel

# Install package
pip install -e .

# Play the game
play

---

⚙️ Setup

Using Conda (Recommended)

conda env create -f environment.yml
conda activate scoundrel
pip install -e .

---

🤖 Agent Approaches

This implementation includes two AI agent approaches for playing Scoundrel:

🌳 MCTS Agent

Monte Carlo Tree Search agent with parallelization support for high-performance gameplay.

Features:

• ⚡ Parallel simulation workers
• 🧠 Transposition table caching
• 📊 Performance visualization tools
• 🎯 Configurable exploration parameters

Console Scripts:

Command	Description
mcts	Watch the MCTS agent play interactively
mcts-eval	Evaluate MCTS agent performance
mcts-plot	Visualize MCTS episode performance

Usage Examples:

# Interactive gameplay
mcts --num-simulations 1000000 --num-workers 8

# Performance evaluation
mcts-eval --num-games 10 --verbose

# Episode visualization
mcts-plot --num-simulations 1000000 --batch 5 --confidence

Interactive MCTS visualizer showing real-time gameplay

Average outlook of the action picked at each turn

MCTS performance variability across multiple runs (6 out of 10 runs won)

🎯 MCTS Data Collection (AlphaGo Style)

MCTS data collection pipeline for training AlphaGo-style neural network agents with supervised learning from expert gameplay.

MCTS data collection showing game statistics and performance distribution

Data Collection Results:

Games: 5041

Statistics:
  Wins: 1316 (26.11%)
  Average score: -21.45
  Best score: 30
  Worst score: -188
  Average turns per game: 42.8
  Total turns: 215803

🧠 RL Agent

Reinforcement learning agent using a Transformer-based architecture with PPO training.

Features:

• 🔄 Transformer encoder for sequence planning
• 🎯 MLP for immediate tactical decisions
• 📈 TensorBoard integration
• 💾 Checkpoint management

Training:

cd scoundrel/rl/transformer_mlp/scripts
./train.sh

---

🛠️ Development

Running Tests

pytest

Code Formatting

black .
isort .

Project Structure

scoundrel/
├── game/          # Core game logic
├── models/        # Game state models
├── rl/            # AI agents
│   ├── mcts/      # MCTS implementation
│   └── transformer_mlp/  # RL agent
└── ui/            # Terminal UI

---

Made with ❤️ for card game enthusiasts