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