pvpAI

AI Combat Arena — Train AI agents with natural language and battle in ranked PvP matches.

---

Overview

pvpAI is a competitive turn-based combat game where you create, train, and battle AI-controlled agents. Write training rules in plain English—our compiler converts them into combat behavior. Watch your agents execute strategies in real-time battles and climb the global leaderboard.

Key Features

• 🤖 Natural Language Training — Define agent behavior with simple rules like "When enemy HP is below 30%, prioritize aggressive attacks"
• ⚔️ Real-Time Combat — Watch agents execute strategies against opponents in live battles
• 🏆 Ranked Ladder — Elo-based matchmaking with seasonal rewards
• 📊 Battle Replays — Review past matches to analyze decisions and improve strategies
• 🥋 Training Dojo — Practice against AI opponents before ranked play
• ⚖️ Fair Competition — All agents use the same house model; victory comes from strategy, not compute

---

Getting Started

Prerequisites

• Bun v1.2.0+
• Convex account (for backend)

Installation

# Clone the repository
git clone https://github.com/Dexploarer/pvpAI.git
cd pvpAI

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env.local
# Add your Convex URL and other required env vars

# Start Convex development server (in a separate terminal)
bun run convex:dev

# Start the development server
bun run dev

The app will be available at http://localhost:3000.

---

Project Structure

pvpAI/
├── apps/
│   └── web/                 # Next.js 16 frontend (React 19, Tailwind 4)
├── packages/
│   ├── shared/              # Combat engine, training compiler, types
│   └── backend/             # Convex functions and database schema
├── turbo.json               # Turborepo configuration
└── package.json             # Workspace root

---

Scripts

Command	Description
bun run dev	Start all workspaces in development mode
bun run build	Build all packages for production
bun run typecheck	Run TypeScript type checking
bun run convex:dev	Start Convex development server
bun run convex:deploy	Deploy Convex to production

---

Core Systems

Combat Engine

Deterministic turn-based combat with phases:

1. Movement — Positioning and distance management
2. Setup — Buffs, stances, and preparations
3. Attack — Initiative-ordered strike resolution
4. Effects — Status effects and regeneration

Training Compiler

Converts natural language training rules into executable agent behavior:

• IF/THEN rules for conditional actions
• AVOID rules to prevent unwanted behaviors
• PRIORITY rules for action weighting
• Built-in safety checks against prompt injection

Match System

• Real-time match orchestration via Convex
• Integrity system penalizes invalid actions
• Full combat logging for replay analysis

---

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, Tailwind CSS 4
Backend	Convex (serverless functions + database)
Build	Turborepo, Bun
AI	AI SDK, OpenAI Gateway
Auth	Privy

---

Contributing

Contributions are welcome! Please read the contribution guidelines before submitting a pull request.

---

License

This project is private and proprietary.

---

Links

• Live App: pvpai.fun
• Documentation: /docs

---

_{Built with ❤️ by the pvpAI team}