# hamza-apps/osu-humanized-bot architecture

> Architecture diagram of the GitHub repository hamza-apps/osu-humanized-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamza-apps/osu-humanized-bot
- Repository: https://github.com/hamza-apps/osu-humanized-bot

## Overview

This is a Python osu! standard-mode gameplay automation bot. The documented workflow captures the game screen, detects hit objects, decides whether and when to hit, then moves and clicks the cursor; configuration controls behavior, while the bot tracks hit statistics. The source shows that the beatmap analyzer is initialized but not used in gameplay, and its analysis methods are placeholders. The README also describes broader timing and anti-detection capabilities, but sampled code does not establish additional subsystems or integrations.

Main entry points: [`src/osu_bot.py`](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/osu_bot.py) (Gameplay loop), [`src/screen_capture.py`](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/screen_capture.py) (Screen capture), [`src/hit_object_detector.py`](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/hit_object_detector.py) (Hit-object detection), [`src/cursor_controller.py`](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/cursor_controller.py) (Cursor movement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Gameplay orchestration"]
  node_bot["Gameplay loop<br/>[osu_bot.py]"]
  node_stats["Hit statistics<br/>[osu_bot.py]"]
end

subgraph group_perception["Screen perception"]
  node_screen["Screen capture<br/>[screen_capture.py]"]
  node_detector["Hit-object detection"]
end

subgraph group_action["Humanized action"]
  node_cursor["Cursor movement"]
end

subgraph group_configuration["Settings and analysis"]
  node_settings["Settings loader<br/>[settings.py]"]
  node_configfile["Bot settings<br/>[bot_settings.json]"]
  node_analyzer["Beatmap analysis"]
end

node_player(("Bot operator"))
node_desktop(("Game display"))
node_input(("Mouse input"))

node_player -->|"starts"| node_bot
node_bot -->|"loads settings"| node_settings
node_settings -->|"reads or creates"| node_configfile
node_bot -->|"captures screen"| node_screen
node_screen -->|"captures pixels"| node_desktop
node_screen -->|"returns screenshot"| node_bot
node_bot -->|"detects objects"| node_detector
node_detector -->|"returns detections"| node_bot
node_bot -->|"moves cursor"| node_cursor
node_cursor -->|"moves pointer"| node_input
node_bot -->|"clicks target"| node_input
node_bot -->|"updates hit count"| node_stats
node_bot -->|"initializes"| node_analyzer

click node_bot "https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/osu_bot.py"
click node_stats "https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/osu_bot.py"
click node_screen "https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/screen_capture.py"
click node_detector "https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/hit_object_detector.py"
click node_cursor "https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/cursor_controller.py"
click node_settings "https://github.com/hamza-apps/osu-humanized-bot/blob/master/config/settings.py"
click node_configfile "https://github.com/hamza-apps/osu-humanized-bot/blob/master/config/bot_settings.json"
click node_analyzer "https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/beatmap_analyzer.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_bot,node_stats toneBlue
class node_screen,node_detector toneAmber
class node_cursor toneMint
class node_settings,node_configfile,node_analyzer toneRose
class node_player,node_desktop,node_input toneIndigo
```

## Components

### Gameplay orchestration

- [Gameplay loop](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/osu_bot.py): `src/osu_bot.py`
- [Hit statistics](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/osu_bot.py): `src/osu_bot.py`

### Screen perception

- [Screen capture](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/screen_capture.py): `src/screen_capture.py`
- [Hit-object detection](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/hit_object_detector.py): `src/hit_object_detector.py`

### Humanized action

- [Cursor movement](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/cursor_controller.py): `src/cursor_controller.py`

### Settings and analysis

- [Settings loader](https://github.com/hamza-apps/osu-humanized-bot/blob/master/config/settings.py): `config/settings.py`
- [Bot settings](https://github.com/hamza-apps/osu-humanized-bot/blob/master/config/bot_settings.json): `config/bot_settings.json`
- [Beatmap analysis](https://github.com/hamza-apps/osu-humanized-bot/blob/master/src/beatmap_analyzer.py): `src/beatmap_analyzer.py`

### Other components

- **Bot operator**
- **Game display**
- **Mouse input**

## Connections

- Bot operator → Gameplay loop: starts (evidence: `README.md`)
- Gameplay loop → Settings loader: loads settings (evidence: `src/osu_bot.py`)
- Settings loader → Bot settings: reads or creates (evidence: `config/settings.py`)
- Gameplay loop → Screen capture: captures screen (evidence: `src/osu_bot.py`)
- Screen capture → Game display: captures pixels (evidence: `src/screen_capture.py`)
- Screen capture → Gameplay loop: returns screenshot (evidence: `src/osu_bot.py`)
- Gameplay loop → Hit-object detection: detects objects (evidence: `src/osu_bot.py`)
- Hit-object detection → Gameplay loop: returns detections (evidence: `src/osu_bot.py`)
- Gameplay loop → Cursor movement: moves cursor (evidence: `src/osu_bot.py`)
- Cursor movement → Mouse input: moves pointer (evidence: `src/cursor_controller.py`)
- Gameplay loop → Mouse input: clicks target (evidence: `src/osu_bot.py`)
- Gameplay loop → Hit statistics: updates hit count (evidence: `src/osu_bot.py`)
- Gameplay loop → Beatmap analysis: initializes (evidence: `src/osu_bot.py`)
