ZeldaWWHDRecomp

ZeldaWWHDRecomp is a native PC port of The Legend of Zelda: The Wind Waker HD for Windows, Linux, and macOS with features like save states and an in-game settings overlay.

README

The Legend of Zelda: The Wind Waker HD — native port (macOS, Linux, Windows, Android)

Discord

A static recompilation of the Wii U version (USA or European) that runs natively on macOS (Apple Silicon), Linux, Windows and Android (arm64; the setup app builds the game on the phone, see Android). The game's PowerPC code is translated to C ahead of time, the Cafe OS libraries the game uses are reimplemented natively, and GX2 graphics are implemented directly on Metal (macOS) or Vulkan (all platforms), with no Cemu runtime and no GPU command emulation.

How it works and how it differs from running the game in Cemu: docs/how-it-works.md.

The project has three parts:

  • The port (this repository): the recompiled game on macOS, Linux, Windows and Android, described below.
  • The decompilation (ZeldaWWHDDecomp/wwhd): readable C++ source for the game's code, each function tested against the original. The port can already run it in an experimental decomp build, the path towards a fully native source port; see decomp build.
  • Mods (ZeldaWWHDRecomp/ZeldaWWHDMods): built-in options and a catalogue of community mods, installed from inside the game; see Mods.

What's new

v0.5.1: a built-in randomizer, GameCube models and many ideas from the Android forks.

  • Randomizer built in: make a randomized game from a preset, seed name or permalink in setup, or import a seed from the official TWWHD Randomizer. Each randomized game keeps its own saves.
  • New options: GameCube player models from a pack you have, Achievements and Game progress, walk-through doors, instant text, Deku Leaf wave to rise, 16-character names, a cloud save folder, GameCube controller layout and prompts, keyboard and mouse prompts, and experimental 60 fps frame generation on Vulkan.
  • Smoother and more exact: 60 fps interpolation now runs the same game logic as 30 fps (True 60 is retired), HDR with truer shadows, and Android back to full speed with less memory use and fixes for Adreno and Huawei GPUs.
  • Many fixes on every platform, and more for mod makers. Thanks to all contributors and the GreenNaugahyde and Nycolazs Android forks.

The changes in each update are in CHANGELOG.md and in the release notes on the Releases page.

Legal notice

This is an unofficial fan project. It is not affiliated with, endorsed or sponsored by Nintendo. "The Legend of Zelda", "The Wind Waker", "Wii U" and related names are trademarks of their respective owners and are used here only to describe what this software is compatible with.

This repository contains no game code, no game assets and no keys: no executable, no recompiled or disassembled game code, no textures, models, audio, shaders, screenshots or other material from the game, and no console encryption keys. It contains only the tools and the runtime written for this project (plus the third-party code listed under Credits).

To use it you need your own, legally obtained copy of the game, dumped from your own Wii U disc and console. Everything game-specific (the extracted files, the recompiled code in build/gen/, shader caches) is generated locally on your machine from your dump, and must not be redistributed. The .gitignore keeps all of it out of the repository.

Install (releases)

Releases are portable: unzip, start Wind Waker HD, choose your dump. Releases contain only this project's runtime, tools and setup: no game files, no game code and no keys. The game's code can only exist once it is built from your own dump, so the first start prepares the game once, on your computer (about two minutes); every later start launches the game directly.

  1. Download the zip for your system from the Releases page and unzip it anywhere (a games folder, an external drive):

    • macOS: Apple Silicon, macOS 14 or newer (Metal renderer; Vulkan through MoltenVK, included, can be picked in Graphics > Renderer)
    • Windows: x86-64 (windows-x86_64, Windows 10 version 1903 or newer, or Windows 11) or arm64 (windows-arm64, Windows 11 on ARM, e.g. Snapdragon X), a GPU with Vulkan 1.3 drivers (or Vulkan 1.1 / 1.2 drivers with VK_KHR_dynamic_rendering). The arm64 zip runs natively, and only on ARM64 (its setup says so on an x86-64 PC). On ARM, 60 fps keeps the game's speed by default (Graphics > "Keep game speed"), as on Android: where two frames per step do not fit, in-between frames are skipped instead of slowing the whole game down
    • Linux: x86-64 (linux-x86_64) or arm64 (linux-aarch64, e.g. Raspberry Pi 5, Asahi Linux on Apple Silicon, other ARM boards and laptops), glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, Fedora 36+, Arch, SteamOS 3, Raspberry Pi OS 12), a GPU with Vulkan 1.3 drivers (or 1.1 / 1.2 with VK_KHR_dynamic_rendering). Take the zip that matches uname -m (x86_64 or aarch64); setup says so if it doesn't. Or take the single-file AppImage (same two architectures) instead of the zip (issue #55): chmod +x it and start it from anywhere, Steam Deck included. Nothing is unzipped and the file itself is never written to.
  2. Start Wind Waker HD (Wind Waker HD.app, Wind Waker HD.exe, or wind-waker-hd / Wind Waker HD.desktop on Linux). The first start asks for:

    • your disc image (.wux or .wud), a Cemu archive (.wua), or an already extracted game folder (with code, content and meta, e.g. from dumpling or Cemu). An extracted folder is used where it is, nothing is copied; a disc image or Cemu archive is extracted into the release folder (about 1.7 GB);
    • for a disc image, its disc key (a .key file with the image's name next to it is used automatically) and the Wii U common key (16 bytes, the same on every console; choose a key file or paste the 32 hex digits into the hidden field; a common.key next to the image or in the release folder is used automatically). Keys are checked before anything is extracted, never stored, and not part of any log. A Cemu archive or an extracted folder needs no keys.
    • A Cemu archive (Cemu's "Convert to compressed Wii U archive (.wua)") often holds the game, its update and DLC together. Setup uses the game itself, title 00050000-10143500 (USA) or 00050000-10143600 (Europe), version 0, and says so in its log; an update in the archive is not used: the port is built for the code of version 0, and the update's files belong to its newer code. The archive's checksum is verified before anything is extracted.

    Then it prepares the game (extract, translate the code to C, compile with a pinned compiler) and offers to bring in a save: a Wind Waker HD cking.sav folder (Cemu, Wii U), a GameCube .gci (converted to HD), or the saves and settings of an earlier installation or another Wind Waker HD folder (copied, never moved). The USA version (title 00050000-10143500) and the European one (00050000-10143600) are supported, version 0 of either (the disc or eShop release, without the update): before translating, setup checks the game's code (code/cking.rpx) against the SHA-256 of each and explains what to use instead when it matches neither (e.g. a game folder with an update copied over it). The European game plays in English, French, German, Italian or Spanish — its own text, chosen in the settings' Language tab. How one port serves both: docs/builds.md.

  3. That's it: start Wind Waker HD to play. To repair, update or change the game, hold Shift while starting it (macOS, Windows) or start it with --setup (Linux; also the "Setup" action of its menu entry).

First start, per system:

  • macOS: the release is not signed by Apple, so the first time macOS says the app "cannot be opened". macOS 14: right-click (Ctrl-click) the app, Open, Open. macOS 15 and newer: click Done, then System Settings › Privacy & Security › Open Anyway. If Apple's Command Line Tools (the free compiler, which also brings Python) are missing, Wind Waker HD offers Apple's installer. Start the app inside the unzipped folder and keep it there: it needs tools/, sdk/ and portable.txt next to it. Don't drag only Wind Waker HD.app into Applications; to keep the game somewhere else, move the whole folder. The folder must be writable (not a disk image or a read-only drive). If macOS asks whether Wind Waker HD may access your Downloads (or Desktop, Documents) folder, click Allow: the game is prepared in that folder. Releases up to v0.2.3 stopped with "Setup could not continue … must stay in the unpacked release folder" when started straight from the unzipped download (issue #48, macOS App Translocation); with those, run xattr -dr com.apple.quarantine <the unzipped folder> in Terminal once, then open the app again. When setup cannot continue it says what failed and what to do, and writes it to data/setup-window.log (or ~/Library/Logs/Wind Waker HD setup.log when the folder is not writable).
  • Windows: the release is not code-signed, so SmartScreen may say "Windows protected your PC": More info › Run anyway. Python comes with the release (tools/python, the official embeddable Python). The first start downloads the compiler (llvm-mingw, 190 MB) into the release folder, SHA-256 checked, no administrator rights; at the end you can remove the compiler again (it is only needed to repair, and downloaded again then).
  • Linux: start wind-waker-hd (or Wind Waker HD.desktop; some desktops ask to allow launching it first). It uses your Python 3 and downloads the compiler (zig, 55 MB; the x86-64 or arm64 build matching your system) into the release folder; you can remove it at the end.
  • Linux (AppImage): chmod +x WindWakerHD-*-linux-*.AppImage, then start that file (from a file manager, a terminal or Steam as a non-Steam game). It needs no unzipping and no writable folder of its own. Ubuntu 24.04 and newer have no FUSE by default: install libfuse2t64 (libfuse2 on older releases), or start it with --appimage-extract-and-run. Repair or change the game with --setup. Everything it creates is listed under "Everything stays in the release folder" below.
  • Linux with an NVIDIA GPU on Wayland (issue #309): on Wayland the game turns on NVIDIA's older sync method by itself (__NV_DISABLE_EXPLICIT_SYNC=1), because the newer one can make the desktop close the game's window. If you see flicker or slowdown, start it with __NV_DISABLE_EXPLICIT_SYNC=0 to switch that off; if the window still closes, start it with SDL_VIDEO_DRIVER=x11 (XWayland). A hybrid laptop also needs prime-run to use the NVIDIA GPU.

Everything stays in the release folder (in data/): the built game, the extracted game files, saves (data/save), settings, controls, save states and shader caches (data/user), crash logs (data/captures), the setup log and the downloaded compiler. Nothing is written to your user folders (Application Support, AppData, .config, Applications, Start menu) unless you tick "add a shortcut" at the end. To remove everything, delete the folder. Starting a newer release: unzip it next to the old one, start it, choose your game (the old folder's data/game can be used in place) and copy your saves and settings from the old folder.

The Linux AppImage is not a portable folder (issue #55): its file is read-only, so the game, its code and saves go to ~/.local/share/wwhd and the settings, controls, save states and caches to ~/.config/wwhd (or $XDG_DATA_HOME / $XDG_CONFIG_HOME; --data-dir FOLDER chooses another place for the first, for example an SD card on a Steam Deck). Nothing is written beside the .AppImage; the menu entry the setup adds starts the same game. To remove everything, delete the file and those two folders. Portable use (the AppImage runtime's own portable mode): start the AppImage once with --appimage-portable-home, or create a folder named like it plus .home next to it (for example WindWakerHD-v0.2.13-linux-x86_64.AppImage.home). The AppImage then uses that folder as your home folder, so the game, its code, saves, settings and caches stay in it (.local/share/wwhd, .config/wwhd, .cache); keep the file and the folder together, and start the AppImage itself (the setup's menu entry stays inside that folder too). If your session sets XDG_DATA_HOME or XDG_CONFIG_HOME, those still win over the portable folder. The .data folder of v0.2.13 is no longer used (the AppImage says so when it finds one); the changelog has how to move it to .home.

The setup also runs in a terminal (the fallback): tools/Setup in Terminal.command (macOS), tools/Setup in a console window.bat (Windows), tools/setup-in-terminal.sh (Linux). How it works and the interface between the window and tools/installer/setup.py: tools/installer/README.md. Scripted use: tools/installer/setup.py --help.

Source builds (below) and the Linux AppImage (without a .home folder) are not portable: they keep using the per-user folders (~/Library/Application Support/wwhd, %LOCALAPPDATA%\WWHD for the game and saves, ~/.config/wwhd for the settings on Linux), as before.

Requirements (building from source)

  • macOS on Apple Silicon, Linux (x86-64 or arm64, Vulkan) or Windows (x86-64 or arm64, Vulkan); the platform-specific build steps are under "Building" below
  • macOS: Xcode command line tools (xcode-select --install)
  • zstd for the extractor's .wua support: a system one if installed (brew install zstd, apt install libzstd-dev; found through its CMake package or pkg-config), otherwise CMake downloads the pinned source (-DWWHD_BUNDLED_ZSTD=ON always does, as release builds do)
  • CMake 3.20 or newer
  • Python 3 with pycryptodome for tools/wudextract.py (pip3 install pycryptodome); the native wwhd-extract built with the project (build/cmake/wwhd-extract --help) needs neither
  • optional: capstone (pip3 install capstone) for the disassembler helper tools/ppcdis.py
  • optional, decompilation tools only: ninja and the requirements of the zeldaret/tww build (see below)

You also need, from your own console and disc:

  • a disc image of The Wind Waker HD (USA or Europe) in .wud or .wux format (or a Cemu archive, .wua: build/cmake/wwhd-extract --title 0005000010143500 extract game.wua game, with 0005000010143600 for the European game, no keys);
  • its disc key (16 bytes) in a .key file next to the image, with the same base name;
  • the Wii U common key, either in a file common.key (16 raw bytes or 32 hex digits) next to the image or in the current directory, or in the WIIU_COMMON_KEY environment variable (32 hex digits). As a text file it is one line of 32 hex digits, nothing else; a wrong or malformed common key also makes the extraction fail with a decryption error.

None of these are included or will be provided.

Building

For the Vulkan renderer also: brew install vulkan-headers vulkan-loader molten-vk glslang (the build needs them; the app still runs with Metal on a Mac without them). -DWWHD_RENDERER=METAL builds a Metal-only app without any Vulkan dependency.

# 1. extract the game into game/ (game.wux with game.key next to it, plus your common key)
python3 tools/wudextract.py game.wux extract game
#    -> game/code/cking.rpx, game/content/..., game/meta/...

# 2. recompile the game code to C (writes build/gen/; stays on your machine)
python3 tools/recomp/recomp.py game/code/cking.rpx build/gen

# 3. build
cmake -S . -B build/cmake && make -C build/cmake -j$(sysctl -n hw.ncpu) wwhd
Linux

The Linux build uses the Vulkan renderer with the SDL3 host (windows, input, audio). On Ubuntu 24.04:

sudo apt install clang cmake ninja-build zlib1g-dev liblz4-dev libvulkan-dev glslang-dev \
  mesa-vulkan-drivers libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxss-dev \
  libxfixes-dev libxkbcommon-dev libwayland-dev libasound2-dev libpulse-dev libudev-dev libdbus-1-dev
# SDL3 is not packaged in 24.04: build it from source (https://github.com/libsdl-org/SDL, release-3.2.x)
cmake -S . -B build/linux -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build build/linux
./build/linux/wwhd --renderer-smoke     # checks the Vulkan renderer, no game files needed

If linking fails with unwinder errors (missing _Unwind_* symbols or -lunwind), your clang is set up to use LLVM's libunwind. Configure with the GCC unwinder instead:

cmake -S . -B build/linux -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_EXE_LINKER_FLAGS="--unwindlib=libgcc"

On Arch-based systems (Arch, CachyOS, Manjaro):

sudo pacman -S clang cmake ninja sdl3 vulkan-headers vulkan-icd-loader glslang shaderc python-pycryptodome
# plus the Vulkan driver for your GPU, e.g. vulkan-radeon (AMD) or vulkan-intel

Wii U volumes are case-insensitive and the game asks for paths in a different case than the extracted folders (e.g. Audiores vs AudioRes); the runtime resolves such paths itself on case-sensitive file systems. When the game asks for text (your name), a text window appears over the game (see Entering text under Playing).

On Linux and Windows, F11 or Alt+Enter switches the focused window (TV or GamePad) to full screen and back; the TV window's full screen (also the settings overlay's Display > Full screen) is remembered in settings.ini and the next start begins the same way. Clicking/dragging with the left mouse button in the GamePad window uses the touch screen. The GamePad screen has the macOS modes (settings overlay, Display): a separate window, a picture-in-picture overlay in a corner of the TV window (corner, size and opacity selectable; click it to touch), the automatic overlay, off, or the GamePad picture alone in the TV window (click it to touch); Ctrl+G shows/hides it, and the choices are saved in settings.ini. Closing the TV window ends the game; closing the GamePad window only hides it. These builds have no menu bar: the macOS menus' options (Graphics, Display, Input, Save States) are in the settings overlay (F1, see Playing), plus the number-key shortcuts and the environment variables below.

Settings, controls and save states live under ~/.config/wwhd (or $XDG_CONFIG_HOME/wwhd). To check the build without the game, python3 tools/recomp/stubgen.py build/gen-stub writes placeholder guest code and -DGEN_DIR=$PWD/build/gen-stub builds against it (the result cannot run the game).

Windows

The Windows build uses the same Vulkan renderer and SDL3 host as Linux. Both native LLVM and MSYS2 CLANG64 builds are supported. Choose either method below and use separate build directories when switching toolchains. Both require the generated build/gen from the recompiler steps above.

Native LLVM (PowerShell, without MSYS2)

Install LLVM (with clang and clang++), CMake, Ninja, Visual Studio's Desktop development with C++ workload (for the Windows headers and runtime libraries), and the Vulkan SDK. Ensure clang, clang++, cmake and ninja are on PATH, and VULKAN_SDK points to the SDK installation. Run from PowerShell:

cmake -S . -B build/windows -G Ninja