# jooi025/brawlstarsbot architecture

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

- Interactive diagram: https://gitdiagram.com/jooi025/brawlstarsbot
- Repository: https://github.com/jooi025/brawlstarsbot

## Overview

BrawlStarsBot automates solo-showdown mastery farming in Brawl Stars running through BlueStacks. Its main workflow captures the game window, detects players, bushes, and enemies, then drives movement and combat while screen-state automation handles defeat, loading, and requeue actions. Configuration and bundled YOLO models support that loop; the README also documents a separate helper for measuring a brawler’s height scale factor. Source excerpts are partial, so some runtime data wiring is represented only where supported by the documented workflow.

Main entry points: [`main.py`](https://github.com/jooi025/brawlstarsbot/blob/main/main.py) (Runtime Orchestrator), [`constants.py`](https://github.com/jooi025/brawlstarsbot/blob/main/constants.py) (Bot Configuration), [`modules/screendetect.py`](https://github.com/jooi025/brawlstarsbot/blob/main/modules/screendetect.py) (Screen-State Detection), [`modules/bot.py`](https://github.com/jooi025/brawlstarsbot/blob/main/modules/bot.py) (Combat / Bush Logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_main["Runtime Orchestrator<br/>[main.py]"]
  node_config["Bot Configuration<br/>[constants.py]"]
  node_bot["Combat / Bush Logic<br/>[bot.py]"]
  node_stats["Brawler Stats<br/>[brawler_stats.json]"]
end

subgraph group_vision["Game Perception"]
  node_capture["Window Capture<br/>[windowcapture.py]"]
  node_detect["YOLO Detection<br/>[detection.py]"]
  node_models["YOLO Models"]
end

subgraph group_automation["Match Automation"]
  node_screen["Screen-State Detection<br/>[screendetect.py]"]
end

subgraph group_setup["Brawler Setup"]
  node_hsf["Height-Scale Helper<br/>[hsf_finder.py]"]
end

node_player(("Operator"))
node_game["BlueStacks / Game"]

node_player -->|"starts bot"| node_main
node_main -->|"starts capture"| node_capture
node_main -->|"starts detector"| node_detect
node_main -->|"starts monitor"| node_screen
node_main -->|"starts / stops"| node_bot
node_main -->|"reads settings"| node_config
node_config -->|"loads stats"| node_stats
node_config -->|"selects model"| node_models
node_capture -->|"provides frames"| node_detect
node_detect -->|"provides detections"| node_bot
node_bot -->|"controls movement / combat"| node_game
node_screen -->|"checks pixels / clicks"| node_game
node_screen -->|"reports match state"| node_main
node_main -->|"selects foreground window"| node_game
node_player -.->|"measures brawler"| node_hsf
node_hsf -.->|"returns scale factor"| node_player

click node_main "https://github.com/jooi025/brawlstarsbot/blob/main/main.py"
click node_config "https://github.com/jooi025/brawlstarsbot/blob/main/constants.py"
click node_capture "https://github.com/jooi025/brawlstarsbot/blob/main/modules/windowcapture.py"
click node_detect "https://github.com/jooi025/brawlstarsbot/blob/main/modules/detection.py"
click node_models "https://github.com/jooi025/brawlstarsbot/tree/main/yolov8_model"
click node_bot "https://github.com/jooi025/brawlstarsbot/blob/main/modules/bot.py"
click node_screen "https://github.com/jooi025/brawlstarsbot/blob/main/modules/screendetect.py"
click node_stats "https://github.com/jooi025/brawlstarsbot/blob/main/brawler_stats.json"
click node_hsf "https://github.com/jooi025/brawlstarsbot/blob/main/hsf_finder.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,node_bot,node_stats toneBlue
class node_capture,node_detect,node_models toneAmber
class node_screen toneMint
class node_hsf toneRose
class node_player,node_game toneIndigo
```

## Components

### Bot Runtime

- [Runtime Orchestrator](https://github.com/jooi025/brawlstarsbot/blob/main/main.py): `main.py`
- [Bot Configuration](https://github.com/jooi025/brawlstarsbot/blob/main/constants.py): `constants.py`
- [Combat / Bush Logic](https://github.com/jooi025/brawlstarsbot/blob/main/modules/bot.py): `modules/bot.py`
- [Brawler Stats](https://github.com/jooi025/brawlstarsbot/blob/main/brawler_stats.json): `brawler_stats.json`

### Game Perception

- [Window Capture](https://github.com/jooi025/brawlstarsbot/blob/main/modules/windowcapture.py): `modules/windowcapture.py`
- [YOLO Detection](https://github.com/jooi025/brawlstarsbot/blob/main/modules/detection.py): `modules/detection.py`
- [YOLO Models](https://github.com/jooi025/brawlstarsbot/tree/main/yolov8_model): `yolov8_model`

### Match Automation

- [Screen-State Detection](https://github.com/jooi025/brawlstarsbot/blob/main/modules/screendetect.py): `modules/screendetect.py`

### Brawler Setup

- [Height-Scale Helper](https://github.com/jooi025/brawlstarsbot/blob/main/hsf_finder.py): `hsf_finder.py`

### Other components

- **Operator**
- **BlueStacks / Game**

## Connections

- Operator → Runtime Orchestrator: starts bot
- Runtime Orchestrator → Window Capture: starts capture
- Runtime Orchestrator → YOLO Detection: starts detector
- Runtime Orchestrator → Screen-State Detection: starts monitor
- Runtime Orchestrator → Combat / Bush Logic: starts / stops
- Runtime Orchestrator → Bot Configuration: reads settings
- Bot Configuration → Brawler Stats: loads stats
- Bot Configuration → YOLO Models: selects model
- Window Capture → YOLO Detection: provides frames
- YOLO Detection → Combat / Bush Logic: provides detections
- Combat / Bush Logic → BlueStacks / Game: controls movement / combat
- Screen-State Detection → BlueStacks / Game: checks pixels / clicks
- Screen-State Detection → Runtime Orchestrator: reports match state
- Runtime Orchestrator → BlueStacks / Game: selects foreground window
- Operator → Height-Scale Helper: measures brawler
- Height-Scale Helper → Operator: returns scale factor