RESEARCH_SUMMARY.md

# 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.