How sonicnext-dev/marathonrecomp works
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.