Metadata-Version: 2.4
Name: essence-wars
Version: 0.11.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Dist: numpy>=1.24.0
Requires-Dist: gymnasium>=0.29.0
Requires-Dist: essence-wars[train,analysis,pettingzoo,artgen] ; extra == 'all'
Requires-Dist: pandas>=2.2.0 ; extra == 'analysis'
Requires-Dist: matplotlib>=3.8.0 ; extra == 'analysis'
Requires-Dist: seaborn>=0.13.0 ; extra == 'analysis'
Requires-Dist: plotly>=5.18.0 ; extra == 'analysis'
Requires-Dist: jinja2>=3.1.0 ; extra == 'analysis'
Requires-Dist: rich>=13.7.0 ; extra == 'analysis'
Requires-Dist: pyyaml>=6.0.0 ; extra == 'analysis'
Requires-Dist: google-genai>=1.0.0 ; extra == 'artgen'
Requires-Dist: fal-client>=0.5.0 ; extra == 'artgen'
Requires-Dist: pillow>=10.0.0 ; extra == 'artgen'
Requires-Dist: elevenlabs>=1.0.0 ; extra == 'artgen'
Requires-Dist: pydub>=0.25.0 ; extra == 'artgen'
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
Requires-Dist: pettingzoo>=1.25.0 ; extra == 'pettingzoo'
Requires-Dist: torch>=2.9.1 ; extra == 'train'
Requires-Dist: onnxscript>=0.2.0 ; extra == 'train'
Requires-Dist: tensorboard>=2.14.0 ; extra == 'train'
Requires-Dist: wandb>=0.16.0 ; extra == 'train'
Requires-Dist: tqdm>=4.66.0 ; extra == 'train'
Provides-Extra: all
Provides-Extra: analysis
Provides-Extra: artgen
Provides-Extra: dev
Provides-Extra: pettingzoo
Provides-Extra: train
License-File: LICENSE
Summary: High-performance card game environment
Keywords: reinforcement-learning,game,gymnasium,ai,mcts,card-game,pettingzoo
Author: Christian Wissmann
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://christianWissmann85.github.io/essence-wars/
Project-URL: Homepage, https://github.com/christianWissmann85/essence-wars
Project-URL: Issues, https://github.com/christianWissmann85/essence-wars/issues
Project-URL: Repository, https://github.com/christianWissmann85/essence-wars

<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) |

## Architecture

<p align="center">
  <img src="docs/screenshots/architecture-visualization.webp" alt="Architecture Diagram" width="85%">
</p>

Essence Wars is organized as a layered Rust monorepo with Python ML bindings on top. From bottom to top:

- **Data Layer** — Card definitions (YAML), deck compositions (TOML), and bot weight files live under `data/`.
- **Foundation Layer** — Core types (`CardId`, `PlayerId`, `Slot`), keyword rules (Rush, Guard, Lethal, …), card database, and static config.
- **Core Game Engine** — `GameEngine` facade exposes `apply_action`, `get_legal_actions`, and `is_terminal`. State mutations flow through a non-recursive effect queue for deterministic trigger ordering.
- **Client API Layer** — `GameClient` wraps the engine with event emission (creature spawned/damaged/killed), state diffing for efficient UI updates, and action history for replays.
- **User Interfaces** — Three independent consumers of the same engine: the Tauri/Svelte 5 desktop app, the MCP server (JSON-RPC for Claude Code), and the Python ML bindings (PyO3/FFI for Gymnasium & PyTorch).

For the full design walkthrough see [docs/development/architecture.md](docs/development/architecture.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>

