# sonicnext-dev/marathonrecomp architecture

> Architecture diagram of the GitHub repository sonicnext-dev/marathonrecomp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sonicnext-dev/marathonrecomp
- Repository: https://github.com/sonicnext-dev/marathonrecomp

## Overview

##### Project Type and Purpose
- Marathon Recompiled is a native, cross-platform C++ “engine” and installer for Sonic 2006, created by statically recompiling Xbox 360 PowerPC and Xenos shader code into C++ and HLSL.
- It is essentially a game-engine port with a layered architecture: a build/recompilation pipeline, core runtime engine, modular subsystems (CPU emulation stubs, GPU renderer, audio engine, input, OS abstraction, installer, UI), and a plugin/patch system.

##### High-Level Structure (from file tree)
- Top-level components:
- Build & Tooling (CMakeLists, CMakePresets.json, vcpkg.json, docs/, thirdparty/, tools/)
- Core Engine (MarathonRecomp/ + MarathonRecompLib/)
- Resources (MarathonRecompResources/)
- Inside MarathonRecomp/: modular folders that map 1:1 to engine subsystems:
- api/ – Recompiled game APIs (CSD Manager, SonicTeam code, SoX framework)
- apu/ – Audio decoding and playback
- cpu/ – PowerPC context/threads emulation stubs
- gpu/ – Render pipeline, shader caches, ImGui integration
- hid/ – SDL2 input abstraction
- install/ – Installer and VFS for original Xbox files
- kernel/ – Low-level I/O, memory, imports, Xbox kernel replacements
- os/ – Cross-platform OS abstraction (Win32, Linux, macOS)
- mod/ – Mod loader and .ini handling
- patches/ – Runtime code patching hooks
- ui/ – Custom menus, installer wizard, overlays (ImGui utilities)
- user/ – Configuration, save/achievement data management
- utils/ – Helpers (bitstreams, ring buffers, hash maps)

##### Key Insights from README
- Uses two external recompilers: XenonRecomp (PowerPC→C++) and XenosRecomp (Xenos→HLSL).
- Cross-platform support via CMake and an OS-abstraction layer built atop SDL2 (media, input) + MoltenVK/Metal, Vulkan, DirectX.
- Installer consumes original .xex/.arl files and builds a patchable VFS.

a. Build & Recompilation Pipeline
- XenonRecomp → regenerates C++ in api/
- XenosRecomp → generates HLSL shaders in gpu/shader/hlsl (and MSL for Metal)
- CMake + vcpkg → orchestrates thirdparty libs (SDL, ffmpeg, ImGui, MoltenVK, stb, etc.) → produces MarathonRecompLib & exe
b. Runtime Engine Core
- Main Application (app.cpp / AppMarathon)
- Kernel layer → implements Xbox kernel syscalls, file_system, memory, imports
- CPU stubs → guest_thread, PPC context
- GPU renderer → video.cpp, shader cache, command submission to graphics back ends (DX11/Metal/Vulkan)
- Audio subsystem → APU, XMA decoder, SDL2 driver
- Input subsystem → SDL HID driver, event listener
- Installer & VFS → scans original game files, builds virtual file system, patches content
c. Higher-Level Subsystems
- UI overlays & menus (ImGui wrappers, installer wizard, black bars, achievement overlays)
- Game logic & recompiled game code (in api/Sonicteam and api/CSD Manager)
- Mod loader & patch manager → hot-patches game code at runtime
- User data manager → configuration (config.toml), save data, achievements

##### Architectural Patterns and Design Principles
- Layered architecture:
1) Build pipeline
2) Core engine (kernel → CPU/GPU/Audio/Input)
3) Game code (api/)
4) UI, Installer, Mods, User data
- Platform abstraction: os/ and thirdparty/ isolate Windows/Linux/macOS differences.
- Plugin & patch pattern: mod/ and patches/ provide extension points and runtime hooks.
- Dependency injection via ImGui utilities, virtual file systems, and abstract audio/input interfaces.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build Pipeline Layer
    subgraph "Build & Recompilation Pipeline"
        direction TB
        CMakeLists["CMakeLists.txt"]:::build
        CMakePresets["CMakePresets.json"]:::build
        Vcpkg["vcpkg.json"]:::build
        XenonRecomp["XenonRecomp"]:::build
        XenosRecomp["XenosRecomp"]:::build
        Thirdparty["thirdparty/"]:::build
    end

    %% Engine Core Layer
    subgraph "Engine Core"
        direction TB
        subgraph "Main Application"
            direction TB
            MainCPP["main.cpp"]:::core
            AppCPP["app.cpp / app.h"]:::core
            PreloadExec["preload_executable.cpp / .h"]:::core
        end

        subgraph "Kernel Layer"
            direction TB
            KernelDir["kernel/"]:::core
        end

        subgraph "CPU Emulation Stubs"
            direction TB
            CPUDir["cpu/"]:::core
        end

        subgraph "GPU Renderer"
            direction TB
            GPUDir["gpu/"]:::core
        end

        subgraph "Audio Subsystem (APU)"
            direction TB
            APUDir["apu/"]:::core
        end

        subgraph "Input Subsystem (HID)"
            direction TB
            HIDDir["hid/"]:::core
        end

        subgraph "OS Abstraction"
            direction TB
            OSDir["os/"]:::core
        end
    end

    %% Game Code Layer
    subgraph "Game Code (Recompiled API)"
        direction TB
        ApiDir["api/"]:::game
    end

    %% UI, Installer & Mods Layer
    subgraph "UI, Installer, Mods & Patches"
        direction TB
        InstallerDir["install/"]:::ui
        UiDir["ui/"]:::ui
        ModDir["mod/"]:::ui
        PatchesDir["patches/"]:::ui
    end

    %% User Data Layer
    subgraph "User Data Management"
        direction TB
        UserDir["user/"]:::user
    end

    %% Runtime Graphics APIs
    subgraph "Graphics Back-Ends"
        direction TB
        DX11["DirectX 11"]:::ext
        Vulkan["Vulkan"]:::ext
        Metal["Metal/MoltenVK"]:::ext
    end

    %% Connections: Build Pipeline -> Engine Core & Game Code
    XenonRecomp -->|"generates C++"| ApiDir
    XenosRecomp -->|"generates HLSL/MSL"| GPUDir
    CMakeLists -->|"orchestrates build"| MainCPP
    CMakePresets --> MainCPP
    Vcpkg --> Thirdparty
    Thirdparty --> MainCPP

    %% Runtime Flow
    MainCPP -->|"calls"| KernelDir
    KernelDir --> CPUDir
    KernelDir --> GPUDir
    KernelDir --> APUDir
    KernelDir --> HIDDir
    KernelDir --> OSDir

    GPUDir --> DX11
    GPUDir --> Vulkan
    GPUDir --> Metal

    InstallerDir -->|"populates VFS"| KernelDir
    InstallerDir --> ApiDir

    UiDir --> ApiDir
    UiDir --> KernelDir

    ModDir --> ApiDir
    ModDir --> KernelDir

    PatchesDir -.-> ApiDir
    PatchesDir -.-> KernelDir

    UserDir -->|"reads/writes"| KernelDir

    %% Click Events
    click CMakeLists "https://github.com/sonicnext-dev/marathonrecomp/blob/main/CMakeLists.txt"
    click CMakePresets "https://github.com/sonicnext-dev/marathonrecomp/blob/main/CMakePresets.json"
    click Vcpkg "https://github.com/sonicnext-dev/marathonrecomp/blob/main/vcpkg.json"
    click XenonRecomp "https://github.com/sonicnext-dev/marathonrecomp/tree/main/tools/XenonRecomp"
    click XenosRecomp "https://github.com/sonicnext-dev/marathonrecomp/tree/main/tools/XenosRecomp"
    click Thirdparty "https://github.com/sonicnext-dev/marathonrecomp/tree/main/thirdparty/"
    click MainCPP "https://github.com/sonicnext-dev/marathonrecomp/blob/main/MarathonRecomp/main.cpp"
    click AppCPP "https://github.com/sonicnext-dev/marathonrecomp/blob/main/MarathonRecomp/app.cpp"
    click PreloadExec "https://github.com/sonicnext-dev/marathonrecomp/blob/main/MarathonRecomp/preload_executable.cpp"
    click KernelDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/kernel/"
    click CPUDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/cpu/"
    click GPUDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/gpu/"
    click APUDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/apu/"
    click HIDDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/hid/"
    click OSDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/os/"
    click InstallerDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/install/"
    click UiDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/ui/"
    click ModDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/mod/"
    click PatchesDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/patches/"
    click UserDir "https://github.com/sonicnext-dev/marathonrecomp/tree/main/MarathonRecomp/user/"

    %% Styles
    classDef build fill:#cccccc,stroke:#666,stroke-width:1px;
    classDef core fill:#a8d0e6,stroke:#005b96,stroke-width:1px;
    classDef game fill:#98fb98,stroke:#228b22,stroke-width:1px;
    classDef ui fill:#ffcc80,stroke:#e65100,stroke-width:1px;
    classDef user fill:#fff176,stroke:#f9a825,stroke-width:1px;
    classDef ext   fill:#f0f0f0,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5;
```
