Essence Wars

A deterministic, perfect-information strategy card game designed for AI research

Quick Start • Features • Project Structure • Documentation • Contributing

What is Essence Wars?

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

• Perfect Information — Both players see all cards, including hands and decks. Victory comes from outthinking your opponent, not luck.
• Deterministic Execution — Seeded RNG ensures every game is reproducible, perfect for AI training and analysis.
• Lane-Based Combat — Creatures occupy board positions, creating spatial strategy alongside card selection.
• ML-Ready Design — 328-float state tensors, 256 discrete actions, and high-performance Rust engine (~33k games/sec).

Features

Desktop Application

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

AI & Machine Learning

• Multiple Bot Types — Random, Greedy (28 tunable weights), MCTS, Alpha-Beta search
• Python ML Framework — Gymnasium/PettingZoo environments, PPO, AlphaZero, Card2Vec
• Training Infrastructure — Callbacks, experiment tracking, Elo ratings, HTML reports

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

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 ML Agents (Python)

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

# Train a PPO agent
essence-wars train ppo --timesteps 500000

# Benchmark against baselines
essence-wars benchmark --checkpoint model.pt

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

Three Factions

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

Art & Assets

• Style Guide — Visual design guidelines
• Asset Generation — AI-assisted art pipeline

ML & AI

• Bot System — Bot architecture, weight tuning
• Training Pipeline — PPO, AlphaZero, behavioral cloning
• Ratings System — Elo tracking for decks and agents

Development

• CLI Reference — Command-line tools
• Reporting — Analysis and visualization

Performance

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 lint                               # Rust (clippy)
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