Upload RESEARCH_SUMMARY.md with huggingface_hub

RESEARCH_SUMMARY.md

@@ -0,0 +1,74 @@
+# 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.