essence-wars 0.12.0

High-performance card game environment

A deterministic strategy card game engine

Try in Colab • Quick Start • Features • Project Structure • Documentation • Contributing

---

Try it in Google Colab

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

Notebook	Description
	Quickstart — Explore the game engine, play games, see the API
	Train a PPO Agent — Build and train a neural network to play
	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.

Features

Desktop Application

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

Test Lab 🧪

Built-in QA test harness for verifying game mechanics. Each scenario pre-loads the right deck, bot, and seed — one click to reproduce any mechanic interaction.

Scenarios are grouped by mechanic (Ambush, Flanking, Level-Up, Overload, Prepare, Ritual) with both Player-side and Opponent-side variants, so you can verify a mechanic from either perspective. Adding a new scenario is a single .toml file drop — no recompile needed.

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

# 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. For local development:

# 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 for the full guide.

Play via Claude Code (MCP)

Add to your .mcp.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
essence-wars-ui	Cross-platform desktop client	README
essence-wars-mcp	MCP server for Claude Code	README
python	ML agents, training, benchmarking	README

Architecture

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.

---

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 — Complete rules, keywords, card types
• Lore & World — Faction history and characters

ML & AI

• Quickstart Notebook — Game API, environments, built-in bots
• PPO Training Notebook — Train a neural network agent
• Evaluation Notebook — Benchmark agents against baselines
• Python Package — Full ML infrastructure documentation

Development

• Architecture — System design overview

Performance

Metric	Value
Random games	~17,000/sec
Greedy bot games	~1,200/sec
MCTS (100 sims)	~27 ms/move
MCTS parallel (8 trees)	~13 ms/move
Alpha-Beta depth 6	~1.05 ms/move
Engine state clone	~417 ns
State tensor encode	~168 ns
Greedy evaluate	~9.0 ns
Zobrist hash	~11.1 ns
Apply action (attack)	~188 ns
MCTS parallel speedup (8×)	~4.3× (54% efficiency)

Hardware: AMD Ryzen AI 7-350, 32 GB RAM, WSL2 (Ubuntu on Windows 11). Timing figures are hardware-dependent — run cargo bench -p cardgame to measure on your machine. The parallel speedup ratio (4.3×) and balance win-rate metrics are hardware-independent.

Commands

# 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

# 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:

@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 for details.

---

Built with Rust, Svelte, and PyTorch
Designed for humans and AIs alike