# WaveRace64-Recomp

A native PC port of **Wave Race 64** (USA Rev 1) using [N64Recomp](https://github.com/N64Recomp/N64Recomp) static recompilation.

---

## Current Status

| Phase | Description | Status |
|-------|-------------|--------|
| **Phase 1** | Environment Setup & Toolchain | **COMPLETE** |
| **Phase 2** | Static Recompilation | **COMPLETE** |
| **Phase 3** | Runtime Integration | **COMPLETE** |
| **Phase 4** | Build & Link (RT64 + Runtime) | **COMPLETE** -- First successful build |
| **Phase 5** | Audio & Input | Not Started |
| **Phase 6** | Game-Specific Fixes | Not Started |
| **Phase 7** | Enhancements | Not Started |
| **Phase 8** | Release Preparation | Not Started |

> **Not yet playable** -- First successful build achieved (11 MB ELF executable). Runtime boots but game-specific testing has not started.

### Build Statistics

| Metric | Value |
|--------|-------|
| **Executable** | `build/WaveRace64Recomp` (ELF, 11 MB) |
| **Build system** | CMake + Ninja |
| **Platform** | Linux x86_64 (Vulkan/SDL2) |
| **Dependencies linked** | RT64, N64ModernRuntime (ultramodern), recompiled funcs |
| **Link strategy** | `--start-group` / `--end-group` for circular dependencies |

### Known Limitations (Phase 4)

- **Audio:** Stub implementations only -- no audio output yet
- **Overlays:** `relocatable_sections_path` disabled (overlay sections lack relocation data)
- **Controller Pak:** Stub functions only (osPfs*)
- **Runtime:** Game has not been launched/tested yet -- build compiles and links but gameplay is unverified

### Recompilation Statistics

| Metric | Value |
|--------|-------|
| **Functions recompiled** | 1,228 |
| **Generated C source files** | 22 (`funcs_0.c` -- `funcs_21.c`) |
| **Total output size** | ~19.5 MB |
| **Header file** | `funcs.h` (65KB, all function declarations) |
| **Overlay dispatch table** | `recomp_overlays.inl` (90KB) |
| **Entry point** | `lookup.cpp` (ROM name + entrypoint) |

Symbols were sourced from the [Wave Race 64 decomp project](https://github.com/WACOMalt/Wave-Race-64):
- **756** base functions extracted from decomp symbol files
- **1,228** functions after JAL-target auto-splitting

---

## What is this?

This project uses static recompilation to translate Wave Race 64's N64 MIPS binary code into native PC code, enabling the game to run natively on modern hardware with enhancements like:

- Arbitrary resolution support (720p, 1080p, 4K+)
- Widescreen and ultrawide aspect ratios
- Modern controller support (Xbox, PlayStation, Switch Pro, keyboard+mouse)
- Enhanced rendering via [RT64](https://github.com/rt64/rt64)
- 60fps support (planned)

## Prerequisites

### Required
- **Wave Race 64 (USA Rev 1) ROM** -- You must legally own and provide your own ROM file
  - Expected SHA-1: `508dfc2d4caa42b6f6de5263d0aed5e44ac7966a`
  - Place as `baserom.us.rev1.z64` in the project root
- **CMake** >= 3.20
- **C++ Compiler** -- MSVC 2022 (Windows), GCC 12+ (Linux), or Clang 15+
- **Python** >= 3.10

### Platform-Specific
- **Windows:** Windows 10 SDK, Visual Studio 2022 with C++ workload
- **Linux:** Vulkan SDK >= 1.3, SDL2 development libraries

## Building

```bash
# 1. Clone with submodules
git clone --recurse-submodules https://github.com/WACOMalt/WaveRace64-Recomp.git
cd WaveRace64-Recomp

# 2. Place your ROM in the project root
cp /path/to/your/rom baserom.us.rev1.z64

# 3. Build the N64Recomp toolchain (if not already built)
cd lib/N64Recomp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j$(nproc)
cd ../..

# 4. Run the recompiler to generate RecompiledFuncs/
./lib/N64Recomp/build/N64Recomp recomp/waverace64.toml

# 5. Build the project
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build --config Release -j$(nproc)
```

The build produces `build/WaveRace64Recomp` (Linux) or `build/WaveRace64Recomp.exe` (Windows).

## Running the Recompiler

The static recompilation step has already been completed. To reproduce it:

```bash
# 1. Place your ROM in the project root
cp /path/to/your/rom baserom.us.rev1.z64

# 2. Build the N64Recomp toolchain (if not already built)
cd lib/N64Recomp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j$(nproc)
cd ../..

# 3. Run the recompiler
./lib/N64Recomp/build/N64Recomp recomp/waverace64.toml
```

The recompiler reads `baserom.us.rev1.z64` and `recomp/waverace64.us.rev1.syms.toml`, then outputs recompiled C code to `RecompiledFuncs/`.

## Project Structure

```
WaveRace64-Recomp/
|-- CMakeLists.txt                  # Root build configuration
|-- README.md                       # This file
|-- LICENSE                         # GPLv3
|
|-- lib/                            # Git submodules
|   |-- N64Recomp/                  # Static recompiler (MIPS -> C)
|   |-- rt64/                       # GPU rendering engine (F3D -> D3D12/Vulkan)
|   +-- N64ModernRuntime/           # Runtime library (OS stubs, threading)
|
|-- recomp/                         # N64Recomp configuration
|   |-- waverace64.toml             # Recompiler main config
|   |-- waverace64.us.rev1.syms.toml  # Symbol definitions (1,228 functions)
|   +-- overlays.us.rev1.txt        # Overlay address table
|
|-- RecompiledFuncs/                # Generated by N64Recomp (not committed)
|   |-- funcs_0.c -- funcs_21.c    # 22 recompiled C source files (~19.5MB)
|   |-- funcs.h                     # Function declarations header (65KB)
|   |-- lookup.cpp                  # Entrypoint + ROM name
|   +-- recomp_overlays.inl         # Overlay dispatch table (90KB)
|
|-- scripts/                        # Build and utility scripts
|   |-- generate_symbols.py         # Extract symbols from decomp -> TOML format
|   |-- auto_split_functions.py     # JAL-scan to discover sub-functions
|   +-- find_missing_jal_targets.py # Detect missing call targets in ROM
|
|-- src/                            # Game-specific source code
|   |-- main.cpp                    # Application entry point
|   |-- rt64_render_context.cpp     # RT64 rendering integration
|   +-- os_stubs.cpp                # N64 OS function stub implementations
|
|-- assets/                         # Non-copyrighted application assets
+-- docs/                           # Documentation
```

## Development Progress

### Phase 1: Environment Setup & Toolchain (COMPLETE)
- [x] Created `WACOMalt/WaveRace64-Recomp` repository on GitHub
- [x] Added N64Recomp, RT64, N64ModernRuntime as git submodules
- [x] Created CMakeLists.txt for the project
- [x] Built N64Recomp toolchain from source
- [x] Exported symbols from decomp project into N64Recomp-compatible TOML format
- [x] Created `generate_symbols.py` -- extracts 756 base functions from decomp symbol files
- [x] Created `auto_split_functions.py` -- JAL scanning expanded 756 -> 1,228 functions
- [x] Created `find_missing_jal_targets.py` -- validates all call targets are covered

### Phase 2: Static Recompilation (COMPLETE)
- [x] Created `waverace64.toml` configuration for N64Recomp
- [x] Defined all 19 overlays with ROM/VRAM addresses
- [x] Fixed entrypoint (0x80000400 -> 0x80046800)
- [x] Fixed `__osException` merge issue (two symbol files defining the same function)
- [x] Fixed auto-split function boundaries for edge cases
- [x] Successfully recompiled all 1,228 functions to C
- [x] Generated overlay dispatch table (`recomp_overlays.inl`)
- [x] All generated code compiles cleanly

### Phase 3: Runtime Integration (COMPLETE)
- [x] Set up main.cpp with ultramodern runtime initialization
- [x] Configured RT64 render context for Linux (SDL_Window* passthrough)
- [x] Fixed `get_game_thread_name()` API signature (`const OSThread* t`)
- [x] Added RT64 internal include paths and compile definitions to CMakeLists.txt

### Phase 4: Build & Link (COMPLETE -- First Successful Build)
- [x] Re-ran N64Recomp to regenerate RecompiledFuncs (fixed truncated funcs_21.c)
- [x] Disabled `relocatable_sections_path` in waverace64.toml (overlay sections lack relocation data)
- [x] Added os_stubs.cpp with stub implementations for missing N64 OS functions
- [x] Used `--start-group`/`--end-group` for circular link dependencies
- [x] Build produces 11 MB WaveRace64Recomp ELF executable

### Phase 5: Audio & Input (NEXT)
- [ ] SM64-derived HLE audio integration
- [ ] SDL2 controller mapping (N64 -> modern gamepad)
- [ ] EEPROM save -> file-based save redirect

### Phase 6: Game-Specific Fixes
- [ ] Full gameplay testing (all modes, courses, riders)
- [ ] Water rendering verification
- [ ] Overlay transition testing

### Phases 7-8: Enhancements & Release
- [ ] Widescreen, 60fps, HD texture support
- [ ] Release packaging

## Tools

| Script | Purpose |
|--------|---------|
| [`generate_symbols.py`](scripts/generate_symbols.py) | Extracts function symbols from the decomp project's linker scripts and converts them to N64Recomp TOML format |
| [`auto_split_functions.py`](scripts/auto_split_functions.py) | Scans the ROM binary for JAL instructions to discover function boundaries not in the decomp symbol files (756 -> 1,228) |
| [`find_missing_jal_targets.py`](scripts/find_missing_jal_targets.py) | Validates that all JAL call targets in the ROM are covered by symbol definitions |

## Related Projects

| Project | Description |
|---------|-------------|
| [N64Recomp](https://github.com/N64Recomp/N64Recomp) | The static recompilation tool |
| [RT64](https://github.com/rt64/rt64) | N64 rendering engine for PC |
| [N64ModernRuntime](https://github.com/N64Recomp/N64ModernRuntime) | Runtime support library |
| [Wave-Race-64 Decomp](https://github.com/WACOMalt/Wave-Race-64) | Our decomp fork (symbol source) |
| [Zelda64Recomp](https://github.com/Zelda64Recomp/Zelda64Recomp) | Reference implementation (Majora's Mask) |

## Legal

This project does **not** contain any Nintendo copyrighted code or assets. You must provide your own legally-obtained ROM file to use this software.

## License

GPLv3 -- see [LICENSE](LICENSE) for details.