<p align="center">
  <img src="crates/essence-wars-ui/static/ui/essence_wars_banner.webp" alt="Essence Wars" width="700">
</p>

<p align="center">
  <strong>A deterministic strategy card game engine</strong>
</p>

<p align="center">
  <a href="#try-it-in-google-colab">Try in Colab</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#features">Features</a> •
  <a href="#project-structure">Project Structure</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#contributing">Contributing</a>
</p>

---

## Try it in Google Colab

Want to build an AI agent for Essence Wars? Jump right in — no setup required:

| Notebook | Description |
|----------|-------------|
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/christianWissmann85/essence-wars/blob/main/python/notebooks/01_quickstart.ipynb) | **Quickstart** — Explore the game engine, play games, see the API |
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/christianWissmann85/essence-wars/blob/main/python/notebooks/02_training_ppo.ipynb) | **Train a PPO Agent** — Build and train a neural network to play |
| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/christianWissmann85/essence-wars/blob/main/python/notebooks/03_evaluation.ipynb) | **Evaluate & Benchmark** — Test agents against built-in bots |

## What is Essence Wars?

Essence Wars is a strategic two-player card game engine with a focus on:

- **Perfect Information (Engine)** — The core engine is fully open: bots and ML agents see all cards, hands, and decks. In the desktop UI, opponent hands are hidden for a more natural play experience. Victory comes from outthinking your opponent, not luck.
- **Deterministic Execution** — Seeded RNG ensures every game is reproducible.
- **Lane-Based Combat** — Creatures occupy board positions, creating spatial strategy alongside card selection.

<p align="center">
  <img src="docs/screenshots/human-vs-ai.webp" alt="Gameplay" width="80%">
</p>

## Features

### Desktop Application
Full-featured Tauri desktop client with Human vs AI, Spectator mode, Replays, and Deck Builder.

<p align="center">
  <img src="docs/screenshots/main-menu.webp" alt="Main Menu" width="32%">
  <img src="docs/screenshots/spectator-mode.webp" alt="Spectator Mode" width="32%">
  <img src="docs/screenshots/deck-builder.webp" alt="Deck Builder" width="32%">
</p>

### AI & Machine Learning
- **Multiple Bot Types** — Random, Greedy (28 tunable weights), MCTS, Alpha-Beta search
- **Python ML Framework** — Gymnasium/PettingZoo environments, PPO, AlphaZero, Game Transformer
- **Training Infrastructure** — Callbacks, experiment tracking, W&B integration

### Claude Code Integration
Play Essence Wars directly in Claude Code via MCP (Model Context Protocol):
- Natural language game control
- AI move recommendations with analysis
- Live game visualization in Tauri UI (Launch the Essence Wars UI App, and ask Claude to sync, watch her play the game live in the App!)

## Quick Start

### Play the Desktop App

```bash
# Clone and build
git clone https://github.com/christianWissmann85/essence-wars
cd essence-wars
cargo build --release

# Launch the UI
cd crates/essence-wars-ui
pnpm install && pnpm tauri:dev
```

### Train Your Own AI Agent

The fastest way to get started is the [Colab notebooks above](#try-it-in-google-colab). For local development:

```bash
# Install Python package
uv pip install essence-wars[train]

# 1. Train a PPO agent
uv run python python/scripts/training/ppo.py --timesteps 500000

# 2. Export to ONNX (the training script prints the exact command to use)
uv run python -m essence_wars.agents.export_onnx \
  experiments/ppo/<your_run>/best_model.pt \
  ~/.essence-wars/agents/my_agent.onnx

# 3. Play against it in the CLI
cargo run --release --bin arena -- \
  --bot1 greedy --deck1 architect_fortify \
  --bot2 "neural:$HOME/.essence-wars/agents/my_agent.onnx" --deck2 archon_burst \
  --games 100
```

Exported `.onnx` agents in `~/.essence-wars/agents/` are also automatically available in the desktop app's bot selection menu. See the [Python README](python/README.md#train-export-and-play-full-workflow) for the full guide.

### Play via Claude Code (MCP)

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "essence-wars": {
      "command": "./target/release/essence-wars-mcp"
    }
  }
}
```

Then in Claude Code: *"Start a game with the Iron Wall deck against Swarm Aggro"*

## Project Structure

```
essence-wars/
├── crates/
│   ├── cardgame/           # Core game engine (Rust)
│   ├── essence-wars-ui/    # Desktop app (Tauri + Svelte)
│   └── essence-wars-mcp/   # MCP server for Claude Code
├── python/                 # ML agents & training (PyTorch)
├── data/
│   ├── cards/              # Card definitions (YAML)
│   ├── decks/              # Deck definitions (TOML)
│   └── weights/            # Bot weight files
└── docs/                   # Documentation
```

| Component | Description | README |
|-----------|-------------|--------|
| **cardgame** | High-performance game engine, bots, CLI tools | [README](crates/cardgame/README.md) |
| **essence-wars-ui** | Cross-platform desktop client | [README](crates/essence-wars-ui/README.md) |
| **essence-wars-mcp** | MCP server for Claude Code | [README](crates/essence-wars-mcp/README.md) |
| **python** | ML agents, training, benchmarking | [README](python/README.md) |

## Three Factions

| Faction | Identity | Keywords |
|---------|----------|----------|
| **Argentum Combine** | Defense & durability | Guard, Shield, Fortify, Piercing |
| **Symbiote Circles** | Aggressive tempo | Rush, Lethal, Regenerate, Volatile |
| **Obsidion Syndicate** | Burst damage | Lifesteal, Stealth, Quick, Charge |

Plus **Neutral** cards and **12 unique Commanders** with passive abilities.

## Documentation

### Game Design
- [Game Rules](docs/game-design/rules.md) — Complete rules, keywords, card types
- [Lore & World](docs/game-design/lore.md) — Faction history and characters

### ML & AI
- [Quickstart Notebook](python/notebooks/01_quickstart.ipynb) — Game API, environments, built-in bots
- [PPO Training Notebook](python/notebooks/02_training_ppo.ipynb) — Train a neural network agent
- [Evaluation Notebook](python/notebooks/03_evaluation.ipynb) — Benchmark agents against baselines
- [Python Package](python/README.md) — Full ML infrastructure documentation

### Development
- [Architecture](docs/development/architecture.md) — System design overview

## Performance

| Metric | Value |
|--------|-------|
| Random games | ~23,700/sec |
| Greedy bot games | ~1,500/sec |
| MCTS (100 sims) | ~18.6 ms/move |
| MCTS parallel (8 trees) | ~9.3 ms/move |
| Alpha-Beta depth 6 | ~1.4 ms/move |
| Engine state clone | ~404 ns |
| State tensor encode | ~157 ns |
| Greedy evaluate | ~5.6 ns |
| Zobrist hash | ~6.8 ns |
| Apply action (attack) | ~190 ns |

Run `cargo bench -p cardgame` for the full suite.

## Commands

```bash
# Build & Test
cargo build --release                    # Full workspace
cargo nextest run --status-level=fail    # Rust tests
uv run pytest python/tests               # Python tests

# Lint
cargo clippy                             # Rust lint
uv run mypy python/essence_wars          # Python types
pnpm run check                           # Svelte/TS (in UI crate)

# Game Tools
cargo run --release --bin arena --       # Bot matches
cargo run --release --bin validate --    # Quick balance check
cargo run --release --bin benchmark --   # Thorough analysis
cargo run --release --bin swiss --       # Tournament mode
```

## Contributing

Contributions are welcome! This project uses:

- **Rust** for the core engine and desktop backend
- **Svelte 5** (with runes) for the desktop frontend
- **Python** for ML agents and training

Each crate has its own `CLAUDE.md` with AI-developer context and `README.md` with human contributor documentation.

### Development Setup

```bash
# Rust
cargo build --release

# Python (using uv)
uv sync --all-groups
uv run pytest python/tests

# UI (using pnpm)
cd crates/essence-wars-ui
pnpm install
pnpm tauri:dev
```

## Citation

If you use Essence Wars in your research, please cite:

```bibtex
@software{essence_wars,
  title = {Essence Wars: A High-Performance Card Game Environment for RL Research},
  author = {Wissmann, Christian},
  year = {2025},
  url = {https://github.com/christianWissmann85/essence-wars}
}
```

## License

MIT License — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <strong>Built with Rust, Svelte, and PyTorch</strong><br>
  <em>Designed for humans and AIs alike</em>
</p>
