WaveRace64-Recomp

A native PC port of Wave Race 64 (USA Rev 1) using 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:

• 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
• 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

# 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:

# 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)

• Created WACOMalt/WaveRace64-Recomp repository on GitHub
• Added N64Recomp, RT64, N64ModernRuntime as git submodules
• Created CMakeLists.txt for the project
• Built N64Recomp toolchain from source
• Exported symbols from decomp project into N64Recomp-compatible TOML format
• Created generate_symbols.py -- extracts 756 base functions from decomp symbol files
• Created auto_split_functions.py -- JAL scanning expanded 756 -> 1,228 functions
• Created find_missing_jal_targets.py -- validates all call targets are covered

Phase 2: Static Recompilation (COMPLETE)

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

Phase 3: Runtime Integration (COMPLETE)

• Set up main.cpp with ultramodern runtime initialization
• Configured RT64 render context for Linux (SDL_Window* passthrough)
• Fixed get_game_thread_name() API signature (const OSThread* t)
• Added RT64 internal include paths and compile definitions to CMakeLists.txt

Phase 4: Build & Link (COMPLETE -- First Successful Build)

• Re-ran N64Recomp to regenerate RecompiledFuncs (fixed truncated funcs_21.c)
• Disabled relocatable_sections_path in waverace64.toml (overlay sections lack relocation data)
• Added os_stubs.cpp with stub implementations for missing N64 OS functions
• Used --start-group/--end-group for circular link dependencies
• 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	Extracts function symbols from the decomp project's linker scripts and converts them to N64Recomp TOML format
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	Validates that all JAL call targets in the ROM are covered by symbol definitions

Related Projects

Project	Description
N64Recomp	The static recompilation tool
RT64	N64 rendering engine for PC
N64ModernRuntime	Runtime support library
Wave-Race-64 Decomp	Our decomp fork (symbol source)
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 for details.