How xamexer/koopapilot works
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: environment.py SMW environment · main.py Mode dispatch · retrojet_runner.py RetroJet adapter · vec_env.py Vector environments
Components 27
Runtime modes
- Mode dispatch
server/main.py - PPO training
server/training.py - BizHawk evaluation
server/evaluation.py - RetroJet evaluation
server/retrojet_evaluation.py - Saved-model demo
server/demo.py - Human play
server/human_play.py
SMW environment
- SMW environment
server/environment.py - Vector environments
server/vec_env.py - State observations
server/observation.py - Reward shaping
server/reward.py - Action table
server/games/smw/actions.py
Emulation backends
- Emulator launcher
server/emulator_manager.py - TCP server
server/socket_server.py - BizHawk agent
lua/smw_agent.lua - RetroJet adapter
server/games/smw/retrojet_runner.py - WRAM decoder
server/games/smw/memory.py
Policy learning
- PPO agent
server/agent.py - Model checkpoints
models
Metrics and dashboard
- Run metrics
server/metrics.py - Dashboard API
server/dashboard/app.py - Dashboard UI
server/dashboard/static/dashboard.js - Metrics files
logs
Other components
- User
- BizHawk
- RetroJet engine
- SMW ROM
roms - Savestates
savestates
Connections 34
- 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