Skip to content
ReCarbonby RetroNativealpha
ALPHA docs. ReCarbon has no public release yet: these pages describe the current development build. Known issues

Developers

View source on GitHub

Requirements

Section titled “Requirements”

macOS on Apple Silicon and Homebrew:

Terminal window
brew install llvm lld cmake ninja python
brew install sdl3 vulkan-loader vulkan-headers glslang spirv-tools molten-vk

Build

Section titled “Build”

From the repository root:

Terminal window
scripts/setup_tools.sh     # XenonRecomp (pinned + patches), extract-xiso, xexsurvey, FFmpeg's XMA decoder
scripts/survey.sh          # analyse default.xex, regenerate config/, recompile to ppc/, validate
tests/run_instr_tests.sh   # instruction tests for the patched XenonRecomp


cmake -S . -B build/main -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang \
  -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++
ninja -C build/main ReCarbon

Then install the game from your disc image into it (build/main/runtime/ReCarbon --install <image.iso>): see Installation.

To build the unit tests too, configure with -DRECARBON_TESTS=ON (needs scripts/setup_tools.sh first, like the game), then:

Terminal window
ninja -C build/main
ctest --test-dir build/main

The macOS deployment target defaults to your own macOS (MACOSX_DEPLOYMENT_TARGET when set). To choose another, set MACOSX_DEPLOYMENT_TARGET for both setup_tools.sh and the first cmake run. tools/, game/, ppc/ and build/ are git-ignored: never commit or share them.

On the main test machine (MacBook Air M5, 24 GB) a clean native build took 97.9 s with a 2.56 GB peak. The recompiler produces 72,864 functions in 289 files (181 MB).

How it fits together

Section titled “How it fits together”
  1. XenonRecomp translates the game’s PowerPC code (from your default.xex) into C++.
  2. That C++ compiles to native arm64 and links with the runtime, adapted from SpeedBreaker: the Xbox 360 kernel and XAM calls, memory and threads, the Xenos GPU on Vulkan (MoltenVK on Metal), XMA audio (FFmpeg), and input (SDL3).
  3. Input runs in three layers: device input → binding resolution → a virtual Xbox 360 controller. Mappings are data, so the site’s controls are generated from the same tables.

Useful environment variables

Section titled “Useful environment variables”
Variable Does
RECARBON_INPUT_SCRIPT Scripted input, e.g. 12:START,15.5:A,30-90/4:DOWN
RECARBON_VIRTUAL_PAD An SDL virtual controller for tests without a person
RECARBON_INPUT_LOG=1 The left stick and triggers once a second, raw and as the game gets them

Each Settings option also has one: see Settings.

Contributing

Section titled “Contributing”

ReCarbon’s runtime, these docs and the website are in one repository, retronative/recarbon (GPL-3.0-or-later).

  • Report a problem in its issue tracker: what you did, what happened, your Mac and macOS version, and the bug report the game saves (Troubleshooting).
  • Pull requests follow the repository’s AGENTS.md: one focused change per commit, with the tests it needs; a new instruction needs hand-computed instruction tests.
  • Never attach or commit game files, disc images, decrypted executables, generated ppc/ code or anything from game/. ReCarbon only works with each player’s own disc.
View source on GitHub

A RetroNative project.

ReCarbon is an unofficial fan project. It is not affiliated with, endorsed by or sponsored by Electronic Arts Inc. or the Need for Speed brand. Need for Speed and Carbon are trademarks of Electronic Arts Inc. and are used here only to describe the game. No game files are included or distributed: you need your own legally obtained copy of the Xbox 360 disc.