Wii decomp guide

What this system is like

The Wii runs PowerPC code, like the GameCube. The two systems share most tools. A Wii game is one main program file, main.dol. Many games also load extra code files called RELs.

Path A uses static recompilation. A tool reads the game's code and writes C++ that does the same thing. Since August 2026, most Wii ports reviewed here use the WiiCompiled translator and the Aurora graphics layer. The hard part is not the translator. It is the runtime: the code that stands in for the Wii's graphics, sound, input and files.

Path B is a matching decompilation. You write C or C++ that the original compiler turns back into the same bytes. The tools are decomp-toolkit, objdiff and the Metrowerks compiler. At least one Wii game, Mario Strikers Charged, is fully matched and linked. A PC port was built on top of it.

Almost everything runs on Windows. WSL is only needed for decomp-permuter's shared mode and for Linux builds. Wii games are big. The games checked here have 14,620 to 92,522 functions, so plan for a long Path B.

Two paths

Path A: Get it running on PC

You write a small YAML manifest for your game. The WiiCompiled translator reads main.dol and writes C++. You compile that with a runtime that replaces the Wii's system code. Aurora draws the GX graphics on your GPU. Most work goes into moving runtime hooks to your game's addresses and fixing one crash at a time.

1. Scope the game and pin the disc

   You pick one game and one exact disc version. You record its ID and hash. You also look for work that already exists. A symbol map or a sister port can save weeks.

   • Pick one disc version. Write down its six-letter game ID, for example RMCE01.
   • Check the image with nodtool info <IMAGE> and nodtool verify <IMAGE>.
   • Extract it outside your repo: nodtool extract <IMAGE> D:/wii/<GAMEID>.
   • Hash the code in PowerShell: Get-FileHash D:/wii/<GAMEID>/sys/main.dol -Algorithm SHA256.
   • List the REL modules under files/. Check subfolders and other names too: Mario Kart has files/rel/StaticR.rel, and Super Paper Mario uses files/rel/relF.bin. Note any .map file on the disc.
   • Search decomp.dev and GitHub for a decomp, a symbol list or a WiiCompiled port of a sister game.
   • Write SCOPE.md: goal, disc ID and revision, hash, technique, first milestone and what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a static recomp of <GAME> (<GAMEID>, revision <REV>) on WiiCompiled.
   READ FIRST: `D:/wii/<GAMEID>/` (read-only), https://github.com/patchzyy/Wiicompiled/blob/main/translator/README.md
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Never copy game files into the repo. Do not install anything.
   CHECK: Run `Get-FileHash D:/wii/<GAMEID>/sys/main.dol -Algorithm SHA256`. Done means the hash matches the one in `SCOPE.md`, and `SCOPE.md` names the disc ID, revision, the REL modules, the prior work found with links, and one first milestone with a check a script can run.
   BUDGET: Stop after 45 minutes of searching.
   IF BLOCKED: Stop. Do not guess a hash or a link. Tell me what you could not confirm and what you need.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the hash command output. 3) Files changed. 4) Open questions for me. 5) New parking-lot items.

   Done whenSCOPE.md lists the disc ID, revision and main.dol SHA-256, and you approved it.

   Proof this works: Mario Kart WiiCompiled, Shake It! Native PC, https://github.com/encounter/nod

2. Set up the toolchain and the one check

   You install the tools and clone WiiCompiled. Then you write one script that builds and tests everything. Claude runs that script after every change.

   • Install the .NET 8 SDK, CMake 3.25 or newer, Ninja, Git, Python and PowerShell 7. The install commands are in the tools list.
   • PowerShell 7 runs as pwsh. It is a separate install from the powershell that comes with Windows.
   • Unzip llvm-mingw-20261104-ucrt-x86_64.zip from the llvm-mingw releases page. Add its bin folder to PATH.
   • Clone with submodules: git clone --recursive https://github.com/patchzyy/Wiicompiled, then cd Wiicompiled. The submodule aurora-main is the project's copy of Aurora.
   • Build the translator: dotnet build translator/Translator.sln -c Release.
   • The translator then runs as dotnet translator/src/Translator.Cli/bin/Release/net8.0/Translator.Cli.dll <COMMAND>.
   • Run its tests: dotnet test translator/Translator.sln -c Release. They need no game files.
   • Add generated/, build/ and your game folder to .gitignore.
   • Write tools/check.ps1. It translates, builds, runs the golden run and prints one line: PASS or FAIL.
   • Give it the switches later steps use: -BuildOnly, -Scenario <NAME> and -Full. Unfinished parts may print FAIL for now.
   • Write CLAUDE.md, PROGRESS.md and notes/parking-lot.md.
   Prompt for ClaudeCopy

   GOAL: Make `pwsh tools/check.ps1` run translate, build and golden run, accept `-BuildOnly`, `-Scenario <NAME>` and `-Full`, and print PASS or FAIL as its last line.
   READ FIRST: `SCOPE.md`, `translator/README.md`, `projects/examples/generic-dol.yml`
   FENCE: Edit only `tools/check.ps1`, `.gitignore`, `CLAUDE.md`, `PROGRESS.md`. Do not change `translator/` or `runtime/`. Do not install anything; tell me what is missing.
   CHECK: Run `dotnet test translator/Translator.sln -c Release` (must pass). Then run `pwsh tools/check.ps1`. Done means it runs to the end and prints PASS or FAIL. FAIL is fine at this stage.
   BUDGET: Stop after 3 failed tries on the same error.
   IF BLOCKED: Stop. Do not work around a missing tool. Tell me which tool and version is missing.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the last 20 lines of both commands. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whendotnet test passes and pwsh tools/check.ps1 runs to the end with a clear PASS or FAIL line.

   Proof this works: Mario Kart WiiCompiled, NSMB Wii Recompiled, https://github.com/patchzyy/Wiicompiled

3. Write the manifest and the function map

   The translator only knows code it can reach from the entry point. A function map tells it where every function starts. You also link RELs offline so their code gets translated too.

   • Copy projects/examples/generic-dol.yml to projects/<game>/recomp.yml.
   • Set inputs.dol.path to your main.dol and add its SHA-256 pin from step 1. A pinned file with a wrong hash is rejected.
   • Read the DOL header with dtk dol info D:/wii/<GAMEID>/sys/main.dol. The entry point sits at offset 0xE0.
   • Read the lis/ori pairs in __init_registers. Write them as sda_base (r13) and sda2_base (r2). The translator will not guess them.
   • Build MAP.txt with one hexaddr name line per function. Take names from a decomp's symbols.txt if one exists. Point translation.function_map.path at it.
   • With no decomp, use function starts from dolrecomp and names from Dolphin's signature database. Keep only exact-size, unique matches.
   • Change allow_unsupported_instructions to false. The example file sets it to true, and a build with it on can never ship.
   • If the game loads RELs at boot, link them offline at fixed addresses into one file, like prelink_rels.py does.
   • Write notes/functions.csv with address, size, name source and status.
   Prompt for ClaudeCopy

   GOAL: Write `projects/<game>/recomp.yml` and `projects/<game>/MAP.txt` so `translate-recursive` covers the whole game.
   READ FIRST: `SCOPE.md`, `translator/README.md`, `projects/examples/generic-dol.yml`, `<SYMBOL_SOURCE>`
   FENCE: Edit only `projects/<game>/` and `notes/functions.csv`. Never edit `generated/`. Set `allow_unsupported_instructions: false` and keep it there.
   CHECK: Run `dotnet translator/src/Translator.Cli/bin/Release/net8.0/Translator.Cli.dll translate-recursive <ENTRY> --project projects/<game>/recomp.yml`. Done means it exits 0 with no unsupported instruction, and `notes/functions.csv` has one row per function.
   BUDGET: Stop after 5 failed translate runs, or 60 minutes with no new functions found.
   IF BLOCKED: Stop. Do not turn on `allow_unsupported_instructions`. Paste the failing address and instruction.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the translator summary. 3) Files changed. 4) How each SDA value was found. 5) New parking-lot items.

   Done whentranslate-recursive exits with no unsupported instruction, and notes/functions.csv lists every function with its name source.

   Proof this works: Brawl Recompiled, New Super Paper Bros, Shake It! Native PC, OceanTriRecomp

4. Translate and build the program

   You run the three translator commands. Then CMake and Ninja compile the result. This is the first full pass from disc to .exe. The game will not run yet.

   • Run each translator command as dotnet translator/src/Translator.Cli/bin/Release/net8.0/Translator.Cli.dll <COMMAND>. Any command lists its options with --help.
   • Run translate-recursive <ENTRY> --project projects/<game>/recomp.yml.
   • Run generate-data-init --project projects/<game>/recomp.yml.
   • Run emit-build-shards --project projects/<game>/recomp.yml. It writes the CMake build graph. The Mario Kart, NSMBW and Paper Mario builds also run emit-base-manifest before it.
   • Configure with CMake, the Ninja generator and clang from llvm-mingw. Build the WiiCompiled target.
   • Allow one compile job per 2.5 GB of RAM. One job per core ran a 16 GB PC out of memory.
   • Mark very slow functions noopt or isolate instead of waiting on them.
   Prompt for ClaudeCopy

   GOAL: Build one native `.exe` from the translated game with no compile or link errors.
   READ FIRST: `SCOPE.md`, `translator/README.md`, `projects/<game>/recomp.yml`
   FENCE: Edit only `tools/check.ps1` and `projects/<game>/`. Never edit `generated/` or `runtime/`.
   CHECK: Run `pwsh tools/check.ps1 -BuildOnly`. Done means the link step succeeds and a second clean run gives the same result.
   BUDGET: Stop after 3 failed builds on the same error. Use at most <N> parallel compile jobs.
   IF BLOCKED: Stop. If an error is in generated code, do not patch it; name the translator rule that made it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the last 30 build lines. 3) Files changed. 4) Build time and peak RAM. 5) New parking-lot items.

   Done whenThe build links one .exe with no errors, twice in a row from a clean build/ folder.

   Proof this works: Mario Kart WiiCompiled, Brawl Recompiled, Resident Evil: The Umbrella Chronicles

5. Boot to the first frame

   The runtime calls into the game at fixed addresses. These are hooks. You move each hook from the base game to yours. Every address needs proof, or the game breaks in odd ways.

   • Start from the WiiCompiled runtime. Copy it; do not write a new one.
   • List every hook and replaced SDK function the base runtime uses.
   • Find each one in your game by a string, a caller or a matching code shape.
   • Record it in projects/<game>/hle_targets.tsv with how you proved it.
   • Check the register use of each replaced SDK call against the real code.
   • Run until a window shows the first frame. Save the screenshot and the log in notes/.
   Prompt for ClaudeCopy

   GOAL: Boot <GAME> to its first drawn frame.
   READ FIRST: `SCOPE.md`, `PROGRESS.md`, `projects/<game>/hle_targets.tsv`, `runtime/` (hook list only)
   FENCE: Edit only `runtime/` and `projects/<game>/`. Never edit `generated/`. Every new address needs a proof note in `hle_targets.tsv`.
   CHECK: Run `pwsh tools/check.ps1 -Scenario boot`. Done means a frame is drawn, a screenshot is saved, and it shows the same screen Dolphin shows at that point.
   BUDGET: Stop after 4 hooks you could not prove, or 90 minutes with no new progress in the log.
   IF BLOCKED: Stop. Do not stub a function or fake an event to get past a screen. List the hook and the evidence you have.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Screenshot path and the last 20 log lines. 3) Files changed. 4) Hooks still unproven. 5) New parking-lot items.

   Done whenA window shows the first frame, and the screenshot matches the same moment in Dolphin.

   Proof this works: NSMB Wii Recompiled, New Super Paper Bros, Resident Evil: The Umbrella Chronicles

6. Build a test harness

   Claude needs to run the game without you. A harness feeds scripted input, waits for game states and saves proof. It becomes the golden run in your check script.

   • Add scripted input and a time limit. Never send real keyboard or mouse input.
   • Copy saves into a folder per run. Never touch your real saves.
   • Run in a 1280x720 window, never fullscreen.
   • Wait on game state, not on sleep timers.
   • Write report.json with the state reached, the time and a screenshot. On failure, write failure.json.
   • Add a level sweep: load each level, count undrawn pixels and keep a small screenshot.
   • Make tools/check.ps1 call the harness.
   Prompt for ClaudeCopy

   GOAL: Add a harness so `pwsh tools/check.ps1` boots to the title screen with no person and writes `report.json`.
   READ FIRST: `SCOPE.md`, `PROGRESS.md`, `tools/check.ps1`
   FENCE: Edit only `tools/`, `tests/` and the harness hook in `runtime/`. Do not change game logic. Never use real input or real saves. Never run fullscreen.
   CHECK: Run `pwsh tools/check.ps1` three times. Done means all three runs reach the title screen and each writes `report.json` with a screenshot.
   BUDGET: Stop after 3 failed designs, or 2 hours.
   IF BLOCKED: Stop. Tell me what game state you could not detect and what you tried.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the three PASS lines and report paths. 3) Files changed. 4) What the harness cannot do yet. 5) New parking-lot items.

   Done whenpwsh tools/check.ps1 reaches the title screen three runs in a row and writes report.json each time.

   Proof this works: Resident Evil: The Umbrella Chronicles, New Super Paper Bros, Brawl Recompiled

7. Fix one problem at a time

   This is the long middle. Each task is one crash, one missing call or one wrong picture. Claude proves the cause first, then fixes the right layer.

   • Pick one item from PROGRESS.md.
   • Reproduce it with a harness scenario before changing code.
   • For Missing translated target, add the address to MAP.txt or add a seeding rule for that code shape.
   • For a wrong picture, compare with Dolphin. Use a savestate and a FIFO log of one frame.
   • Fix the translator, the manifest or the runtime. Never the generated code.
   • Add a scenario that would have caught the bug.
   Prompt for ClaudeCopy

   GOAL: Fix <BUG_ID>: <ONE_LINE_DESCRIPTION>.
   READ FIRST: `PROGRESS.md`, `notes/findings.md`, the run folder `<RUN_DIR>` with `failure.json`
   FENCE: Edit only `runtime/`, `projects/<game>/` or `tests/`. Never edit `generated/`. No stubs, no fake events, no per-screen hacks.
   CHECK: Run `pwsh tools/check.ps1 -Scenario <SCENARIO>` and then the full `pwsh tools/check.ps1`. Done means both print PASS.
   BUDGET: Stop after 3 failed fixes, or 60 minutes without a proven cause.
   IF BLOCKED: Stop. Write what you know in `notes/findings.md` and tell me which evidence you need, such as a Dolphin capture.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The proven cause and both PASS lines. 3) Files changed. 4) The new scenario name. 5) New parking-lot items.

   Done whenThe bug's scenario passes, and every older scenario still passes.

   Proof this works: OceanTriRecomp, Resident Evil: The Umbrella Chronicles, Crash of the Titans: Wiicompiled

8. Harden and package

   You make sure old fixes stay fixed. You remove first-launch stutter. You package tools so players build the game from their own disc.

   • Run the full level sweep on a clean checkout.
   • Ship a seed of GPU pipelines seen in test runs, so first launch does not stall.
   • Pin every input by hash: the disc, the toolchain and every download.
   • Scan git for game files and translated code before each release.
   • Ship the tools and let the player's PC translate and build, as WiiCompiled does.
   • Write player docs: the exact disc ID, CPU needs such as AVX2, and how to report a bug.
   Prompt for ClaudeCopy

   GOAL: Make a clean checkout pass the full check and produce a release with no game data.
   READ FIRST: `SCOPE.md`, `PROGRESS.md`, `tools/check.ps1`, `.gitignore`
   FENCE: Edit only `tools/`, `docs/` and packaging files. No gameplay changes.
   CHECK: In a fresh clone, run `pwsh tools/check.ps1 -Full`. Done means PASS, and `git ls-files` shows no `.dol`, `.rel`, disc image or `generated/` file.
   BUDGET: Stop after 3 failed tries on one problem.
   IF BLOCKED: Stop. List what fails and the log line.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the PASS line and the file scan. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenA clean clone prints PASS from pwsh tools/check.ps1 -Full, and git holds no game data or translated code.

   Proof this works: Mario Kart WiiCompiled, Metroid Prime 3: Corruption PC, Shake It! Native PC

Path B: Full decomp for porting

You split the game with decomp-toolkit using the dtk-template layout. You write C or C++ until each unit builds to the same bytes with the original Metrowerks compiler. objdiff scores each unit, and ninja checks the whole DOL hash. Then you port the source to PC with Aurora, using small patches.

1. Scope and look for prior work

   A full decomp is months or years of work. First check if someone has started. A sister game decomp can give you a lot of code.

   • Look up your game on decomp.dev and GitHub. Note matched and linked percent.
   • If a decomp is at 100%, skip to the port steps.
   • Look for a sister game on the same engine. The Strikers Charged decomp borrowed code from the GameCube Super Mario Strikers decomp.
   • Read the project's rules on AI changes. Petari does not accept AI changes.
   • Expect a large game. Strikers Charged has 17,689 functions. Brawl has 92,522.
   • Write SCOPE.md with the version, the main.dol SHA-1 and the first milestone.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a matching decomp of <GAME> (<GAMEID>).
   READ FIRST: https://decomp.dev, https://github.com/encounter/dtk-template, `notes/prior-work.md`
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Do not clone or download any decomp yet.
   CHECK: Run `Get-FileHash <DISC_FOLDER>/sys/main.dol -Algorithm SHA1`. Done means the hash matches the one in `SCOPE.md`, and `SCOPE.md` names the version, every prior project found with its matched and linked percent, any sister-game decomp, and upstream AI rules.
   BUDGET: Stop after 45 minutes.
   IF BLOCKED: Stop. Say which facts you could not confirm. Do not guess percentages.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) A table of prior work with links. 3) Files changed. 4) Your advice: start new, join, or port. 5) New parking-lot items.

   Done whenSCOPE.md names the version, its SHA-1 and all prior work, and you approved it.

   Proof this works: https://decomp.dev/yannicksuter/mscharged-decomp, https://github.com/yannicksuter/mscharged-decomp, Nebula

2. Set up from dtk-template

   dtk-template is the layout most GameCube and Wii decomps use. It needs only Python and Ninja. The first build downloads the compilers and tools for you.

   • Create a new repo from dtk-template and clone it.
   • Install Python and Ninja on Windows: pip install ninja. WSL is not needed.
   • Rename orig/GAMEID and config/GAMEID to your game ID.
   • Put extracted game files in orig/<GAMEID>, so orig/<GAMEID>/sys/main.dol exists. Use Dolphin's Data Partition, Extract Entire Partition, or nodtool extract <IMAGE> orig/<GAMEID>. The template also takes a whole disc image, but then sys/main.dol only appears after the first build, so the hash command below fails.
   • Edit config/<GAMEID>/config.yml. Remove modules if the game has no RELs.
   • Make the hash file: dtk shasum orig/<GAMEID>/sys/main.dol orig/<GAMEID>/files/*.rel -o config/<GAMEID>/build.sha1. On Wii, RELs often sit in a subfolder such as files/rel/, so list each REL path you found in step 1.
   • Change the paths in build.sha1 to point at build/. The DOL builds to build/<GAMEID>/main.dol and each module to build/<GAMEID>/<MODULE>/<MODULE>.rel.
   • Set VERSIONS in configure.py. Run python configure.py, then ninja.
   Prompt for ClaudeCopy

   GOAL: Get a `dtk-template` project for <GAMEID> to run its first analysis.
   READ FIRST: `SCOPE.md`, `docs/getting_started.md`, `docs/dependencies.md`, `config/GAMEID/config.example.yml`
   FENCE: Edit only `config/<GAMEID>/`, `configure.py` and `.gitignore`. Never commit anything from `orig/`.
   CHECK: Run `python configure.py` then `ninja`. Done means the analysis finishes and writes `config/<GAMEID>/symbols.txt` and `splits.txt`.
   BUDGET: Stop after 3 failed runs on the same error.
   IF BLOCKED: Stop. Paste the error. Do not edit `build.sha1` hashes to get past it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the last 20 lines of `ninja`. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenninja finishes the first analysis and writes symbols.txt and splits.txt.

   Proof this works: https://github.com/encounter/dtk-template, https://github.com/yannicksuter/mscharged-decomp

3. Map the binary and pass the hash

   You make the project rebuild the original DOL while all code is still assembly. You mark library code so nobody decompiles it by hand first. The result is a ledger of every unit.

   • If the disc has a .map file, add a map key in config.yml. Remove it after the analysis.
   • Set up the C++ exception split for Wii linkers, as the template docs show.
   • Put SDK, runtime and middleware units in the sdk progress category.
   • Build until ninja prints build/<GAMEID>/main.dol: OK.
   • Write notes/units.csv from build/<GAMEID>/report.json: unit, size, category, status.
   Prompt for ClaudeCopy

   GOAL: Make `ninja` rebuild a byte-identical `main.dol` with every unit still in assembly, and write the unit ledger.
   READ FIRST: `SCOPE.md`, `config/<GAMEID>/config.yml`, `config/<GAMEID>/splits.txt`, `docs/splits.md`, `docs/symbols.md`
   FENCE: Edit only `config/<GAMEID>/`, `configure.py` and `notes/units.csv`. Never edit `build.sha1`.
   CHECK: Run `ninja`. Done means it prints `build/<GAMEID>/main.dol: OK` and `notes/units.csv` has one row per unit.
   BUDGET: Stop after 5 failed split fixes, or 2 hours.
   IF BLOCKED: Stop. Paste the first link or hash error and the split you suspect.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the OK line. 3) Files changed. 4) Unit counts by category. 5) New parking-lot items.

   Done whenninja prints build/<GAMEID>/main.dol: OK and notes/units.csv lists every unit.

   Proof this works: https://github.com/encounter/dtk-template/blob/main/docs/getting_started.md, https://github.com/encounter/decomp-toolkit

4. Match one small unit end to end

   This is first light for Path B. One unit goes from assembly to matching C. It proves the compiler, flags and diff loop all work.

   • Pick the smallest game unit with few functions.
   • Draft C with m2c, using the target ppc-mwcc-c++ or ppc-mwcc-c.
   • Open the project in objdiff. It reads objdiff.json and rebuilds on save.
   • Edit until the unit shows 100% in objdiff.
   • Mark the unit as matching in configure.py.
   • Run ninja. The DOL must still print OK.
   Prompt for ClaudeCopy

   GOAL: Make unit <UNIT> match 100% and link it from source.
   READ FIRST: `SCOPE.md`, `notes/units.csv`, the unit's assembly, `configure.py`
   FENCE: Edit only `src/<UNIT_PATH>`, its header in `include/`, and the unit's line in `configure.py`. No inline `asm`, no `#pragma` tricks, no edits to `build.sha1`.
   CHECK: Run `ninja`. Done means `build/<GAMEID>/main.dol: OK` and `build/<GAMEID>/report.json` shows the unit at 100%.
   BUDGET: Stop after 5 real tries per function with no gain.
   IF BLOCKED: Stop. Show the best score and the exact differing instructions.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the OK line and the unit's score. 3) Files changed. 4) Compiler flags that mattered. 5) New parking-lot items.

   Done whenobjdiff shows 100% for the unit, and ninja prints build/<GAMEID>/main.dol: OK with the unit linked from source.

   Proof this works: https://github.com/matt-kempster/m2c, https://github.com/encounter/objdiff, https://github.com/yannicksuter/mscharged-decomp

5. Grind units in parallel

   Now many workers each take one unit. A script picks the next unit, not Claude. Each worker has a strict try limit and its own git worktree.

   • Write tools/next_units.py. It picks the smallest units first, then those most like matched code.
   • Give each worker one unit and one git worktree.
   • Each worker drafts with m2c, compiles, compares, and stops after 5 real tries.
   • Run decomp-permuter in WSL only on near misses. Add permuter_settings.toml with build_system = "ninja" to the repo root. Then run ./import.py <FILE.c> <FILE.s> and ./permuter.py <DIR> -j <THREADS>.
   • Explain a permuter result before you keep it.
   • Merge one unit per commit. Run ninja on the merged branch after each merge.
   • Log every failed try in notes/units.csv so no one repeats it.
   Prompt for ClaudeCopy

   GOAL: Run one batch of <N> units from `tools/next_units.py`, one worker per unit.
   READ FIRST: `CLAUDE.md`, `notes/units.csv`, `notes/compiler-quirks.md`
   FENCE: Each worker edits only its unit's `src/` file, its header and its `configure.py` line, in its own worktree. Use absolute paths. No inline `asm`.
   CHECK: After each merge, run `ninja` on the main branch. Done means `build/<GAMEID>/main.dol: OK` after every merge and each merged unit is at 100% in `report.json`.
   BUDGET: Each worker stops after 5 real tries with no gain. The batch stops after <M> units or 3 hours.
   IF BLOCKED: A blocked worker writes its best score and differing instructions to `notes/units.csv` and stops.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) A table: unit, result, score. 3) Merged commits. 4) Units sent to the hard queue. 5) New parking-lot items.

   Done whenThe matched count in notes/units.csv rises and ninja prints OK after every merge.

   Proof this works: https://github.com/doldecomp/melee/pull/2076, https://github.com/encounter/objdiff, https://github.com/simonlindholm/decomp-permuter

6. Crack hard units and link the files

   Some units resist. A stronger job type takes them with fresh eyes. Matching is not the end: each file must also link from source.

   • Send units that failed 5 tries to a hard job.
   • Before calling a unit stuck, name the exact differing instructions and a reason class.
   • Search matched units for the same code shape. Copy the pattern, not the code.
   • Keep a unit NonMatching rather than force it with inline assembly.
   • Track linked percent as well as matched percent in report.json.
   Prompt for ClaudeCopy

   GOAL: Match unit <UNIT>, which failed <K> earlier tries.
   READ FIRST: `notes/units.csv` row for <UNIT>, the earlier attempt files, `notes/compiler-quirks.md`
   FENCE: Edit only the unit's `src/` file and header. No inline `asm`, no section forcing, no `volatile` added only to match.
   CHECK: Run `ninja`. Done means `build/<GAMEID>/main.dol: OK` and the unit is 100% in `report.json`.
   BUDGET: Stop after 8 real tries with no gain.
   IF BLOCKED: Stop. 'Compiler artifact' is not an answer. Name the differing instructions and two matched units with a similar shape.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Score before and after. 3) Files changed. 4) A one-line rule for `notes/compiler-quirks.md`. 5) New parking-lot items.

   Done whenEvery unit is matched or marked NonMatching with a written reason, and ninja prints OK.

   Proof this works: https://github.com/zcanann/SFA-Decomp/blob/main/CLAUDE.md, https://jpb.dev/blog/teaching-a-model-to-decompile

7. Harden the decomp

   A byte match proves the code. It does not prove names or types. You add checks that keep the build honest and review the source.

   • For each supported version, run python configure.py --version <GAMEID>, then ninja all_source and ninja.
   • Write a lint that fails on inline asm, odd #pragma lines and edits to build.sha1.
   • Review names and types. Keep a name neutral when you are not sure.
   • Keep a baseline report. No change may lower any unit's score.
   • Have a fresh verify session read each batch for cheating.
   Prompt for ClaudeCopy

   GOAL: Add a full check that builds every version, runs the lint and compares against the baseline report.
   READ FIRST: `SCOPE.md`, `configure.py`, `notes/units.csv`
   FENCE: Edit only `tools/` and CI files. Do not change `src/`.
   CHECK: Run `python tools/full_check.py`. Done means it prints OK for every version, the lint finds nothing, and no unit scores lower than the baseline.
   BUDGET: Stop after 3 failed tries on one problem.
   IF BLOCKED: Stop. List what fails.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenA clean clone builds every version to OK, and the lint and baseline check pass.

   Proof this works: https://github.com/yannicksuter/mscharged-decomp, https://github.com/lukechampine/melee-harness

8. Port the decomp to PC

   You build the matched source for a 64-bit PC. The decomp stays untouched. Every change is a small patch applied at build time.

   • Start a new repo. Pin the decomp, Aurora, Dawn and nod as git submodules at exact commits.
   • Never edit the decomp. Write each change as a small patch with its reason in the header.
   • Keep two patch series: faithful fixes for a 64-bit little-endian PC, and gameplay tweaks.
   • Use Aurora for GX, video and disc reads. Run the SDK's own audio and controller code on a native layer.
   • Swap the byte order of game data once, at load or import.
   • Compile with clang and -fno-strict-aliasing and -ffp-contract=off.
   • Read the player's own disc image at run time. Ship no game data.
   Prompt for ClaudeCopy

   GOAL: Boot the ported game to its title screen on Windows from my own disc image.
   READ FIRST: `SCOPE.md`, `patches/README.md`, https://github.com/encounter/aurora
   FENCE: Edit only `patches/`, `src/platform/` and `src/runtime/`. Never edit the pinned decomp copy. One patch per change, with a reason in its header.
   CHECK: Run `pwsh tools/check.ps1 -Scenario title`. Done means the title screen is reached by scripted input and a screenshot is saved.
   BUDGET: Stop after 3 failed tries on one crash, or 2 hours.
   IF BLOCKED: Stop. Paste the crash address and the patch you suspect.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Screenshot path and log tail. 3) New patches with one line each. 4) What is left. 5) New parking-lot items.

   Done whenThe port reaches the title screen from the player's disc, and the decomp copy has no direct edits.

   Proof this works: Recharged, Nebula, https://github.com/encounter/aurora

9. Prove the port with golden runs

   You need proof the port plays like the original. A scripted tour with screenshots catches changes between builds. Random input finds crashes.

   • Script a tour of the game with fixed inputs.
   • Run it on the old and new build. Compare every screenshot.
   • Add random-input crash runs and many boot runs.
   • Ship a GPU pipeline list recorded from scripted runs.
   • Build one game module per disc version from the decomp's version macros.
   Prompt for ClaudeCopy

   GOAL: Add a scripted tour that compares screenshots between two builds.
   READ FIRST: `SCOPE.md`, `PROGRESS.md`, `tools/check.ps1`
   FENCE: Edit only `tools/` and `tests/`. Do not change game code.
   CHECK: Run `pwsh tools/tour.ps1 -Old <OLD_BUILD> -New <NEW_BUILD>`. Done means every stop is reached and the report lists each picture as same or changed.
   BUDGET: Stop after 3 failed designs, or 3 hours.
   IF BLOCKED: Stop. Tell me which stop cannot be reached by script.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the summary. 3) Files changed. 4) Stops still missing. 5) New parking-lot items.

   Done whenThe scripted tour reaches every stop on a clean checkout, with no picture changes you did not intend.

   Proof this works: Nebula, Recharged

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

Path A: one task is one hook to move, one crash, one missing call or one wrong picture. Each has a harness scenario that must pass. Path B: one task is one unit, a source file the compiler builds alone. ninja must still print OK after the merge. Keep the lists in PROGRESS.md and notes/units.csv, never in the chat.

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

- At the start of every session, read `SCOPE.md`, `PROGRESS.md` and `notes/findings.md`. Only the owner edits `SCOPE.md`.
- The one check is `pwsh tools/check.ps1` (Path A) or `ninja` printing `build/<GAMEID>/main.dol: OK` (Path B). No PASS or OK line means not done.
- Never edit `generated/`. It is build output. Fix the translator, `recomp.yml`, `MAP.txt` or `runtime/` instead.
- Keep `allow_unsupported_instructions: false`. A build with it on can never ship.
- Read-only: `orig/`, the disc folder, `config/<GAMEID>/build.sha1` and the SHA-256 pin in `recomp.yml`.
- Every hook or SDK address goes in `hle_targets.tsv` with how it was proven. Signature names alone are not proof.
- No stubs and no fake events. A missing SDK call stops with a clear error naming the address.
- Live tests use the harness only: no real input, no real saves, 1280x720 window, never fullscreen.
- No inline `asm`, `#pragma` tricks or match-only `volatile` in `src/`. A clean `NonMatching` unit beats a forced match.
- In a worktree, use absolute paths and edit only the files on your task card. One writer per file.
- Write dead ends and findings in `notes/findings.md`. Side issues go in `notes/parking-lot.md`; do not act on them.
- Never commit disc images, `.dol` or `.rel` files, extracted assets or translated code.

Keep the context small

• Give Claude one address or one unit name, not pasted assembly. It can read the file itself.
• Have a subagent read big logs and the harness failure.json, then report ten lines back.
• Keep CLAUDE.md short. Point to notes/compiler-quirks.md and the hook table by name.
• Clear the chat between units. The ledger files carry the state, not the chat.
• Never let Claude read all of generated/. Search it for one function by address.

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 which path fits <GAME> (<GAMEID>) and draft `SCOPE.md`.
READ FIRST: https://decomp.dev, https://github.com/patchzyy/Wiicompiled, `notes/prior-work.md`
FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Do not download anything.
CHECK: Run `Get-FileHash <DISC_FOLDER>/sys/main.dol -Algorithm SHA256`. Done means the hash matches the draft, and the draft lists the disc ID, revision, REL modules, every prior decomp or port with its percent, and one milestone with a runnable check.
BUDGET: Stop after 45 minutes.
IF BLOCKED: Stop. List the facts you could not confirm.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Your pick: recomp, decomp or port, with three reasons. 3) Files changed. 4) Risks. 5) New parking-lot items.

GOAL: Write `notes/functions.csv` with every function in `main.dol` and the RELs.
READ FIRST: `SCOPE.md`, `projects/<game>/MAP.txt` or `config/<GAMEID>/symbols.txt`
FENCE: Edit only `notes/functions.csv`. Do not change the manifest or symbols.
CHECK: Run `python tools/check_ledger.py`. Done means every function in the symbol file is in the ledger once, with size, name source and status.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. List the address ranges you could not classify.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Counts: game, SDK, middleware, unknown. 3) Files changed. 4) Ranges to look at. 5) New parking-lot items.

GOAL: Fix the crash in scenario <SCENARIO> at guest address <ADDR>.
READ FIRST: `<RUN_DIR>/failure.json`, `PROGRESS.md`, `notes/findings.md`
FENCE: Edit only `runtime/`, `projects/<game>/` or `tests/`. Never edit `generated/`. No stubs or fake events.
CHECK: Run `pwsh tools/check.ps1 -Scenario <SCENARIO>`, then `pwsh tools/check.ps1`. Done means both print PASS.
BUDGET: Stop after 3 failed fixes or 60 minutes without a proven cause.
IF BLOCKED: Stop. Write the evidence in `notes/findings.md` and tell me what capture you need.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Cause and both PASS lines. 3) Files changed. 4) New scenario. 5) New parking-lot items.

GOAL: Make unit <UNIT> match 100%.
READ FIRST: the unit's assembly, `notes/units.csv` row for <UNIT>, `notes/compiler-quirks.md`
FENCE: Edit only `src/<UNIT_PATH>`, its header and its `configure.py` line. No inline `asm`, no `#pragma` tricks, no edits to `build.sha1`.
CHECK: Run `ninja`. Done means `build/<GAMEID>/main.dol: OK` and the unit is 100% in `build/<GAMEID>/report.json`.
BUDGET: Stop after 5 real tries with no gain. Each try is a new file, so the best one survives.
IF BLOCKED: Stop. Give the best score and the differing instructions.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) OK line and score. 3) Files changed. 4) One quirk learned, if any. 5) New parking-lot items.

GOAL: Launch <N> workers, one per task from `tools/next_units.py` (or the top of `PROGRESS.md`).
READ FIRST: `CLAUDE.md`, `notes/units.csv` or `PROGRESS.md`
FENCE: Do not do the tasks yourself. Give each worker its own worktree with absolute paths and one task card. Edit only the ledger.
CHECK: After all workers report, run the full check on the main branch. Done means it passes and the ledger matches the reports.
BUDGET: Stop after <N> tasks or 3 hours. Cap compile jobs at one per 2.5 GB of RAM in total.
IF BLOCKED: Stop launching. Tell me which worker is stuck and why.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) A table of task, worker result and proof. 3) Merges made. 4) Tasks for the hard queue. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> at <PLACE_IN_GAME>. Do not fix it yet.
READ FIRST: the harness screenshot, a Dolphin savestate and FIFO log of the same frame at <PATHS>
FENCE: Read-only. You may add logging in `runtime/` behind a flag. Write findings only in `notes/findings.md`.
CHECK: First run `pwsh tools/check.ps1 -Scenario <SCENARIO>` and confirm it shows the symptom. Done means you name the first point where the port and Dolphin differ, such as a TEV stage, matrix load or memory write, with the values from both.
BUDGET: Stop after 90 minutes.
IF BLOCKED: Stop. Tell me what extra capture would split the cause.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The first difference with both values. 3) Files changed. 4) The likely fix and its layer. 5) New parking-lot items.

GOAL: Check that the work in commits <RANGE> is real.
READ FIRST: `git diff <RANGE>`, `CLAUDE.md`, the workers' reports
FENCE: Read-only. Do not fix anything.
CHECK: Rerun the full check from a clean build. Then search the diff for edits to `generated/`, `build.sha1` or the hash pin, inline `asm`, `#pragma`, stubs, fake events, disabled tests and edits outside each task's fence.
BUDGET: Stop after 45 minutes.
IF BLOCKED: Stop. Say which claim you could not test.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The check output. 3) Each problem with file and line. 4) Which claims hold. 5) New parking-lot items.

GOAL: Give me a status report from the ledger files only.
READ FIRST: `PROGRESS.md`, `notes/units.csv` or `notes/functions.csv`, `notes/findings.md`
FENCE: Read-only.
CHECK: Every number comes from a file or a command you ran, such as `build/<GAMEID>/report.json`.
BUDGET: 15 minutes.
IF BLOCKED: Say which file is missing or out of date.
REPORT: 1) Milestone and its check result. 2) Counts: done, in progress, stuck. 3) Top three blockers. 4) Next three tasks. No other text.

GOAL: Write what the next session needs into the ledger files.
READ FIRST: this session's changes (`git status`, `git log -5`), `PROGRESS.md`
FENCE: Edit only `PROGRESS.md`, `notes/findings.md` and `notes/units.csv`.
CHECK: Run `git diff --stat -- PROGRESS.md notes/` and paste it. Done means a new session could start the next task from these files alone, and each open task has its next step and its check command.
BUDGET: 10 minutes.
IF BLOCKED: Say what you could not record.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE or PARTIAL. 2) What works now, with proof. 3) Dead ends tried. 4) The next task card, ready to paste.

GOAL: Give me a plain answer on <TASK>: can it be done, and how?
READ FIRST: `notes/findings.md`, the attempt files for <TASK>
FENCE: Read-only.
CHECK: Run the task's own check command once more and paste the output. Your answer names the exact blocker with evidence: differing instructions, a log line or an address. 'Compiler artifact' or 'probably' is not evidence.
BUDGET: 20 minutes.
IF BLOCKED: Say BLOCKED and what would unblock it.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The blocker in one sentence. 3) The evidence. 4) Two or three options with cost. 5) Your pick.

GOAL: Ask me before you leave the fence for <TASK>.
READ FIRST: the task card, `SCOPE.md`
FENCE: Change nothing until I answer yes.
CHECK: Your request names the files, why the current fence is not enough, and the risk to other units or scenarios.
BUDGET: 10 minutes.
IF BLOCKED: Wait for my answer.
REPORT: 1) BLOCKED. 2) Files you want to change. 3) Why. 4) Risk and how you would check it. 5) What you will do if I say no.

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

• Whether a sister game already has a WiiCompiled port or a decomp. Brawl Recompiled had its first release a day after it forked the same author's Super Paper Mario port.
• Whether a symbol map exists. Without one, missed functions show up one crash at a time.
• How many RELs the game loads. A game with one main.dol is simpler than Metroid Prime 3 with 74 modules or Brawl with 126.
• Game size. Strikers Charged has 17,689 functions; Brawl has 92,522.
• Whether you build a harness early. Without it, every test needs you at the keyboard.
• Compile time and RAM. Building the Wario Land port on a player's PC takes 15 to 45 minutes and 16 GB of RAM is advised.

The facts behind these numbers

Projects reviewed (13)

The top-starred project for each of the top 12 Wii games on RecompLauncher, plus one project its developer says was written by AI. RecompLauncher lists 25 Wii projects for 19 games. None came from outside it.

What each project teaches

What we could not check

• When most Wii ports really started. Many published their first commit and first release on the same day, so earlier private work is unknown.
• Whether AI was used on the Mario Strikers Charged decomp. Its README and CONTRIBUTING.md do not say, and no commit has an AI co-author line.
• When exactly the Strikers decomp reached 100%. The date above comes from its last regional linking commits.
• Whether plain decomp-permuter runs on native Windows. Its README only says permuter@home does not.
• Whether the Ghidra GameCube Loader opens Wii DOL files. Its README names GameCube only, and its latest zip targets Ghidra 12.1.
• Whether dolphin-debugger-mcp works on a Wii project. It was built for a GameCube decomp.
• The Dolphin download page. It refused automated reading again on 2026-11-13 (HTTP 403), so the install line was not checked there.
• Which compilers third-party Wii games used. The reviewed decomps only show Metrowerks tools.
• The tools/check.ps1 (with its -BuildOnly, -Scenario and -Full switches), tools/check_ledger.py, tools/next_units.py, tools/tour.ps1 and tools/full_check.py files are ones you write. No reviewed project ships them under these names. Only Shake It! Native PC keeps an hle_targets.tsv.
• The manifest key name for the main.dol SHA-256 pin. The translator README says the pin exists, but the example manifest does not show it. Copy it from a reviewed port's recomp.yml.
• Whether the Ghidra GameCube Loader zip labelled Ghidra 12.1 installs on Ghidra 12.1.4. If not, build it from source.
• How to export a function list from DolRecomp. Its README does not show it; Shake It! Native PC says it used DolRecomp boundaries.
• The folder layout nodtool extract gives for a Wii disc. The sys/ and files/ layout here comes from WiiCompiled's macOS guide, read through its review card. Check that sys/main.dol exists after you extract.
• The exact arguments WiiCompiled build scripts pass on Windows. The full list was read only from its macOS guide and from the Brawl and Super Paper Mario cards.
• Time ranges for one person. No reviewed project gives hours spent.

Sources

• WiiCompiled README
• WiiCompiled translator README
• Aurora README
• nod and nodtool README
• decomp-toolkit README
• dtk-template getting started
• dtk-template dependencies
• objdiff README
• m2c README
• decomp-permuter README
• DolRecomp README
• NWiiRecomp README and licence
• llvm-mingw README
• Ghidra GameCube Loader README
• GhidraMCP README
• Dolphin debugger MCP README
• Mario Strikers Charged decomp README
• decomp.dev: Mario Strikers Charged
• decomp.dev: Petari
• decomp.dev: Brawl
• WiiBrew: DOL format
• WiiBrew: Broadway CPU
• WiiBrew: Hollywood
• MKWii wiki: REL file format
• Melee decomp final pull request
• WiiCompiled example manifest
• Aurora build and CMake guide
• m2c target options
• Microsoft: install .NET on Windows
• Microsoft: install PowerShell on Windows
• CMake downloads
• Python downloads
• Git for Windows install