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

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

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

Generated by ML Intern

This model repository was generated by 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

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.