# Burnout Revenge ReXGlue Recompilation

This project is a static recompilation of **Burnout Revenge** (Xbox 360, Title ID `454107DC`, Media ID `223759FA`) using ReXGlue.

No copyrighted game files are included. This tree excludes the extracted game
directory, `default.xex`, build outputs, and logs.

## Quick start

Building requires completing every step below in order. Skipping any step will cause the next one to fail.

1. Install [prerequisites](#prerequisites)
2. Clone with submodules: `git clone --recurse-submodules <this repo>`
3. Extract game data into `game/`
4. Configure: `cmake --preset win-amd64`
5. Build (includes codegen): `cmake --build --preset win-amd64-release`
6. Run: `project\out\build\win-amd64\Release\burnout.exe`

See the sections below for details.

## Prerequisites

- **CMake 3.25+**
- **Ninja** build system
- **Clang** (clang-cl on Windows, clang/clang++ on Linux)
- **Visual Studio 2022** with "Desktop development with C++" workload (provides MSVC runtime headers for clang-cl)
  - Must include: **C++ Clang Compiler for Windows**

## Required local game files

Provide the `default.xex` inside `game/`:

```
game/default.xex
```

The game data must contain the full Xbox 360 ISO extract (filesystem, audio, textures, etc.).

## Build

From the repository root:

```bat
cmake --preset win-amd64
cmake --build --preset win-amd64-release
```

The SDK is compiled from source as a submodule — no pre-built SDK needed.

If configuration fails with a missing SDK message, run:

```bat
git submodule update --init --recursive
```

## Regenerate codegen

After editing `config/burnout_functions.toml` or the game executable:

```bat
cmake --build --preset win-amd64-release --target burnout_codegen
```

Or rebuild the full target — codegen runs as a PRE_BUILD step when `generated/burnout_init.h` is missing.

## Run

Provide the game directory via `--game_data_root` (optional — the executable
also checks the build-output `game/` subdirectory automatically).

```bat
project\out\build\win-amd64\Release\burnout.exe
```

## Tuning function boundaries

When the runtime hits an unregistered PPC guest address it crashes with:

```
Call to invalid or unregistered function at guest address 0xXXXXXXXX
```

To fix:
1. Note the address from the crash log
2. Add to `config/burnout_functions.toml`:
   ```toml
   "0xXXXXXXXX" = {}
   ```
3. Regenerate codegen: `cmake --build ... --target burnout_codegen`
4. Rebuild: `cmake --build ...`
5. Repeat

## Settings

Copy `config/burnout.example.toml` beside the executable as `burnout.toml` to override cvars.

## Layout

```
config/                         Function overrides + example settings
ppc/                            PPC config headers
project/                        Host project (sources + CMake)
project/src/                    Hand-written C++ (safe to edit)
project/cmake/                  CMake modules
project/patches/                Local SDK patches (applied at configure time)
scripts/                        Helper scripts
third_party/rexglue-sdk         ReXGlue SDK submodule (source tree)
generated/                      Auto-generated recomp sources (do not edit)
```

## Known Issues

| Issue | Status |
|-------|--------|
| 2D/UI color inversion | 🟡 In Progress — gamma_unorm16 RT transfer fix ported, needs visual verification |
| Audio crackle after SFX | 🟡 Open — XMA decode fixed, mixing/clipping remains |
| Music playback (XMP) | 🟡 Open — auto-discovery + FFmpeg decode implemented, playlist fallback in progress |
| Post-match save screen hang | 🟡 Open — `XamContentOpenFile` patched, save/load still hangs |

See `docs/xmp_music_playback.md` for audio research notes.