# GTA IV Recompiled (rexglue)

A **static recompilation** of the Xbox 360 version of *Grand Theft Auto IV* to
native x86-64, built on the [rexglue](https://github.com/) SDK (a Xenia-derived
PowerPC→C++ recompiler + Xenos GPU runtime). PowerPC guest code is translated to
C++ ahead of time; the kernel, GPU command processor, VFS and audio come from the
rexglue runtime.

> **Status: early / experimental.** The game boots, renders, and reaches
> interactive gameplay, but **world collision does not load** — the player falls
> through the ground (see [Known issues](#known-issues)). This repo is published
> so people with deeper RAGE-engine / recompilation knowledge can pick it up.

This project contains **no game assets**. You must provide files from your own
legally-acquired Xbox 360 copy of GTA IV.

---

## What works

- Boots cleanly: **35,888 functions recompiled, 0 unresolved calls**.
- Applies **Title Update 8** at runtime (`3.0.0.0` image → patched).
- Direct3D 12 renderer (via the rexglue Xenos runtime) initializes and presents.
- Full opening cinematic renders (characters, lighting, world streaming).
- Reaches interactive **gameplay**: HUD, radar, mission subtitles, pause menu.
- Keyboard/mouse input (emulated 360 controller).
- HDD **cache partition** is mounted so the world geometry streams and renders.

## Known issues

### What does not work

- **World collision (static bounds) never loads** → the player/vehicle falls
  through the ground ("the limbo"). Everything else (physics, AI, water
  collision) works; only the static-terrain `phBound` streaming is broken. This
  is the one blocking issue. See [`docs/COLLISION_BUG.md`](docs/COLLISION_BUG.md).
- Save games are enumerated from disk but rejected by the in-game menu
  (secondary issue).
- Audio: non-fatal XMA decode warnings.
- Android/other platforms: not attempted here. (rexglue already carries the
  ARM64/Android plumbing used by other ports, so it's a future option.)

---

## Building

> **This is not a clone-and-build repo** — like every static-recompilation
> project, it cannot ship the game. A clone has no `game/` data, no generated
> C++, and no SDK. You provide the game files, clone + patch the rexglue SDK, run
> codegen, then build. Follow the steps below and the [Setup Guide](docs/SETUP.md).

### Prerequisites

- **Windows** with:
  - LLVM/Clang (tested: 22.1.8) — `clang`/`clang++`
  - `llvm-rc` (ships with LLVM) for the resource compiler
  - MSVC Build Tools 2022 (for the Windows SDK headers/libs)
  - CMake ≥ 3.25, Ninja
  - Python 3 (used by the codegen title-update staging scripts)
- The **rexglue SDK** source tree and a built `rexglue.exe` codegen tool. It is
  public: [`mchughalex/rexglue-skate3`](https://github.com/mchughalex/rexglue-skate3)
  (branch `skate3-sdk-clean`). Point `REXSDK_DIR` at your clone (see
  `docs/CMakeUserPresets.json.example`). **Apply
  [`docs/rexglue-sdk-gta4.patch`](docs/rexglue-sdk-gta4.patch)** to that clone —
  it adds two cvars GTA IV needs (`mount_cache_device`, `invalid_call_nonfatal`)
  as guarded additions:
  ```bash
  cd <your rexglue-skate3 clone>
  git apply /path/to/gta4recomp/docs/rexglue-sdk-gta4.patch
  ```
- ~40 GB free disk (game data 6.5 GB + generated C++ ~170 MB + build tree).

### 1. Provide the game files and assemble the folders

Fastest path — one script does extraction + staging + codegen:

```bash
python setup.py --iso "GTA IV.iso" --tu "TU_...0205" --rexglue path/to/rexglue.exe
```

Or do it by hand: **➡️ the step-by-step [Setup Guide](docs/SETUP.md)** covers
extracting the XGD2 disc into `game/`, staging the Title Update 8 image in
`tu8/`, and populating `update/` — using the pure-Python tools in
[`tools/`](tools) (no external dependencies). Either way you build:

```
game/     extracted Xbox 360 disc root (default.xex, *.rpf, common/, xbox360/)
tu8/      default.xex + default.xexp (Title Update 8) as siblings
update/   the rest of the TU8 payload (data/, shaders/, text/)
```

TU8 media id is `6AC07221` and must match your disc.

### 2. Generate the recompiled C++

Run from the **project root** (paths in the manifest are relative on purpose):

```bash
rexglue codegen gta4_manifest.toml
```

This writes ~86 `generated/default/gta4_recomp.*.cpp` files (~170 MB).

### 3. Configure & build

Point `CMakeUserPresets.json` at your rexglue SDK tree, then:

```bash
cmake --preset win-amd64
cmake --build out/build/win-amd64 -j 2
```

> Use a low `-j` (2) on machines with ≤ 8 GB RAM: the generated translation
> units are large and the LLVM optimizer is memory-hungry.

### 4. Run

Place a `gta4.toml` next to `gta4.exe` (see `docs/gta4.toml.example`) pointing at
your `game/`, `update/` folders, then run `gta4.exe`.

---

## Repository layout

```
CMakeLists.txt            Project build (arch baseline + rexglue glue)
CMakePresets.json         Standard presets (win/linux/mac × debug/rel)
gta4_manifest.toml        Codegen manifest (entrypoint, TU8, includes)
src/
  main.cpp                REX_DEFINE_APP entry
  gta4_app.h              App class (overrides rex::ReXApp)
config/
  gta4_functions.toml     Manual function-boundary fixes (3 branch targets)
  gta4_ctors.toml         1,454 static C++ constructors (reached only by a
                          pointer table the analyzer can't see)
  gta4_auto.toml          ~795 vtable/callback entry points
  gta4_ptrs.toml          Function addresses materialized in code (lis/addi)
  gta4_thunks.toml        16-byte virtual-dispatch thunks
tools/
  extract_xiso.py         Extract an Xbox 360 XDVDFS disc image (pure Python)
  extract_stfs.py         Extract an STFS package: TU or save (pure Python)
docs/
  SETUP.md                Step-by-step: disc -> game/tu8/update folders
  COLLISION_BUG.md        Deep dive on the blocking collision bug
  gta4.toml.example       Runtime config template
  CMakeUserPresets.json.example
  libertyrecomp_gta4_config.toml   Reference config from the LibertyRecomp project
```

The `config/*.toml` files are the accumulated result of iterative bring-up:
rexglue discovers most functions from `.pdata`, and these files add the entry
points it can't reach statically (constructor tables, vtables, computed jumps).

---

## Notes & references

- **LibertyRecomp** (OZORDI/LibertyRecomp) is a parallel GTA IV port on a fork of
  the same rexglue SDK. Its codegen config is preserved in
  `docs/libertyrecomp_gta4_config.toml`. Independently, it declares the **same 3
  unresolved branch targets** this project found (`0x8217C108`, `0x82A77E28`,
  `0x8219E410`) and also targets **TU8** — cross-validating the approach.
- The `[rexcrt]` mechanism (replacing the game's static CRT `memset`/`memcpy`/…
  with native implementations) was tested here; it did **not** affect the
  collision bug, so it was left out to keep the tree minimal.

## Legal

This project distributes no copyrighted material. It is a recompiler front-end;
you must own GTA IV for Xbox 360 and supply the files yourself. Trademarks belong
to their respective owners.