Hugging Face's logo

stevenkhan
/
clashcr

ml-intern
Model card Files
xet
 Community
clashcr
File size: 3,672 Bytes
4d56ed3
 
 
 
58ea772
20b1310
58ea772
20b1310
58ea772
 
20b1310
58ea772
 
 
 
 
20b1310
58ea772
20b1310
58ea772
20b1310
58ea772
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20b1310
58ea772
 
 
 
 
 
 
 
 
 
 
20b1310
 
58ea772
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4d56ed3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
---
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.