Wii U decomp guide

What this system is like

The Wii U runs on a PowerPC chip called Espresso. Each game keeps its main code in one .rpx file. An .rpx is a changed kind of ELF file, the common format for programs. Since 2026, tools turn that file into C or C++ that a PC can build. This is called static recompilation.

Ten of the 14 projects reviewed here used static recompilation. Most new ones did not start from zero. They borrowed the recompiler and runtime of an earlier port, such as the Wind Waker HD port. A runtime is the code that stands in for the console. Several reached a first boot within days.

A full decomp is harder. The original compiler, Green Hills MULTI, is a paid tool that hobbyists cannot simply get. So byte matching is mostly closed. The best result so far, for Wind Waker HD, checks each readable function against the recompiled original. It is nearly complete, but it still needs the recomp to run.

Path A runs on Windows. Plan to use WSL for the Path B test harness and for any Linux build.

Two paths

Path A: Get it running on PC

A recompiler reads your game's .rpx and writes C for every function. You build that C together with a runtime that stands in for Cafe OS, GX2 graphics, sound and input. You borrow the runtime from a working port. Then you fill in the system calls your game needs, one at a time.

1. Scope the game and pin the exact file

   Pick one game, one region and one update. Check if someone already ported it, or a game on the same engine. Then write the Scope Contract. Every later session works on that same file.

   • Search RecompLauncher and GitHub for your game. Twilight Princess HD started as a fork of the Wind Waker HD port.
   • Dump your own copy with Dumpling on your Wii U. It writes the game, its update and DLC as extracted code/, content/ and meta/ folders.
   • Merge the update over the base game into one game/ folder. Captain Toad does this with hash-checked copies into an empty folder.
   • Record the hash of the main file. In PowerShell run Get-FileHash game/code/<NAME>.rpx -Algorithm SHA256.
   • Write SCOPE.md: game, region, title ID, update version, the .rpx hash, the donor port, and what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for a static recompilation of <GAME> on Wii U.
   READ FIRST: `notes/game-files.txt` (my folder list, title ID and the `.rpx` hash), `notes/prior-work.md` if it exists.
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `Select-String -Path SCOPE.md -Pattern '^## (Game|Region|Title ID|Update|Hash|Donor port|Milestone|Out of scope)$'`. Done means it prints 8 lines. The Hash section must hold the same SHA-256 that `Get-FileHash game/code/<NAME>.rpx -Algorithm SHA256` prints. The Donor port section names one port and one reason, with a link.
   BUDGET: Stop after 30 minutes of searching for prior work.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the Select-String output and both hashes. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenSelect-String -Path SCOPE.md -Pattern '^## (Game|Region|Title ID|Update|Hash|Donor port|Milestone|Out of scope)$' prints 8 lines. The hash in SCOPE.md equals what Get-FileHash prints. Then you approve it.

   Proof this works: Twilight Princess HD: Recompiled, Captain Toad EUR - Android recompilation prototype, Smash 4 PC, https://github.com/dumpling-app/dumpling

2. Set up the Windows tools and the donor runtime

   Install the compiler, the build tools and the Vulkan SDK. Copy the donor port at one fixed commit. Prove the toolchain works before any game code goes in. Then write one check command.

   • Install LLVM from LLVM-23.1.5-win64.msi, CMake, Ninja and the Vulkan SDK 1.4.363.1. Add Visual Studio's Desktop development with C++ workload for the Windows headers. Put clang, clang++, cmake and ninja on PATH, and set VULKAN_SDK.
   • Run pip install pycryptodome for the donor's disc extractor. pip install capstone is optional. It powers the disassembler helper tools/ppcdis.py.
   • Clone the donor: git clone https://github.com/ZeldaWWHDRecomp/ZeldaWWHDRecomp donor. Then pin it with git -C donor checkout <COMMIT>. Captain Toad also pins its donor to one commit.
   • Build the donor with placeholder code first. Run python donor/tools/recomp/stubgen.py build/gen-stub, then configure with -DGEN_DIR=$PWD/build/gen-stub.
   • Configure and build: cmake -S donor -B build/windows -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release, then cmake --build build/windows. The build folder stays outside donor/, so the checkout stays clean.
   • Use Clang, never cl.exe. The generated code needs Clang's musttail feature.
   • Add game/, build/ and generated/ to .gitignore. Write tools/check.ps1 that builds, runs ctest, runs --renderer-smoke and prints PASS or FAIL.
   Prompt for ClaudeCopy

   GOAL: Make `tools/check.ps1` build the pinned donor runtime with stub game code and print PASS or FAIL.
   READ FIRST: `SCOPE.md`, the donor README section Windows (Native LLVM), `donor/CMakeLists.txt`.
   FENCE: Edit only `tools/`, `.gitignore` and `CLAUDE.md`. The `donor/` checkout and `game/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Stub`. Done means it runs `stubgen.py`, configures with Clang and Ninja, builds, runs `ctest --test-dir build/windows --output-on-failure` and `--renderer-smoke`, then prints one line: PASS or FAIL with the reason. The switches `-Stub`, `-Codegen`, `-BootSeconds <N>` and `-Golden [<name>]` must exist. A switch with nothing to test yet prints SKIP.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: Stop. Do not switch to `cl.exe` or edit the donor to get past it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the last 20 lines of the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpowershell -ExecutionPolicy Bypass -File tools/check.ps1 -Stub prints PASS: the stub build, ctest and --renderer-smoke all pass with no game files.

   Proof this works: Wind Waker HD Recomp, NSMBU Recomp, VR-WakerHD, https://github.com/ZeldaWWHDRecomp/ZeldaWWHDRecomp

3. Map the executable and audit its imports

   Learn what the game asks of the system before you build it. List every import and compare it with the donor runtime. Also export a function list to track progress.

   • Install Ghidra 12.0 with Java 21. Copy GhidraRPXLoader-0.9.2-d496d43-Ghidra_12.0.zip into Ghidra's Extensions/Ghidra folder. Then add it with File, Install Extensions.
   • Import <NAME>.rpx, pick the Gekko/Broadway/Espresso language, then run fix_primary_imports.java so imports show real names.
   • Write tools/audit_imports.py. It lists each .fimport_* and .dimport_* entry and marks it present or missing in the runtime. Captain Toad's audit_rpx.py found 362 function imports this way.
   • Export every function to notes/functions.csv with address, size, name and a status column. Cha-Cha keeps these tables in config/*.csv.
   • Check for a symbol table. Minecraft and Tekken had .symtab names. Super Mario Maker had none, so its functions were found from branch targets.
   Prompt for ClaudeCopy

   GOAL: Fill `notes/imports.csv` and `notes/functions.csv` for <GAME>'s `<NAME>.rpx`.
   READ FIRST: `SCOPE.md`, the Ghidra export in `notes/ghidra/`, the donor's Cafe OS folder `donor/runtime/src/`.
   FENCE: Edit only `notes/imports.csv`, `notes/functions.csv`, `notes/findings.md` and `tools/audit_imports.py`. Ghidra project files, `donor/` and `game/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python tools/audit_imports.py game/code/<NAME>.rpx donor/runtime/src`. Done means it prints PASS and a count line: total imports, present, missing. Every row of `notes/functions.csv` has address, size and status, with no overlaps.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Do not guess an import's meaning. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the count line and five sample missing imports. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/audit_imports.py prints PASS with a missing-import count, and notes/functions.csv has a status column.

   Proof this works: Captain Toad EUR - Android recompilation prototype, Cha-Cha-Plus, Project Yamamura, https://github.com/Maschell/GhidraRPXLoader

4. Run the first codegen with the donor's hooks off

   Now the recompiler writes C for your game. First switch off the donor's game patches. Those hooks were made for another game's addresses. Left on, they would patch random code in yours.

   • Empty the donor's hook lists. Copy donor/tools/recomp to tools/recomp in your repo. Delete its hooks*.txt, then create an empty hooks.txt. The Wind Waker HD decomp empties the hooks the same way.
   • Run python tools/recomp/recomp.py game/code/<NAME>.rpx build/gen. Never edit build/gen by hand.
   • Point CMake at it with -DGEN_DIR=$PWD/build/gen and build. The first build compiles hundreds of thousands of lines, so allow time and memory.
   • Add your own game target and hook file in your repo, not in donor/. Captain Toad keeps its changes as patch files.
   • Log any words the recompiler could not decode. Captain Toad found 36 that may be data or padding.
   • Give your game its own .rpx check. The donor runtime checks at start that game/code/cking.rpx matches the generated code. Captain Toad adds a profile with its own .rpx hash.
   Prompt for ClaudeCopy

   GOAL: Make the recompiler run on <GAME>'s `<NAME>.rpx` and make the generated code build.
   READ FIRST: `SCOPE.md`, `donor/docs/how-it-works.md`, the last log in `out/logs/codegen.txt`.
   FENCE: Edit only `patches/`, `tools/recomp/hooks.txt`, `CMakeLists.txt` in my repo and `notes/findings.md`. `build/gen` is machine-made and read-only. `donor/` is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Codegen`. Done means `recomp.py` exits 0, the build links, and the donor's hook lists are empty. Copy every undecoded word into `notes/findings.md` with its address.
   BUDGET: Stop after 3 failed tries on one error.
   IF BLOCKED: Stop. Do not edit generated files to make them compile. Tell me the error, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: last log lines and the empty hook list. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpowershell -ExecutionPolicy Bypass -File tools/check.ps1 -Codegen prints PASS: codegen exits 0, the game executable links, and no donor hook is active.

   Proof this works: Captain Toad EUR - Android recompilation prototype, https://github.com/ZeldaWWHDDecomp/wwhd, Pikmin 3: native Windows port (static recompilation)

5. Boot to the first frame

   Run the game until it stops. Most early stops are a missing system call. Add that call to the runtime, rebuild and run again. Repeat until a picture shows.

   • Run the game under a time limit, such as ./build/windows/<game>.exe with a -BootSeconds 120 wrapper in tools/check.ps1.
   • Make every missing import fail loudly with its name. Captain Toad exits with code 78 rather than faking success.
   • Write each missing call in the runtime's Cafe OS folder, named after the real export, such as OSCreateThread. Track each one in notes/imports.csv as stub, partial or done.
   • Keep the console's thread rules: one thread at a time per core, strict priorities. Wind Waker HD saw data corruption without them.
   • Compare with Cemu when unsure what a call should return.
   Prompt for ClaudeCopy

   GOAL: Get <GAME> past its next boot stop at import <IMPORT> or address <ADDRESS>.
   READ FIRST: `SCOPE.md`, the last 50 lines of `out/logs/boot.txt`, `notes/imports.csv`.
   FENCE: Edit only `src/cafe/` and `notes/imports.csv`. `build/gen`, `donor/` and `game/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -BootSeconds 120`. Done means the log no longer stops at <IMPORT>. Paste the old and new last log lines.
   BUDGET: One stop per session. Stop after 3 failed tries.
   IF BLOCKED: Stop. Do not return a fake success code to move on. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: old and new last log lines. 3) Files changed. 4) The import's new status, and why. 5) New parking-lot items.

   Done whenpowershell -ExecutionPolicy Bypass -File tools/check.ps1 -BootSeconds 120 prints PASS: the log shows the first-frame line you chose, and out/shots/boot.png exists.

   Proof this works: Captain Toad EUR - Android recompilation prototype, Cha-Cha-Plus, Wind Waker HD Recomp, https://github.com/cemu-project/Cemu

6. Fix one bug at a time, with evidence

   Now play forward. Each crash, hang, wrong picture or missing sound is one unit of work. Find the cause first. Run the same scene in Cemu before you change code.

   • Log each bug in notes/bugs.md with exact steps to see it.
   • Run the same scene in Cemu. If it breaks there too, look at the original game's behavior before blaming the port.
   • Change behavior with a hook in your repo. Tekken's design lets you replace sub_<address> and still call sub_<address>_orig. Never edit generated code.
   • Use RenderDoc for graphics bugs. Pikmin 3 found lost shader writes only this way.
   • Check memory rules on a hang. Tekken and Smash mark every guest load and store volatile, because Clang folded a spin-wait into one read.
   Prompt for ClaudeCopy

   GOAL: Find and fix the cause of bug <BUG-ID> in <GAME>.
   READ FIRST: `notes/bugs.md` entry <BUG-ID>, `notes/findings.md`, the log and capture files named in the bug.
   FENCE: Edit only `src/` and `tools/recomp/hooks.txt`. `build/gen`, `donor/` and `game/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden`. Done means the bug's repro run passes and every older golden run still passes. Show the cause with evidence, such as a Cemu comparison or a RenderDoc capture, before you change code.
   BUDGET: Stop after 2 failed fixes, or 45 minutes with no new evidence.
   IF BLOCKED: Stop. Do not hide the crash by skipping the call. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the cause with its evidence, then the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpowershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden prints PASS for the bug's repro run and for every older golden run.

   Proof this works: Tekken Tag Tournament 2 Ultimate, Smash 4 PC, Pikmin 3: native Windows port (static recompilation), Wind Waker HD Recomp

7. Build golden runs

   Playing by hand does not scale. Script runs that reach a scene, play fixed input and check the result. Run them after every change. Then old fixes stay fixed.

   • Add a way to start in any scene. Twilight Princess HD uses a warp setting, WWHD_WARP, to load each of its 78 stages.
   • Record and replay input. SplatPC uses RBREW_INPUT_RECORD and RBREW_INPUT_REPLAY to reproduce bugs the same way each time.
   • Take a screenshot and log line at a set time. Compare them with saved baselines.
   • Give Claude a command line for the running game. NSMBU's nsmbu tool can boot a scene, wait, take a picture and diff two runs.
   • Wrap it all in powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden so one command prints PASS or FAIL for each run.
   Prompt for ClaudeCopy

   GOAL: Add golden run <NAME> that reaches <SCENE> and checks it.
   READ FIRST: `SCOPE.md`, `tools/check.ps1`, `tests/golden/README.md`.
   FENCE: Edit only `tests/golden/` and `tools/`. Never touch my real save folder. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden <NAME>` three times. Done means it passes all three times on the current build. It must also FAIL when I swap in the screenshot from <OTHER-SCENE>.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: Stop. Do not loosen the image threshold to make it pass. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the three passing runs and the one forced failure. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOn a clean checkout, powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden prints PASS for every golden run.

   Proof this works: Twilight Princess HD: Recompiled, SplatPC, NSMBU Recomp, Wind Waker HD Recomp

8. Package it without game data

   Players must use their own copy. Your repo and releases hold only your code. The reviewed ports build the game on the player's PC from the player's own dump.

   • Check the player's .rpx by SHA-256 against your known list. Refuse the rest with a clear reason. Tekken's recompiler refuses any other Tekken.rpx.
   • Keep build/gen, game/ and save states out of git. Twilight Princess HD scans each release zip for game code and keys with guard.py.
   • Keep CI working without the game. Build against stub game code and run ctest. NSMBU uses stubgen.py. BotW Native links a guest stub.
   • Pin every downloaded tool by version and hash. VR-WakerHD checks llvm-mingw by SHA-256.
   • Check the licence of borrowed code. The Wind Waker HD port and Cemu use MPL-2.0. Tekken uses MIT.
   Prompt for ClaudeCopy

   GOAL: Make the setup accept only supported copies of <GAME> and keep game data out of the repo and releases.
   READ FIRST: `SCOPE.md`, `installer/`, `config/supported-versions.json`.
   FENCE: Edit only `installer/`, `config/supported-versions.json` and `tools/check-boundary.ps1`. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check-boundary.ps1` and `powershell -ExecutionPolicy Bypass -File installer/test.ps1`. Done means both print PASS. A changed `.rpx` must be rejected with a reason. The boundary check must FAIL when I add a test file named `game/code/test.rpx` to git.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: Stop. Do not weaken the hash check. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs, the rejection message and the forced failure. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOn a clean clone with your own dump, powershell -ExecutionPolicy Bypass -File tools/check-boundary.ps1 and powershell -ExecutionPolicy Bypass -File installer/test.ps1 both print PASS.

   Proof this works: Tekken Tag Tournament 2 Ultimate, Twilight Princess HD: Recompiled, NSMBU Recomp, VR-WakerHD

Path B: Full decomp for porting

No Wii U game has a full matching decomp. The route here starts from your Path A recomp. You replace machine-made functions with readable C++, one unit at a time. A test harness runs each new function next to its recompiled twin and compares every result. The Wind Waker HD decomp verified 38,828 functions this way.

1. Choose how you will prove each function

   Decide what counts as correct. Matching means your code builds to the exact original bytes. That needs the Green Hills compiler under licence. Verified non-matching uses your Path A recomp as the judge instead.

   • Look for prior work: a decomp of the same game on GameCube, Wii, Xbox 360 or Switch. Wind Waker HD used zeldaret/tww. Minecraft used the Xbox 360 build as a behavior reference.
   • Check for a symbol table and C++ type info in the .rpx. Minecraft's unstripped file named every class.
   • If you hold a Green Hills licence, matching is possible. Project Yamamura matched 2,360 Super Mario Maker functions with ccppc 5.3.27.
   • Without a licence, take the verified non-matching route. The rest of this path covers that route.
   • Update SCOPE.md with the route, the per-function check and what done means.
   Prompt for ClaudeCopy

   GOAL: Recommend matching or verified non-matching decompilation for <GAME> and update SCOPE.md.
   READ FIRST: `SCOPE.md`, `notes/prior-work.md`, https://github.com/ZeldaWWHDDecomp/wwhd, https://github.com/Jacobwasbeast/mcwiiu-reconstructed.
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `Select-String -Path SCOPE.md -Pattern '^## (Route|Per-function check|Compiler|Sister decomp|Symbols|First unit)$'`. Done means it prints 6 lines, and every claim under them has a link or a file path.
   BUDGET: Stop after 45 minutes.
   IF BLOCKED: Stop. Do not suggest ways to get the Green Hills compiler that may break its licence. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the new SCOPE.md sections. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenSelect-String -Path SCOPE.md -Pattern '^## (Route|Per-function check|Compiler|Sister decomp|Symbols|First unit)$' prints 6 lines. Then you approve it.

   Proof this works: https://github.com/ZeldaWWHDDecomp/wwhd, Project Yamamura, Minecraft: Wii U Edition - source reconstruction

2. Freeze a plain recomp as your reference

   Your recompiled game is the oracle. An oracle is a trusted source of right answers. Build a plain copy with no game patches, so it acts exactly like the original. Then pin it so it never drifts.

   • Copy the recompiler and empty its hook lists, as in Path A step 4.
   • Regenerate from a copy of the recompiler. The Wind Waker HD decomp runs WWHD_RECOMP_PLAIN=1 python3 tools/recomp_verify/recomp.py game/code/cking.rpx build/gen --ppc-nan-propagation. Check which flags your donor supports.
   • Tag the port commit, for example git tag reference-v1. The Wind Waker HD decomp names its exact port commit in the README.
   • Save your golden runs and their screenshots from Path A.
   Prompt for ClaudeCopy

   GOAL: Build and freeze a plain recompiled reference of <GAME> for Path B.
   READ FIRST: `SCOPE.md`, `tools/check.ps1`, the donor's recompiler options in `donor/docs/how-it-works.md`.
   FENCE: Edit only `tools/make_reference.ps1`, `notes/reference.md` and git tags. Code, config and `build/gen` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/make_reference.ps1` then `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden` on a clean clone of the tag. Done means the plain reference has zero hooks, every golden run passes, and `notes/reference.md` lists the tag, donor commit, recompiler flags and `.rpx` hash.
   BUDGET: Stop after 2 failed clean builds.
   IF BLOCKED: Stop. Do not change code to make a run pass. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the check output and the hook count. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whengit tag lists the reference tag. On a clean clone of it, powershell -ExecutionPolicy Bypass -File tools/make_reference.ps1 reports zero hooks and check.ps1 -Golden prints PASS.

   Proof this works: https://github.com/ZeldaWWHDDecomp/wwhd, Wind Waker HD Recomp

3. Name functions and split them into units

   A decomp needs names, types and sensible units of work. Get names from the file itself, then from a sister decomp. Record each name with how you know it.

   • Read names from .symtab and C++ type info when present. Cha-Cha named 26,000 functions from engine tables and Green Hills type info.
   • Match against a sister decomp if one exists. The Wind Waker HD port runs python3 tools/decomp/match.py game/code/cking.rpx tww build/names.tsv.
   • Mark unsure names with a ? suffix, as Cha-Cha's rules ask. Never invent a library name. NSMBU keeps sub_<ADDRESS> instead.
   • Group functions into units: one class family or one source file each. Minecraft uses one header and one code file per class family.
   • Mark library code, such as the Green Hills C runtime and nw::font. Wind Waker HD left those as recompiled code.
   Prompt for ClaudeCopy

   GOAL: Name the functions in unit <UNIT> of <GAME> and record the evidence.
   READ FIRST: `notes/functions.csv`, `notes/findings.md`, the Ghidra export for the unit's address range.
   FENCE: Edit only `notes/functions.csv`, `notes/findings.md`, `notes/units.csv` and `tools/check_names.py`. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: If `tools/check_names.py` is missing, write it first. Run `python tools/check_names.py`. Done means it prints PASS (no duplicate names, no name clashes with Cafe OS imports), and each new name has evidence and a confidence: confirmed, probable or guess.
   BUDGET: Name at most 25 functions. Stop after 60 minutes.
   IF BLOCKED: Stop. Keep `sub_<ADDRESS>` instead of inventing a name. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the check output and a count by confidence. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check_names.py prints PASS, and every function in the unit has a name or sub_<ADDRESS>, a confidence and an evidence note.

   Proof this works: Cha-Cha-Plus, NSMBU Recomp, Minecraft: Wii U Edition - source reconstruction, https://github.com/ZeldaWWHDDecomp/wwhd

4. Build the differential test harness

   Write one tool that runs a function both ways and compares the results. Every worker will use it. Then test the tester, so a broken function cannot pass.

   • Start from the Wind Waker HD decomp's tools/verify/. It runs both versions on 10,000 generated inputs per seed. Then it compares what each returns, writes and calls.
   • Track coverage: the inputs must reach nearly all basic blocks of the original. A basic block is a run of code with no branch inside.
   • Add mutation testing. Break the new code on purpose with mutate.py and confirm the harness catches it.
   • Run it in WSL. The harness uses Linux signals such as SIGUSR1, and a few units need tens of GB of memory.
   • Make it print one row per function: address, name, inputs passed, coverage and the first difference.
   Prompt for ClaudeCopy

   GOAL: Adapt a differential harness so `tools/verify/verify.py <UNIT>` compares rewritten functions of <GAME> with their recompiled twins.
   READ FIRST: `SCOPE.md`, `notes/reference.md`, https://github.com/ZeldaWWHDDecomp/wwhd/blob/main/tools/verify/README.md.
   FENCE: Edit only `tools/verify/` and `notes/harness.md`. `build/gen`, `src/decomp/` and `game/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: In WSL run `python3 tools/verify/verify.py <TEST-UNIT> -n 10000 -seed 1` on an exact copy of one function: every row must say ok. Then change one constant in the copy: the row must FAIL and name the first difference.
   BUDGET: Stop after 3 failed designs.
   IF BLOCKED: Stop. Do not compare only the return value. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the ok run and the forced FAIL run. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenIn WSL, python3 tools/verify/verify.py <TEST-UNIT> -n 10000 -seed 1 prints ok for an exact copy, and FAIL with the first difference for a broken one.

   Proof this works: https://github.com/ZeldaWWHDDecomp/wwhd, Wind Waker HD Recomp, Tekken Tag Tournament 2 Ultimate

5. First light: one readable function

   Take one small function that calls nothing else. Write it as plain C++ with real names and types. Prove it acts the same on both seeds. A seed is a starting number for the random inputs.

   • Pick a leaf function of 6 to 16 instructions. Project Yamamura started with leaves of that size.
   • Read the disassembly as evidence only. Never paste it into the source. Minecraft's rules forbid decompiler output in source/.
   • Write it in src/decomp/<unit>/<name>.cpp with the original address in a comment.
   • Run python3 tools/verify/verify.py <unit> -n 10000 -seed 1 and again with -seed 7.
   • Run python3 tools/verify/mutate.py <unit> --n 1000 --max 200 to prove the test can catch a broken copy.
   Prompt for ClaudeCopy

   GOAL: Rewrite `sub_<ADDR>` (<NAME>) of <GAME> as readable C++ that acts the same.
   READ FIRST: the disassembly of `sub_<ADDR>` from `tools/verify/wdis.py <ADDR>` or Ghidra, the `notes/functions.csv` row for it.
   FENCE: Edit only `src/decomp/<UNIT>/<NAME>.cpp` and the unit spec in `tools/verify/units/<UNIT>`. `build/gen` and the harness code are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: In WSL run `python3 tools/verify/verify.py <UNIT> -n 10000 -seed 1` and `-seed 7`. Done means both rows say ok with coverage of at least <COVERAGE>, and `mutate.py <UNIT> --n 1000 --max 200` reports no surviving mutant you cannot explain.
   BUDGET: Stop after 5 tries with no gain.
   IF BLOCKED: Stop. Do not call the original address from inside the new function. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both verify rows and the mutation summary. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython3 tools/verify/verify.py <UNIT> -n 10000 prints ok with the agreed coverage on -seed 1 and -seed 7, and mutate.py <UNIT> --n 1000 --max 200 leaves no unexplained mutant alive.

   Proof this works: https://github.com/ZeldaWWHDDecomp/wwhd, Project Yamamura, Minecraft: Wii U Edition - source reconstruction

6. Grind through the units in parallel

   Now repeat for many units. Do leaf functions first, then the ones that call them. Each worker takes one unit in its own git worktree. A worktree is a second copy of the repo on its own branch.

   • A lead session picks the next units from notes/units.csv and writes one task card each.
   • Start each worker with claude -w <name> so it gets its own worktree. Link build/ and game/ into it, since ignored folders are not copied.
   • Give each worker its evidence pack: disassembly, callers, callees and names. Minecraft hands workers one class family at a time with evidence.
   • Merge only when the unit passes both seeds on the merged branch.
   • Send units that fail three tries to a hard job. Record what was tried in the ledger.
   Prompt for ClaudeCopy

   GOAL: Rewrite the next <N> units of <GAME> from the ledger, one worker each.
   READ FIRST: `notes/units.csv` (status todo), `CLAUDE.md`.
   FENCE: You are the lead. Edit only `notes/units.csv` and `notes/dispatch.md`. Workers each edit one unit folder in `src/decomp/`. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: After each merge, run `python3 tools/verify/verify.py <UNIT> -n 10000 -seed 1` and `-seed 7` on main in WSL. Done means every merged unit passes both, and the ledger shows each unit as done, hard or failed.
   BUDGET: At most <WORKERS> workers at once. Each worker stops after 3 tries.
   IF BLOCKED: Stop dispatching. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: ledger counts before and after, and the last verify rows. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe ledger shows the batch as done, hard or failed. Every done unit passes verify.py on -seed 1 and -seed 7 on main.

   Proof this works: Minecraft: Wii U Edition - source reconstruction, https://github.com/ZeldaWWHDDecomp/wwhd, https://code.claude.com/docs/en/worktrees.md

7. Recover structures and make it readable

   Readable code needs real classes and fields, not raw offsets. Write headers for the game's objects. Then rewrite machine-like code into the style a person would write.

   • Write one header per class with its fields, offsets and size. Add static_assert checks for every offset and the total size.
   • Ban machine idioms. Minecraft's rules forbid raw memory loads for member access, hand-built vtables and decompiler names.
   • Run a readability check. The Wind Waker HD decomp has readable_check.py and readable_lint.py.
   • Rerun the harness after every rewrite. Wind Waker HD checked that results and coverage did not change.
   Prompt for ClaudeCopy

   GOAL: Write a header for class <CLASS> of <GAME> and use it in the rewritten functions that touch it.
   READ FIRST: `notes/findings.md` entries for <CLASS>, the rewritten files listed in `notes/units.csv` for it.
   FENCE: Edit only `src/decomp/include/<CLASS>.h` and the rewritten files that use it. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Build the units with every `static_assert`. Then in WSL run `python3 tools/verify/verify.py <UNIT> -n 10000 -seed 1` and `-seed 7` for each touched unit, and the readability check. Done means all pass and coverage is not lower than before.
   BUDGET: Stop after 3 failed layouts.
   IF BLOCKED: Stop. Use a padding field marked unknown instead of guessing. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: build output, verify rows and coverage before and after. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe headers build with every assert on, every touched unit passes both seeds, and coverage did not drop.

   Proof this works: https://github.com/ZeldaWWHDDecomp/wwhd, Minecraft: Wii U Edition - source reconstruction

8. Harden the decomp

   Check that the progress is real. A fresh session hunts for cheats. Then swap the decompiled code into the running game and compare it with the normal build.

   • Run every unit from a clean clone, once per seed: python3 tools/verify/verify_all.py -n 10000 -seed 1, then the same with -seed 7.
   • Run a fresh verify session on each merged batch. It looks for calls back to the function's own original address, stubs and edited unit specs.
   • Swap decompiled functions into the game and replay a scripted session. Wind Waker HD compared camera, random numbers, sounds and the picture step by step. Its swap build is not in the decomp repo. The port's -DWWHD_DECOMP=ON build does this on macOS only, so on Windows you must build your own.
   • Track the share of verified functions in PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Verify the last batch of rewritten units of <GAME> is real work.
   READ FIRST: `git log` since tag <TAG>, `notes/units.csv`, `CLAUDE.md`.
   FENCE: Read-only review. Edit only `notes/verify-<DATE>.md`. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: On a clean clone in WSL, run `python3 tools/verify/verify_all.py -n 10000 -seed 1` and again with `-seed 7`. Done means you list each claimed unit as OK or SUSPECT. Look for: calls to the function's own original address, stubs, edited unit specs or input steering, lowered coverage, and changes outside the fence.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: Stop. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the run summary and the OK and SUSPECT lists. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOn a clean clone, verify_all.py -n 10000 -seed 1 and -seed 7 pass every unit. The verify note has no unexplained SUSPECT unit.

   Proof this works: https://github.com/ZeldaWWHDDecomp/wwhd, Wind Waker HD Recomp

9. Build it on its own, then port

   A verified unit still calls other functions by their original address. To port, remove that glue so the code stands alone. Then put the console parts behind clear interfaces and build for the new system.

   • Replace each call-by-address with a direct call once both sides are decompiled. The Wind Waker HD code uses gabi::call(0xADDR, ...) until then.
   • For a rebuild that boots on Wii U or in Cemu, compile with a Green Hills ABI compiler. Minecraft runs python tools/prepare.py, then python tools/build.py, which builds RedHills in Docker. Then it runs python tools/package.py and Cemu -g build/title/code/Minecraft.Client.rpx.
   • Keep a platform seam. Minecraft's rule: a function sits below the seam only if it reaches a system import.
   • Turn PowerPC sync, lwsync and eieio into real memory barriers on ARM chips such as Apple Silicon. Make file paths case-insensitive on Linux.
   • Run the golden runs on the new system.
   Prompt for ClaudeCopy

   GOAL: Make <GAME> build and boot on <TARGET> from the decompiled source.
   READ FIRST: `SCOPE.md`, `notes/port-<TARGET>.md`, the build log from the last try.
   FENCE: Edit only `src/platform/<TARGET>/`, `CMakeLists.txt` and `notes/port-<TARGET>.md`. Verified code in `src/decomp/` is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `<TARGET BUILD COMMAND>`, then the golden runs on <TARGET>. Done means it boots and the first golden run passes.
   BUDGET: One build error or one crash per session. Stop after 3 failed tries.
   IF BLOCKED: Stop. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: build and golden run output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOn the new system, the golden run command prints PASS for the same runs as on Windows.

   Proof this works: Minecraft: Wii U Edition - source reconstruction, https://github.com/ZeldaWWHDDecomp/wwhd, Wind Waker HD Recomp

Tools you need

Skills and add-ons

Read any skill before you install it. A skill is a set of instructions that Claude will follow. See Tools and Skills for the full list and safety notes.

Claude setup for this system

Cut Path A by stop point. One unit is one missing import, one crash, or one wrong picture, each with a repro run. Cut Path B by unit. One unit is one class family or source file, checked by the harness on two seeds. Keep library code, such as the Green Hills runtime, out of the units. Every unit ends with a run, never with a build alone.

Which model and effort for each job

The model and effort names come from one shared table, so they stay the same on every guide. See Claude Setup for the reasons.

How many sessions at once

Lines for this project's CLAUDE.md

- Read `SCOPE.md` and `PROGRESS.md` at the start of every session.
- Never edit `build/gen` or any generated file. Change the recompiler config, the hook list or the runtime instead.
- `game/`, `donor/` and `build/` are read-only. Never commit game files, keys, generated code, save states or screenshots.
- Addresses belong to one build. If the `.rpx` hash differs from `SCOPE.md`, stop and tell me.
- Do not guess facts about the binary. Confirm in Ghidra or Cemu first, and mark unsure names with a `?` suffix.
- A missing system call fails loudly with its name. Never return a fake success to get past it.
- The only proof is `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden`, or both harness seeds for Path B. A green build alone is not done.
- Record every finding in `notes/findings.md` with date, address, evidence and confidence. Record dead ends too.
- Run the game only under a time limit. Stop only your own process, by its process ID.
- Never run a command that opens an interactive screen. Use flags only.
- In a worktree, use absolute paths and run the full check before you report.
- Start every report with DONE, PARTIAL or BLOCKED, then paste the check output.

Keep the context small

• Never let Claude list or read all of build/gen. Point it at one function by address.
• Give the last 50 log lines and the stop address, not the whole log.
• Keep findings in CSV and short notes that the next session reads first, as Cha-Cha does with HANDOFF.md and docs/research-log.md.
• Add Read(./game/**) to permissions.deny in .claude/settings.json.
• Use /clear between units. The state lives in the ledger files, not the chat.

More prompts for this system

Each step above has its own prompt. These extra prompts cover the rest of the work. Fill in the parts in <ANGLE_BRACKETS>.

GOAL: Tell me if <GAME> (Wii U, title ID <TITLE ID>) is a good recomp target, and draft SCOPE.md.
READ FIRST: `notes/game-files.txt`, RecompLauncher's list for my game, https://github.com/ZeldaWWHDRecomp/ZeldaWWHDRecomp, https://github.com/Petexy/Tekken-Tag-2-Ultimate-Edition.
FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `Select-String -Path SCOPE.md -Pattern '^## (Prior work|Donor port|Update|Engine|Risks)$'`. Done means it prints 5 lines: prior ports of this game or its engine with links, the donor you suggest and why, the update needed, the engine if known, and risks. Each fact has a link or a file path.
BUDGET: Stop after 45 minutes of research.
IF BLOCKED: Stop. Say what you could not find. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the links. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Produce `notes/functions.csv` and `notes/imports.csv` for `game/code/<NAME>.rpx`.
READ FIRST: `SCOPE.md`, the Ghidra headless export in `notes/ghidra/`, `donor/runtime/src/`.
FENCE: Edit only `notes/functions.csv`, `notes/imports.csv`, `notes/findings.md` and `tools/`. `game/` and `donor/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: If `tools/ledger_check.py` is missing, write it first. Run `python tools/audit_imports.py game/code/<NAME>.rpx donor/runtime/src` and `python tools/ledger_check.py notes/functions.csv`. Done means both print PASS. Report the function count, how many have names, and how many imports are missing.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Do not invent names. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs and the counts. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Implement Cafe OS import <IMPORT> so <GAME> gets past it.
READ FIRST: `notes/imports.csv` row for <IMPORT>, the last 50 lines of `out/logs/boot.txt`, how Cemu handles <IMPORT> (read only, copy no code).
FENCE: Edit only `src/cafe/<LIBRARY>/` and `notes/imports.csv`. `build/gen`, `donor/` and `game/` are read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -BootSeconds 120` and `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden`. Done means the log passes <IMPORT> and every golden run still passes.
BUDGET: Stop after 3 failed tries.
IF BLOCKED: Stop. Do not return a fake success. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: old and new last log lines and the golden run output. 3) Files changed. 4) The import's new status. 5) New parking-lot items.

GOAL: Rewrite unit <UNIT> of <GAME> as readable C++ that passes the harness.
READ FIRST: `notes/units.csv` row for <UNIT>, its evidence pack in `notes/packs/<UNIT>/`, `CLAUDE.md`.
FENCE: Edit only `src/decomp/<UNIT>/` and `tools/verify/units/<UNIT>`. Never call a function's own original address from its new body. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: In WSL run `python3 tools/verify/verify.py <UNIT> -n 10000 -seed 1` and `-seed 7`. Done means every row says ok and coverage is at least <COVERAGE>.
BUDGET: Stop after 5 tries with no gain.
IF BLOCKED: Stop. Leave the unit as recompiled code. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both verify outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Pick the next <N> units for <GAME> and launch one worker per unit.
READ FIRST: `notes/units.csv`, `notes/imports.csv`, `PROGRESS.md`.
FENCE: You are the lead. Edit only `notes/dispatch.md` and the status column of the ledgers. Do not edit code. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Each worker reports its check output. Done means every unit in `notes/dispatch.md` is marked done, hard or failed, with pasted proof.
BUDGET: At most <WORKERS> workers at once. Stop after one batch.
IF BLOCKED: Stop dispatching. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the dispatch table with results. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> in <GAME>. Do not fix it yet.
READ FIRST: `notes/bugs.md` entry <BUG-ID>, the last 50 lines of its log, the RenderDoc capture or input recording named there.
FENCE: Read-only, except `notes/bugs.md` and new files in `notes/traces/`. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Done means you name one cause and show two pieces of evidence: the same scene in Cemu, a frame capture, a trace or a replayed input that shows it. State how a fix would be checked.
BUDGET: Stop after 45 minutes with no new evidence.
IF BLOCKED: Stop. List what you ruled out and what evidence you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the evidence. 3) Files changed. 4) Suggested fix and its check. 5) New parking-lot items.

GOAL: Check that the claimed work in <BRANCH OR TAG RANGE> for <GAME> is real.
READ FIRST: `git log <RANGE>`, `git diff <RANGE>`, `CLAUDE.md`.
FENCE: Read-only review. Edit only `notes/verify-<DATE>.md`. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: On a clean clone, run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden`, and for Path B run `python3 tools/verify/verify_all.py -n 10000 -seed 1` and `-seed 7` in WSL. Done means each claimed unit is listed OK or SUSPECT. Look for: edits to generated code, fake success returns, new stubs not in `notes/imports.csv`, calls to a function's own original address, edited baselines or unit specs, lowered coverage, and changes outside the fence.
BUDGET: Stop after 90 minutes.
IF BLOCKED: Stop. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the check outputs and the OK and SUSPECT lists. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Report the status of the <GAME> project with numbers only.
READ FIRST: `PROGRESS.md`, `notes/imports.csv`, `notes/functions.csv`, `notes/units.csv`, `notes/bugs.md`.
FENCE: Read-only. Edit only `PROGRESS.md`. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `powershell -ExecutionPolicy Bypass -File tools/check.ps1 -Golden` once. Done means `PROGRESS.md` shows imports done of total, golden runs passing of total, open bugs, and for Path B verified functions of total, each with the date.
BUDGET: Stop after 20 minutes.
IF BLOCKED: Stop. Say which number you could not get. Tell me what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the check output and the counts. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Write what the next session needs into the ledger files for <GAME>.
READ FIRST: `PROGRESS.md`, `notes/findings.md`, `git status`, `git log -5`.
FENCE: Edit only `PROGRESS.md`, `notes/handoff.md` and `notes/findings.md`. Do not edit code. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Done means `notes/handoff.md` has four parts: what works with proof, what is half done with the file names, the next unit with its check command, and open questions. A fresh session must be able to start from it alone.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop. Tell me what blocked you and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the new `notes/handoff.md`. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Give me a plain answer on whether <UNIT OR BUG> in <GAME> can be done with the current tools.
READ FIRST: `notes/findings.md`, `notes/bugs.md` or `notes/units.csv` entries for <UNIT OR BUG>, the logs of the failed tries.
FENCE: Read-only. Edit only `notes/findings.md`. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Done means you answer CAN, CANNOT or UNKNOWN in the first line, then list what was tried, the exact failing output, and two or three options with their cost in sessions.
BUDGET: Stop after 20 minutes.
IF BLOCKED: Stop. Answer UNKNOWN and say what evidence would decide it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the failing output. 3) Files changed. 4) Options. 5) New parking-lot items.

GOAL: Ask me before you leave the fence for <TASK> in <GAME>.
READ FIRST: `SCOPE.md`, the current task card, `notes/parking-lot.md`.
FENCE: Do not edit any file outside the current fence. Edit only `notes/scope-requests.md`. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Done means `notes/scope-requests.md` has one entry with: the file or folder you want to touch, why the task needs it, the risk, and how the change would be checked.
BUDGET: Stop after 10 minutes.
IF BLOCKED: Stop and wait for my answer. Do not start the change.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the new entry. 3) Files changed. 4) What is left. 5) New parking-lot items.

Keep Claude on task

These are the detours Claude tends to take on this system, and the rule that stops each one. The full method is on Stay on Task.

Problems other projects hit

How long it takes

What makes it faster or slower

• A donor port of a sister game. Twilight Princess HD forked the Wind Waker HD port and reached its title screen by 2026-10-14. That port's first commit was 2026-10-01.
• How many imports and GX2 features your game needs that the donor lacks. Captain Toad started with 62 missing imports.
• Region and update. Each build has its own addresses, so hooks and names do not carry over.
• For Path B, a sister decomp. Wind Waker HD borrowed names and structures from the GameCube decomp.
• For Path B, game size. Wind Waker HD has 39,713 functions; Tekken's recompiler found 205,200 entry points.

The facts behind these numbers

Projects reviewed (14)

RecompLauncher has fewer than 10 games for Wii U: 8 projects for 6 games, and we reviewed all 8. We added 6 projects from outside RecompLauncher, one per new game, for 14 projects and 12 games. More than 10 real projects exist, but the field is young: most started in October 2026.

What each project teaches

What we could not check

• No reviewed project uses the ZeldaWWHDRecomp recompiler on a new game through the exact steps in Path A. Captain Toad comes closest, but its public build does not yet make a playable game.
• Adding your own game target to the donor's CMake setup was not tested here. How much work it takes is not known.
• The donor runtime checks for cking.rpx at start. How much must change so it accepts another game's .rpx was not tested.
• WWHD_WARP was seen only in the Twilight Princess HD card. A code search of the donor repo did not find it.
• The in-game swap test of Path B has no public Windows setup. The port's decomp build runs on macOS only so far.
• The harness was not built in WSL here. Whether Ubuntu 24.04's clang 18 is new enough was not tested.
• The cafe-recomp route was not tried in WSL. Its README targets Linux and shows Arch Linux packages.
• The PowerShell check commands were tested here only on small sample files, in Windows PowerShell 5.1.
• Whether GhidraRPXLoader-0.9.2, built for Ghidra 12.0, also loads in Ghidra 12.0.4 was not tested.
• Building the loader for Ghidra 12.1.4, so that GhidraMCP can run beside it, was not tested.
• The Wind Waker HD harness uses Linux signals, so the guide says WSL. Whether it runs on native Windows was not checked.
• The harness was built for Wind Waker HD only. How much it must change for another game is not known.
• RedHills has no releases and 0 stars. Its build steps were read in the Minecraft card, not run here.
• Whether objdiff can compare Wii U code was not checked. Its README lists PowerPC for GameCube, Wii, PS3 and Xbox 360 only.
• Whether you may legally use any Green Hills compiler copy is your call. The Breath of the Wild matching repo downloads one, and this guide does not recommend that.
• AI use for several projects comes only from a store flag, not from the developers.
• None of the tools or projects was built or run here. Commands come from their READMEs and the review cards.

Sources

• ZeldaWWHDRecomp README
• Wind Waker HD verified decompilation README
• wwhd tools/verify README
• Tekken Tag 2 Ultimate Edition README
• Breath of the Wild Wii U reconstruction README
• red-pro2 README
• GhidraRPXLoader README and releases
• Ghidra releases
• GhidraMCP README
• Cemu README
• Dumpling README
• wiiurpxtool README
• m2c README
• wut README
• RedHills repository
• LLVM 23.1.5 release
• llvm-mingw releases
• Vulkan SDK latest versions
• RenderDoc releases
• WiiUBrew: Hardware
• WiiUBrew: RPL
• NSMBU Recomp repository
• Captain Toad recompilation prototype
• Minecraft Wii U reconstruction
• Cha-Cha-Plus repository
• Claude Code worktrees
• Claude Code permissions
• Install WSL (Microsoft)
• Git for Windows download
• Python for Windows download
• Unleashed Recompiled repository