rainchus/quest64-recomp

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