# hastylmao/hasty-cr architecture

> Architecture diagram of the GitHub repository hastylmao/hasty-cr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hastylmao/hasty-cr
- Repository: https://github.com/hastylmao/hasty-cr

## Overview

HastyCR combines a deterministic Clash Royale simulator, an agent trained against it, and a live-game bridge. The main workflow is to run or train a policy in the simulator, evaluate it, then use perception and device controls for live play. Calibration and video analysis form a separate research branch. README statements and indexed references support the connections shown; unsampled training and runtime code limits finer-grained wiring.

Main entry points: [`sim/match.py`](https://github.com/hastylmao/hasty-cr/blob/main/sim/match.py) (Match runner), [`scripts/studio/app.py`](https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/app.py) (Studio controls), [`sim/engine.py`](https://github.com/hastylmao/hasty-cr/blob/main/sim/engine.py) (Battle tick), [`src/hastycr/pipeline.py`](https://github.com/hastylmao/hasty-cr/blob/main/src/hastycr/pipeline.py) (Action pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Battle simulation"]
  node_arena["Arena geometry<br/>[arena.py]"]
  node_carddata[("Card data<br/>[gamedata.py]")]
  node_entities["Battle entities<br/>[entities.py]"]
  node_spells["Spell mechanics<br/>[spells.py]"]
  node_engine["Battle tick<br/>[engine.py]"]
  node_match["Match runner<br/>[match.py]"]
  node_tower["Tower mechanics<br/>[towers.py]"]
  node_runner["Simulation runner<br/>[runner.py]"]
end

subgraph group_learning["Agent learning"]
  node_brain["Rule policy<br/>[policy.py]"]
  node_clone["Policy cloning<br/>[clone.py]"]
  node_ppo["PPO training<br/>[train_ppo.py]"]
end

subgraph group_live["Live play"]
  node_studio["Studio controls<br/>[app.py]"]
  node_capture["Screen capture<br/>[capture.py]"]
  node_detector["Object detection<br/>[detect.py]"]
  node_feed["Game feed<br/>[feed.py]"]
  node_render["Live display<br/>[render.py]"]
  node_models["Action/state models<br/>[models.py]"]
  node_livepipeline["Action pipeline<br/>[pipeline.py]"]
end

subgraph group_research["Calibration research"]
  node_calibration["Calibration core<br/>[core.py]"]
  node_replay["Replay calibration"]
  node_vod["Video analysis<br/>[pipeline.py]"]
end

node_operator(("Engineer"))
node_liveuser(("Live-game operator"))
node_device["Android emulator"]

node_operator -->|"runs matches"| node_match
node_engine -->|"uses geometry"| node_arena
node_engine -->|"updates entities"| node_entities
node_engine -->|"loads stats"| node_carddata
node_engine -->|"resolves spells"| node_spells
node_match -->|"runs battle"| node_engine
node_match -->|"uses geometry"| node_arena
node_match -->|"uses entities"| node_entities
node_match -->|"loads stats"| node_carddata
node_match -->|"uses spell rules"| node_spells
node_match -.->|"uses tower rules"| node_tower
node_operator -->|"starts cloning"| node_clone
node_operator -->|"starts training"| node_ppo
node_brain -.->|"provides examples"| node_clone
node_liveuser -->|"operates"| node_studio
node_studio -->|"starts capture"| node_capture
node_studio -->|"starts detection"| node_detector
node_studio -->|"uses feed"| node_feed
node_studio -->|"configures display"| node_render
node_capture -.->|"captures screen"| node_device
node_studio -.->|"connects live cycle"| node_livepipeline
node_livepipeline -->|"uses state and actions"| node_models
node_livepipeline -.->|"sends actions"| node_device
node_operator -->|"calibrates mechanics"| node_calibration
node_replay -->|"provides calibration primitives"| node_calibration
node_operator -.->|"analyzes recordings"| node_vod

click node_arena "https://github.com/hastylmao/hasty-cr/blob/main/sim/arena.py"
click node_carddata "https://github.com/hastylmao/hasty-cr/blob/main/sim/gamedata.py"
click node_entities "https://github.com/hastylmao/hasty-cr/blob/main/sim/entities.py"
click node_spells "https://github.com/hastylmao/hasty-cr/blob/main/sim/spells.py"
click node_engine "https://github.com/hastylmao/hasty-cr/blob/main/sim/engine.py"
click node_match "https://github.com/hastylmao/hasty-cr/blob/main/sim/match.py"
click node_tower "https://github.com/hastylmao/hasty-cr/blob/main/sim/towers.py"
click node_runner "https://github.com/hastylmao/hasty-cr/blob/main/sim/runner.py"
click node_brain "https://github.com/hastylmao/hasty-cr/blob/main/scripts/brain/policy.py"
click node_clone "https://github.com/hastylmao/hasty-cr/blob/main/sim/clone.py"
click node_ppo "https://github.com/hastylmao/hasty-cr/blob/main/sim/train_ppo.py"
click node_studio "https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/app.py"
click node_capture "https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/capture.py"
click node_detector "https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/detect.py"
click node_feed "https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/feed.py"
click node_render "https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/render.py"
click node_models "https://github.com/hastylmao/hasty-cr/blob/main/src/hastycr/models.py"
click node_livepipeline "https://github.com/hastylmao/hasty-cr/blob/main/src/hastycr/pipeline.py"
click node_calibration "https://github.com/hastylmao/hasty-cr/blob/main/tools/calibration/core.py"
click node_replay "https://github.com/hastylmao/hasty-cr/blob/main/tools/replay_calibration.py"
click node_vod "https://github.com/hastylmao/hasty-cr/blob/main/tools/vod/pipeline.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_arena,node_carddata,node_entities,node_spells,node_engine,node_match,node_tower,node_runner toneBlue
class node_brain,node_clone,node_ppo toneAmber
class node_studio,node_capture,node_detector,node_feed,node_render,node_models,node_livepipeline toneMint
class node_calibration,node_replay,node_vod toneRose
class node_operator,node_liveuser,node_device toneIndigo
```

## Components

### Battle simulation

- [Arena geometry](https://github.com/hastylmao/hasty-cr/blob/main/sim/arena.py): `sim/arena.py`
- [Card data](https://github.com/hastylmao/hasty-cr/blob/main/sim/gamedata.py): `sim/gamedata.py`
- [Battle entities](https://github.com/hastylmao/hasty-cr/blob/main/sim/entities.py): `sim/entities.py`
- [Spell mechanics](https://github.com/hastylmao/hasty-cr/blob/main/sim/spells.py): `sim/spells.py`
- [Battle tick](https://github.com/hastylmao/hasty-cr/blob/main/sim/engine.py): `sim/engine.py`
- [Match runner](https://github.com/hastylmao/hasty-cr/blob/main/sim/match.py): `sim/match.py`
- [Tower mechanics](https://github.com/hastylmao/hasty-cr/blob/main/sim/towers.py): `sim/towers.py`
- [Simulation runner](https://github.com/hastylmao/hasty-cr/blob/main/sim/runner.py): `sim/runner.py`

### Agent learning

- [Rule policy](https://github.com/hastylmao/hasty-cr/blob/main/scripts/brain/policy.py): `scripts/brain/policy.py`
- [Policy cloning](https://github.com/hastylmao/hasty-cr/blob/main/sim/clone.py): `sim/clone.py`
- [PPO training](https://github.com/hastylmao/hasty-cr/blob/main/sim/train_ppo.py): `sim/train_ppo.py`

### Live play

- [Studio controls](https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/app.py): `scripts/studio/app.py`
- [Screen capture](https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/capture.py): `scripts/studio/capture.py`
- [Object detection](https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/detect.py): `scripts/studio/detect.py`
- [Game feed](https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/feed.py): `scripts/studio/feed.py`
- [Live display](https://github.com/hastylmao/hasty-cr/blob/main/scripts/studio/render.py): `scripts/studio/render.py`
- [Action/state models](https://github.com/hastylmao/hasty-cr/blob/main/src/hastycr/models.py): `src/hastycr/models.py`
- [Action pipeline](https://github.com/hastylmao/hasty-cr/blob/main/src/hastycr/pipeline.py): `src/hastycr/pipeline.py`

### Calibration research

- [Calibration core](https://github.com/hastylmao/hasty-cr/blob/main/tools/calibration/core.py): `tools/calibration/core.py`
- [Replay calibration](https://github.com/hastylmao/hasty-cr/blob/main/tools/replay_calibration.py): `tools/replay_calibration.py`
- [Video analysis](https://github.com/hastylmao/hasty-cr/blob/main/tools/vod/pipeline.py): `tools/vod/pipeline.py`

### Other components

- **Engineer**
- **Live-game operator**
- **Android emulator**

## Connections

- Engineer → Match runner: runs matches (evidence: `README.md`)
- Battle tick → Arena geometry: uses geometry (evidence: `sim/engine.py`)
- Battle tick → Battle entities: updates entities (evidence: `sim/engine.py`)
- Battle tick → Card data: loads stats (evidence: `sim/engine.py`)
- Battle tick → Spell mechanics: resolves spells (evidence: `sim/engine.py`)
- Match runner → Battle tick: runs battle (evidence: `sim/match.py`)
- Match runner → Arena geometry: uses geometry (evidence: `sim/match.py`)
- Match runner → Battle entities: uses entities (evidence: `sim/match.py`)
- Match runner → Card data: loads stats (evidence: `sim/match.py`)
- Match runner → Spell mechanics: uses spell rules (evidence: `sim/match.py`)
- Match runner → Tower mechanics: uses tower rules (evidence: `sim/match.py`)
- Engineer → Policy cloning: starts cloning (evidence: `README.md`)
- Engineer → PPO training: starts training (evidence: `README.md`)
- Rule policy → Policy cloning: provides examples
- Live-game operator → Studio controls: operates (evidence: `README.md`)
- Studio controls → Screen capture: starts capture (evidence: `scripts/studio/app.py`)
- Studio controls → Object detection: starts detection (evidence: `scripts/studio/app.py`)
- Studio controls → Game feed: uses feed (evidence: `scripts/studio/app.py`)
- Studio controls → Live display: configures display (evidence: `scripts/studio/app.py`)
- Screen capture → Android emulator: captures screen
- Studio controls → Action pipeline: connects live cycle
- Action pipeline → Action/state models: uses state and actions (evidence: `src/hastycr/pipeline.py`)
- Action pipeline → Android emulator: sends actions
- Engineer → Calibration core: calibrates mechanics (evidence: `README.md`)
- Replay calibration → Calibration core: provides calibration primitives (evidence: `tools/replay_calibration.py`)
- Engineer → Video analysis: analyzes recordings
