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.
- Type: PC port
- Game: The Legend of Zelda: The Wind Waker HD
- Runs on Windows, Linux, macOS and Android
- By ZeldaWWHDRecomp
- Latest release v0.5.1, 2026-11-06
- Source: https://github.com/ZeldaWWHDRecomp/ZeldaWWHDRecomp
README
The Legend of Zelda: The Wind Waker HD — native port (macOS, Linux, Windows, Android)
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.
-
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 withVK_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 withVK_KHR_dynamic_rendering). Take the zip that matchesuname -m(x86_64oraarch64); setup says so if it doesn't. Or take the single-file AppImage (same two architectures) instead of the zip (issue #55):chmod +xit and start it from anywhere, Steam Deck included. Nothing is unzipped and the file itself is never written to.
-
Start Wind Waker HD (
Wind Waker HD.app,Wind Waker HD.exe, orwind-waker-hd/Wind Waker HD.desktopon Linux). The first start asks for:- your disc image (
.wuxor.wud), a Cemu archive (.wua), or an already extracted game folder (withcode,contentandmeta, 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
.keyfile 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; acommon.keynext 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.savfolder (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. - your disc image (
-
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/andportable.txtnext to it. Don't drag onlyWind Waker HD.appinto 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, runxattr -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 todata/setup-window.log(or~/Library/Logs/Wind Waker HD setup.logwhen 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(orWind 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: installlibfuse2t64(libfuse2on 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=0to switch that off; if the window still closes, start it withSDL_VIDEO_DRIVER=x11(XWayland). A hybrid laptop also needsprime-runto 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
.wuasupport: 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=ONalways does, as release builds do) - CMake 3.20 or newer
- Python 3 with
pycryptodomefortools/wudextract.py(pip3 install pycryptodome); the nativewwhd-extractbuilt with the project (build/cmake/wwhd-extract --help) needs neither - optional:
capstone(pip3 install capstone) for the disassembler helpertools/ppcdis.py - optional, decompilation tools only:
ninjaand 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
.wudor.wuxformat (or a Cemu archive,.wua:build/cmake/wwhd-extract --title 0005000010143500 extract game.wua game, with0005000010143600for the European game, no keys); - its disc key (16 bytes) in a
.keyfile 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 theWIIU_COMMON_KEYenvironment 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