# guywithpaper/snowrunner-minimap architecture

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

- Interactive diagram: https://gitdiagram.com/guywithpaper/snowrunner-minimap
- Repository: https://github.com/guywithpaper/snowrunner-minimap

## Overview

Map Runner is a Windows minimap overlay for SnowRunner. Its main workflow reads the truck’s live position, identifies the current region, builds or loads that region’s map and markers from installed game files, and presents the result in the overlay and big map. Save data supplies vehicle and completion state; settings govern display and controls. The README documents additional map layers and waypoint features. Several implementation files are represented by their exact paths, but unsampled internals are not inferred beyond documented behavior or indexed references.

Main entry points: [`minimap/app.py`](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/app.py) (Overlay app), [`minimap/maprender.py`](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/maprender.py) (Region map rendering), [`minimap/reader.py`](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/reader.py) (Truck position reader), [`minimap/settings.py`](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/settings.py) (Settings model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Overlay runtime"]
  node_app["Overlay app<br/>[app.py]"]
  node_bigmap["Big map and pins<br/>[app.py]"]
end

subgraph group_world["Game world data"]
  node_truckread["Truck position reader<br/>[reader.py]"]
  node_memory["Process memory access<br/>[procmem.py]"]
  node_rtti["RTTI lookup<br/>[rtti.py]"]
  node_gwaypoint["Game waypoints<br/>[gamewp.py]"]
  node_savedata["Save data<br/>[savedata.py]"]
end

subgraph group_mapping["Map and navigation"]
  node_level["Region detection and markers<br/>[levels.py]"]
  node_maprender["Region map rendering<br/>[maprender.py]"]
  node_terrain["Terrain rendering<br/>[terrain.py]"]
  node_mesh["Mesh parsing<br/>[sr_mesh.py]"]
  node_trees["Tree sprites<br/>[treesprites.py]"]
  node_icons["Map icons<br/>[icons.py]"]
  node_gameicons["Game icon data<br/>[gameicons.py]"]
  node_routing["Route planning<br/>[routing.py]"]
  node_mapcache[("Rendered map cache")]
end

subgraph group_preferences["Settings and updates"]
  node_paths["Game and data paths<br/>[paths.py]"]
  node_settings["Settings model<br/>[settings.py]"]
  node_settingswin["Settings window<br/>[settingswin.py]"]
  node_updater["Update checks<br/>[updater.py]"]
  node_version["Version metadata<br/>[version.py]"]
end

node_player(("Player"))
node_snowrunner["SnowRunner"]
node_gamefiles["Installed game files"]
node_savefiles["Game save files"]
node_user(("User"))

node_player -->|"drives"| node_snowrunner
node_snowrunner -->|"provides live process"| node_truckread
node_truckread -->|"reads memory"| node_memory
node_truckread -->|"finds RTTI class"| node_rtti
node_app -->|"reads position"| node_truckread
node_app -->|"detects region"| node_level
node_level -->|"uses map index"| node_maprender
node_maprender -->|"reads map assets"| node_gamefiles
node_maprender -->|"renders ground"| node_terrain
node_maprender -->|"parses meshes"| node_mesh
node_maprender -->|"builds tree sprites"| node_trees
node_app -->|"requests map"| node_maprender
node_app -->|"loads or saves"| node_mapcache
node_app -->|"uses marker icons"| node_icons
node_icons -->|"uses game icon data"| node_gameicons
node_app -->|"reads save state"| node_savedata
node_savedata -->|"reads saves"| node_savefiles
node_app -->|"plans routes"| node_routing
node_app -->|"syncs waypoints"| node_gwaypoint
node_user -->|"uses overlay"| node_app
node_user -->|"pans and pins"| node_bigmap
node_app -->|"opens big map"| node_bigmap
node_app -->|"loads settings"| node_settings
node_app -->|"opens settings"| node_settingswin
node_settingswin -->|"edits settings"| node_settings
node_app -->|"checks updates"| node_updater
node_updater -->|"checks version"| node_version
node_settings -->|"locates settings"| node_paths
node_maprender -->|"locates game data"| node_paths

click node_app "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/app.py"
click node_bigmap "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/app.py"
click node_truckread "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/reader.py"
click node_memory "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/procmem.py"
click node_rtti "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/rtti.py"
click node_gwaypoint "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/gamewp.py"
click node_savedata "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/savedata.py"
click node_level "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/levels.py"
click node_maprender "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/maprender.py"
click node_terrain "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/terrain.py"
click node_mesh "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/sr_mesh.py"
click node_trees "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/treesprites.py"
click node_icons "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/icons.py"
click node_gameicons "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/gameicons.py"
click node_routing "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/routing.py"
click node_paths "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/paths.py"
click node_settings "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/settings.py"
click node_settingswin "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/settingswin.py"
click node_updater "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/updater.py"
click node_version "https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/version.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_app,node_bigmap,node_user toneBlue
class node_truckread,node_memory,node_rtti,node_gwaypoint,node_savedata toneAmber
class node_level,node_maprender,node_terrain,node_mesh,node_trees,node_icons,node_gameicons,node_routing,node_mapcache toneMint
class node_paths,node_settings,node_settingswin,node_updater,node_version toneRose
class node_player,node_snowrunner,node_gamefiles,node_savefiles toneIndigo
```

## Components

### Overlay runtime

- [Overlay app](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/app.py): `minimap/app.py`
- [Big map and pins](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/app.py): `minimap/app.py`

### Game world data

- [Truck position reader](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/reader.py): `minimap/reader.py`
- [Process memory access](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/procmem.py): `minimap/procmem.py`
- [RTTI lookup](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/rtti.py): `minimap/rtti.py`
- [Game waypoints](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/gamewp.py): `minimap/gamewp.py`
- [Save data](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/savedata.py): `minimap/savedata.py`

### Map and navigation

- [Region detection and markers](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/levels.py): `minimap/levels.py`
- [Region map rendering](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/maprender.py): `minimap/maprender.py`
- [Terrain rendering](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/terrain.py): `minimap/terrain.py`
- [Mesh parsing](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/sr_mesh.py): `minimap/sr_mesh.py`
- [Tree sprites](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/treesprites.py): `minimap/treesprites.py`
- [Map icons](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/icons.py): `minimap/icons.py`
- [Game icon data](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/gameicons.py): `minimap/gameicons.py`
- [Route planning](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/routing.py): `minimap/routing.py`
- **Rendered map cache**

### Settings and updates

- [Game and data paths](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/paths.py): `minimap/paths.py`
- [Settings model](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/settings.py): `minimap/settings.py`
- [Settings window](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/settingswin.py): `minimap/settingswin.py`
- [Update checks](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/updater.py): `minimap/updater.py`
- [Version metadata](https://github.com/guywithpaper/snowrunner-minimap/blob/main/minimap/version.py): `minimap/version.py`

### Other components

- **Player**
- **SnowRunner**
- **Installed game files**
- **Game save files**
- **User**

## Connections

- Player → SnowRunner: drives (evidence: `README.md`)
- SnowRunner → Truck position reader: provides live process (evidence: `README.md`)
- Truck position reader → Process memory access: reads memory (evidence: `minimap/reader.py`)
- Truck position reader → RTTI lookup: finds RTTI class (evidence: `minimap/reader.py`)
- Overlay app → Truck position reader: reads position (evidence: `minimap/app.py`)
- Overlay app → Region detection and markers: detects region (evidence: `minimap/app.py`)
- Region detection and markers → Region map rendering: uses map index (evidence: `minimap/levels.py`)
- Region map rendering → Installed game files: reads map assets (evidence: `README.md`)
- Region map rendering → Terrain rendering: renders ground (evidence: `minimap/terrain.py`)
- Region map rendering → Mesh parsing: parses meshes (evidence: `minimap/sr_mesh.py`)
- Region map rendering → Tree sprites: builds tree sprites (evidence: `minimap/maprender.py`)
- Overlay app → Region map rendering: requests map (evidence: `minimap/app.py`)
- Overlay app → Rendered map cache: loads or saves (evidence: `README.md`)
- Overlay app → Map icons: uses marker icons (evidence: `minimap/app.py`)
- Map icons → Game icon data: uses game icon data (evidence: `minimap/icons.py`)
- Overlay app → Save data: reads save state (evidence: `minimap/app.py`)
- Save data → Game save files: reads saves (evidence: `minimap/savedata.py`)
- Overlay app → Route planning: plans routes (evidence: `minimap/app.py`)
- Overlay app → Game waypoints: syncs waypoints (evidence: `minimap/app.py`)
- User → Overlay app: uses overlay (evidence: `README.md`)
- User → Big map and pins: pans and pins (evidence: `README.md`)
- Overlay app → Big map and pins: opens big map (evidence: `README.md`)
- Overlay app → Settings model: loads settings (evidence: `minimap/app.py`)
- Overlay app → Settings window: opens settings (evidence: `minimap/app.py`)
- Settings window → Settings model: edits settings (evidence: `minimap/settingswin.py`)
- Overlay app → Update checks: checks updates (evidence: `minimap/app.py`)
- Update checks → Version metadata: checks version (evidence: `minimap/updater.py`)
- Settings model → Game and data paths: locates settings (evidence: `minimap/settings.py`)
- Region map rendering → Game and data paths: locates game data (evidence: `minimap/levels.py`)
