Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hedge-dev/UnleashedRecomp/llms.txt

Use this file to discover all available pages before exploring further.

macOS support is community-driven and not currently on the official roadmap, but the build system fully supports it. Vulkan is provided on macOS through MoltenVK, which is included as a submodule under thirdparty/MoltenVK. The macOS deployment target is 13.0. CI builds run on macos-15 (Apple Silicon, arm64), though x86-64 builds can be produced by passing -DCMAKE_OSX_ARCHITECTURES=x86_64 at configure time.

​
Build Steps

1

Clone the repository

Clone the repository with all submodules:
git clone --recurse-submodules https://github.com/hedge-dev/UnleashedRecomp.git
cd UnleashedRecomp
2

Add the required game files

Copy the following files from your legally acquired copy of Sonic Unleashed into ./UnleashedRecompLib/private/:
  • default.xex — found in the game’s root directory
  • default.xexp — obtained from the title update package
  • shader.ar — found in the game’s root directory
Install the game using an existing Unleashed Recompiled release to get verified copies of these files. They will be stored under game and update subdirectories of your installation.
3

Install Xcode or Command Line Tools

Install Xcode 16.3 or later from the Mac App Store, or install the equivalent Xcode Command Line Tools from Apple:
xcode-select --install
Xcode provides the Apple Clang compiler and the required macOS SDK headers. Make sure the active developer directory points to your Xcode installation:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
4

Install additional build tools

Install CMake, Ninja, and pkg-config using your preferred package manager:
brew install cmake ninja pkg-config
5

Configure the project

From the repository root, run CMake with your chosen preset. The example below uses macos-release; see the preset reference for all options:
cmake . --preset macos-release
CMake will bootstrap vcpkg and compile all required libraries into ./thirdparty/vcpkg/. This only happens on the first configure and can take several minutes.
6

Build the project

Compile the UnleashedRecomp target:
cmake --build ./out/build/macos-release --target UnleashedRecomp
The first build takes longer than usual because XenonRecomp and XenosRecomp translate the game’s PowerPC binary and Xenos shader bytecode into C++ and HLSL as part of the build. Subsequent builds skip this step unless the input game files change.
7

Run the game

The build produces a macOS app bundle. Navigate to ./out/build/macos-release/UnleashedRecomp/ and open it with:
open -a "Unleashed Recompiled.app"
Or double-click Unleashed Recompiled.app in Finder.On the first run the game will prompt you for your Sonic Unleashed game files if it cannot find an existing installation.

​
Available Presets

PresetBuild typeNotes
macos-debugDebugFull debug symbols, no optimisation
macos-relwithdebinfoRelWithDebInfoDebug symbols + optimisation; recommended for development
macos-releaseReleaseLTO enabled; best runtime performance
macOS support is community-driven and is not officially on the project roadmap. Unleashed Recompiled uses plume as its graphics abstraction layer, which will be gaining Metal support in a future update. You can follow the macOS discussion on GitHub issue #455.

Build docs developers (and LLMs) love

Get started for freeTalk to us