AI Royale

Autonomous Clash Royale gameplay agent with real-time vision, strategic LLM planning, and tap-level execution.

Overview

The agent continuously watches a live BlueStacks session, detects battlefield units and cards in hand, reads OCR signals for elixir and tower HP, then decides when to play and where to place cards.

Perception runs at high frame rate while strategic inference is event-gated, so decisions stay timely without overcalling the model.

Perception loop runs continuously; Claude is called only on meaningful decision windows to keep latency and cost low.

How It Works

BlueStacks (Clash Royale)
    ↓ screen capture @ ~60fps (mss)
YOLOv8  -> battlefield units, positions, HP
YOLOv8n -> cards in hand
OCR     -> elixir bar, tower HP
    ↓ structured game state (JSON)
Claude API -> strategic decision every 2-3s
    ↓ {"card":"hog_rider","x":540,"y":800}
ADB input_tap
    ↓
BlueStacks executes tap

Architecture

clash-royale-agent/
├── perception/
│   ├── screen_capture.py
│   ├── unit_detector.py
│   ├── card_detector.py
│   └── ocr_reader.py
├── agent/
│   ├── claude_planner.py
│   ├── opponent_memory.py
│   └── decision_trigger.py
├── execution/
│   ├── adb_controller.py
│   └── card_placer.py
├── data/
│   ├── card_stats.json
│   └── arena_map.py
├── logs/
├── models/
├── requirements.txt
└── .env.example

Datasets

AngelFire's Clash Royale Dataset

148 classes for ally + enemy versions of core units (archer, hog rider, giant, balloon, and more).

Open dataset

Vision Bot Card Detection

Card-in-hand classification from spectator and player viewpoints.

Open dataset

Setup

Prerequisites

Python 3.11+
BlueStacks 5 with Clash Royale installed
ADB enabled in BlueStacks settings
Anthropic API key

Installation

git clone https://github.com/yourusername/clash-royale-agent
cd clash-royale-agent

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt

Environment

cp .env.example .env
ANTHROPIC_API_KEY=your_key_here

Connect Services

adb connect 127.0.0.1:5555
adb devices  # should show emulator-5554

Model Setup

python scripts/download_models.py
# Downloads AngelFire + Vision Bot weights from Roboflow

Run Services

python main.py

Decision Engine

Claude is invoked every 2-3 seconds or when a trigger fires (new opponent play, elixir threshold, bridge crossing, tower pressure).

State Snapshot (Input)

{
  "elixir": 7,
  "my_towers": { "left": 2400, "right": 2400, "king": 4000 },
  "opp_towers": { "left": 1800, "right": 2400, "king": 4000 },
  "battlefield_units": [
    { "type": "hog_rider", "team": "opponent", "x": 9, "y": 14, "hp": 1200 }
  ],
  "my_hand": ["knight", "fireball", "musketeer", "arrows"],
  "opponent_seen_cards": ["hog_rider", "fireball", "ice_spirit"],
  "time_remaining": 87
}

Structured Action (Output)

{
  "action": "play_card",
  "card": "knight",
  "x": 9,
  "y": 15,
  "reasoning": "Opponent hog rider approaching right tower. Knight at 9,15 intercepts cleanly with elixir advantage."
}

Investigation decisions and outputs are logged to keep system behavior inspectable and explainable.

Decision Triggers

Elixir crosses a threshold (>= 6 by default)
Opponent plays a card
A unit crosses the bridge
Tower HP drops below 50%
Time remaining enters double elixir (60s)

Opponent Modeling

Cards seen so far plus estimated cycle position
Aggression score (push frequency and elixir spent per minute)
Preferred lane (left/right bias)
Win/loss history persisted in SQLite

Metrics

Win rate vs random baseline

60%+

Decision latency (Claude round-trip)

<2s

YOLO unit detection accuracy

>85% mAP

Tool call success rate

>95%

API calls per match

~15-25

Disclaimer

Built for educational and portfolio purposes. Automated play on official Clash Royale servers violates Supercell Terms of Service and can lead to account bans. Use a secondary test account or private matches.