# xamexer/koopapilot architecture

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

- Interactive diagram: https://gitdiagram.com/xamexer/koopapilot
- Repository: https://github.com/xamexer/koopapilot

## Overview

KoopaPilot trains and runs PPO policies for Super Mario World. Its principal loop resets one or more environments, obtains game-state observations, selects controller actions, and returns rewards and episode outcomes to the learner. The README documents two runtime backends: visible BizHawk via Lua/TCP and headless RetroJet via an SMW compatibility layer. Separate modes support evaluation, saved-model demos, live demos, and human play; metrics feed a Flask dashboard. The graph preserves these documented capabilities, while links through unsampled mode implementations are limited to documented dispatch and subsystem relationships.

Main entry points: [`server/environment.py`](https://github.com/xamexer/koopapilot/blob/main/server/environment.py) (SMW environment), [`server/main.py`](https://github.com/xamexer/koopapilot/blob/main/server/main.py) (Mode dispatch), [`server/games/smw/retrojet_runner.py`](https://github.com/xamexer/koopapilot/blob/main/server/games/smw/retrojet_runner.py) (RetroJet adapter), [`server/vec_env.py`](https://github.com/xamexer/koopapilot/blob/main/server/vec_env.py) (Vector environments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Runtime modes"]
  node_main["Mode dispatch<br/>[main.py]"]
  node_training["PPO training<br/>[training.py]"]
  node_evaluation["BizHawk evaluation<br/>[evaluation.py]"]
  node_retro_eval["RetroJet evaluation"]
  node_demo["Saved-model demo<br/>[demo.py]"]
  node_human["Human play<br/>[human_play.py]"]
end

subgraph group_environment["SMW environment"]
  node_environment["SMW environment<br/>[environment.py]"]
  node_vec_env["Vector environments<br/>[vec_env.py]"]
  node_observation["State observations<br/>[observation.py]"]
  node_reward["Reward shaping<br/>[reward.py]"]
  node_actions["Action table<br/>[actions.py]"]
end

subgraph group_backends["Emulation backends"]
  node_emulator_manager["Emulator launcher"]
  node_socket["TCP server<br/>[socket_server.py]"]
  node_lua["BizHawk agent<br/>[smw_agent.lua]"]
  node_retro_runner["RetroJet adapter<br/>[retrojet_runner.py]"]
  node_memory["WRAM decoder<br/>[memory.py]"]
end

subgraph group_learning["Policy learning"]
  node_agent["PPO agent<br/>[agent.py]"]
  node_checkpoint["Model checkpoints"]
end

subgraph group_observability["Metrics and dashboard"]
  node_metrics["Run metrics<br/>[metrics.py]"]
  node_dashboard["Dashboard API<br/>[app.py]"]
  node_browser["Dashboard UI<br/>[dashboard.js]"]
  node_logs["Metrics files"]
end

node_user(("User"))
node_bizhawk["BizHawk"]
node_retrojet["RetroJet engine"]
node_rom["SMW ROM"]
node_savestates["Savestates"]

node_user -->|"selects mode"| node_main
node_main -->|"dispatches"| node_training
node_main -->|"dispatches"| node_evaluation
node_main -->|"dispatches"| node_retro_eval
node_main -->|"dispatches"| node_demo
node_main -->|"dispatches"| node_human
node_training -->|"creates environments"| node_vec_env
node_evaluation -->|"uses environments"| node_vec_env
node_demo -->|"uses environments"| node_vec_env
node_human -->|"plays through"| node_environment
node_vec_env -->|"steps"| node_environment
node_environment -->|"builds observations"| node_observation
node_environment -->|"calculates reward"| node_reward
node_environment -->|"maps actions"| node_actions
node_environment -->|"uses TCP backend"| node_socket
node_emulator_manager -->|"launches"| node_bizhawk
node_emulator_manager -->|"loads"| node_rom
node_emulator_manager -->|"starts script"| node_lua
node_lua -->|"sends state and input"| node_socket
node_socket -->|"delivers state"| node_environment
node_environment -.->|"uses headless backend"| node_retro_runner
node_retro_runner -->|"runs frames and memory reads"| node_retrojet
node_retro_runner -->|"decodes captures"| node_memory
node_retro_runner -->|"loads configured states"| node_savestates
node_training -->|"trains policy"| node_agent
node_agent -->|"saves and loads"| node_checkpoint
node_agent -->|"logs progress"| node_metrics
node_metrics -->|"writes run data"| node_logs
node_main -->|"starts dashboard"| node_dashboard
node_dashboard -->|"reads run metrics"| node_metrics
node_browser -->|"fetches metrics"| node_dashboard
node_demo -->|"loads policy"| node_checkpoint
node_evaluation -->|"loads policy"| node_checkpoint
node_retro_eval -->|"loads policy"| node_checkpoint

click node_main "https://github.com/xamexer/koopapilot/blob/main/server/main.py"
click node_training "https://github.com/xamexer/koopapilot/blob/main/server/training.py"
click node_evaluation "https://github.com/xamexer/koopapilot/blob/main/server/evaluation.py"
click node_retro_eval "https://github.com/xamexer/koopapilot/blob/main/server/retrojet_evaluation.py"
click node_demo "https://github.com/xamexer/koopapilot/blob/main/server/demo.py"
click node_human "https://github.com/xamexer/koopapilot/blob/main/server/human_play.py"
click node_environment "https://github.com/xamexer/koopapilot/blob/main/server/environment.py"
click node_vec_env "https://github.com/xamexer/koopapilot/blob/main/server/vec_env.py"
click node_observation "https://github.com/xamexer/koopapilot/blob/main/server/observation.py"
click node_reward "https://github.com/xamexer/koopapilot/blob/main/server/reward.py"
click node_actions "https://github.com/xamexer/koopapilot/blob/main/server/games/smw/actions.py"
click node_emulator_manager "https://github.com/xamexer/koopapilot/blob/main/server/emulator_manager.py"
click node_socket "https://github.com/xamexer/koopapilot/blob/main/server/socket_server.py"
click node_lua "https://github.com/xamexer/koopapilot/blob/main/lua/smw_agent.lua"
click node_retro_runner "https://github.com/xamexer/koopapilot/blob/main/server/games/smw/retrojet_runner.py"
click node_memory "https://github.com/xamexer/koopapilot/blob/main/server/games/smw/memory.py"
click node_agent "https://github.com/xamexer/koopapilot/blob/main/server/agent.py"
click node_checkpoint "https://github.com/xamexer/koopapilot/tree/main/models"
click node_metrics "https://github.com/xamexer/koopapilot/blob/main/server/metrics.py"
click node_dashboard "https://github.com/xamexer/koopapilot/blob/main/server/dashboard/app.py"
click node_browser "https://github.com/xamexer/koopapilot/blob/main/server/dashboard/static/dashboard.js"
click node_logs "https://github.com/xamexer/koopapilot/tree/main/logs"
click node_rom "https://github.com/xamexer/koopapilot/tree/main/roms"
click node_savestates "https://github.com/xamexer/koopapilot/tree/main/savestates"

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_training,node_evaluation,node_retro_eval,node_demo,node_human,node_user toneBlue
class node_environment,node_vec_env,node_observation,node_reward,node_actions toneAmber
class node_emulator_manager,node_socket,node_lua,node_retro_runner,node_memory toneMint
class node_agent,node_checkpoint toneRose
class node_metrics,node_dashboard,node_browser,node_logs,node_bizhawk,node_retrojet toneIndigo
class node_rom,node_savestates toneTeal
```

## Components

### Runtime modes

- [Mode dispatch](https://github.com/xamexer/koopapilot/blob/main/server/main.py): `server/main.py`
- [PPO training](https://github.com/xamexer/koopapilot/blob/main/server/training.py): `server/training.py`
- [BizHawk evaluation](https://github.com/xamexer/koopapilot/blob/main/server/evaluation.py): `server/evaluation.py`
- [RetroJet evaluation](https://github.com/xamexer/koopapilot/blob/main/server/retrojet_evaluation.py): `server/retrojet_evaluation.py`
- [Saved-model demo](https://github.com/xamexer/koopapilot/blob/main/server/demo.py): `server/demo.py`
- [Human play](https://github.com/xamexer/koopapilot/blob/main/server/human_play.py): `server/human_play.py`

### SMW environment

- [SMW environment](https://github.com/xamexer/koopapilot/blob/main/server/environment.py): `server/environment.py`
- [Vector environments](https://github.com/xamexer/koopapilot/blob/main/server/vec_env.py): `server/vec_env.py`
- [State observations](https://github.com/xamexer/koopapilot/blob/main/server/observation.py): `server/observation.py`
- [Reward shaping](https://github.com/xamexer/koopapilot/blob/main/server/reward.py): `server/reward.py`
- [Action table](https://github.com/xamexer/koopapilot/blob/main/server/games/smw/actions.py): `server/games/smw/actions.py`

### Emulation backends

- [Emulator launcher](https://github.com/xamexer/koopapilot/blob/main/server/emulator_manager.py): `server/emulator_manager.py`
- [TCP server](https://github.com/xamexer/koopapilot/blob/main/server/socket_server.py): `server/socket_server.py`
- [BizHawk agent](https://github.com/xamexer/koopapilot/blob/main/lua/smw_agent.lua): `lua/smw_agent.lua`
- [RetroJet adapter](https://github.com/xamexer/koopapilot/blob/main/server/games/smw/retrojet_runner.py): `server/games/smw/retrojet_runner.py`
- [WRAM decoder](https://github.com/xamexer/koopapilot/blob/main/server/games/smw/memory.py): `server/games/smw/memory.py`

### Policy learning

- [PPO agent](https://github.com/xamexer/koopapilot/blob/main/server/agent.py): `server/agent.py`
- [Model checkpoints](https://github.com/xamexer/koopapilot/tree/main/models): `models`

### Metrics and dashboard

- [Run metrics](https://github.com/xamexer/koopapilot/blob/main/server/metrics.py): `server/metrics.py`
- [Dashboard API](https://github.com/xamexer/koopapilot/blob/main/server/dashboard/app.py): `server/dashboard/app.py`
- [Dashboard UI](https://github.com/xamexer/koopapilot/blob/main/server/dashboard/static/dashboard.js): `server/dashboard/static/dashboard.js`
- [Metrics files](https://github.com/xamexer/koopapilot/tree/main/logs): `logs`

### Other components

- **User**
- **BizHawk**
- **RetroJet engine**
- [SMW ROM](https://github.com/xamexer/koopapilot/tree/main/roms): `roms`
- [Savestates](https://github.com/xamexer/koopapilot/tree/main/savestates): `savestates`

## Connections

- User → Mode dispatch: selects mode
- Mode dispatch → PPO training: dispatches
- Mode dispatch → BizHawk evaluation: dispatches
- Mode dispatch → RetroJet evaluation: dispatches
- Mode dispatch → Saved-model demo: dispatches
- Mode dispatch → Human play: dispatches
- PPO training → Vector environments: creates environments
- BizHawk evaluation → Vector environments: uses environments
- Saved-model demo → Vector environments: uses environments
- Human play → SMW environment: plays through
- Vector environments → SMW environment: steps
- SMW environment → State observations: builds observations
- SMW environment → Reward shaping: calculates reward
- SMW environment → Action table: maps actions
- SMW environment → TCP server: uses TCP backend
- Emulator launcher → BizHawk: launches
- Emulator launcher → SMW ROM: loads
- Emulator launcher → BizHawk agent: starts script
- BizHawk agent → TCP server: sends state and input
- TCP server → SMW environment: delivers state
- SMW environment → RetroJet adapter: uses headless backend
- RetroJet adapter → RetroJet engine: runs frames and memory reads
- RetroJet adapter → WRAM decoder: decodes captures
- RetroJet adapter → Savestates: loads configured states
- PPO training → PPO agent: trains policy
- PPO agent → Model checkpoints: saves and loads
- PPO agent → Run metrics: logs progress
- Run metrics → Metrics files: writes run data
- Mode dispatch → Dashboard API: starts dashboard
- Dashboard API → Run metrics: reads run metrics
- Dashboard UI → Dashboard API: fetches metrics
- Saved-model demo → Model checkpoints: loads policy
- BizHawk evaluation → Model checkpoints: loads policy
- RetroJet evaluation → Model checkpoints: loads policy