# sacrappy/heylisten architecture

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

- Interactive diagram: https://gitdiagram.com/sacrappy/heylisten
- Repository: https://github.com/sacrappy/heylisten

## Overview

HeyListen is a Windows native port of a specific Switch 2 Ocarina of Time build. The user supplies their own game dump to the Builder, which fetches and verifies local tools, builds the game, and launches it; subsequent runs prepare shaders and render through the Vulkan backend. The graph also preserves documented runtime capabilities including saves, in-game controls, frame generation, and pipeline reuse. Several engine internals are represented at their enclosing directories because their implementation files were not sampled; their detailed call relationships therefore remain unverified.

Main entry points: [`engine/host/hos.h`](https://github.com/sacrappy/heylisten/blob/main/engine/host/hos.h) (Host runtime), [`engine/builder/py/hookshot_builder/core.py`](https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/core.py) (Build orchestration), [`engine/gpu/vk/vk_draw.cpp`](https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/vk_draw.cpp) (Vulkan renderer), [`engine/builder/py/hookshot_builder/window.py`](https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/window.py) (HeyListen Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build and launch"]
  node_builder["HeyListen Builder<br/>[window.py]"]
  node_builder_core["Build orchestration<br/>[core.py]"]
  node_tool_setup["Tool setup<br/>[setup_parts.py]"]
  node_game_build["Game build"]
end

subgraph group_translate["Recompiler"]
  node_decode["Maxwell decode"]
  node_translate_ir["IR translation<br/>[program.cpp]"]
  node_ir_opt["IR optimization"]
  node_spirv["SPIR-V emission"]
end

subgraph group_runtime["Game runtime"]
  node_game["HeyListen game<br/>[hos_main.c]"]
  node_host["Host runtime<br/>[hos.h]"]
end

subgraph group_graphics["Graphics"]
  node_nvn_native["Native NVN<br/>[nvn_native.c]"]
  node_gfx_bridge["Graphics bridge<br/>[GfxBridge.h]"]
  node_gfx_frontend["Graphics front end<br/>[hl_gfx.cpp]"]
  node_vulkan["Vulkan renderer<br/>[vk_draw.cpp]"]
  node_render_backend["Renderer backend"]
  node_pipeline_cache[("Pipeline cache<br/>[rx_pipecache.cpp]")]
end

subgraph group_features["Player features"]
  node_builder_saves["Save import/export<br/>[Saves.cs]"]
  node_save_files[("Game saves")]
  node_menu["In-game menu"]
  node_upscaling["Upscaling and framegen"]
end

node_player(("Player"))
node_game_dump["Own game dump"]
node_external_save[("Emulator save sources")]

node_player -->|"chooses dump"| node_builder
node_game_dump -->|"supplies dump"| node_builder
node_builder -.->|"starts build"| node_builder_core
node_builder_core -.->|"fetches tools"| node_tool_setup
node_builder_core -->|"builds game"| node_game_build
node_tool_setup -->|"provides tools"| node_game_build
node_game_build -->|"produces executable"| node_game
node_player -->|"launches game"| node_game
node_game -.->|"runs on"| node_host
node_host -.->|"dispatches shaders"| node_decode
node_decode -.->|"builds IR"| node_translate_ir
node_translate_ir -.->|"optimizes IR"| node_ir_opt
node_ir_opt -.->|"emits shaders"| node_spirv
node_host -.->|"issues NVN calls"| node_nvn_native
node_nvn_native -->|"records and replays"| node_render_backend
node_host -.->|"uses native graphics"| node_gfx_frontend
node_gfx_frontend -->|"creates bridge"| node_gfx_bridge
node_render_backend -->|"renders with Vulkan"| node_vulkan
node_vulkan -->|"reuses pipelines"| node_pipeline_cache
node_player -->|"imports or exports"| node_builder_saves
node_external_save -->|"provides save"| node_builder_saves
node_builder_saves -->|"backs up and writes"| node_save_files
node_player -->|"opens controls"| node_menu
node_menu -.->|"configures graphics"| node_upscaling
node_vulkan -.->|"runs shader effects"| node_upscaling

click node_builder "https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/window.py"
click node_builder_core "https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/core.py"
click node_tool_setup "https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/setup_parts.py"
click node_game_build "https://github.com/sacrappy/heylisten/tree/main/engine/nx2"
click node_game "https://github.com/sacrappy/heylisten/blob/main/engine/host/hos_main.c"
click node_host "https://github.com/sacrappy/heylisten/blob/main/engine/host/hos.h"
click node_decode "https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk/eden/shader_recompiler/frontend/maxwell"
click node_translate_ir "https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/eden/shader_recompiler/frontend/ir/program.cpp"
click node_ir_opt "https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk/eden/shader_recompiler/ir_opt"
click node_spirv "https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/eden/shader_recompiler/backend/spirv/spirv_emit_context.cpp"
click node_nvn_native "https://github.com/sacrappy/heylisten/blob/main/engine/host/nvn_native.c"
click node_gfx_bridge "https://github.com/sacrappy/heylisten/blob/main/engine/native/include/hl/bridge/GfxBridge.h"
click node_gfx_frontend "https://github.com/sacrappy/heylisten/blob/main/engine/native/src/c/hl_gfx.cpp"
click node_vulkan "https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/vk_draw.cpp"
click node_render_backend "https://github.com/sacrappy/heylisten/tree/main/engine/gpu/render"
click node_pipeline_cache "https://github.com/sacrappy/heylisten/blob/main/engine/gpu/render/rx_pipecache.cpp"
click node_builder_saves "https://github.com/sacrappy/heylisten/blob/main/engine/builder/HookshotBuilder/Saves.cs"
click node_save_files "https://github.com/sacrappy/heylisten/tree/main/engine/host"
click node_menu "https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk"
click node_upscaling "https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk/shaders"

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_builder,node_builder_core,node_tool_setup,node_game_build toneBlue
class node_decode,node_translate_ir,node_ir_opt,node_spirv,node_external_save toneAmber
class node_game,node_host toneMint
class node_nvn_native,node_gfx_bridge,node_gfx_frontend,node_vulkan,node_render_backend,node_pipeline_cache toneRose
class node_builder_saves,node_save_files,node_menu,node_upscaling,node_player,node_game_dump toneIndigo
```

## Components

### Build and launch

- [HeyListen Builder](https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/window.py): `engine/builder/py/hookshot_builder/window.py`
- [Build orchestration](https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/core.py): `engine/builder/py/hookshot_builder/core.py`
- [Tool setup](https://github.com/sacrappy/heylisten/blob/main/engine/builder/py/hookshot_builder/setup_parts.py): `engine/builder/py/hookshot_builder/setup_parts.py`
- [Game build](https://github.com/sacrappy/heylisten/tree/main/engine/nx2): `engine/nx2`

### Recompiler

- [Maxwell decode](https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk/eden/shader_recompiler/frontend/maxwell): `engine/gpu/vk/eden/shader_recompiler/frontend/maxwell`
- [IR translation](https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/eden/shader_recompiler/frontend/ir/program.cpp): `engine/gpu/vk/eden/shader_recompiler/frontend/ir/program.cpp`
- [IR optimization](https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk/eden/shader_recompiler/ir_opt): `engine/gpu/vk/eden/shader_recompiler/ir_opt`
- [SPIR-V emission](https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/eden/shader_recompiler/backend/spirv/spirv_emit_context.cpp): `engine/gpu/vk/eden/shader_recompiler/backend/spirv/spirv_emit_context.cpp`

### Game runtime

- [HeyListen game](https://github.com/sacrappy/heylisten/blob/main/engine/host/hos_main.c): `engine/host/hos_main.c`
- [Host runtime](https://github.com/sacrappy/heylisten/blob/main/engine/host/hos.h): `engine/host/hos.h`

### Graphics

- [Native NVN](https://github.com/sacrappy/heylisten/blob/main/engine/host/nvn_native.c): `engine/host/nvn_native.c`
- [Graphics bridge](https://github.com/sacrappy/heylisten/blob/main/engine/native/include/hl/bridge/GfxBridge.h): `engine/native/include/hl/bridge/GfxBridge.h`
- [Graphics front end](https://github.com/sacrappy/heylisten/blob/main/engine/native/src/c/hl_gfx.cpp): `engine/native/src/c/hl_gfx.cpp`
- [Vulkan renderer](https://github.com/sacrappy/heylisten/blob/main/engine/gpu/vk/vk_draw.cpp): `engine/gpu/vk/vk_draw.cpp`
- [Renderer backend](https://github.com/sacrappy/heylisten/tree/main/engine/gpu/render): `engine/gpu/render`
- [Pipeline cache](https://github.com/sacrappy/heylisten/blob/main/engine/gpu/render/rx_pipecache.cpp): `engine/gpu/render/rx_pipecache.cpp`

### Player features

- [Save import/export](https://github.com/sacrappy/heylisten/blob/main/engine/builder/HookshotBuilder/Saves.cs): `engine/builder/HookshotBuilder/Saves.cs`
- [Game saves](https://github.com/sacrappy/heylisten/tree/main/engine/host): `engine/host`
- [In-game menu](https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk): `engine/gpu/vk`
- [Upscaling and framegen](https://github.com/sacrappy/heylisten/tree/main/engine/gpu/vk/shaders): `engine/gpu/vk/shaders`

### Other components

- **Player**
- **Own game dump**
- **Emulator save sources**

## Connections

- Player → HeyListen Builder: chooses dump
- Own game dump → HeyListen Builder: supplies dump
- HeyListen Builder → Build orchestration: starts build (evidence: `engine/builder/py/hookshot_builder/window.py`)
- Build orchestration → Tool setup: fetches tools (evidence: `engine/builder/py/hookshot_builder/core.py`)
- Build orchestration → Game build: builds game
- Tool setup → Game build: provides tools
- Game build → HeyListen game: produces executable
- Player → HeyListen game: launches game
- HeyListen game → Host runtime: runs on (evidence: `engine/host/hos_main.c`)
- Host runtime → Maxwell decode: dispatches shaders
- Maxwell decode → IR translation: builds IR
- IR translation → IR optimization: optimizes IR
- IR optimization → SPIR-V emission: emits shaders
- Host runtime → Native NVN: issues NVN calls (evidence: `engine/host/nvn_native.c`)
- Native NVN → Renderer backend: records and replays (evidence: `engine/host/nvn_native.c`)
- Host runtime → Graphics front end: uses native graphics
- Graphics front end → Graphics bridge: creates bridge (evidence: `engine/native/src/c/hl_gfx.cpp`)
- Renderer backend → Vulkan renderer: renders with Vulkan
- Vulkan renderer → Pipeline cache: reuses pipelines
- Player → Save import/export: imports or exports
- Emulator save sources → Save import/export: provides save
- Save import/export → Game saves: backs up and writes
- Player → In-game menu: opens controls
- In-game menu → Upscaling and framegen: configures graphics
- Vulkan renderer → Upscaling and framegen: runs shader effects