# shirtep/fly-mania architecture

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

- Interactive diagram: https://gitdiagram.com/shirtep/fly-mania
- Repository: https://github.com/shirtep/fly-mania

## Overview

fly-mania trains a fly-inspired controller to play osu!mania 4K, then uses that same inference path for evaluation and video rendering. The README documents the perception-to-action workflow, fixed connectome, training-only DAgger teacher, physical actuator, and official scoring. The graph also includes the major rendering and training subsystems. Some connections rely on README or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`src/viewer/video_renderer.py`](https://github.com/shirtep/fly-mania/blob/main/src/viewer/video_renderer.py) (Video renderer), [`scripts/train.py`](https://github.com/shirtep/fly-mania/blob/main/scripts/train.py) (Training entry), [`src/evaluation/play_map.py`](https://github.com/shirtep/fly-mania/blob/main/src/evaluation/play_map.py) (Map simulation), [`src/training/policy_runtime.py`](https://github.com/shirtep/fly-mania/blob/main/src/training/policy_runtime.py) (Policy runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training"]
  node_rollout_packs["Rollout packs<br/>[rollout_packs.py]"]
  node_teacher["DAgger teacher<br/>[teacher.py]"]
  node_rollout_loss["Rollout learning<br/>[rollout_loss.py]"]
  node_train_script["Training entry<br/>[train.py]"]
end

subgraph group_gameplay["Gameplay"]
  node_causal_map["Causal perception<br/>[causal_map.py]"]
  node_connectome["Fixed connectome<br/>[connectome.py]"]
  node_policy["Recurrent policy<br/>[policy.py]"]
  node_actuator["Physical actuator<br/>[actuator.py]"]
  node_runtime["Policy runtime<br/>[policy_runtime.py]"]
  node_scoring["Official scoring<br/>[scoring.py]"]
  node_play_map["Map simulation<br/>[play_map.py]"]
end

subgraph group_rendering["Rendering"]
  node_render_ui["Render interface<br/>[render_ui.py]"]
  node_video_renderer["Video renderer<br/>[video_renderer.py]"]
  node_scene_renderer["3D scene"]
  node_kinematics["Fly kinematics<br/>[fly_kinematics.py]"]
  node_hud["Connectome HUD<br/>[connectome_hud.py]"]
  node_neural_display["Neural display<br/>[neural_display.py]"]
  node_mania_screen["Game screen<br/>[mania_screen.py]"]
  node_fonts["Text fonts<br/>[fonts.py]"]
end

subgraph group_inputs["Maps and data"]
  node_corpus[("Training corpus<br/>[corpus.py]")]
  node_parser["Beatmap parser<br/>[osu_parser.py]"]
end

node_operator(("Trainer"))
node_map_user(("Map user"))

node_operator -.->|"starts training"| node_train_script
node_train_script -->|"loads corpus"| node_corpus
node_corpus -->|"parses maps"| node_parser
node_operator -.-> node_map_user
node_map_user -->|"selects map"| node_render_ui
node_render_ui -->|"requests render"| node_video_renderer
node_parser -->|"provides beatmap"| node_causal_map
node_train_script -->|"builds rollouts"| node_rollout_packs
node_rollout_packs -->|"uses chart"| node_causal_map
node_train_script -->|"trains against"| node_teacher
node_teacher -->|"plans key actions"| node_actuator
node_train_script -->|"optimizes with"| node_rollout_loss
node_rollout_loss -->|"advances policy"| node_runtime
node_runtime -->|"commands"| node_actuator
node_runtime -.->|"runs inference"| node_policy
node_runtime -.->|"updates neural state"| node_connectome
node_play_map -->|"parses map"| node_parser
node_play_map -->|"builds perception"| node_causal_map
node_play_map -.->|"advances policy"| node_runtime
node_play_map -->|"judges events"| node_scoring
node_video_renderer -->|"renders scene"| node_scene_renderer
node_scene_renderer -->|"uses motion"| node_kinematics
node_video_renderer -->|"draws overlay"| node_hud
node_video_renderer -->|"draws activity"| node_neural_display
node_video_renderer -->|"draws game screen"| node_mania_screen
node_hud -->|"loads text"| node_fonts
node_video_renderer -->|"captures simulation"| node_play_map

click node_corpus "https://github.com/shirtep/fly-mania/blob/main/src/training/corpus.py"
click node_parser "https://github.com/shirtep/fly-mania/blob/main/src/environment/osu_parser.py"
click node_causal_map "https://github.com/shirtep/fly-mania/blob/main/src/environment/causal_map.py"
click node_connectome "https://github.com/shirtep/fly-mania/blob/main/src/training/connectome.py"
click node_policy "https://github.com/shirtep/fly-mania/blob/main/src/training/policy.py"
click node_actuator "https://github.com/shirtep/fly-mania/blob/main/src/environment/actuator.py"
click node_runtime "https://github.com/shirtep/fly-mania/blob/main/src/training/policy_runtime.py"
click node_scoring "https://github.com/shirtep/fly-mania/blob/main/src/environment/scoring.py"
click node_play_map "https://github.com/shirtep/fly-mania/blob/main/src/evaluation/play_map.py"
click node_rollout_packs "https://github.com/shirtep/fly-mania/blob/main/src/training/rollout_packs.py"
click node_teacher "https://github.com/shirtep/fly-mania/blob/main/src/training/teacher.py"
click node_rollout_loss "https://github.com/shirtep/fly-mania/blob/main/src/training/rollout_loss.py"
click node_train_script "https://github.com/shirtep/fly-mania/blob/main/scripts/train.py"
click node_render_ui "https://github.com/shirtep/fly-mania/blob/main/scripts/render_ui.py"
click node_video_renderer "https://github.com/shirtep/fly-mania/blob/main/src/viewer/video_renderer.py"
click node_scene_renderer "https://github.com/shirtep/fly-mania/blob/main/src/viewer/scene_renderer_3d.py"
click node_kinematics "https://github.com/shirtep/fly-mania/blob/main/src/viewer/fly_kinematics.py"
click node_hud "https://github.com/shirtep/fly-mania/blob/main/src/viewer/connectome_hud.py"
click node_neural_display "https://github.com/shirtep/fly-mania/blob/main/src/viewer/neural_display.py"
click node_mania_screen "https://github.com/shirtep/fly-mania/blob/main/src/environment/mania_screen.py"
click node_fonts "https://github.com/shirtep/fly-mania/blob/main/src/fonts.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_rollout_packs,node_teacher,node_rollout_loss,node_train_script,node_map_user toneBlue
class node_causal_map,node_connectome,node_policy,node_actuator,node_runtime,node_scoring,node_play_map toneAmber
class node_render_ui,node_video_renderer,node_scene_renderer,node_kinematics,node_hud,node_neural_display,node_mania_screen,node_fonts toneMint
class node_corpus,node_parser toneRose
class node_operator toneIndigo
```

## Components

### Training

- [Rollout packs](https://github.com/shirtep/fly-mania/blob/main/src/training/rollout_packs.py): `src/training/rollout_packs.py`
- [DAgger teacher](https://github.com/shirtep/fly-mania/blob/main/src/training/teacher.py): `src/training/teacher.py`
- [Rollout learning](https://github.com/shirtep/fly-mania/blob/main/src/training/rollout_loss.py): `src/training/rollout_loss.py`
- [Training entry](https://github.com/shirtep/fly-mania/blob/main/scripts/train.py): `scripts/train.py`

### Gameplay

- [Causal perception](https://github.com/shirtep/fly-mania/blob/main/src/environment/causal_map.py): `src/environment/causal_map.py`
- [Fixed connectome](https://github.com/shirtep/fly-mania/blob/main/src/training/connectome.py): `src/training/connectome.py`
- [Recurrent policy](https://github.com/shirtep/fly-mania/blob/main/src/training/policy.py): `src/training/policy.py`
- [Physical actuator](https://github.com/shirtep/fly-mania/blob/main/src/environment/actuator.py): `src/environment/actuator.py`
- [Policy runtime](https://github.com/shirtep/fly-mania/blob/main/src/training/policy_runtime.py): `src/training/policy_runtime.py`
- [Official scoring](https://github.com/shirtep/fly-mania/blob/main/src/environment/scoring.py): `src/environment/scoring.py`
- [Map simulation](https://github.com/shirtep/fly-mania/blob/main/src/evaluation/play_map.py): `src/evaluation/play_map.py`

### Rendering

- [Render interface](https://github.com/shirtep/fly-mania/blob/main/scripts/render_ui.py): `scripts/render_ui.py`
- [Video renderer](https://github.com/shirtep/fly-mania/blob/main/src/viewer/video_renderer.py): `src/viewer/video_renderer.py`
- [3D scene](https://github.com/shirtep/fly-mania/blob/main/src/viewer/scene_renderer_3d.py): `src/viewer/scene_renderer_3d.py`
- [Fly kinematics](https://github.com/shirtep/fly-mania/blob/main/src/viewer/fly_kinematics.py): `src/viewer/fly_kinematics.py`
- [Connectome HUD](https://github.com/shirtep/fly-mania/blob/main/src/viewer/connectome_hud.py): `src/viewer/connectome_hud.py`
- [Neural display](https://github.com/shirtep/fly-mania/blob/main/src/viewer/neural_display.py): `src/viewer/neural_display.py`
- [Game screen](https://github.com/shirtep/fly-mania/blob/main/src/environment/mania_screen.py): `src/environment/mania_screen.py`
- [Text fonts](https://github.com/shirtep/fly-mania/blob/main/src/fonts.py): `src/fonts.py`

### Maps and data

- [Training corpus](https://github.com/shirtep/fly-mania/blob/main/src/training/corpus.py): `src/training/corpus.py`
- [Beatmap parser](https://github.com/shirtep/fly-mania/blob/main/src/environment/osu_parser.py): `src/environment/osu_parser.py`

### Other components

- **Trainer**
- **Map user**

## Connections

- Trainer → Training entry: starts training (evidence: `README.md`)
- Training entry → Training corpus: loads corpus (evidence: `scripts/train.py`)
- Training corpus → Beatmap parser: parses maps (evidence: `src/training/corpus.py`)
- Trainer → Map user
- Map user → Render interface: selects map (evidence: `README.md`)
- Render interface → Video renderer: requests render (evidence: `scripts/render_ui.py`)
- Beatmap parser → Causal perception: provides beatmap (evidence: `src/environment/causal_map.py`)
- Training entry → Rollout packs: builds rollouts (evidence: `scripts/train.py`)
- Rollout packs → Causal perception: uses chart (evidence: `src/training/rollout_packs.py`)
- Training entry → DAgger teacher: trains against (evidence: `scripts/train.py`)
- DAgger teacher → Physical actuator: plans key actions (evidence: `src/training/teacher.py`)
- Training entry → Rollout learning: optimizes with (evidence: `scripts/train.py`)
- Rollout learning → Policy runtime: advances policy (evidence: `src/training/rollout_loss.py`)
- Policy runtime → Physical actuator: commands (evidence: `src/training/policy_runtime.py`)
- Policy runtime → Recurrent policy: runs inference
- Policy runtime → Fixed connectome: updates neural state
- Map simulation → Beatmap parser: parses map (evidence: `src/evaluation/play_map.py`)
- Map simulation → Causal perception: builds perception (evidence: `src/evaluation/play_map.py`)
- Map simulation → Policy runtime: advances policy (evidence: `src/evaluation/play_map.py`)
- Map simulation → Official scoring: judges events (evidence: `src/evaluation/play_map.py`)
- Video renderer → 3D scene: renders scene (evidence: `src/viewer/video_renderer.py`)
- 3D scene → Fly kinematics: uses motion (evidence: `src/viewer/scene_renderer_3d.py`)
- Video renderer → Connectome HUD: draws overlay (evidence: `src/viewer/video_renderer.py`)
- Video renderer → Neural display: draws activity (evidence: `src/viewer/video_renderer.py`)
- Video renderer → Game screen: draws game screen (evidence: `src/viewer/video_renderer.py`)
- Connectome HUD → Text fonts: loads text (evidence: `src/viewer/connectome_hud.py`)
- Video renderer → Map simulation: captures simulation (evidence: `src/viewer/video_renderer.py`)
