#   #  ####    ###   #   #         #####   ###    ###   #       ###
 #   #  #   #  #   #  #   #           #    #   #  #   #  #      #
  # #   ####   #   #   # #            #    #   #  #   #  #       ##
  # #   #   #  #   #   # #            #    #   #  #   #  #         #
 #   #  #   #  #   #  #   #           #    #   #  #   #  #         #
 #   #  ####    ###   #   #           #     ###    ###   #####   ###

 Static Recompilation Toolkit for Original Xbox Games

Turn any Xbox game binary into a native Windows executable. No emulation. No interpreter. Just raw, recompiled C.

Join the sp00nznet recomp Discord — the community hub for sp00nznet's recomp projects, where ps3recomp development happens in the open. Good place to ask questions, show a port you are working on, or find out what people are stuck on before you duplicate the effort.

Title-agnostic. The runtime, kernel layer, D3D8 abstraction, NV2A translator, and the Python pipeline (parser → disasm → func_id → abi_analysis → recomp) all derive per-title layout and behavior from the XBE itself. Burnout 3: Takedown was the reference title the toolkit was built against, so many docs use its metrics as examples — see docs/technical/candidate-games.md for ports in progress.

Current version: v0.12.0 — "Never Taken" (September 2026). See the Changelog for what landed and when.

This is a complete toolkit for statically recompiling original Xbox (2001-2005) games from their retail XBE executables into native Windows programs.

Static recompilation takes the raw x86 machine code from an Xbox binary and translates every function — every mov, every jmp, every call — into equivalent C source code. That C code compiles with MSVC into a native x86-64 .exe that runs on modern Windows. The game's original logic executes directly on your CPU, not through an interpreter or JIT compiler.

This is the first public static recompilation toolkit for the original Xbox. Microsoft got here first: their internal Ficl/Fission recompiler shipped Xbox back-compat on the 360. We have since studied it — see Microsoft's Own Recompiler.

The technique has been proven on other platforms — N64Recomp showed MIPS-to-C was viable, XenonRecomp brought it to Xbox 360's PowerPC — but nobody had tackled the OG Xbox until now. Its x86 architecture makes it both easier (same instruction set family as the host) and harder (variable-length instructions, complex addressing modes, x87 FPU stack) than MIPS or PPC targets.

Emulators are great. Cxbx-Reloaded and xemu do incredible work. But static recomp offers some unique advantages:

• Native performance — recompiled code runs at full speed, no interpretation overhead
• Moddability — the output is human-readable C code; you can patch, extend, and improve the game
• Portability — the C output can target any platform with a C compiler (ARM, RISC-V, WebAssembly...)
• Preservation — a self-contained native binary is the ultimate form of game preservation
• Understanding — the process forces you to deeply understand the game at the machine code level

         YOUR XBOX DISC
              |
              v
    +-------------------+
    |  1. Extract XBE   |     Extract default.xbe from the disc image
    +-------------------+
              |
              v
    +-------------------+
    |  2. Parse XBE     |     Read headers, sections, kernel imports
    +-------------------+     tools/xbe_parser/
              |
              v
    +-------------------+
    |  3. Disassemble   |     Find functions, build control flow graphs
    +-------------------+     tools/disasm/
              |
              v
    +-------------------+
    |  4. Identify      |     Classify: CRT, RenderWare, D3D, game code
    +-------------------+     tools/func_id/
              |
              v
    +-------------------+
    |  5. Lift to C     |     Translate x86 instructions to C statements
    +-------------------+     tools/recomp/
              |
              v
    +-------------------+
    |  6. Build Runtime  |    Kernel shim, D3D translation, memory layout
    +-------------------+     templates/runtime/
              |
              v
    +-------------------+
    |  7. Compile & Run  |    MSVC builds native .exe — game runs!
    +-------------------+

Following the RexGlueSDK pattern (which does the same for Xbox 360 via Xenia), xboxrecomp provides link-time libraries extracted from xemu and purpose-built compatibility layers. Your recompiled game links against these — no emulator needed at runtime.

cd xboxrecomp
cmake -S . -B build
cmake --build build --config Release

This produces 6 static libraries in build/src/*/Release/. Link your game project against xboxrecomp (umbrella target) or individual libraries.

This repo builds libraries only — there is no game .exe here, and building it will never produce one. The executable is built by your game project, which lives in its own directory and links these libraries. Start it by copying templates/new-game/: it has the CMakeLists.txt that produces the .exe and the main.c that boots the guest. See Getting Started, Step 6.

Your recompiled game provides two callback functions that the kernel bridge calls to resolve function addresses:

typedef void (*recomp_func_t)(void);
recomp_func_t recomp_lookup(uint32_t xbox_va);        // Auto-generated dispatch table
recomp_func_t recomp_lookup_manual(uint32_t xbox_va);  // Hand-written overrides

The recompiler output (tools/recomp) generates these automatically. The xboxrecomp libraries handle everything else — memory layout, kernel calls, graphics, audio, and input.

┌─────────────────────────────────────────────────┐
│              Your Game (.exe)                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ recomp/  │ │ manual   │ │ game-specific    │ │
│  │ gen/*.c  │ │ overrides│ │ loaders/formats  │ │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│       │             │                │            │
│       └──────┬──────┘────────────────┘            │
│              │ recomp_lookup() / ICALL dispatch    │
├──────────────┼────────────────────────────────────┤
│              │   xboxrecomp libraries             │
│  ┌───────────┴──────────┐                         │
│  │    xbox_kernel        │  Memory layout, file    │
│  │    (kernel_bridge.c)  │  I/O, threading, sync   │
│  └───────────┬──────────┘                         │
│              │                                     │
│  ┌───────┐ ┌┴──────┐ ┌────────┐ ┌──────┐ ┌─────┐│
│  │xbox_  │ │xbox_  │ │xbox_   │ │xbox_ │ │xbox_││
│  │d3d8   │ │dsound │ │apu     │ │nv2a  │ │input││
│  │D3D8→  │ │DSound→│ │MCPX APU│ │NV2A  │ │XPP→ ││
│  │D3D11  │ │mixer  │ │(xemu)  │ │(xemu)│ │XInput│
│  └───────┘ └───────┘ └────────┘ └──────┘ └─────┘│
├──────────────────────────────────────────────────┤
│  Windows 11: D3D11, XInput, waveOut, Win32 API   │
└──────────────────────────────────────────────────┘

• Windows 11/10 (D3D11 backend) — or Linux (OpenGL backend; tools/linux/install_deps.sh)
• macOS: homebrew, docker tools/macos/setup.sh
• Python 3.10+ with capstone (pip install capstone)
• Visual Studio 2022 (MSVC compiler)
• CMake 3.20+
• An original Xbox game disc image (you must own the game)

py -3 below is the Windows Python Launcher — on Linux and macOS use python3, and on a Microsoft Store install that has no py, use python.

The condensed version. docs/GETTING_STARTED.md is the long one, and the one to read if a step here does not go as written — it explains why each flag is there, which is what you need when your title behaves differently from the example.

# 1. Clone this repo
git clone https://github.com/sp00nznet/xboxrecomp.git
cd xboxrecomp

# 2. Extract default.xbe from your Xbox disc image
#    (Use xdvdfs, extract-xiso, or similar tool)
mkdir game_files
# copy default.xbe and game data into game_files/

# 3. Parse the XBE — learn what you're working with
#    --json is NOT optional: step 4 reads the section layout back out of it.
#    The name matters too. Step 4 looks for <xbe stem>_analysis.json beside the
#    XBE, so keep it there and keep the suffix.
py -3 -m tools.xbe_parser game_files/default.xbe --json game_files/default_analysis.json
#    Output: section map, kernel imports, entry point, XDK version

# 4. Disassemble — find all functions
py -3 -m tools.disasm game_files/default.xbe --text-only
#    Output: tools/disasm/output/ (functions.json, xrefs.json, strings.json)
#    --text-only does what it says: only .text. A title with code in its XDK
#    library sections (D3D, DSOUND, XPP...) needs them named explicitly, e.g.
#    --extra-sections XIPS,DOLBY. Drop --text-only to take every code section.

# 5. Identify library functions
py -3 -m tools.func_id game_files/default.xbe -v
#    Output: tools/func_id/output/ (CRT, RenderWare, vtables classified)

# 6. Recover calling conventions and parameter counts
py -3 -m tools.abi_analysis game_files/default.xbe -v
#    Output: tools/abi_analysis/output/abi_functions.json
#    Skipping this still "works", but every function falls back to
#    cdecl / 0 params / int-or-void, so the generated signatures are guesses.

# 6b. Optional: real names instead of sub_XXXXXXXX, if you have Ghidra.
#     FidDb recognises the statically linked CRT/XDK helpers and names a few
#     hundred of them. Do it BEFORE step 8: the recompiler emits whatever name
#     is on the functions.json entry, so the names reach the generated C,
#     crash traces and ABI reports. See docs/GETTING_STARTED.md step 4.5.
XBE=game_files/default.xbe tools/ghidra_naming/run_ghidra.sh
py -3 tools/ghidra_naming/merge_names.py --apply

# 7. Create your game project — this is what becomes the .exe
#    The toolkit is a library; the executable lives in your own project.
cp -r templates/new-game ../mygame        # Windows cmd: xcopy /E /I templates\new-game ..\mygame
#    Then edit:
#      ../mygame/CMakeLists.txt  -> project name, XBOXRECOMP_DIR path
#      ../mygame/src/main.c      -> YOUR_GAME_ENTRY_POINT / XBE path from step 3

# 8. Lift to C — the big one
#    --gen-dir writes the generated code into your game project, where the
#    template's CMakeLists globs src/recomp/gen/*.c. Without it the output
#    lands in this repo (src/game/recomp/gen/) and nothing compiles it.
py -3 -m tools.recomp game_files/default.xbe --all --split 250 --gen-dir ../mygame/src/recomp/gen
#    Output: recomp_0000.c ... recomp_dispatch.c, recomp_funcs.h (millions of
#    lines of C), plus recomp_types.h — the runtime register model the
#    generated code includes. You do not supply that one; if the build says
#    "Cannot open include file: 'recomp_types.h'", this step did not finish.

# 9. Build and run — from the game project, not from xboxrecomp
cd ../mygame
cmake -S . -B build
cmake --build build --config Release
build\Release\your_game_recomp.exe          # named after project() in your CMakeLists

The first time you run a recompiled game, it will crash. That's normal. The process is iterative:

1. Boot — get past the entry point (usually straightforward)
2. Stub — identify and stub out functions that touch hardware you haven't implemented yet
3. Fix ICALLs — indirect calls (vtable dispatches, function pointers) are the hardest 10%
4. Add runtime — implement kernel functions, D3D calls, and input as the game needs them
5. Debug — use the ICALL trace ring buffer, memory access logging, and your debugger
6. Iterate — each crash teaches you something about the game. Fix it and move on.

With Burnout 3 (the first game recompiled with this toolkit), the process from "empty repo" to "game boots and renders textured 3D tracks" took about two weeks of iterative development.

xboxrecomp/
├── README.md                    # You are here
├── CMakeLists.txt               # Top-level build (builds all runtime libs)
├── tools/                       # The recompilation toolchain (Python)
│   ├── xbe_parser/              # XBE file format parser
│   ├── disasm/                  # x86 disassembler + function detector
│   ├── func_id/                 # Library function identifier
│   ├── abi_analysis/            # Calling convention / param recovery
│   ├── recomp/                  # x86 -> C static recompiler
│   ├── debug_symbols/           # Debug-build symbol recovery
│   ├── symbols/ ghidra_naming/  # Optional symbol-name recovery (Ghidra)
│   ├── ida_naming/              # ... or the same thing through IDA
│   ├── xiso/ xmv/               # Disc image and video container tools
│   └── fusion/                  # MS Ficl/Fission study tooling
├── src/                         # Runtime libraries (C, link-time)
│   ├── kernel/                  # xbox_kernel - Xbox kernel → Win32
│   ├── d3d/                     # xbox_d3d8   - D3D8 → D3D11 graphics
│   ├── audio/                   # xbox_dsound - DirectSound compat
│   ├── apu/                     # xbox_apu    - MCPX APU emulation (xemu)
│   ├── nv2a/                    # xbox_nv2a   - NV2A GPU emulation (xemu)
│   ├── input/                   # xbox_input  - Gamepad → XInput
│   └── video/                   # xbox_video  - FMV playback + framebuffer window
├── include/xbox/                # Public umbrella header (xboxrecomp.h)
├── templates/                   # Starter templates for new projects
│   ├── new-game/                # ** Copy this to start a game project **
│   │   ├── CMakeLists.txt       # Builds the game .exe, links xboxrecomp
│   │   └── src/main.c           # Host entry point: loads XBE, boots guest
│   └── runtime/                 # Runtime shim templates
│       ├── recomp_types.h       # Register model + ICALL macros
│       ├── xbox_memory.h        # Memory layout helpers
│       └── kernel_stubs.h       # Kernel function stub templates
└── docs/                        # Documentation
    ├── pipeline/                # Step-by-step pipeline guides
    ├── technical/               # Deep technical documentation
    ├── formats/                 # Xbox file format references
    └── runtime/                 # Runtime implementation guides

• Getting Started Guide — End-to-end walkthrough from XBE to running game
• Decompilation Guide — Using this as a function splitter instead: one byte-exact .s per function, with signatures and the call graph. You never run the recompiler
• Tools Reference — Detailed usage for every pipeline tool
• Runtime Libraries — Architecture, build instructions, integration guide

• xbox_kernel — Memory layout, file I/O, threading, sync, crypto, EEPROM, SMBus (11,128 LOC)
• xbox_d3d8 — D3D8 interface, register combiners, vertex shaders, texture unswizzle (8,838 LOC)
• xbox_dsound — DirectSound buffers, 3D audio, mixbins (573 LOC)
• xbox_apu — MCPX APU voice processor, mixer, MMIO (4,168 LOC)
• xbox_nv2a — NV2A GPU registers, push buffer, PGRAPH→D3D11 (4,892 LOC)
• xbox_input — Gamepad state, vibration, button mapping (360 LOC)

• Extracting and Parsing XBE Files
• Disassembly and Function Detection
• Function Identification
• x86 to C Lifting
• Building the Runtime
• Iterative Debugging

• The Register Model — Why global registers work and how the stack is simulated
• Memory Layout Reproduction — CreateFileMapping, mirror views, and address space tricks
• Indirect Call Dispatch — The RECOMP_ICALL problem and how to solve it
• D3D8 to D3D11 Translation — Bridging Xbox's graphics API to modern DirectX
• NV2A Shader Translation — Register combiners and vertex microcode to HLSL
• D3D8LTCG Device Context — Device field map, PB ring management, stub calling conventions
• Xbox Kernel Replacement — Mapping Xbox kernel ordinals to Win32
• SEH and Exception Handling — Structured exception handling in recompiled code
• Lessons Learned — What worked, what didn't, mistakes to avoid
• Gap Analysis vs xemu — What's implemented, what's missing, prioritized roadmap
• Microsoft's Own Recompiler — White-room analysis of Ficl/Fission: pipeline, address map, HLE boundary
• Ficl/Fission Codegen Teardown — IDA/Hex-Rays teardown of both their translators, and how it reframes our roadmap
• SVOD Extraction — reading the BC package container to get the donor title's guest XBE out, and the validation gate that catches a plausible-looking bad extraction
• Burnout 3 Reunification — bringing the origin title back onto the extracted toolkit: what's done, and the threading gate that makes the runtime a merge not a swap