# rainchus/quest64-recomp architecture

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

- Interactive diagram: https://gitdiagram.com/rainchus/quest64-recomp
- Repository: https://github.com/rainchus/quest64-recomp

## Overview

1. **What this repo is**
   - This is a **native Quest 64 port built by static recompilation**, not an emulator.
   - The shipped code is the application/runtime; the **original US Quest 64 ROM and assets are user-provided** and loaded at runtime.

2. **Top-level architecture**
   - The repo splits into three major runtime domains:
     - **`src/main`**: application bootstrap, platform integration, rendering setup.
     - **`src/game`**: game-facing systems, config, input, save/load, ROM handling, and recompilation hooks.
     - **`src/ui`**: launcher, config menus, mod UI, and the custom UI framework.
   - Supporting code lives in **`include/`**, **`patches/`**, **`lib/`**, and **`assets/`**.

3. **Startup and platform boundary**
   - `src/main/main.cpp` is the entry point for the native app.
   - Platform-specific support is split across desktop targets, with extra glue for **Windows/macOS/Linux** and packaging in `.github/`, `flatpak/`, and Linux/macOS support files.
   - The startup path initializes the runtime, registers overlays/patches, and wires the game systems to the renderer and UI.

4. **Rendering subsystem**
   - The rendering engine is **RT64** (`lib/rt64`), which is the main graphics backend for the port.
   - `src/main/rt64_render_context.cpp` and shader files in `shaders/` define the rendering bridge and UI/interface rendering path.
   - The README’s feature set shows RT64 is responsible for the project’s high-framerate, widescreen, and visual-enhancement behavior.

5. **Game/runtime subsystem**
   - `src/game/` contains the Quest 64-specific logic that sits between the recompilation output and the native app.
   - Key responsibilities include:
     - **configuration** (`config.cpp`)
     - **controls/input** (`controls.cpp`, `input.cpp`)
     - **debug and quicksaving**
     - **ROM decompression**
     - **scene and data tables**
     - **API shims** (`recomp_api.cpp`, `recomp_data_api.cpp`, `recomp_actor_api.cpp`)
   - This layer is the main boundary where recompilation-era calls are adapted into native systems.

6. **Patch and overlay system**
   - `patches/` contains source and linker metadata for game patches, hooks, and replacement functions.
   - Files like `main.c`, `graphics.h`, `input.h`, `sound.h`, and `ui_funcs.h` indicate this repo patches multiple game subsystems rather than only graphics.
   - `register_overlays.cpp` and `register_patches.cpp` show that overlays are registered into the runtime explicitly during startup.

7. **UI subsystem**
   - `src/ui/` is a substantial standalone UI layer built on **RmlUi**.
   - It includes:
     - a **custom UI core and element model** in `src/ui/core` and `src/ui/elements`
     - **launcher**, **config menus**, **mod menus**, **mod detail panels**, **installer**, and **prompt dialogs**
     - API glue for events, images, renderer integration, and state management
   - This UI is not just cosmetic; it drives config, mod installation, and launcher flow before gameplay starts.

8. **UI data and styling pipeline**
   - The UI markup lives in `assets/*.rml` and nested config menu files.
   - Styling is split between **RML stylesheets** and a larger **SCSS source tree** under `assets/scss/`, which appears to generate the final visual theme for menus.
   - Fonts, icons, and prompt assets are bundled alongside the markup, making the launcher/config experience self-contained.

9. **Input and control flow**
   - Input is handled across game and UI layers:
     - the game layer maps controller/keyboard/mouse state into gameplay input
     - the UI layer handles menu interactions and clickable widgets
   - `recompcontrollerdb.txt` and `include/recomp_input.h` suggest a normalized controller mapping layer.
   - The included `GamepadMotionHelpers` library indicates the codebase is prepared for motion/gyro-related controller support, even if that feature is still evolving.

10. **Config, saves, and local state**
   - Game and UI settings are persisted through the runtime config system, with save/config paths described in the README.
   - Portable mode is supported by placing `portable.txt` beside the executable, which changes where saves, configs, and mods are stored.
   - This means the app has a clear separation between **ephemeral runtime state**, **user config**, and **persistent save data**.

11. **Mod support architecture**
   - Mod installation and management are first-class subsystems in `src/ui/ui_mod_*` and `mods/`.
   - The app supports installing mods/texture packs, toggling them in UI, and loading built-in mods such as the d-pad-related mod listed in `mods/`.
   - The mod system is part of the user-facing UI, but it ultimately feeds into the game/runtime layer as content and behavior overrides.

12. **Build, dependency, and packaging boundaries**
   - The project is built with **CMake** and includes some custom build metadata (`CMakeLists.txt`, `BUILDING.md`, `CMakeSettings.json`).
   - Third-party libraries are vendored in `lib/`, including **RmlUi**, **RT64**, **lunasvg**, **FreeType support**, and helper libraries used by the runtime.
   - CI and release packaging are handled separately in `.github/`, with platform-specific wrappers for Linux, macOS, Flatpak, and desktop integration.

13. **Useful diagram framing**
   - A clean architecture diagram should show:
     - **User-provided ROM/assets** entering the app boundary
     - **Startup/bootstrap** initializing runtime, renderer, and UI
     - **UI/config/mod management** as a user-facing control plane
     - **Game/recompilation runtime** as the execution core
     - **RT64 rendering** as the graphics backend
     - **patches/overlays** as the bridge for game-specific modifications
     - **persistent save/config storage** as a separate local-state boundary

Main entry points: [`src/game/recomp_api.cpp`](https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_api.cpp) (Recomp API), [`src/main/main.cpp`](https://github.com/rainchus/quest64-recomp/blob/main/src/main/main.cpp) (Main), [`src/ui/core/ui_context.cpp`](https://github.com/rainchus/quest64-recomp/blob/main/src/ui/core/ui_context.cpp) (UI context), [`patches/main.c`](https://github.com/rainchus/quest64-recomp/blob/main/patches/main.c) (Patch code)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_game_config["Config<br/>game settings<br/>[config.cpp]"]
  node_src_game_controls_input["Input<br/>control mapping<br/>[input.cpp]"]
  node_src_game_debug_quicksave["Debug save<br/>runtime tools<br/>[debug.cpp]"]
  node_src_game_rom_decompression["ROM decode<br/>asset loader"]
  node_src_game_recomp_api["Recomp API<br/>api shim<br/>[recomp_api.cpp]"]
  node_src_game_recomp_actor_api["Actor API<br/>api shim"]
  node_src_game_recomp_data_api["Data API<br/>api shim"]
end

subgraph group_ui["UI"]
  node_src_ui_ui_launcher["Launcher<br/>[ui_launcher.cpp]"]
  node_src_ui_ui_config["Config UI<br/>settings ui<br/>[ui_config.cpp]"]
  node_src_ui_ui_mod_menu["Mods<br/>mod manager<br/>[ui_mod_menu.cpp]"]
  node_src_ui_core_ui_context["UI context<br/>ui core<br/>[ui_context.cpp]"]
  node_src_ui_ui_renderer["UI renderer<br/>rmlui bridge<br/>[ui_renderer.cpp]"]
end

subgraph group_platform["Platform"]
  node_src_main_main["Main<br/>entrypoint<br/>[main.cpp]"]
  node_src_main_support["Support<br/>platform glue<br/>[support.cpp]"]
  node_src_main_register_overlays["Overlays<br/>overlay reg"]
  node_src_main_register_patches["Patches<br/>patch reg"]
  node_src_main_rt64_render_context["RT64 bridge<br/>render bridge"]
  node_patches_main["Patch code<br/>game patches<br/>[main.c]"]
  node_patches_input["Input patch<br/>patch hooks<br/>[input.h]"]
  node_patches_graphics["Graphics patch<br/>patch hooks<br/>[graphics.h]"]
end

subgraph group_assets["Assets"]
  node_assets_launcher["Launcher RML<br/>ui markup<br/>[launcher.rml]"]
  node_assets_config_menu["Config RML<br/>ui markup<br/>[config_menu.rml]"]
  node_assets_scss["Theme SCSS<br/>ui styling<br/>[main.scss]"]
  node_assets_shaders["Shaders<br/>[InterfaceVS.hlsl]"]
end

subgraph group_vendor["Vendor"]
  node_lib_rt64[("RT64<br/>graphics backend")]
  node_lib_rmlui[("RmlUi<br/>ui library")]
end

node_user_rom_assets["ROM + assets<br/>user input"]

node_user_rom_assets -->|"load"| node_src_main_main
node_src_main_main -->|"init"| node_src_main_support
node_src_main_main -->|"register"| node_src_main_register_overlays
node_src_main_main -->|"register"| node_src_main_register_patches
node_src_main_main -->|"bind"| node_src_main_rt64_render_context
node_src_main_main -->|"start UI"| node_src_ui_core_ui_context
node_src_main_main -->|"launch game"| node_src_game_recomp_api
node_src_main_rt64_render_context -->|"uses"| node_lib_rt64
node_src_ui_core_ui_context -->|"uses"| node_lib_rmlui
node_src_ui_ui_renderer -->|"draws via"| node_lib_rt64
node_src_ui_ui_launcher -->|"loads"| node_assets_launcher
node_src_ui_ui_config -->|"loads"| node_assets_config_menu
node_src_ui_ui_renderer -->|"styles"| node_assets_scss
node_src_ui_ui_launcher -->|"runs on"| node_src_ui_core_ui_context
node_src_ui_ui_config -->|"runs on"| node_src_ui_core_ui_context
node_src_ui_ui_mod_menu -->|"runs on"| node_src_ui_core_ui_context
node_src_ui_ui_mod_menu -->|"edits"| node_src_game_config
node_src_game_recomp_api -->|"delegates"| node_src_game_recomp_actor_api
node_src_game_recomp_api -->|"delegates"| node_src_game_recomp_data_api
node_src_game_recomp_api -->|"reads"| node_src_game_config
node_src_game_recomp_api -->|"reads"| node_src_game_controls_input
node_src_game_recomp_api -->|"loads"| node_src_game_rom_decompression
node_src_game_recomp_api -->|"uses"| node_src_game_debug_quicksave
node_src_game_controls_input -.->|"patched by"| node_patches_input
node_src_main_rt64_render_context -.->|"patched by"| node_patches_graphics
node_src_game_recomp_api -.->|"overridden by"| node_patches_main
node_patches_main -->|"includes"| node_patches_input
node_patches_main -->|"includes"| node_patches_graphics
node_patches_main -->|"hooks UI"| node_src_ui_ui_renderer
node_src_ui_ui_config -->|"persists"| node_src_game_config
node_src_ui_ui_mod_menu -->|"feeds"| node_src_game_recomp_api

click node_src_main_main "https://github.com/rainchus/quest64-recomp/blob/main/src/main/main.cpp"
click node_src_main_support "https://github.com/rainchus/quest64-recomp/blob/main/src/main/support.cpp"
click node_src_main_register_overlays "https://github.com/rainchus/quest64-recomp/blob/main/src/main/register_overlays.cpp"
click node_src_main_register_patches "https://github.com/rainchus/quest64-recomp/blob/main/src/main/register_patches.cpp"
click node_src_main_rt64_render_context "https://github.com/rainchus/quest64-recomp/blob/main/src/main/rt64_render_context.cpp"
click node_src_game_config "https://github.com/rainchus/quest64-recomp/blob/main/src/game/config.cpp"
click node_src_game_controls_input "https://github.com/rainchus/quest64-recomp/blob/main/src/game/input.cpp"
click node_src_game_debug_quicksave "https://github.com/rainchus/quest64-recomp/blob/main/src/game/debug.cpp"
click node_src_game_rom_decompression "https://github.com/rainchus/quest64-recomp/blob/main/src/game/rom_decompression.cpp"
click node_src_game_recomp_api "https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_api.cpp"
click node_src_game_recomp_actor_api "https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_actor_api.cpp"
click node_src_game_recomp_data_api "https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_data_api.cpp"
click node_src_ui_ui_launcher "https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_launcher.cpp"
click node_src_ui_ui_config "https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_config.cpp"
click node_src_ui_ui_mod_menu "https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_mod_menu.cpp"
click node_src_ui_core_ui_context "https://github.com/rainchus/quest64-recomp/blob/main/src/ui/core/ui_context.cpp"
click node_src_ui_ui_renderer "https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_renderer.cpp"
click node_lib_rt64 "https://github.com/rainchus/quest64-recomp/tree/main/lib/rt64"
click node_lib_rmlui "https://github.com/rainchus/quest64-recomp/tree/main/lib/RmlUi"
click node_patches_main "https://github.com/rainchus/quest64-recomp/blob/main/patches/main.c"
click node_patches_input "https://github.com/rainchus/quest64-recomp/blob/main/patches/input.h"
click node_patches_graphics "https://github.com/rainchus/quest64-recomp/blob/main/patches/graphics.h"
click node_assets_launcher "https://github.com/rainchus/quest64-recomp/blob/main/assets/launcher.rml"
click node_assets_config_menu "https://github.com/rainchus/quest64-recomp/blob/main/assets/config_menu.rml"
click node_assets_scss "https://github.com/rainchus/quest64-recomp/blob/main/assets/scss/main.scss"
click node_assets_shaders "https://github.com/rainchus/quest64-recomp/blob/main/shaders/InterfaceVS.hlsl"

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_src_game_config,node_src_game_controls_input,node_src_game_debug_quicksave,node_src_game_rom_decompression,node_src_game_recomp_api,node_src_game_recomp_actor_api,node_src_game_recomp_data_api toneBlue
class node_src_ui_ui_launcher,node_src_ui_ui_config,node_src_ui_ui_mod_menu,node_src_ui_core_ui_context,node_src_ui_ui_renderer toneAmber
class node_src_main_main,node_src_main_support,node_src_main_register_overlays,node_src_main_register_patches,node_src_main_rt64_render_context,node_patches_main,node_patches_input,node_patches_graphics toneMint
class node_assets_launcher,node_assets_config_menu,node_assets_scss,node_assets_shaders toneRose
class node_lib_rt64,node_lib_rmlui toneIndigo
class node_user_rom_assets toneNeutral
```

## Components

### Runtime

Native app, game systems, and rendering bridge

- [Config](https://github.com/rainchus/quest64-recomp/blob/main/src/game/config.cpp): game settings · Game-side configuration state and persistence · `src/game/config.cpp`
- [Input](https://github.com/rainchus/quest64-recomp/blob/main/src/game/input.cpp): control mapping · Normalizes controller, keyboard, and mouse input · `src/game/input.cpp`
- [Debug save](https://github.com/rainchus/quest64-recomp/blob/main/src/game/debug.cpp): runtime tools · Debugging and quicksaving support · `src/game/debug.cpp`
- [ROM decode](https://github.com/rainchus/quest64-recomp/blob/main/src/game/rom_decompression.cpp): asset loader · Decompresses user-provided ROM data for runtime use · `src/game/rom_decompression.cpp`
- [Recomp API](https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_api.cpp): api shim · General adapter layer for recompilation-era calls · `src/game/recomp_api.cpp`
- [Actor API](https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_actor_api.cpp): api shim · Actor-specific recompilation bridge · `src/game/recomp_actor_api.cpp`
- [Data API](https://github.com/rainchus/quest64-recomp/blob/main/src/game/recomp_data_api.cpp): api shim · Data access bridge for recompilation output · `src/game/recomp_data_api.cpp`

### UI

Launcher, config, mod management, and custom widgets

- [Launcher](https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_launcher.cpp): launcher ui · Pre-game launcher and entry UI · `src/ui/ui_launcher.cpp`
- [Config UI](https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_config.cpp): settings ui · Main configuration menus and option flow · `src/ui/ui_config.cpp`
- [Mods](https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_mod_menu.cpp): mod manager · Mod browsing, toggles, and installation entry point · `src/ui/ui_mod_menu.cpp`
- [UI context](https://github.com/rainchus/quest64-recomp/blob/main/src/ui/core/ui_context.cpp): ui core · Core UI state, resource lifetime, and integration · `src/ui/core/ui_context.cpp`
- [UI renderer](https://github.com/rainchus/quest64-recomp/blob/main/src/ui/ui_renderer.cpp): rmlui bridge · Renders the custom UI layer through the rendering backend · `src/ui/ui_renderer.cpp`

### Platform

Startup, overlays, patches, and OS integration

- [Main](https://github.com/rainchus/quest64-recomp/blob/main/src/main/main.cpp): entrypoint · Native application entry and bootstrap · `src/main/main.cpp`
- [Support](https://github.com/rainchus/quest64-recomp/blob/main/src/main/support.cpp): platform glue · Shared desktop/runtime integration helpers · `src/main/support.cpp`
- [Overlays](https://github.com/rainchus/quest64-recomp/blob/main/src/main/register_overlays.cpp): overlay reg · Registers overlay modules into the runtime · `src/main/register_overlays.cpp`
- [Patches](https://github.com/rainchus/quest64-recomp/blob/main/src/main/register_patches.cpp): patch reg · Registers game patches during startup · `src/main/register_patches.cpp`
- [RT64 bridge](https://github.com/rainchus/quest64-recomp/blob/main/src/main/rt64_render_context.cpp): render bridge · Connects the app runtime to the RT64 renderer · `src/main/rt64_render_context.cpp`
- [Patch code](https://github.com/rainchus/quest64-recomp/blob/main/patches/main.c): game patches · Source and hooks that replace or augment original game functions · `patches/main.c`
- [Input patch](https://github.com/rainchus/quest64-recomp/blob/main/patches/input.h): patch hooks · Input-related patch hooks and overrides · `patches/input.h`
- [Graphics patch](https://github.com/rainchus/quest64-recomp/blob/main/patches/graphics.h): patch hooks · Rendering-related patch hooks and overrides · `patches/graphics.h`

### Assets

Markup, styles, shaders, and bundled UI resources

- [Launcher RML](https://github.com/rainchus/quest64-recomp/blob/main/assets/launcher.rml): ui markup · Launcher layout markup · `assets/launcher.rml`
- [Config RML](https://github.com/rainchus/quest64-recomp/blob/main/assets/config_menu.rml): ui markup · Configuration menu markup set · `assets/config_menu.rml`
- [Theme SCSS](https://github.com/rainchus/quest64-recomp/blob/main/assets/scss/main.scss): ui styling · Source stylesheet tree for the custom launcher and menus · `assets/scss/main.scss`
- [Shaders](https://github.com/rainchus/quest64-recomp/blob/main/shaders/InterfaceVS.hlsl): gpu shaders · Interface shader pair for the rendering bridge · `shaders/InterfaceVS.hlsl`

### Vendor

Bundled third-party libraries and support code

- [RT64](https://github.com/rainchus/quest64-recomp/tree/main/lib/rt64): graphics backend · Main rendering engine for the port · `lib/rt64`
- [RmlUi](https://github.com/rainchus/quest64-recomp/tree/main/lib/RmlUi): ui library · Underlying immediate UI framework used by the launcher and menus · `lib/RmlUi`

### Other components

- **ROM + assets**: user input · User-provided Quest 64 ROM and original assets loaded at runtime

## Connections

- ROM + assets → Main: load · User ROM and assets enter through the native bootstrap
- Main → Support: init · Bootstraps platform-specific support and runtime helpers
- Main → Overlays: register · Installs overlay modules into the runtime
- Main → Patches: register · Installs patch set during startup
- Main → RT64 bridge: bind · Connects the app to the rendering backend
- Main → UI context: start UI · Creates the UI runtime context
- Main → Recomp API: launch game · Transfers control into the recompilation runtime
- RT64 bridge → RT64: uses · Rendering bridge targets RT64
- UI context → RmlUi: uses · UI context builds on RmlUi
- UI renderer → RT64: draws via · UI rendering is composited through RT64
- Launcher → Launcher RML: loads · Launcher markup defines the startup UI
- Config UI → Config RML: loads · Config screens are driven by RML markup
- UI renderer → Theme SCSS: styles · Custom theme is sourced from SCSS-generated styling
- Launcher → UI context: runs on · Launcher executes within the shared UI core
- Config UI → UI context: runs on · Config menus use the shared UI core
- Mods → UI context: runs on · Mod management UI uses the shared UI core
- Mods → Config: edits · Mod and launcher choices feed runtime configuration
- Recomp API → Actor API: delegates · General API layer dispatches actor-specific calls
- Recomp API → Data API: delegates · General API layer dispatches data access calls
- Recomp API → Config: reads · Runtime API consults game settings
- Recomp API → Input: reads · Runtime API consumes normalized control state
- Recomp API → ROM decode: loads · Runtime API depends on decompressed ROM data
- Recomp API → Debug save: uses · Debug and quicksave features are exposed through the runtime
- Input → Input patch: patched by · Input handling is extended through patch hooks
- RT64 bridge → Graphics patch: patched by · Rendering behavior is augmented by graphics patches
- Recomp API → Patch code: overridden by · Core runtime behavior is replaced or augmented by patch code
- Patch code → Input patch: includes · Patch code spans multiple game subsystems
- Patch code → Graphics patch: includes · Patch code spans multiple game subsystems
- Patch code → UI renderer: hooks UI · Patch layer exposes UI-facing integration points
- Config UI → Config: persists · Configuration UI writes to runtime settings
- Mods → Recomp API: feeds · Selected mods and content affect runtime behavior