# joellim31314/clashbot architecture

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

- Interactive diagram: https://gitdiagram.com/joellim31314/clashbot
- Repository: https://github.com/joellim31314/clashbot

## Overview

ClashBot automates Clash Royale in an Android emulator: it captures each frame, classifies the screen and battle scene, chooses a Hog 2.6 action, then taps or swipes through emulator control. The runtime also handles menus and post-battle screens. Perception combines pixel-based state and elixir checks, YOLO arena detections, and template-matched hand cards; strategy consumes that scene. A separate model-development branch generates synthetic detection data and trains YOLO. Unsampled modules are included only where README capabilities and the visible entry-point wiring support their roles.

Main entry points: [`main.py`](https://github.com/joellim31314/clashbot/blob/master/main.py) (Game loop), [`bot/state.py`](https://github.com/joellim31314/clashbot/blob/master/bot/state.py) (State and scene detection), [`bot/strategy.py`](https://github.com/joellim31314/clashbot/blob/master/bot/strategy.py) (Hog 2.6 strategy), [`bot/screen.py`](https://github.com/joellim31314/clashbot/blob/master/bot/screen.py) (Frame capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_main["Game loop<br/>[main.py]"]
  node_config["Game configuration<br/>[config.py]"]
end

subgraph group_perception["Game Perception"]
  node_screen["Frame capture<br/>[screen.py]"]
  node_state["State and scene detection<br/>[state.py]"]
  node_vision["Arena detection<br/>[vision.py]"]
  node_cards["Hand card matching<br/>[vision.py]"]
end

subgraph group_play["Strategy And Actions"]
  node_models["Scene and action data<br/>[models.py]"]
  node_strategy["Hog 2.6 strategy<br/>[strategy.py]"]
  node_actions["Emulator actions<br/>[actions.py]"]
end

subgraph group_modeling["Detection Model Development"]
  node_synthetic["Synthetic data generation"]
  node_dataset["Dataset definition<br/>[dataset.yaml]"]
  node_training["YOLO training<br/>[train_yolo.py]"]
end

node_user(("Bot operator"))
node_emulator["Android emulator"]
node_sprites["Sprite library and backgrounds"]
node_yolo["YOLO framework"]

node_user -->|"starts"| node_main
node_main -->|"creates capture"| node_screen
node_main -->|"creates detector"| node_state
node_main -->|"initializes"| node_vision
node_main -->|"initializes"| node_cards
node_main -->|"creates strategy"| node_strategy
node_main -->|"creates executor"| node_actions
node_screen -->|"captures frames"| node_emulator
node_state -->|"requests frames"| node_screen
node_state -->|"detects arena"| node_vision
node_state -->|"identifies hand"| node_cards
node_state -->|"builds battle scene"| node_models
node_state -->|"reads thresholds"| node_config
node_main -->|"captures and classifies"| node_state
node_main -->|"requests battle scene"| node_state
node_main -->|"decides action"| node_strategy
node_strategy -->|"reads scene returns action"| node_models
node_strategy -->|"reads deck rules"| node_config
node_main -->|"dispatches taps and plays"| node_actions
node_actions -->|"sends taps and swipes"| node_emulator
node_synthetic -->|"loads inputs"| node_sprites
node_synthetic -->|"generates training data"| node_dataset
node_training -->|"trains from definition"| node_dataset
node_training -->|"trains model"| node_yolo

click node_main "https://github.com/joellim31314/clashbot/blob/master/main.py"
click node_config "https://github.com/joellim31314/clashbot/blob/master/config.py"
click node_screen "https://github.com/joellim31314/clashbot/blob/master/bot/screen.py"
click node_state "https://github.com/joellim31314/clashbot/blob/master/bot/state.py"
click node_vision "https://github.com/joellim31314/clashbot/blob/master/bot/vision.py"
click node_cards "https://github.com/joellim31314/clashbot/blob/master/bot/vision.py"
click node_models "https://github.com/joellim31314/clashbot/blob/master/bot/models.py"
click node_strategy "https://github.com/joellim31314/clashbot/blob/master/bot/strategy.py"
click node_actions "https://github.com/joellim31314/clashbot/blob/master/bot/actions.py"
click node_synthetic "https://github.com/joellim31314/clashbot/blob/master/data/generate_training_data.py"
click node_dataset "https://github.com/joellim31314/clashbot/blob/master/data/dataset.yaml"
click node_training "https://github.com/joellim31314/clashbot/blob/master/data/train_yolo.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_main,node_config toneBlue
class node_screen,node_state,node_vision,node_cards toneAmber
class node_models,node_strategy,node_actions toneMint
class node_synthetic,node_dataset,node_training,node_sprites toneRose
class node_user,node_emulator,node_yolo toneIndigo
```

## Components

### Bot Runtime

- [Game loop](https://github.com/joellim31314/clashbot/blob/master/main.py): `main.py`
- [Game configuration](https://github.com/joellim31314/clashbot/blob/master/config.py): `config.py`

### Game Perception

- [Frame capture](https://github.com/joellim31314/clashbot/blob/master/bot/screen.py): `bot/screen.py`
- [State and scene detection](https://github.com/joellim31314/clashbot/blob/master/bot/state.py): `bot/state.py`
- [Arena detection](https://github.com/joellim31314/clashbot/blob/master/bot/vision.py): `bot/vision.py`
- [Hand card matching](https://github.com/joellim31314/clashbot/blob/master/bot/vision.py): `bot/vision.py`

### Strategy And Actions

- [Scene and action data](https://github.com/joellim31314/clashbot/blob/master/bot/models.py): `bot/models.py`
- [Hog 2.6 strategy](https://github.com/joellim31314/clashbot/blob/master/bot/strategy.py): `bot/strategy.py`
- [Emulator actions](https://github.com/joellim31314/clashbot/blob/master/bot/actions.py): `bot/actions.py`

### Detection Model Development

- [Synthetic data generation](https://github.com/joellim31314/clashbot/blob/master/data/generate_training_data.py): `data/generate_training_data.py`
- [Dataset definition](https://github.com/joellim31314/clashbot/blob/master/data/dataset.yaml): `data/dataset.yaml`
- [YOLO training](https://github.com/joellim31314/clashbot/blob/master/data/train_yolo.py): `data/train_yolo.py`

### Other components

- **Bot operator**
- **Android emulator**
- **Sprite library and backgrounds**
- **YOLO framework**

## Connections

- Bot operator → Game loop: starts
- Game loop → Frame capture: creates capture
- Game loop → State and scene detection: creates detector
- Game loop → Arena detection: initializes
- Game loop → Hand card matching: initializes
- Game loop → Hog 2.6 strategy: creates strategy
- Game loop → Emulator actions: creates executor
- Frame capture → Android emulator: captures frames
- State and scene detection → Frame capture: requests frames
- State and scene detection → Arena detection: detects arena
- State and scene detection → Hand card matching: identifies hand
- State and scene detection → Scene and action data: builds battle scene
- State and scene detection → Game configuration: reads thresholds
- Game loop → State and scene detection: captures and classifies
- Game loop → State and scene detection: requests battle scene
- Game loop → Hog 2.6 strategy: decides action
- Hog 2.6 strategy → Scene and action data: reads scene returns action
- Hog 2.6 strategy → Game configuration: reads deck rules
- Game loop → Emulator actions: dispatches taps and plays
- Emulator actions → Android emulator: sends taps and swipes
- Synthetic data generation → Sprite library and backgrounds: loads inputs
- Synthetic data generation → Dataset definition: generates training data
- YOLO training → Dataset definition: trains from definition
- YOLO training → YOLO framework: trains model