# FM4-Recomp

A work-in-progress native Windows static recompilation project for the Xbox 360 release of Forza Motorsport 4.

FM4-Recomp translates Xbox 360 PowerPC guest code into native AMD64 instructions using the ReXGlue static recompilation runtime. The project provides an independent launcher, build orchestration, kernel emulation hooks, runtime diagnostics, and analysis configurations to run the game natively on modern 64-bit Windows systems.

This repository contains only independently authored launcher code, build scripts, host application source, analysis configuration files, and runtime patches. It does not contain any game executables, assets, disc images, or copyrighted material.

## Disclaimer and Credits

- Base Project Credit: This project is directly based on and adapted from Pinyon Shift (created by arcanite24), which pioneered the static recompilation pipeline and ReXGlue integration for the ForzaTech engine. Special thanks to arcanite24 and the contributors to Pinyon Shift, ReXGlue, and Xenia for their foundational work.
- AI Assisted Development: Development, debugging, address mapping, and refactoring in this repository were performed with the assistance of Google DeepMind Gemini 3.7 Flash and Anthropic Claude Opus 4.6 as AI pair programming assistants.
- Legal Notice: This is an independent open-source software project created for preservation, compatibility, and educational research purposes. Forza Motorsport, ForzaTech, Turn 10 Studios, Xbox, and Microsoft are trademarks or registered trademarks of Microsoft Corporation. This project is not affiliated with, sponsored by, or endorsed by Microsoft Corporation or Turn 10 Studios.

## Project Status

- Target Game: Forza Motorsport 4 (Xbox 360)
- Verified Disc Dump: Disc 1 (World / Retail, Title ID: 4D530910)
- Pipeline Base: ReXGlue SDK 0.10.0 with project-specific engine patches
- Modules:
  - default.xex (Main Game Executable)
  - SpeechFacade_default.xex (Speech Subsystem Facade)
  - XMediaFacade_default.xex (Media Subsystem Facade)
- Current Milestone: Initial boot and runtime execution. Function discovery, indirect branch resolution, and virtual method thunking are actively being debugged and mapped.

## Repository Layout

- `src/` - Native host application, diagnostics, and runtime hooks.
- `launcher/` - Standalone WPF / C# launcher interface for disc verification, setup, and launch.
- `config/` - ReXGlue analysis manifests, supported dump signatures, and gamepad mappings.
- `config/rexglue/analysis/` - Target-specific binary analysis facts and mid-asm hooks for Forza Motorsport 4.
- `patches/rexglue/` - Upstream ReXGlue SDK patches and runtime enhancements.
- `reference/fh1/` - Historical reference configs and hooks from the Forza Horizon 1 port. (Reference only; addresses do not map to FM4).
- `tools/` - PowerShell and Python automation scripts for building, testing, launching, and diagnostics.
- `docs/` - Technical documentation and porting guides.

## Prerequisites

- Operating System: Windows 10 (version 1903 or later) or Windows 11 (64-bit x64).
- Processor: x86-64 CPU with SSE4.1 support minimum (AVX2 recommended).
- Graphics: DirectX 12 (Feature Level 11_0 or higher) compatible GPU.
- Memory: 8 GB RAM minimum (16 GB recommended).
- Storage: 25 GB free storage space on a fast drive for toolchain, extraction, and compilation.
- Game Disc: A legally owned retail copy of Forza Motorsport 4 (Disc 1).

## Getting Started

### 1. Verify and Extract Game ISO

Verify your disc dump against the supported checksums:

```powershell
.\tools\setup-preview.ps1 -IsoPath "C:\path\to\Forza_Motorsport_4_Disc1.iso" -VerifyOnly
```

Extract the game assets and set up the local workspace:

```powershell
.\tools\setup-preview.ps1 -IsoPath "C:\path\to\Forza_Motorsport_4_Disc1.iso"
```

### 2. Build the Recompiler and Game Binary

Run the automated build script to compile the toolchain, translate guest modules, and link the host executable:

```powershell
.\tools\build-preview.ps1
```

### 3. Launch the Preview

Launch the built executable through the orchestration runner:

```powershell
.\tools\launch-preview.ps1
```

To run with an existing user save profile from your local AppData directory:

```powershell
$stateRoot = Join-Path $env:LOCALAPPDATA 'Fm4Recomp\source\0.1.0\.local\preview'
.\tools\launch-preview.ps1 -StateRoot $stateRoot
```

## Running Automated Tests

The repository includes test suites verifying code generation allowlists, release contracts, and markdown validity:

```powershell
python -m unittest discover tools/tests
```

## Contributing

Contributions are welcome. Please ensure that:
1. Commit messages adhere to the Conventional Commits specification: `<type>(scope): <imperative summary>`.
2. Analysis entries in `config/rexglue/analysis/` are accompanied by binary evidence and reproducible logs from Forza Motorsport 4.
3. All automated tests in `tools/tests/` pass before opening a pull request.

## License

This project is licensed under the BSD 3-Clause License. See the [LICENSE](LICENSE) file for details.