Hugging Face's logo

stevenkhan
/
clashcr

ml-intern
Model card Files
xet
 Community
clashcr / RESEARCH_SUMMARY.md
stevenkhan's picture
stevenkhan
Upload RESEARCH_SUMMARY.md with huggingface_hub
1468136 verified
preview code
|
raw
history blame contribute delete
4.66 kB

ClashCR Research Summary

Evaluated Projects and APIs

KataCR (wty-yy)

  • Paper: arXiv:2504.04783 (April 2025)
  • Code: https://github.com/wty-yy/katacr
  • Dataset: https://github.com/wty-yy/Clash-Royale-Detection-Dataset
  • What it does: Full non-embedded AI agent playing Clash Royale via screen capture.
  • Visual mode: Live gameplay (mobile screen streamed via scrcpy/V4L2).
  • Architecture:
    • YOLOv8-l x2 combo detector for arena units (150 classes, AP50=84.3%).
    • ResNet classifier for own hand cards (Part 3 crop).
    • PaddleOCR for time/elixir text.
    • StARformer-3L RL policy.
  • Critical finding: KataCR detects opponent unit spawns in the arena via YOLO. It does NOT track opponent hand cards. It uses RL state builder to fuse unit positions/health/classes into game state.
  • Credibility: ★★★★★ — Published paper, open dataset, reproducible training code.
  • Pitfall for opponent tracking: Only tracks own hand cards via crop + classifier. Opponent cards must be inferred from arena detections.
  • Dataset staleness: Last updated May 2024 (Season 59). Missing 2025-2026 cards.

CR Vision (bytkim)

  • Repo: https://github.com/bytkim/cr_vision (active, last commit Feb 2026)
  • What it does: Real-time opponent elixir + card cycle tracker.
  • Visual mode: Live gameplay (BlueStacks emulator on macOS).
  • Architecture:
    • YOLOv8 troop detection on screen capture (mss).
    • Grid-based multi-frame confirmation (TROOP_TRACKER: 3 frames @ 0.6 conf).
    • Wall-clock elixir regeneration model (1 elixir / 2.8s, doubles at 2:00, triples at 3:00+).
    • Card cycle inference from detected troop names mapped to costs.
  • Credibility: ★★★★☆ — Clean architecture, actively maintained, directly addresses opponent tracking.
  • Pitfall: Spells are transient and hard to detect. Missing evolution/hero support in current cost table. ~60 cards covered.

HuggingFace TV Royale Dataset (chrisrca)

  • URL: https://huggingface.co/datasets/chrisrca/clash-royale-tv-replays
  • Schema: card (string), png_bytes (binary), x/y (int16), arena (string), replay (string), frame (int16).
  • Critical finding: TV Royale replay dataset, not live gameplay. x=-1, y=-1 means card is in hand/not deployed. Usable for unit detection validation, not opponent hand tracking.
  • Credibility: ★★★☆☆ — Large dataset (23 GB), but wrong visual mode for our task.

RoyaleAPI cr-api-data

  • URL: https://royaleapi.github.io/cr-api-data/json/cards.json
  • Total cards: 120 (as of dataset snapshot).
  • Types: Troop (87), Building (14), Spell (19).
  • Rarities: Common, Rare, Epic, Legendary, Champion (6 champions).
  • Evolution support: 8 evolution cards (Knight, Barbarians, Skeletons, Royal Giant, Royal Recruits, Bats, Firecracker, Mortar).
  • Missing cards: Vines, Spirit Empress, Rune Giant, Berserker, Boss Bandit, Goblinstein, Royal Chef, and all Hero cards (Hero Knight, Hero Musketeer, Hero Giant, etc.).
  • Credibility: ★★★☆☆ — Reliable static data source, but visibly stale for 2025-2026.

Official Clash Royale API

  • URL: https://developer.clashroyale.com/
  • Endpoint: /v1/cards
  • Python client: clashroyale package
  • Credibility: ★★★★★ — Official source of truth. Requires API token.

Gaps for 2026 Cards/Heroes/Evolutions

Category KataCR (May 2024) CR Vision Needed
Total cards ~125 ~60 120+
Evolutions 17 evolution units None All 20+
Heroes 6 heroes (missing royal-guardian) None All 7+
New 2025-2026 dagger-duchess missing None Need updates
Spells Some (zap, fireball effects) None All spell visuals
Buildings Yes Some All

Final Verdict

No existing open-source project provides a complete, working opponent card tracker for live Clash Royale gameplay. The closest is CR Vision, which implements the correct architecture (spawn detection + elixir tracking + cycle inference) but lacks evolution/hero support and has limited spell detection. KataCR is the most credible academic foundation but focuses on self-play AI, not opponent tracking.

To build a working 2026 opponent tracker:

  1. Fork CR Vision's architecture (spawn detection + cycle logic).
  2. Retrain YOLO detector with KataCR dataset + new card slices.
  3. Update unit-to-card mappings for all evolutions and heroes.
  4. Add spell effect detection (or accept that spells will be missed without more data).
  5. Use official Clash Royale API to maintain current card list and elixir costs.