FirstLight CR
From replays to agents. From self-play to the arena.
Train Clash Royale agents and play offline, with imitation learning and PPO self-play.
English · 简体中文
Installation · Training · Training history · Models · Architecture · Policy API
Video: the model's Hall of Fame push and a walkthrough of the AI architecture
Pretrained models
General is a strong model across decks. The author used the Hog 2.6 specialist to reach Hall of Fame.
The training history covers how the models were trained and evaluated.
Choose General for different decks or a Hog 2.6 specialist for Hog Cycle. Both are included in the repository. See the model guide for checkpoint details and evaluation.
Features
- Native battle environment. Headless and rendered execution, structured observations, card deployment and abilities, with Python
reset/stepinterfaces. - Imitation learning. Reconstruct Parquet replays in the engine and build observation/action sequences for IL training.
- Self-play reinforcement learning. PPO with matchmaking, opponent pools, resident simulation, and distributed collection.
- Models and inputs. The V4 actor-critic uses card features, entity relations, spatial features, and recurrent memory. Training, evaluation, and local inference use the same model and input format.
- Match and replay interface. Play against a model, control both sides manually, or watch training and collected replays in one offline VM.
- Source code. The probe, APK build tools, battle environment, and training code are included.
122 supported cards · 5 included checkpoints · 252,238 replays · 17,836,160 actions
See compatibility data for the cards and forms supported by each version. Download the replay dataset from Hugging Face.
Training flow
flowchart LR
R[Replay dataset] --> C[Native reconstruction]
C --> D[Observation / action sequences]
D --> IL[Imitation learning]
IL --> P[Recurrent policy]
P --> S[Self-play + matchmaking]
S --> PPO[PPO]
PPO --> P
P --> E[Match evaluation]
P --> H[Play against the agent]
P --> API[Local policy service]
See the architecture guide for source entry points and data formats.
Quick start
For a fresh machine or coding-agent setup, follow the installation guide. The steps below are a summary.
Desktop: Windows, Python 3.12 with Tkinter, and an Android 12 instance of regular MuMu Player with root and ARM64 application support. CPU inference is supported. Building the offline APK from source requires JDK 17, Android NDK, and SDK build-tools; running an already built APK does not.
Run from the repository root:
python -m venv .venv .\.venv\Scripts\python.exe -m pip install -r requirements.txt Copy-Item .env.example .env
Fill the Python, VM, and build-tool settings in .env using the installation guide. The supported engine is Null’s Royale 15.535.13 / arm64-v8a with content update 15.535.86.
First, install and open the unmodified original APK in the selected MuMu instance. Let it update naturally until you can enter the normal game lobby, then exit. Keep the original APK as user-provided/nulls-royale.apk. Check the original APK and downloaded resources before building or injecting the probe:
./check_original_game.ps1 -InputApk ./user-provided/nulls-royale.apk ./build_offline_engine.ps1 ` -InputApk ./user-provided/nulls-royale.apk ` -OutputApk ./build/cr-ai-offline.apk ./install_offline_engine.ps1 -Apk ./build/cr-ai-offline.apk
To open the interface after installation, run Firstlight_CR\launch_interface.cmd from its parent folder, or run ./launch_interface.cmd from the repository root.
Train and evaluate
Start with IL_Replay for imitation learning, or generate a small workflow example with python tools/make_demo_data.py. The training guide covers cache generation, IL, engine clusters, Linux AVD preparation, and distributed PPO.
To compare two included checkpoints, stop any console task and run:
./native_runner/start_offline.ps1 .\.venv\Scripts\python.exe -m native_runner.training.v4.evaluate ` --checkpoint-a ./checkpoints/General/checkpoint-step-00000460.pt ` --checkpoint-b ./checkpoints/IL/checkpoint-step-00029396.pt ` --games 2 --output ./evaluations/comparison
Use --games for the match count, --match-config for decks and levels, and --seed for the starting seed. See model evaluation for results and metrics. To integrate your own actor loop, use the JSON-lines policy service.
Documentation
| Guide | Contents |
|---|---|
| Getting started | Requirements, .env, original game update, and offline installation |
| Training history | Five main models, experiments, results, and playstyle tradeoffs |
| Training | Replay cache, IL, batch simulation, Linux guests, and PPO |
| Architecture | Environment, policy, training, and replay source map |
| Models | Model selection, loading, and evaluation metrics |
| Policy service | Recurrent episode lifecycle and request protocol |
| Compatibility data | Card support, model catalogs, and version maintenance |
| Checks | Environment checks, tests, and runtime result checks |
License
FirstLight CR is an independent offline project under Apache-2.0, unaffiliated with Supercell. The repository does not distribute the game APK or its resources; users supply the supported APK locally. See NOTICE.