A computer vision and statistical modeling pipeline that analyzes Clash Royale match replays to evaluate decision-making, calculate expected value (EV) of card plays, and detect suboptimal moves.
- Python 3.11+
- uv (Python package manager)
- System dependencies:
ffmpeg,tesseract, and OpenCV native libs (see setup options below)
If you have Nix with flakes enabled (experimental-features = nix-command flakes in ~/.config/nix/nix.conf):
git clone <repo-url>
cd Clash-Royale-Pod
nix develop # first enter takes a few minutes — system deps + uv sync
uv run crpod --helpIf you use direnv, direnv allow once and the shell auto-activates on cd.
The flake provides: Python 3.11, uv, ffmpeg, tesseract, ruff, plus the native libraries OpenCV/PyTorch need. Python packages (torch, ultralytics, lightgbm, …) are installed into .venv by uv sync.
ultralytics transitively pulls in opencv-python (the full GUI build), which dlopens libxcb.so.1 at import time. NixOS doesn't expose system libs on a standard search path, so the import crashes unless those libs are reachable via nix-ld. Add the following to your system config (the host module that sets programs.nix-ld.enable):
programs.nix-ld = {
enable = true;
libraries = with pkgs; [
zlib
xorg.libxcb
xorg.libX11
xorg.libXext
xorg.libSM
xorg.libICE
libGL
glib
stdenv.cc.cc.lib # libstdc++.so.6
];
};Then sudo nixos-rebuild switch and open a new shell. Your shell must export LD_LIBRARY_PATH=$NIX_LD_LIBRARY_PATH for pip-installed wheels to find these libs. Mac and Windows users don't need any of this — those platforms ship the libs by default.
Install the system dependencies for your platform, then uv sync:
macOS (Homebrew):
brew install python@3.11 uv ffmpeg tesseractUbuntu / Debian:
sudo apt update
sudo apt install python3.11 ffmpeg tesseract-ocr libgl1 libglib2.0-0
# Install uv: https://docs.astral.sh/uv/getting-started/installation/
curl -LsSf https://astral.sh/uv/install.sh | shThen clone and sync:
git clone <repo-url>
cd Clash-Royale-Pod
uv sync
uv run crpod --helpuv run python -c "import torch, cv2, ultralytics, lightgbm, pytesseract; print('ready')"
uv run pytestThe HF TV-replay dataset (chrisrca/clash-royale-tv-replays) ships raw frame images, not pre-extracted card placements. YOLO detection is required to extract card placements from the frames. You'll need trained YOLO weights (default path: output/models/crpod_v1_best.pt, see Sub-Teams — the Data & Detection team owns this).
# List available replays (no weights needed)
uv run crpod list-replays --arena arena_15
# Analyze one HF replay (no EV model → no blunders.json)
uv run crpod analyze arena_15 <replay_id> --weights output/models/crpod_v1_best.pt
# Analyze with an EV model → also writes blunders.json + report.html
uv run crpod analyze arena_15 <replay_id> \
--weights output/models/crpod_v1_best.pt \
--model output/models/ev_wave2j_prime.joblib
# Analyze a local match video (your own screen recording)
uv run crpod analyze-video data/my-match.mp4 \
--weights output/models/crpod_v1_best.pt \
--model output/models/ev_wave2j_prime.joblib
# Train a fresh EV model
uv run crpod train \
--weights output/models/crpod_v1_best.pt \
--out output/models/ev_wave2j_prime.joblib \
--max-replays 50Each analyze run writes to output/analysis/<replay_id>/ (or
output/analysis/<video_stem>/ for analyze-video):
| File | When written | Contents |
|---|---|---|
summary.json |
always | replay id, arena, n_plays, n_interactions, friendly/enemy leak, n_blunders |
placements.png |
always | 2D heatmap of where you placed troops |
tempo.png |
always | running (friendly − enemy) elixir-spent over time |
blunders.json |
only with --model |
top blunders, ordered worst-first: {play_idx, card, ev_predicted, per_card_median, sigma_below} |
report.html |
always | self-contained one-page report — open in Chrome / Safari, no network |
report.html bundles the summary fields, top-5 blunders, and both PNGs
as base64-embedded images. No external dependencies, no JS, no
build step — just open the file.
A play is a blunder when the EV model's predicted outcome for that card sits more than 1σ below the per-card median from the training fold. Per-card medians are persisted inside the EV model artifact, so inference doesn't need training data on hand. Cards with fewer than 5 training samples are excluded from blunder calls (signal too noisy).
Clash-Royale-Pod/
├── flake.nix # Nix dev environment (replaces devcontainer)
├── .envrc # direnv entrypoint (use flake)
├── src/crpod/ # Pipeline package
│ ├── dataset/ # HF replay loader + raw video iterator
│ ├── detection/ # YOLO wrapper (custom-replay path)
│ ├── tracking/ # ByteTrack wrapper (custom-replay path)
│ ├── ocr/ # Tesseract HUD reader
│ ├── features/ # Elixir ledger, interactions, placement zones
│ ├── modeling/ # LightGBM EV model
│ ├── visualization/ # Heatmaps, tempo plots, EV breakdowns
│ ├── pipeline.py # End-to-end orchestrator
│ └── __main__.py # `crpod` CLI
├── tests/ # pytest — pure-logic feature tests
├── output/ # Pipeline artifacts (gitignored)
├── Makefile # Dev shortcuts (sync, lint, format, test)
├── pyproject.toml # Python dependencies (uv)
└── uv.lock # Locked dependency versions
├── pod_summary.md # Project proposal
└── workflow.md # Team workflow and collaboration guide
| Command | What it does |
|---|---|
uv sync |
Install/sync all dependencies from lockfile |
uv add <package> |
Add a new dependency |
uv run python script.py |
Run a script in the project environment |
make lint |
Run ruff linter |
make format |
Auto-format code with ruff |
make type-check |
Run mypy type checker |
make test |
Run pytest suite |
GitHub Actions runs ruff check, ruff format --check, mypy src, and pytest on every PR to main inside nix develop, so CI uses the same toolchain as the local flake. Run make lint format type-check test before pushing to catch failures early.
We use the Shared Repo + Pull Request workflow. Everyone works on the same repo — no forks. No one pushes directly to main — all changes go through PRs that are reviewed and merged by the maintainer (@max).
- Get added as a collaborator — ask @max to add you to the repo on GitHub (Settings → Collaborators).
- Clone the repo:
git clone https://github.com/<repo-owner>/Clash-Royale-Pod.git cd Clash-Royale-Pod
- Set up the environment using either Option A (Nix) or Option B (uv only) above.
That's it. No forks, no upstream remotes. Everyone pushes to the same repo.
If you previously forked the repo, you can switch to the shared model. Delete your fork on GitHub, then update your local clone to point at the main repo:
# Check your current remote
git remote -v
# If origin points to your fork, update it to the main repo
git remote set-url origin https://github.com/<repo-owner>/Clash-Royale-Pod.git
# Verify
git remote -v- Pull the latest main before starting new work:
git checkout main git pull
- Create a branch for your specific task:
git checkout -b data/add-annotation-script
- Do your work and commit with descriptive messages:
git add <files> git commit -m "data: add annotation script for tower labels"
- Push your branch:
git push -u origin data/add-annotation-script
- Open a Pull Request on GitHub from your branch to
main. - Review & merge — automated checks run, the maintainer reviews the code, and once approved it gets merged.
When two or more people in the same subgroup need to work on the same feature, use a shared feature branch with sub-branches:
-
Person A creates the shared feature branch:
git checkout main git pull git checkout -b tracking/bytetrack git push -u origin tracking/bytetrack
-
Person B pulls the shared branch:
git fetch git checkout tracking/bytetrack
-
Each person creates a sub-branch off the shared branch:
# Person A git checkout tracking/bytetrack git checkout -b tracking/bytetrack-detection # Person B git checkout tracking/bytetrack git checkout -b tracking/bytetrack-scoring
-
Each person pushes their sub-branch and PRs into the shared branch (not
main):# Person A git checkout tracking/bytetrack-detection git push -u origin tracking/bytetrack-detectionThen on GitHub: open a PR and change the base branch from
maintotracking/bytetrack(click the base dropdown).Person B does the same:
git checkout tracking/bytetrack-scoring git push -u origin tracking/bytetrack-scoring
Same thing on GitHub: PR into
tracking/bytetrack. -
After both sub-PRs are reviewed and merged, PR the shared branch into
main:git checkout tracking/bytetrack git pull
Then on GitHub: open a PR from
tracking/bytetrack→main. -
Clean up after the PR is merged:
git checkout main git pull git branch -d tracking/bytetrack git branch -d tracking/bytetrack-detection git branch -d tracking/bytetrack-scoring
GitHub will also show a "Delete branch" button on each merged PR to clean up the remote branches.
When the maintainer reviews your PR and requests changes, you don't need to open a new PR. Just push more commits to the same branch — the PR updates automatically:
# You're still on your branch
git checkout data/add-annotation-script
# Make the requested fixes
git add <files>
git commit -m "data: fix edge case in annotation parser"
# Push to the same branch — the PR updates automatically
git pushUse a prefix matching your sub-team:
data/*— Data & Detectiontracking/*— Tracking & Feature Engineeringmodeling/*— Modeling & Visualizationdocs/*— Documentation
A branch should be created for a specific task, worked on for a few days, PR'd, merged, and then deleted. Don't let branches sit for weeks — the longer a branch lives, the more main changes underneath it, and the more likely you are to hit merge conflicts. Finish the task, open the PR, get it merged, move on.
Conflicts happen when two people edit the same lines in the same file. If your PR shows a conflict:
# Update your local main
git checkout main
git pull
# Merge main into your branch
git checkout data/my-branch
git merge mainGit will mark conflicts in the file. Open it, pick the correct version, remove the <<<<<<< / ======= / >>>>>>> markers, then:
git add <conflicted-file>
git commit -m "data: resolve merge conflict"
git pushTo minimize conflicts: pull often, keep branches short-lived, and try to split work by file when possible (if you own annotate.py and your teammate owns train.py, you'll almost never conflict).
The main branch is protected. No one can push to it directly — all changes must go through a Pull Request and be approved by the maintainer.
Use GitHub Issues to report bugs, propose features, and organize tasks. Reference issues in your commits and PRs (e.g., fixes #12).
@max holds merge privileges and reviews all PRs. If your PR is ready for review, request a review from @max on GitHub.
Since we use uv + pyproject.toml, adding packages on feature branches merges cleanly:
- Add a package on your branch:
uv add <package>— this updatespyproject.tomlanduv.lock. - Include both files in your PR commit.
- On merge, Git auto-merges
pyproject.tomlas long as different people edited different lines. If there's a conflict inuv.lock, resolvepyproject.tomlfirst, then runuv lockto regenerate the lockfile.
After pulling the latest changes from main, check what files changed and follow the appropriate steps:
| What changed | What to do |
|---|---|
pyproject.toml / uv.lock (new Python packages) |
Run uv sync — no rebuild needed |
flake.nix / flake.lock (system tools or nixpkgs pin) |
Nix users: re-enter the shell (exit then nix develop). Non-Nix users: no action needed unless new system deps were added — check the commit message |
Makefile |
No action needed |
uv sync is always safe to run.
| Team | Owns |
|---|---|
| Data & Detection | Replay collection, annotation in Roboflow, YOLO training |
| Tracking & Feature Engineering | ByteTrack (via supervision), Tesseract OCR, event log construction |
| Modeling & Visualization | LightGBM, EV calculations, heatmaps, statistical analysis |
- pod_summary.md — Full project proposal, research question, algorithm design
- docs/ev-validation.md — Per-wave EV model holdout metrics (Spearman ρ trajectory)
- docs/latency-budget.md — Per-stage CPU latency baseline
- docs/known-issues.md — Carried limitations and deferred work
- Standalone HTML explainers (in
docs/artifacts/):- Project overview — pipeline architecture and research question
- How blunder detection works — the per-card median + σ threshold
- The post-game report — design notes — what's in
report.htmland why - Project final state — what shipped vs. what was deferred
| Tool | Purpose |
|---|---|
| Python 3.11 | Primary language |
| PyTorch + Ultralytics YOLO | Object detection (troops, spells, structures) |
| OpenCV + FFmpeg | Video/frame extraction and processing |
| supervision | Multi-object tracking (ByteTrack) |
| Tesseract | OCR for HUD reading (elixir, timers, tower HP) |
| LightGBM | EV modeling and outcome prediction |
| pandas / NumPy / SciPy | Data wrangling and statistical analysis |
| matplotlib / seaborn | Visualization |
| uv | Python package and environment management |
| Ruff | Linting and formatting |
| Claude Code / Gemini CLI / Codex CLI | AI coding assistants |