| --- |
| tags: |
| - ml-intern |
| --- |
| # ClashCR |
|
|
| Real-time Clash Royale opponent card tracker for emulator gameplay (MuMu Player, BlueStacks). |
|
|
| ## Key Principle |
| **Prefer "no detection / unknown" over a wrong card.** The tracker is only useful if it stops hallucinating. |
|
|
| ## Why the Old Approach Failed |
| The previous whole-frame card classifier was the wrong visual task. In normal live gameplay, opponent card art and names are **never visible**. The only visible signals are: |
| - Unit spawns on the arena |
| - Spell/effect animations |
| - Building placements |
|
|
| This rewrite detects **card-play events from spawn/effect evidence**, not by classifying random battlefield frames. |
|
|
| ## Architecture |
|
|
| ``` |
| Emulator Capture (Win32 API / mss) |
| | |
| v |
| Battle Gater (detect battle vs lobby, compute ROIs) |
| | |
| v |
| Event Detector (temporal differencing, suppress persistent motion) |
| | |
| v |
| Evidence Model (YOLO unit detector + heuristic spell detectors) |
| | |
| v |
| Card Resolver (unit->card mapping, multi-unit rules, ambiguity->UNKNOWN) |
| | |
| v |
| Elixir Tracker + Deck Tracker |
| ``` |
|
|
| ## Setup |
|
|
| ```bash |
| pip install -e . |
| clashcr sync-cards --config config.yaml |
| ``` |
|
|
| If you have an Official Clash Royale API token, add it to `config.yaml` under `clash_royale_api_token`. |
|
|
| ## CLI Commands |
|
|
| ```bash |
| # Sync card registry from APIs |
| clashcr sync-cards --config config.yaml |
| |
| # Record battle footage |
| clashcr record-battle --config config.yaml --output data/live-recordings/session-001 --seconds 180 --fps 8 |
| |
| # Label a recording (edit labels.csv manually) |
| clashcr label-recording --recording data/live-recordings/session-001 |
| |
| # Train event detection model (placeholder) |
| clashcr train-event-model --config config.yaml --data data/live-recordings |
| |
| # Evaluate predictions vs labels |
| clashcr evaluate-recording --config config.yaml --recording data/live-recordings/session-heldout --labels data/live-recordings/session-heldout/labels.csv |
| |
| # Live tracking run |
| clashcr run --config config.yaml --raw --debug-frame debug-frame.jpg --debug-dir debug-events |
| ``` |
|
|
| ## Project Structure |
|
|
| ``` |
| clashcr/ |
| core/ |
| capture.py # Emulator window capture |
| battle_gating.py # Battle detection and ROI separation |
| event_detector.py # Temporal event detection |
| recorder.py # Evidence recording and labeling |
| evaluator.py # Offline metrics evaluation |
| models/ |
| evidence_model.py # YOLO + spell heuristics |
| card_resolver.py # Unit->card mapping with ambiguity handling |
| game/ |
| elixir_tracker.py # Wall-clock elixir estimation |
| deck_tracker.py # Deck/cycle inference |
| utils/ |
| card_registry.py # Sync card list from RoyaleAPI + Official API |
| cli.py # Entry point |
| ``` |
|
|
| ## Verification |
| See VERIFICATION_PLAN.md for the full validation protocol. No accuracy claims should be made without labeled recordings. |
| |
| ## Research |
| See RESEARCH_SUMMARY.md for evaluated projects, datasets, and APIs. |
|
|
| ## Rewrite Plan |
| See REWRITE_PLAN.md for the detailed technical migration guide. |
| |
| <!-- ml-intern-provenance --> |
| ## Generated by ML Intern |
| |
| This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub. |
| |
| - Try ML Intern: https://smolagents-ml-intern.hf.space |
| - Source code: https://github.com/huggingface/ml-intern |
| |
| ## Usage |
| |
| ```python |
| from transformers import AutoModelForCausalLM, AutoTokenizer |
| |
| model_id = 'stevenkhan/clashcr' |
| tokenizer = AutoTokenizer.from_pretrained(model_id) |
| model = AutoModelForCausalLM.from_pretrained(model_id) |
| ``` |
| |
| For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class. |
| |
