# aynamuk/maplestoryautolevelup-cn architecture

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

- Interactive diagram: https://gitdiagram.com/aynamuk/maplestoryautolevelup-cn
- Repository: https://github.com/aynamuk/maplestoryautolevelup-cn

## Overview

This is a Windows computer-vision auto-leveling tool for MapleStory’s remade Chinese client. Its main workflow is to capture the game window, locate the player on the minimap, detect nearby monsters, follow configured routes, and issue keyboard commands through the Interception driver. The UI manages settings and launches route/template tools; the runtime also supports health/mana monitoring with automatic potions, stuck alerts, and home-route recovery. Core engine wiring is documented and partly sampled; links to unsampled feature modules are limited to documented responsibilities.

Main entry points: [`src/engine/MapleStoryAutoLevelUp.py`](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/engine/MapleStoryAutoLevelUp.py) (Bot engine), [`src/ui/AutoBotController.py`](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/ui/AutoBotController.py) (Bot controller), [`src/ui/ui.py`](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/ui/ui.py) (Control window), [`src/states/hunting.py`](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/states/hunting.py) (Hunting state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface and setup"]
  node_main["Application entry<br/>[main.py]"]
  node_window["Control window<br/>[ui.py]"]
  node_ui_controller["Bot controller"]
  node_route_tool["Route recorder<br/>[routeRecorder.py]"]
end

subgraph group_perception["Capture and perception"]
  node_capture["Window capture"]
  node_vision["Vision utilities<br/>[common.py]"]
  node_bars["Bar reading<br/>[bars.py]"]
  node_mob_library["Monster templates<br/>[mob_library.py]"]
end

subgraph group_automation["Automation runtime"]
  node_engine["Bot engine"]
  node_fsm["State machine"]
  node_hunting["Hunting state<br/>[hunting.py]"]
  node_base_state["State base<br/>[base_state.py]"]
  node_route_logic["Home-route logic<br/>[home_route.py]"]
  node_potions["Potion policy<br/>[potions.py]"]
  node_stuck["Stuck alerts<br/>[stuck_alert.py]"]
end

subgraph group_controls["Input and state"]
  node_keyboard["Keyboard control"]
  node_driver["Interception adapter"]
  node_listener["Hotkey listener"]
end

node_player(("User"))
node_game["Game client"]

node_player -->|"configures and starts"| node_window
node_main -->|"creates"| node_window
node_main -->|"creates"| node_ui_controller
node_window -->|"commands"| node_ui_controller
node_ui_controller -->|"configures and starts"| node_engine
node_ui_controller -->|"checks availability"| node_driver
node_window -->|"launches tools"| node_route_tool
node_route_tool -->|"captures game window"| node_capture
node_engine -->|"obtains frames"| node_capture
node_capture -->|"captures window"| node_game
node_engine -->|"uses image helpers"| node_vision
node_engine -->|"uses monster templates"| node_mob_library
node_engine -->|"reads health and mana"| node_bars
node_engine -->|"uses route recovery"| node_route_logic
node_engine -->|"checks potion policy"| node_potions
node_engine -->|"handles stuck alerts"| node_stuck
node_engine -->|"runs state machine"| node_fsm
node_fsm -->|"dispatches state"| node_hunting
node_hunting -->|"updates route and combat commands"| node_engine
node_hunting -->|"sets commands"| node_keyboard
node_engine -->|"controls"| node_keyboard
node_keyboard -->|"sends key events"| node_driver
node_driver -->|"delivers simulated input"| node_game
node_engine -->|"uses hotkeys"| node_listener
node_listener -->|"signals hotkeys"| node_ui_controller
node_base_state -->|"provides state base"| node_hunting

click node_main "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/main.py"
click node_window "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/ui/ui.py"
click node_ui_controller "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/ui/AutoBotController.py"
click node_route_tool "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/tools/routeRecorder.py"
click node_engine "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/engine/MapleStoryAutoLevelUp.py"
click node_fsm "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/engine/FiniteStateMachine.py"
click node_hunting "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/states/hunting.py"
click node_base_state "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/states/base_state.py"
click node_capture "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/GameWindowCapturor.py"
click node_vision "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/common.py"
click node_bars "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/bars.py"
click node_mob_library "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/mob_library.py"
click node_route_logic "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/home_route.py"
click node_potions "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/potions.py"
click node_stuck "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/stuck_alert.py"
click node_keyboard "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/KeyBoardController.py"
click node_driver "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/InterceptionController.py"
click node_listener "https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/KeyBoardListener.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_window,node_ui_controller,node_route_tool,node_player,node_game toneBlue
class node_capture,node_vision,node_bars,node_mob_library toneAmber
class node_engine,node_fsm,node_hunting,node_base_state,node_route_logic,node_potions,node_stuck toneMint
class node_keyboard,node_driver,node_listener toneRose
```

## Components

### Interface and setup

- [Application entry](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/main.py): `src/main.py`
- [Control window](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/ui/ui.py): `src/ui/ui.py`
- [Bot controller](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/ui/AutoBotController.py): `src/ui/AutoBotController.py`
- [Route recorder](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/tools/routeRecorder.py): `tools/routeRecorder.py`

### Capture and perception

- [Window capture](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/GameWindowCapturor.py): `src/input/GameWindowCapturor.py`
- [Vision utilities](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/common.py): `src/utils/common.py`
- [Bar reading](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/bars.py): `src/utils/bars.py`
- [Monster templates](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/mob_library.py): `src/utils/mob_library.py`

### Automation runtime

- [Bot engine](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/engine/MapleStoryAutoLevelUp.py): `src/engine/MapleStoryAutoLevelUp.py`
- [State machine](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/engine/FiniteStateMachine.py): `src/engine/FiniteStateMachine.py`
- [Hunting state](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/states/hunting.py): `src/states/hunting.py`
- [State base](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/states/base_state.py): `src/states/base_state.py`
- [Home-route logic](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/home_route.py): `src/utils/home_route.py`
- [Potion policy](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/potions.py): `src/utils/potions.py`
- [Stuck alerts](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/utils/stuck_alert.py): `src/utils/stuck_alert.py`

### Input and state

- [Keyboard control](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/KeyBoardController.py): `src/input/KeyBoardController.py`
- [Interception adapter](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/InterceptionController.py): `src/input/InterceptionController.py`
- [Hotkey listener](https://github.com/aynamuk/maplestoryautolevelup-cn/blob/master/src/input/KeyBoardListener.py): `src/input/KeyBoardListener.py`

### Other components

- **User**
- **Game client**

## Connections

- User → Control window: configures and starts
- Application entry → Control window: creates
- Application entry → Bot controller: creates
- Control window → Bot controller: commands
- Bot controller → Bot engine: configures and starts
- Bot controller → Interception adapter: checks availability
- Control window → Route recorder: launches tools
- Route recorder → Window capture: captures game window
- Bot engine → Window capture: obtains frames
- Window capture → Game client: captures window
- Bot engine → Vision utilities: uses image helpers
- Bot engine → Monster templates: uses monster templates
- Bot engine → Bar reading: reads health and mana
- Bot engine → Home-route logic: uses route recovery
- Bot engine → Potion policy: checks potion policy
- Bot engine → Stuck alerts: handles stuck alerts
- Bot engine → State machine: runs state machine
- State machine → Hunting state: dispatches state
- Hunting state → Bot engine: updates route and combat commands
- Hunting state → Keyboard control: sets commands
- Bot engine → Keyboard control: controls
- Keyboard control → Interception adapter: sends key events
- Interception adapter → Game client: delivers simulated input
- Bot engine → Hotkey listener: uses hotkeys
- Hotkey listener → Bot controller: signals hotkeys
- State base → Hunting state: provides state base