# maaend/maaend architecture

> Architecture diagram of the GitHub repository maaend/maaend, 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/maaend/maaend
- Repository: https://github.com/maaend/maaend
- Video tour (about a minute): https://gitdiagram.com/maaend/maaend/video

## Overview

MaaEnd is a game-screen automation assistant: users select a preset or task, the MaaFramework-backed agent runs task actions using screen recognition, then issues controller input and reports completion. The repository separates Go task implementations, C++ recognition and navigation algorithms, and platform-specific control backends. README capabilities also include live combat/story assistance, farming, trading, inventory, puzzle solving, and account utilities. The tree and excerpts support these subsystem boundaries, but not detailed runtime wiring among most task packages, so uncertain call paths are omitted.

Main entry points: [`agent/go-service`](https://github.com/maaend/maaend/tree/v2/agent/go-service) (Game Tasks), [`agent/cpp-algo/source/MapNavigator/MapNavigator.cpp`](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapNavigator/MapNavigator.cpp) (Map Navigator), [`agent/go-service/agent.go`](https://github.com/maaend/maaend/blob/v2/agent/go-service/agent.go) (Agent Runtime), [`agent/go-service/outposttrading`](https://github.com/maaend/maaend/tree/v2/agent/go-service/outposttrading) (Outpost Trading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent and Tasks"]
  node_agentmain["Go Agent<br/>[main.go]"]
  node_agent["Agent Runtime<br/>[agent.go]"]
  node_tasks["Game Tasks"]
  node_live["Live Assistance<br/>[controller.go]"]
  node_essence["Essence Filter"]
  node_trading["Outpost Trading"]
  node_delivery["Delivery Tasks"]
  node_puzzle["Puzzle Solver"]
  node_farm["Eco Farm"]
end

subgraph group_vision["Recognition and Solving"]
  node_grid["Grid Recognition<br/>[GridRecognizer.cpp]"]
  node_icons["Icon Recognition<br/>[IconRecognizer.cpp]"]
  node_maploc["Map Location<br/>[MapLocator.cpp]"]
  node_worldmap["World Map<br/>[WorldMapSolver.cpp]"]
end

subgraph group_navigation["Navigation"]
  node_nav["Map Navigator<br/>[MapNavigator.cpp]"]
  node_navmesh["Navmesh Planning<br/>[BaseNavPlanner.cpp]"]
  node_zipline[("Zipline Data<br/>[ZiplineStore.cpp]")]
end

subgraph group_control["Device Control"]
  node_control["Control Backends<br/>[adaptor.go]"]
  node_cppcontrol["Navigation Inputs<br/>[backend.cpp]"]
end

subgraph group_state["Task State"]
  node_ims[("Item Cache<br/>[storage.go]")]
  node_stock[("Stockpile Records<br/>[daily_storage.go]")]
  node_credit[("Shopping Snapshots<br/>[storage.go]")]
end

node_user(("Player"))
node_framework["MaaFramework"]
node_game["Game Screen"]
node_device["Game Device"]

node_user -->|"selects task"| node_framework
node_framework -->|"dispatches"| node_agentmain
node_agentmain -->|"starts"| node_agent
node_agent -->|"runs tasks"| node_tasks
node_game -->|"screen input"| node_agent
node_tasks -->|"includes assistance"| node_live
node_tasks -->|"runs filtering"| node_essence
node_tasks -->|"runs trading"| node_trading
node_tasks -->|"runs delivery"| node_delivery
node_tasks -->|"solves puzzles"| node_puzzle
node_tasks -->|"runs farming"| node_farm
node_essence -->|"matches icons"| node_icons
node_puzzle -->|"recognizes grid"| node_grid
node_nav -->|"locates map"| node_maploc
node_nav -->|"plans routes"| node_navmesh
node_nav -->|"uses coordinates"| node_zipline
node_nav -->|"issues movement"| node_cppcontrol
node_agent -->|"sends input"| node_control
node_control -->|"controls"| node_device
node_cppcontrol -->|"controls"| node_device
node_trading -->|"records prices"| node_stock
node_tasks -->|"uses item cache"| node_ims
node_trading -->|"records shelves"| node_credit
node_device -->|"renders screen"| node_game
node_worldmap -->|"uses map matching"| node_maploc

click node_agentmain "https://github.com/maaend/maaend/blob/v2/agent/go-service/main.go"
click node_agent "https://github.com/maaend/maaend/blob/v2/agent/go-service/agent.go"
click node_tasks "https://github.com/maaend/maaend/tree/v2/agent/go-service"
click node_live "https://github.com/maaend/maaend/blob/v2/agent/go-service/common/charactercontroller/controller.go"
click node_essence "https://github.com/maaend/maaend/tree/v2/agent/go-service/essencefilter"
click node_trading "https://github.com/maaend/maaend/tree/v2/agent/go-service/outposttrading"
click node_delivery "https://github.com/maaend/maaend/tree/v2/agent/go-service/autodelivery"
click node_puzzle "https://github.com/maaend/maaend/tree/v2/agent/go-service/puzzle-solver"
click node_farm "https://github.com/maaend/maaend/tree/v2/agent/go-service/autoecofarm"
click node_grid "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/RecoGrid/GridRecognizer.cpp"
click node_icons "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/IconRecognition/IconRecognizer.cpp"
click node_maploc "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapLocator/MapLocator.cpp"
click node_worldmap "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/WorldMap/WorldMapSolver.cpp"
click node_nav "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapNavigator/MapNavigator.cpp"
click node_navmesh "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/Navmesh/BaseNavPlanner.cpp"
click node_zipline "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/Zipline/ZiplineStore.cpp"
click node_control "https://github.com/maaend/maaend/blob/v2/agent/go-service/pkg/control/adaptor.go"
click node_cppcontrol "https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapNavigator/Backend/backend.cpp"
click node_ims "https://github.com/maaend/maaend/blob/v2/agent/go-service/ims/storage.go"
click node_stock "https://github.com/maaend/maaend/blob/v2/agent/go-service/autostockpile/daily_storage.go"
click node_credit "https://github.com/maaend/maaend/blob/v2/agent/go-service/creditshopping/storage.go"

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_agentmain,node_agent,node_tasks,node_live,node_essence,node_trading,node_delivery,node_puzzle,node_farm,node_game toneBlue
class node_grid,node_icons,node_maploc,node_worldmap toneAmber
class node_nav,node_navmesh,node_zipline toneMint
class node_control,node_cppcontrol toneRose
class node_ims,node_stock,node_credit,node_user,node_framework,node_device toneIndigo
```

## Components

### Agent and Tasks

- [Go Agent](https://github.com/maaend/maaend/blob/v2/agent/go-service/main.go): `agent/go-service/main.go`
- [Agent Runtime](https://github.com/maaend/maaend/blob/v2/agent/go-service/agent.go): `agent/go-service/agent.go`
- [Game Tasks](https://github.com/maaend/maaend/tree/v2/agent/go-service): `agent/go-service`
- [Live Assistance](https://github.com/maaend/maaend/blob/v2/agent/go-service/common/charactercontroller/controller.go): `agent/go-service/common/charactercontroller/controller.go`
- [Essence Filter](https://github.com/maaend/maaend/tree/v2/agent/go-service/essencefilter): `agent/go-service/essencefilter`
- [Outpost Trading](https://github.com/maaend/maaend/tree/v2/agent/go-service/outposttrading): `agent/go-service/outposttrading`
- [Delivery Tasks](https://github.com/maaend/maaend/tree/v2/agent/go-service/autodelivery): `agent/go-service/autodelivery`
- [Puzzle Solver](https://github.com/maaend/maaend/tree/v2/agent/go-service/puzzle-solver): `agent/go-service/puzzle-solver`
- [Eco Farm](https://github.com/maaend/maaend/tree/v2/agent/go-service/autoecofarm): `agent/go-service/autoecofarm`

### Recognition and Solving

- [Grid Recognition](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/RecoGrid/GridRecognizer.cpp): `agent/cpp-algo/source/RecoGrid/GridRecognizer.cpp`
- [Icon Recognition](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/IconRecognition/IconRecognizer.cpp): `agent/cpp-algo/source/IconRecognition/IconRecognizer.cpp`
- [Map Location](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapLocator/MapLocator.cpp): `agent/cpp-algo/source/MapLocator/MapLocator.cpp`
- [World Map](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/WorldMap/WorldMapSolver.cpp): `agent/cpp-algo/source/WorldMap/WorldMapSolver.cpp`

### Navigation

- [Map Navigator](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapNavigator/MapNavigator.cpp): `agent/cpp-algo/source/MapNavigator/MapNavigator.cpp`
- [Navmesh Planning](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/Navmesh/BaseNavPlanner.cpp): `agent/cpp-algo/source/Navmesh/BaseNavPlanner.cpp`
- [Zipline Data](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/Zipline/ZiplineStore.cpp): `agent/cpp-algo/source/Zipline/ZiplineStore.cpp`

### Device Control

- [Control Backends](https://github.com/maaend/maaend/blob/v2/agent/go-service/pkg/control/adaptor.go): `agent/go-service/pkg/control/adaptor.go`
- [Navigation Inputs](https://github.com/maaend/maaend/blob/v2/agent/cpp-algo/source/MapNavigator/Backend/backend.cpp): `agent/cpp-algo/source/MapNavigator/Backend/backend.cpp`

### Task State

- [Item Cache](https://github.com/maaend/maaend/blob/v2/agent/go-service/ims/storage.go): `agent/go-service/ims/storage.go`
- [Stockpile Records](https://github.com/maaend/maaend/blob/v2/agent/go-service/autostockpile/daily_storage.go): `agent/go-service/autostockpile/daily_storage.go`
- [Shopping Snapshots](https://github.com/maaend/maaend/blob/v2/agent/go-service/creditshopping/storage.go): `agent/go-service/creditshopping/storage.go`

### Other components

- **Player**
- **MaaFramework**
- **Game Screen**
- **Game Device**

## Connections

- Player → MaaFramework: selects task
- MaaFramework → Go Agent: dispatches
- Go Agent → Agent Runtime: starts
- Agent Runtime → Game Tasks: runs tasks
- Game Screen → Agent Runtime: screen input
- Game Tasks → Live Assistance: includes assistance
- Game Tasks → Essence Filter: runs filtering
- Game Tasks → Outpost Trading: runs trading
- Game Tasks → Delivery Tasks: runs delivery
- Game Tasks → Puzzle Solver: solves puzzles
- Game Tasks → Eco Farm: runs farming
- Essence Filter → Icon Recognition: matches icons
- Puzzle Solver → Grid Recognition: recognizes grid
- Map Navigator → Map Location: locates map
- Map Navigator → Navmesh Planning: plans routes
- Map Navigator → Zipline Data: uses coordinates
- Map Navigator → Navigation Inputs: issues movement
- Agent Runtime → Control Backends: sends input
- Control Backends → Game Device: controls
- Navigation Inputs → Game Device: controls
- Outpost Trading → Stockpile Records: records prices
- Game Tasks → Item Cache: uses item cache
- Outpost Trading → Shopping Snapshots: records shelves
- Game Device → Game Screen: renders screen
- World Map → Map Location: uses map matching