wiicompiled/docs/building-macos.md

Building WiiCompiled and Retro Rewind on macOS

This guide covers building WiiCompiled (base game) and Retro Rewind from source on macOS for Apple Silicon (arm64). Follow these instructions to compile the native executables directly.

Note

If you only want to build the base game (WiiCompiled), look for sections marked (Skip if only building WiiCompiled) to bypass Retro Rewind and online payload steps.

---

1. Prerequisites

System Requirements

• Hardware: Apple Silicon Mac (M1/M2/M3/M4)
• Operating System: macOS 14 (Sonoma) or later
• Xcode Command Line Tools:

  xcode-select --install
  

Toolchain Dependencies

Install the required tools using Homebrew:

brew install cmake ninja
brew install --cask dotnet-sdk@8

Verify that Clang, CMake, Ninja, and the .NET 8 runtime are available:

clang --version
cmake --version
ninja --version
dotnet --list-runtimes   # Must list Microsoft.NETCore.App 8.x

---

2. Required Game and Mod Assets

Due to legal requirements, no proprietary Nintendo assets or code are included in this repository. You must provide your own legally dumped game files.

1. Mario Kart Wii PAL (RMCP01) Disc Image (Required):
   • Supported formats: .iso, .wbfs, .ciso, .rvz, .gcm, .gcz.
2. nodtool (Required for disc extraction):
   • Download the macOS Apple Silicon binary of nodtool:

     curl -fsSL "https://github.com/encounter/nod/releases/download/v2.0.0-alpha.10/nodtool-macos-arm64" -o nodtool
     chmod +x nodtool
     

3. Retro Rewind Distribution (Skip if only building WiiCompiled):
   • Download the Retro Rewind release package. You will need the RetroRewind6 folder (which contains Binaries/Code.pul).
4. Retro-WFC Payload (Skip if only building WiiCompiled or building offline):
   • Required for online multiplayer on Retro Rewind. Downloaded during setup from http://nas.play.rwfc.net/payload?g=RMCPD00.

---

3. Step 1: Extract Disc Assets

Extract your clean PAL RMCP01 disc into the Assets/ directory of the repository:

# Using nodtool directly into a temporary scratch directory
mkdir -p /tmp/mkw-extract
./nodtool extract /path/to/RMCP01.iso /tmp/mkw-extract

# Copy extracted assets into the repository Assets directory
rm -rf Assets/DATA/files Assets/DATA/sys
mkdir -p Assets/DATA
cp /tmp/mkw-extract/*/sys/main.dol Assets/main.dol
cp /tmp/mkw-extract/*/files/rel/StaticR.rel Assets/StaticR.rel
cp -R /tmp/mkw-extract/*/files Assets/DATA/files
cp -R /tmp/mkw-extract/*/sys Assets/DATA/sys

# Clean up temporary files
rm -rf /tmp/mkw-extract

Tip

Alternatively, you can use the repository's helper script:

Launcher/macos/extract-disc.command --game /path/to/RMCP01.iso --assets-dir Assets --nodtool ./nodtool

Verify Extracted Asset Hashes

Confirm that the extracted files match the expected clean PAL revision:

shasum -a 256 Assets/main.dol Assets/StaticR.rel

• Assets/main.dol: 80d18895b39c63bd80f457398bfcbb91b7d16ac116a41a88967e954080155b05
• Assets/StaticR.rel: 16d9d146112541fefea701ecb5bc1a496f9d50e4a752fbb5b6778e7c6399f67d

---

4. Step 2: Build the Translator CLI

Compile the static recompiler CLI:

dotnet build translator/src/Translator.Cli/Translator.Cli.csproj -c Release

Define a shell function to invoke the translator (ensuring paths with spaces are handled safely):

translator() {
  dotnet "$(pwd)/translator/src/Translator.Cli/bin/Release/net8.0/Translator.Cli.dll" "$@"
}

---

5. Step 3: Translation

A. Translate Base Game Functions

mkdir -p generated/functions build/base

translator translate-recursive 0x8000629c \
  --project projects/mkwii/recomp.yml \
  --outdir generated/functions \
  --output-metadata generated/base_translation_output.json \
  --production-source-bundle generated/base_translation_sources.bin \
  --no-function-files \
  --prune-stale \
  --threads $(sysctl -n hw.ncpu)

B. Emit Base Manifest

translator emit-base-manifest \
  --project projects/mkwii/recomp.yml \
  --out build/base \
  --functions-dir generated/functions \
  --translation-output-metadata generated/base_translation_output.json \
  --region P

---

C. Stage and Translate Retro Rewind (Skip this step if you only want to build WiiCompiled)

1. Stage Code.pul:

   RETRO_DIR="/path/to/RetroRewind6"
   mkdir -p PulsarPacks/completed/RetroRewind/RetroRewind6/Binaries
   cp "$RETRO_DIR/Binaries/Code.pul" PulsarPacks/completed/RetroRewind/RetroRewind6/Binaries/Code.pul
   

2. Retro-WFC Payload Setup (for Online Multiplayer): Online play in Retro Rewind requires the shared Retro-WFC payload. Download and validate it:

   mkdir -p build/retro-wfc/binary
   curl -fsSL --retry 3 "https://nas.play.rwfc.net/payload?g=RMCPD00" \
     -o build/retro-wfc/binary/payload.RMCPD00.bin
   
   # Validate payload signature and integrity
   translator validate-retro-wfc-payload --directory build/retro-wfc
   

3. Run Retro Rewind translation:

   mkdir -p build/mods/retro_rewind_full_cpp
   
   translator translate-mod \
     --project projects/mkwii/recomp.yml \
     --profile retro-rewind \
     --base-manifest build/base/mkwii_base_manifest.json \
     --base-translation-output-metadata generated/base_translation_output.json \
     --code-pul "$RETRO_DIR/Binaries/Code.pul" \
     --mod-root "$RETRO_DIR" \
     --mod-name "Retro Rewind" \
     --region P \
     --out build/mods/retro_rewind_full_cpp \
     --prefer-cached-inputs \
     --emit-cpp \
     --threads $(sysctl -n hw.ncpu) \
     --retro-wfc-payload build/retro-wfc/binary/payload.RMCPD00.bin
   

   Tip

   If you do not want online play or do not have an internet connection, replace --retro-wfc-payload ... with --skip-retro-wfc.

---

D. Generate Data Initialization and Build Shards

First, generate the embedded game data initializer:

translator generate-data-init --project projects/mkwii/recomp.yml

Next, generate the CMake build shards using one of the following options:

Option 1: Base Game Only (WiiCompiled)

mkdir -p generated/build_shards
translator emit-build-shards \
  --project projects/mkwii/recomp.yml \
  --base-metadata generated/base_translation_output.json \
  --base-functions-dir generated/functions \
  --native-source-dir runtime/src \
  --out generated/build_shards

Option 2: Base Game + Retro Rewind

mkdir -p generated/build_shards
translator emit-build-shards \
  --project projects/mkwii/recomp.yml \
  --base-metadata generated/base_translation_output.json \
  --base-functions-dir generated/functions \
  --native-source-dir runtime/src \
  --out generated/build_shards \
  --resolved-profile build/mods/retro_rewind_full_cpp/resolved_dispatch_profile.json \
  --retro-cpp-dir build/mods/retro_rewind_full_cpp/cpp

---

6. Step 4: Configure and Compile with CMake & Ninja

Configure the native C++ build targeting Apple Silicon:

cmake -S runtime -B build-macos -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DAURORA_SDL3_PROVIDER=vendor

Compile the desired target:

# To build WiiCompiled only:
cmake --build build-macos --target WiiCompiled --parallel $(sysctl -n hw.ncpu)

# OR to build both WiiCompiled and Retro Rewind:
cmake --build build-macos --target WiiCompiled RetroRewind --parallel $(sysctl -n hw.ncpu)

Once compilation completes, the executables are ready in your build directory:

• build-macos/WiiCompiled
• build-macos/RetroRewind (if built)

During the build, CMake automatically copies the required runtime assets into build-macos/:

• build-macos/dsp_coef.bin
• build-macos/initial_pipeline_cache.db
• build-macos/wii_bootstrap/

---

7. Step 5: Running Executables from the Build Folder

Configure Config.toml

The runtime reads configuration from ~/Library/Application Support/WiiCompiled/Config.toml.

Create the directory and configuration file:

mkdir -p "$HOME/Library/Application Support/WiiCompiled"

For Base Game Only (WiiCompiled):

# ~/Library/Application Support/WiiCompiled/Config.toml
[video]
widescreen = true
resolution_multiplier = 1.0
graphics_api = "metal"

[paths]
dvd_root = "/absolute/path/to/Wiicompiled/Assets/DATA"

For Base Game and Retro Rewind:

# ~/Library/Application Support/WiiCompiled/Config.toml
[video]
widescreen = true
resolution_multiplier = 1.0
graphics_api = "metal"

[paths]
dvd_root = "/absolute/path/to/Wiicompiled/Assets/DATA"
retro_rewind_root = "/path/to/RetroRewind6"

Note

Ensure dvd_root points to the directory containing files and sys/fst.bin.

Launching the Game

Run the compiled binaries directly from your terminal or by double clicking:

# Run base WiiCompiled
./build-macos/WiiCompiled

# Run Retro Rewind
./build-macos/RetroRewind

Press F10 in-game at any time to open the configuration bar (controls, resolution, display settings, audio).

---

Quick Reference: Automated Helper Script

The repository provides a script (Launcher/local-build-macos.command) that handles extraction, translation, and compilation in a single command.

Building Base Game Only:

Launcher/local-build-macos.command \
  --profile base \
  --output-dir build-macos/Products \
  --game /path/to/RMCP01.iso \
  --nodtool ./nodtool

Building Both (with Online Retro-WFC Payload):

# 1. Download Retro-WFC payload into a staging directory:
mkdir -p build/retro-wfc/binary
curl -fsSL --retry 3 "http://nas.play.rwfc.net/payload?g=RMCPD00" \
  -o build/retro-wfc/binary/payload.RMCPD00.bin

# 2. Run the automated build with the payload directory:
Launcher/local-build-macos.command \
  --profile both \
  --output-dir build-macos/Products \
  --base-output-dir build-macos/Products \
  --game /path/to/RMCP01.iso \
  --nodtool ./nodtool \
  --retro-rewind-package-dir /path/to/RetroRewind6 \
  --retro-wfc-offline-dir build/retro-wfc

Building Both (Offline, Skipping Payload):

Launcher/local-build-macos.command \
  --profile both \
  --output-dir build-macos/Products \
  --base-output-dir build-macos/Products \
  --game /path/to/RMCP01.iso \
  --nodtool ./nodtool \
  --retro-rewind-package-dir /path/to/RetroRewind6 \
  --skip-retro-wfc-payload

When finished, the compiled executables reside in native-build-macos/ and the bundled .app packages are placed in build-macos/Products/.