Nintendo GameCube decomp guide

What this system is like

The GameCube is one of the best systems for this hobby. Every game uses the same chip, the same compiler family and the same Nintendo code library. That library is called the SDK, short for software kit. Tools know it well, so they can name much of the code for you.

There are two proven ways to get a game running on PC. If someone already finished a decomp of your game, you port it. You compile its C code for PC and let Aurora draw the pictures. If no decomp exists, you recompile. DolRecomp or gcn-recomp turns the game's machine code into C, and a runtime stands in for the console.

A full decomp is slower but very doable. The decomp-toolkit tools run on plain Windows, with no WSL. Melee, Animal Crossing, Mario Party 4, Pikmin and Star Fox Adventures reached 100%. Twilight Princess matches fully, but not every unit is linked yet. Agents helped finish Melee and Star Fox Adventures in 2026.

The hard parts are speed and the last few percent. Recompiled code can run too slow in busy scenes. The last functions of a decomp can take as long as the first half.

Two paths

Path A: Get it running on PC

First check if a decomp of your game exists. If it does, port it with Path B's last steps. If not, a recompiler turns main.dol and its .rel modules into C. A runtime stands in for the console: graphics, sound, discs and saves. You fix one crash at a time with a scripted test run until the game plays.

1. Scope the game and look for prior work

   You pin the exact disc you own. You look for an existing decomp or symbol file. Then you write a one-page plan that the owner signs off.

   • Check your dump: dtk disc verify game.iso or nodtool verify game.iso. Both compare it with the Redump list.
   • Read the disc ID and the DOL: dtk disc info game.iso and dtk dol info 'game.iso:sys/main.dol'.
   • Copy the DOL to a work folder outside the repo: dtk vfs cp 'game.iso:sys/main.dol' <WORK_DIR>. Hash it with dtk shasum <WORK_DIR>/main.dol and write the hash down.
   • Search GitHub and decomp.dev for a decomp of your game. Even a partial one gives you symbols.txt, a list of function names and addresses.
   • List the disc with dtk vfs ls -r -s 'game.iso:' and count the .rel files. Some games pack them in .arc archives. List those too, such as dtk vfs ls 'game.iso:files/RELS.arc:'.
   • Look for middleware names in strings, such as CRI or THP video.
   • Write SCOPE.md: game, disc ID, DOL hash, technique, first milestone, what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a GameCube recomp of <GAME>, disc <DISC_ID>.
   READ FIRST: `notes/disc-info.txt` (output of `dtk disc info` and `dtk dol info`), the GitHub search results I pasted in `notes/prior-work.md`.
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Do not build or download anything.
   CHECK: Run `dtk shasum <WORK_DIR>/main.dol` and compare it with the hash in `SCOPE.md`. Done means they agree, and `SCOPE.md` names the disc ID, the number of `.rel` files, any decomp or `symbols.txt` found, the chosen recompiler (`DolRecomp` or `gcn-recomp`) and the first milestone with its check.
   BUDGET: Stop after 30 minutes of reading.
   IF BLOCKED: Stop. Tell me which fact you could not confirm and where you looked.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The draft. 3) Files changed. 4) Open questions for me. 5) New parking-lot items.

   Done whenSCOPE.md lists the disc ID, the DOL hash, the module count, prior work and the first milestone, and you approved it.

   Proof this works: Luigi's Mansion Recomp, Eternal Darkness Recomp, Spongebob Squarepants: Revenge of the Flying Dutchman, https://github.com/encounter/decomp-toolkit

2. Set up the repo, tools and one check

   You make a repo that holds only your own code. The disc and all generated C stay outside it. You add one command that builds and one that runs a check.

   • Route 1, DolRecomp with ModernGekko (in WSL): make a repo from ModernGekko-Template, then git clone --recurse-submodules <your-repo>.
   • Install the WSL packages the template lists, starting with sudo apt-get install -y ninja-build build-essential pkg-config cmake. Then run make check.
   • Use WSL for Route 1. The DolRecomp README says ModernGekko does not build with MSVC yet.
   • Route 2, gcn-recomp (Windows or WSL): add it as a submodule and call gcn_add_game() with your disc ID and DOL hash. Build with cmake -S . -B build -G Ninja and ninja -C build.
   • Pin every upstream tool to one commit. Keep your fixes as numbered patch files that a script applies.
   • Put iso/, extracted/, generated/ and build/ in .gitignore.
   • Write CLAUDE.md, PROGRESS.md and notes/parking-lot.md.
   Prompt for ClaudeCopy

   GOAL: Make the repo build the recompiler and runtime with one command, and add `tools/check.sh` that runs the current check.
   READ FIRST: `SCOPE.md`, the `ModernGekko-Template` README (or `gcn-recomp` README), `CLAUDE.md`.
   FENCE: Edit only `Makefile`, `CMakeLists.txt`, `tools/`, `.gitignore`, `PROGRESS.md`. Do not touch `lib/` submodules. Do not add features.
   CHECK: Run `make check` (or `cmake -S . -B build -G Ninja && ninja -C build`). Done means it exits 0, and `git status` shows no disc or generated files.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: Stop. Do not work around it. Paste the error and tell me what you need.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenmake check (or the CMake build) exits 0 on a clean clone, and git status lists no game files.

   Proof this works: F-ZERO GLINUX, Eternal Darkness Recomp, Naruto: Clash of Ninja Collection, https://github.com/ExpansionPak/ModernGekko-Template

3. Map the code

   You list every function with its address and size. You mark SDK code so nobody converts it by hand. You also note anything that will need runtime work.

   • Get function edges: dtk dol config main.dol -o config/<ID>/config.yml, add symbols: and splits: paths, then dtk dol split config/<ID>/config.yml build/<ID>.
   • If a decomp exists, take its symbols.txt instead. It names every function.
   • Find OSSaveContext, OSLoadContext, OSReport and OSPanic. dtk may leave some as fn_ names, so check them by hand.
   • Run the recompiler once and save its list of possible self-modifying code. That means code that rewrites itself.
   • Save the map to notes/functions.csv with columns: address, size, name, kind (game or SDK), status.
   • Have Claude write tools/check_map.py first. It compares the CSV with symbols.txt and with the section sizes from dtk dol info.
   Prompt for ClaudeCopy

   GOAL: Produce `notes/functions.csv` for <DISC_ID>: every function with address, size, name, kind (game or SDK) and status.
   READ FIRST: `SCOPE.md`, `config/<DISC_ID>/symbols.txt`, the self-modifying code report at `<PATH>`.
   FENCE: Edit only `notes/functions.csv`, `notes/map.md` and `config/<DISC_ID>/`. Do not edit generated C.
   CHECK: Run `python tools/check_map.py`. Done means every address in `symbols.txt` is in the CSV, sizes add up to the code section sizes from `dtk dol info`, and the five OS functions named in `notes/map.md` are present.
   BUDGET: Stop after 2 hours or 3 failed check runs.
   IF BLOCKED: Stop. List the functions you could not place and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whennotes/functions.csv covers every function, its sizes match the section sizes, and the OS functions are named.

   Proof this works: Naruto: Clash of Ninja Collection, Luigi's Mansion Recomp, Spongebob Squarepants: Revenge of the Flying Dutchman

4. Boot to the first frame

   You recompile the whole game and run it with no person at the keys. The goal is one picture on screen and a clean exit. This is the smallest proof that the pipeline works.

   • Route 1: make run ISO=/path/to/game.iso. For a run with no window, add RUN_ARGS="--headless --graphics Null".
   • Or call the recompiler by hand: ./dolrecomp --gamecube extracted/sys/main.dol build.
   • Route 2: build, then run the headless bench, for example ./build/<game>_bench --seconds=20.
   • Make a crash end with a non-zero exit code, so a script can read it.
   • Write the first golden run into tools/check.sh: boot, wait a set time, check the exit code and one log line.
   Prompt for ClaudeCopy

   GOAL: Make the recompiled game boot headless for 20 seconds and exit cleanly.
   READ FIRST: `SCOPE.md`, `notes/map.md`, `PROGRESS.md`, the last run log at `<LOG_PATH>`.
   FENCE: Edit only runtime and host code under `<RUNTIME_DIR>/` and `tools/`. Never edit files under `build/` or `generated/`. If the generated C is wrong, describe the recompiler fix instead.
   CHECK: Run `tools/check.sh boot`. Done means exit code 0 and the log shows `<FIRST_LOG_LINE>`.
   BUDGET: Stop after 4 failed fixes or 90 minutes without progress.
   IF BLOCKED: Stop. Paste the last 40 log lines and say which layer failed: recompiler, runtime, SDK stand-in or disc reads.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/check.sh boot exits 0 and the log shows the first frame line within 20 seconds.

   Proof this works: F-ZERO GLINUX, Naruto: Clash of Ninja Collection, https://github.com/ExpansionPak/DolRecomp

5. Stand in for the SDK at its edges

   You replace a few Nintendo OS functions with runtime code. Thread switching, the idle loop and error reports are the usual ones. You also make disc reads and audio take real time, as on the console.

   • With gcn-recomp, fill recomp/hle.txt (OSSaveContext, OSLoadContext, OSReport, OSPanic, OSResetSystem), recomp/idle.txt and recomp/special_calls.txt.
   • Put the address of OSSaveContext itself in special_calls.txt, not the call site.
   • Point idle.txt at the backward branch of the idle spin inside SelectThread.
   • Make disc reads take time and make the audio interrupt tick evenly. Instant reads broke boot in Luigi's Mansion.
   • Report the console region the disc names. A PAL disc panics if the runtime says NTSC.
   • Add a frame-keyed input script now, such as GCN_INPUT="frame:BUTTON:duration". Then a script can press Start with no person.
   • On the ModernGekko route, the Dolphin-based runtime already stands in for the SDK. Use this step only for the bugs it misses.
   Prompt for ClaudeCopy

   GOAL: Get <GAME> from boot to the title screen by fixing the SDK stand-in, one function at a time.
   READ FIRST: `notes/map.md`, `recomp/hle.txt`, `recomp/idle.txt`, `recomp/special_calls.txt`, the failing log at `<LOG_PATH>`.
   FENCE: Edit only `recomp/*.txt` and `<RUNTIME_DIR>/hle_*`. Do not put game addresses or game names in shared runtime code. They go in the game's tables.
   CHECK: Run `tools/check.sh title`. Done means the scripted input `<INPUT_SCRIPT>` reaches the title screen and the log line `<TITLE_LOG_LINE>` appears.
   BUDGET: Stop after 3 failed tries on the same function.
   IF BLOCKED: Stop. Name the SDK function, the guest address and the fault text.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/check.sh title reaches the title screen with scripted input and no person.

   Proof this works: Naruto: Clash of Ninja Collection, Luigi's Mansion Recomp, https://github.com/ethannicholas/gcn-recomp

6. Grind: one crash or bug per session

   You build a repeatable test run first. Then each session fixes one crash, one missing call or one drawing bug. A per-frame hash tells you if a fix changed anything else.

   • Use the input script from the last step for every route. Luigi's Mansion reads the same kind of script with --input <file>.
   • Add a per-frame hash of guest memory, or a frame dump by frame number. Ring Out compared 7,000 frames this way.
   • Keep a list of routes: menu, first level, a busy scene. Run them all after each fix.
   • Fix bugs in the recompiler or runtime. Save recompiler fixes as patch files. Never hand-edit the generated C.
   • Log every finding and dead end in notes/findings.md.
   Prompt for ClaudeCopy

   GOAL: Fix one bug: <BUG_DESCRIPTION>, seen on route <ROUTE> at frame <FRAME>.
   READ FIRST: `PROGRESS.md`, `notes/findings.md`, the run log `<LOG_PATH>`, the frame dump `<DUMP_PATH>`.
   FENCE: Edit only `<RUNTIME_DIR>/` and `patches/`. Never edit `build/` or `generated/`. No new features.
   CHECK: Run `tools/check.sh routes`. Done means route <ROUTE> passes and every other route keeps the same frame hashes as before.
   BUDGET: Stop after 3 failed fixes. Prove the cause before each fix.
   IF BLOCKED: Stop. Show the evidence you have and what you need to see next.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/check.sh routes passes for every route and the hashes of untouched routes did not change.

   Proof this works: Ring Out, Luigi's Mansion Recomp, BlueWake

7. Make it fast enough

   Recompiled code can be slow in busy scenes. You measure first, from a fixed save state and a fixed route. You compare with Dolphin running the same game, so you know if the slowdown is yours.

   • Pick one busy scene and one save state. Measure frames per second and CPU cycles there.
   • Have Claude write tools/bench.sh. It loads the save state, runs a fixed number of frames, and prints frames per second and the frame hash.
   • Run the same scene in Dolphin. If Dolphin shows the same bug or slowdown, it is not a recompiler bug.
   • Profile. Fix hot spots in the generator, such as cache instructions handled inline.
   • Try profile-guided builds: llvm-profdata with the same clang that builds the game.
   • Keep a table of ideas you measured and dropped, so no session tries them again.
   Prompt for ClaudeCopy

   GOAL: Raise frame rate in <SCENE> from <CURRENT_FPS> to <TARGET_FPS> without changing game behaviour.
   READ FIRST: `notes/perf.md` (measured and rejected ideas), the profile at `<PROFILE_PATH>`, `tools/bench.sh`.
   FENCE: Edit only the recompiler patch files in `patches/` and `<RUNTIME_DIR>/`. Do not change game timing or skip frames.
   CHECK: Run `tools/bench.sh <SCENE>` three times. Done means the median meets <TARGET_FPS> and the frame hash column matches the old build.
   BUDGET: Stop after 3 ideas that do not help. Log each in `notes/perf.md`.
   IF BLOCKED: Stop. Report the hottest functions and your next idea.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the bench output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/bench.sh meets the target in the chosen scene with the same frame hashes as before.

   Proof this works: Spongebob Squarepants: Revenge of the Flying Dutchman, Ring Out, BlueWake, F-ZERO GLINUX

8. Harden and package

   You make old fixes stay fixed. You make the program check the user's disc. You prove that nothing from the game ends up in your repo or your release.

   • Check the disc ID and the SHA-1 of main.dol before you build. Also check each disc file by size and CRC-32.
   • Add a script that fails if any disc-derived file is staged or packed, like tools/check_publish.py.
   • Run every route from a clean clone with a scratch save folder, never your real saves.
   • Build Linux packages in an older container, so they run on older systems.
   • Write down what you tested and on which device.
   Prompt for ClaudeCopy

   GOAL: Make the full check pass on a clean clone, including the disc check and the publish check.
   READ FIRST: `PROGRESS.md`, `tools/check.sh`, `tools/check_publish.py`.
   FENCE: Edit only `tools/` and `packaging/`. Do not change runtime behaviour.
   CHECK: In a fresh clone, run `tools/check.sh all`. Done means all routes pass, a wrong disc is rejected, and `tools/check_publish.py` finds no game data.
   BUDGET: Stop after 3 failed runs on the same step.
   IF BLOCKED: Stop. Name the failing step and paste its output.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/check.sh all passes on a clean clone, rejects a wrong disc, and the publish check finds no game data.

   Proof this works: Luigi's Mansion Recomp, Naruto: Clash of Ninja Collection, BlueWake

Path B: Full decomp for porting

You write C and C++ that the original CodeWarrior compiler turns back into the same bytes. decomp-toolkit splits the game into pieces, and objdiff scores each function. When every piece matches, the rebuilt main.dol has the same hash as yours. Then you port it: compile the code for PC and let Aurora stand in for the console.

1. Scope: find prior work and the compiler

   Many GameCube decomps exist, some complete. You check for one first. If none fits, you pick the version, find hints about the compiler and write the plan.

   • Search GitHub and decomp.dev for your game. Several games are already at 100%.
   • Look for sister games on the same engine. Wind Waker and Twilight Princess share engine code.
   • Look on the disc for .map files or a debug build: dtk vfs ls -r -s 'game.iso:'. A map file fills in names for free.
   • Note the project rules of any decomp you build on. zeldaret/tww closes pull requests that are mainly AI-made, so keep your AI work in your own fork.
   • Write SCOPE.md: game ID and revision, DOL and REL hashes, likely compiler version, milestones.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a matching decomp of <GAME> (<GAME_ID>, revision <REV>).
   READ FIRST: `notes/prior-work.md`, `notes/disc-info.txt`, the dtk-template docs `docs/getting_started.md`.
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Do not set up the repo yet.
   CHECK: Run `dtk disc verify <DISC_PATH>` and paste the result. Done means the disc matches Redump, and `SCOPE.md` names the game ID, the SHA-1 of `main.dol` and each `.rel`, any map or debug files found, related decomps, their AI rules, and the first matching milestone.
   BUDGET: Stop after 45 minutes of reading.
   IF BLOCKED: Stop. Tell me what you could not confirm.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The draft. 3) Files changed. 4) Open questions. 5) New parking-lot items.

   Done whenSCOPE.md lists the hashes, prior work, the compiler guess and the first milestone, and you approved it.

   Proof this works: https://github.com/zeldaret/tww, https://github.com/zeldaret/tp, Dusklight

2. Set up dtk-template on Windows

   You make the project from dtk-template. It needs only Python and Ninja on Windows. It downloads the right compilers, dtk and objdiff-cli by itself, into build/tools/.

   • Create a repo from dtk-template and clone it.
   • Install Python, then install Ninja with pip install ninja.
   • Rename orig/GAMEID and config/GAMEID to your game ID. Put your disc image, or the files Dolphin extracts, in orig/<GAMEID>. They stay out of git.
   • The hash command reads loose files. If you used a disc image, extract it to a folder outside the repo first. Use Dolphin's Extract Entire Disc, or dtk disc extract <DISC_FILE> <OUT_DIR>. Point the paths below at that folder.
   • Make the hash file: dtk shasum orig/<GAMEID>/sys/main.dol orig/<GAMEID>/files/*.rel -o config/<GAMEID>/build.sha1. Then edit its paths to point at build/ instead of orig/.
   • Add your game ID to VERSIONS in configure.py. Run python configure.py, then ninja.
   • Add a hook that blocks edits to build.sha1 and orig/.
   Prompt for ClaudeCopy

   GOAL: Make `python configure.py` and `ninja` run the first analysis for <GAMEID>.
   READ FIRST: `SCOPE.md`, `docs/getting_started.md`, `config/<GAMEID>/config.example.yml`.
   FENCE: Edit only `configure.py` (the `VERSIONS` list and settings), `config/<GAMEID>/config.yml` and `.claude/settings.json`. Never edit `config/<GAMEID>/build.sha1` after it is made. Never touch `orig/`.
   CHECK: Run `python configure.py` then `ninja`. Done means `config/<GAMEID>/symbols.txt` and `splits.txt` exist.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: Stop. Paste the error and the config section it points to.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 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/zeldaret/tww, Animal Crossing PC Port (now named Nookery)

3. Map the binary and split it into units

   You fix the split points so each unit matches one original source file. You mark SDK and library code. The ledger is the progress report that the build writes.

   • Fix split points in splits.txt and names in symbols.txt. Wrong edges make a function impossible to match.
   • Set up __init_cpp_exceptions.cpp as the dtk-template docs describe, if the game uses C++.
   • Put SDK, MSL_C, Runtime and JSystem units in their own progress category, such as sdk.
   • Borrow names from decomps of sister games that link the same libraries.
   • Read progress from build/<GAMEID>/report.json. Save a baseline with ninja baseline.
   Prompt for ClaudeCopy

   GOAL: Clean up the splits for <AREA> so each unit is one original file, and label SDK units.
   READ FIRST: `config/<GAMEID>/splits.txt`, `config/<GAMEID>/symbols.txt`, `notes/sdk-units.md`.
   FENCE: Edit only `splits.txt`, `symbols.txt`, `configure.py` object lists and `notes/`. Do not write C yet.
   CHECK: Run `ninja`. Done means the `build.sha1` check still passes and `build/<GAMEID>/report.json` lists the new units.
   BUDGET: Stop after 3 failed builds.
   IF BLOCKED: Stop. Show the dtk error and the address range.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenninja still passes the hash check and report.json lists every unit with a category.

   Proof this works: https://github.com/encounter/dtk-template, Ring Out, Eternal Darkness Recomp

4. Match one small unit end to end

   You prove the whole loop on one small file. You write its C, mark it as matching, and the full build still gives the same bytes.

   • Pick a small unit with few functions. SDK units are good first picks.
   • Get a C draft with m2c using the PowerPC and mwcc targets.
   • Compare with objdiff-cli diff -p . -u <unit> -o - <function>, or the objdiff window. The template saves the CLI as build/tools/objdiff-cli.exe. Add that folder to PATH or call it by its full path.
   • When it is 100%, change its line in configure.py to Object(Matching, "<file>").
   • Run ninja. The build.sha1 check must pass with the unit linked.
   Prompt for ClaudeCopy

   GOAL: Match unit <UNIT> fully and link it.
   READ FIRST: `CLAUDE.md`, the unit's asm at `build/<GAMEID>/asm/<UNIT>.s`, matched units in `src/` that look similar.
   FENCE: Edit only `src/<UNIT>.c`, its header, and its one line in `configure.py`. No inline asm, no `#pragma` tricks.
   CHECK: Run `objdiff-cli diff -p . -u <UNIT> -o - <FUNCTION>` for each function, then `ninja`. Done means every function is 100% and the `build.sha1` check passes with `Object(Matching, ...)`.
   BUDGET: Stop after 5 real attempts per function.
   IF BLOCKED: Stop. Paste the best diff and say which instructions differ.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenninja passes the build.sha1 check with the unit set to Matching.

   Proof this works: https://github.com/encounter/objdiff, https://github.com/doldecomp/melee/pull/2076, https://github.com/matt-kempster/m2c

5. Grind: one function per session

   This is most of the work. A script picks the next easy function. A worker gets one function, five tries and a fresh chat. Matches are kept and failures are logged.

   • Sort open functions by size. Do small ones first, then ones that look like matched code.
   • Give each worker its own git worktree, a separate copy of the project folder.
   • Each worker runs m2c, edits C, and checks with objdiff-cli diff.
   • Commit each verified match. Reset on failure and log what was tried.
   • Run ninja changes before each merge. It lists any function that got worse.
   Prompt for ClaudeCopy

   GOAL: Match function <FUNCTION> in unit <UNIT> to 100%.
   READ FIRST: `CLAUDE.md`, `notes/compiler-quirks.md`, the asm for <FUNCTION>, up to three similar matched functions: <LIST>.
   FENCE: Edit only `src/<UNIT>.c` and `include/<UNIT>.h`. Do not edit `configure.py`, `config/`, `build.sha1` or other units. No inline asm.
   CHECK: Run `objdiff-cli diff -p . -u <UNIT> -o - <FUNCTION>`, then `ninja` and `ninja changes`. Done means 100%, the hash check passes and no other function got worse.
   BUDGET: Stop after 5 real attempts. Each attempt must differ from the last.
   IF BLOCKED: Stop. Log the best score and the differing instructions in `notes/attempts/<FUNCTION>.md`.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenobjdiff-cli shows 100%, ninja passes the hash check and ninja changes shows no losses.

   Proof this works: https://github.com/doldecomp/melee/pull/2076, https://github.com/zcanann/SFA-Decomp, https://github.com/lukechampine/melee-harness

6. Crack the hard tail

   Some functions stall at 95 to 99%. You send these to a stronger job type with more context. You do not accept 'impossible' without proof.

   • Ask why it fails first. Is it register choice, order, a missing inline or wrong types?
   • Search matched code for the same instruction pattern. Star Fox Adventures found 'impossible' shapes already matched elsewhere.
   • Try decomp-permuter in WSL on near misses. Add permuter_settings.toml with build_system = "ninja" at the project root first, so import.py reads build.ninja. Treat its output as a hint, not an answer.
   • Keep a shared notes/compiler-quirks.md with general CodeWarrior lessons only.
   • If clean C cannot match, leave the unit NonMatching. A clean 90% beats a hacked 100%.
   Prompt for ClaudeCopy

   GOAL: Find why <FUNCTION> stops at <SCORE>% and match it with clean C, or prove what blocks it.
   READ FIRST: `notes/attempts/<FUNCTION>.md`, `notes/compiler-quirks.md`, the current diff from `objdiff-cli diff -p . -u <UNIT> -o - <FUNCTION>`.
   FENCE: Edit only `src/<UNIT>.c`, `include/<UNIT>.h` and `notes/`. No inline asm, `asm("")` barriers, `#pragma` sandwiches or fake `volatile`.
   CHECK: `objdiff-cli` shows 100%, `ninja` passes the hash check and `ninja changes` shows no losses.
   BUDGET: Stop after 6 attempts or 2 hours.
   IF BLOCKED: Stop. Name the exact differing instructions and a cause you can test. 'Compiler artifact' is not a cause.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe function is 100% with clean C, or notes/attempts/ names the exact blocker and the unit stays NonMatching.

   Proof this works: https://jpb.dev/blog/teaching-a-model-to-decompile, https://github.com/simonlindholm/decomp-permuter, https://github.com/zcanann/SFA-Decomp

7. Verify and link everything

   A fresh session with no memory of the work checks it. It reruns the build, reads the diffs and hunts for cheats. Then every unit gets linked.

   • Start a new session and run ninja from a clean clone.
   • Search the diff for asm, #pragma, edited build.sha1 and units marked Matching that are not 100%.
   • Check that no matched function lost its match after a merge.
   • Link the last units until report.json shows 100% linked.
   Prompt for ClaudeCopy

   GOAL: Check the last <N> merged matches for real results and cheating.
   READ FIRST: `git log --oneline -<N>`, `CLAUDE.md` rules, `build/<GAMEID>/report.json`.
   FENCE: Read only. Do not edit any file. Write findings to `notes/verify-<DATE>.md` only.
   CHECK: From a clean clone run `python configure.py` and `ninja`. Done means you report the hash check result and list every rule break found.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Say what you could not check and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) PASS or FAIL. 2) Proof: paste the check output. 3) Each problem with file and line. 4) What you did not check. 5) New parking-lot items.

   Done whenA fresh session reports PASS from a clean clone and report.json shows 100% matched and linked.

   Proof this works: https://github.com/doldecomp/melee/pull/3409, https://github.com/doldecomp/melee/wiki/FAQ

8. Port: build the code for PC on Aurora

   You compile the decomp's code with a PC compiler. Aurora stands in for graphics, input, disc and memory card. Your PC code lives in its own folder, and every change to game code is marked.

   • Add Aurora as a submodule in extern/aurora. In CMake, call add_subdirectory(extern/aurora EXCLUDE_FROM_ALL) and link aurora::core, aurora::gx, aurora::main and aurora::vi. Turn on AURORA_ENABLE_DVD, which is off by default, to read the disc image.
   • Put PC code in pc/ or src/platform/. Wrap changes to game code in #if TARGET_PC or mark them with // PORT:.
   • Add two switches now: a disc path option (Dusklight uses --dvd <path>) and an exit-after-frames setting (melee-pc uses MELEE_EXIT_AFTER_FRAMES). The check below needs both.
   • Fix byte order. melee-pc marks disc structs with GCC's scalar_storage_order("big-endian").
   • Fix 8-byte pointers. Keep guest addresses below 4 GiB, or ship a 32-bit build too.
   • Let a script write abort-on-call stubs for missing symbols, checked against an allow list.
   Prompt for ClaudeCopy

   GOAL: Make the PC build of <GAME> link and show the title screen from my disc image.
   READ FIRST: `SCOPE.md`, Aurora `docs/building.md`, `pc/README.md`, the link errors at `<LOG_PATH>`.
   FENCE: Edit only `pc/`, `CMakeLists.txt` and game files where a change is wrapped in `#if TARGET_PC` with a `// PORT:` note. Do not reformat game code.
   CHECK: Run `cmake --build build` then `build/<GAME> --dvd <DISC_PATH>` with `<EXIT_AFTER_FRAMES>`. Done means exit code 0 and the title log line appears.
   BUDGET: Stop after 4 failed fixes on one error.
   IF BLOCKED: Stop. Paste the error and say if it is byte order, pointer size, a missing SDK call or a link clash.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe PC build links and reaches the title screen from the disc image in a scripted run.

   Proof this works: Dusklight, melee-pc, Strikers, Animal Crossing PC Port (now named Nookery), https://github.com/encounter/aurora

9. Port: test without a person and harden

   You add switches that let a script run the game the same way each time. Then old fixes stay fixed. CI builds and tests with no disc at all.

   • Add record and replay of input, a fixed random seed and a fixed time step.
   • Add a boot-to-scene switch next to the exit-after-frames switch. Judge runs by exit code and log lines.
   • Build the game code once with -m32 and size checks, to catch struct sizes that grew.
   • Label tests that need the disc, and leave them out of CI.
   • Keep one status table that says what works and on which hardware.
   Prompt for ClaudeCopy

   GOAL: Add a smoke test that boots <SCENE>, runs <N> frames from a recorded input file, and fails on a crash or a missing log line.
   READ FIRST: `pc/`, `tests/`, `notes/findings.md`.
   FENCE: Edit only `pc/`, `tests/` and `tools/`. Do not change game logic.
   CHECK: Run `ctest --test-dir build --output-on-failure` and `tools/smoke_test.py`. Done means both pass, and breaking the scene on purpose makes the smoke test fail.
   BUDGET: Stop after 3 failed tries.
   IF BLOCKED: Stop. Say what the test cannot see and what you need.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenctest and the smoke runs pass on a clean clone, and a broken build makes them fail.

   Proof this works: Strikers, melee-pc, Open Nectar

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

In Path A, one unit is one crash, one missing SDK call or one drawing bug on one route. Its check is a scripted run with frame hashes. In Path B, one unit is one function in one file. Its check is the objdiff-cli score plus the full ninja hash check. Keep shared runtime code free of game addresses, so fixes do not clash. Write every result in a ledger file, not 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

- Read `SCOPE.md` and `PROGRESS.md` at the start of every session.
- The only check is `ninja` (Path B) or `tools/check.sh` (Path A). A score from objdiff is evidence. The full build is the verdict.
- Never edit `config/<GAMEID>/build.sha1`, anything in `orig/`, or anything in `build/` or `generated/`.
- Generated C is never edited by hand. Fix the recompiler and save the fix as a numbered file in `patches/`.
- No inline asm, `asm("")` barriers, per-function `#pragma` blocks or fake `volatile` to force a match. Leave the unit `NonMatching`.
- Nothing game-specific in shared runtime code. A game address belongs in the game's tables, not in a constant.
- Never commit or quote disc images, extracted files, generated C, disassembly or saves.
- Say what you ran and on what device. A build that compiles is not a game that plays.
- Test with a scratch save folder and `--input` scripts, never the owner's real saves.
- Do not update or reset submodules. Pinned commits plus `patches/` are the source of truth.
- Record findings in `notes/findings.md` and dead ends in `notes/dead-ends.md`. Side issues go to `notes/parking-lot.md`.
- In a worktree, use absolute paths and run the build there, not in the main folder.
- Call `objdiff-cli` from `build/tools/`, where `dtk-template` puts it.

Keep the context small

• Give Claude one function name and its unit, not a whole .s file. Let it run objdiff-cli itself.
• Do not paste Dolphin logs. Save them to a file and give the path and the frame number.
• Add Read deny rules for build/, generated/ and orig/, so searches skip huge machine-made files.
• Use a subagent to read a sister game's decomp and report back the few matched functions that look alike.
• Run /clear between functions or bugs. State lives in the ledger files, so nothing is lost.

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 the best route to get <GAME> (<DISC_ID>) running on PC, and draft `SCOPE.md`.
READ FIRST: `notes/disc-info.txt`, `notes/prior-work.md`.
FENCE: Read only, except `SCOPE.md` and `notes/prior-work.md`. Do not install or download anything.
CHECK: Run `dtk disc verify <DISC_PATH>` and `dtk dol info '<DISC_PATH>:sys/main.dol'`, and paste both. Done means the disc matches Redump, and the draft names one route (port of an existing decomp, `DolRecomp` recomp, or `gcn-recomp` recomp), the reason, the first milestone and its check command.
BUDGET: Stop after 45 minutes.
IF BLOCKED: Stop. Say which fact decides the route and how I can get it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The route and why. 3) Risks: speed, RELs, self-modifying code, middleware. 4) The `SCOPE.md` draft. 5) Questions for me.

GOAL: Build `notes/functions.csv` for <GAMEID> from `dtk` output.
READ FIRST: `config/<GAMEID>/symbols.txt`, `config/<GAMEID>/splits.txt`, `dtk dol info` output in `notes/`.
FENCE: Edit only `notes/` files. Do not edit `config/` in this task.
CHECK: Run `python tools/check_map.py`. Done means every symbol is listed once with size and kind, and the size totals match each section.
BUDGET: Stop after 3 failed check runs.
IF BLOCKED: Stop. List the address ranges you could not explain.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Counts: game, SDK, JSystem, unknown. 4) What is left. 5) New parking-lot items.

GOAL: Fix <BUG> on route <ROUTE>.
READ FIRST: `PROGRESS.md`, `notes/findings.md`, `notes/dead-ends.md`, log `<LOG_PATH>`.
FENCE: Edit only `<RUNTIME_DIR>/` and `patches/`. Never edit `generated/` or `build/`. No game addresses in shared code.
CHECK: Run `tools/check.sh routes`. Done means <ROUTE> passes and all other route hashes are unchanged.
BUDGET: Stop after 3 failed fixes. Prove the cause before each one.
IF BLOCKED: Stop. Show the evidence and the next thing you need to see.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) Cause in one sentence. 5) New parking-lot items.

GOAL: Match <FUNCTION> in <UNIT> to 100% with clean C.
READ FIRST: `CLAUDE.md`, `notes/compiler-quirks.md`, `notes/attempts/<FUNCTION>.md` if it exists, similar matched functions: <LIST>.
FENCE: Edit only `src/<UNIT>.c` and `include/<UNIT>.h`. No inline asm. Do not touch `configure.py` or `config/`.
CHECK: Run `objdiff-cli diff -p . -u <UNIT> -o - <FUNCTION>`, then `ninja` and `ninja changes`. Done means 100%, the hash check passes and no other function lost score.
BUDGET: Stop after 5 real attempts.
IF BLOCKED: Stop. Log the best score and the differing instructions in `notes/attempts/<FUNCTION>.md`.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) Best score if not done. 5) New parking-lot items.

GOAL: Pick the next <N> open units and start one worker per unit, each in its own worktree.
READ FIRST: `notes/functions.csv` (status column), `build/<GAMEID>/report.json`, `notes/dead-ends.md`.
FENCE: Edit only `notes/functions.csv` (mark units as claimed). Workers edit only their own unit.
CHECK: After workers finish, run `ninja` and `ninja changes` on the merged branch. Done means every merge passes and the ledger matches the report.
BUDGET: Stop after one round of <N> units.
IF BLOCKED: Stop. List which merges failed and why.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the merged check output. 3) Units matched, partial, failed. 4) Units to send to a hard job. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> at <ROUTE>/<FRAME>. Do not fix it yet.
READ FIRST: `notes/findings.md`, log `<LOG_PATH>`, frame dump `<DUMP_PATH>`.
FENCE: You may add logging behind an environment switch in `<RUNTIME_DIR>/`. No fixes.
CHECK: Run the same route in Dolphin. Done means you state whether Dolphin shows the symptom, and name the guest function and address where behaviour first differs.
BUDGET: Stop after 90 minutes.
IF BLOCKED: Stop. List what you ruled out and what tool or trace you need.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Evidence: log lines, addresses, Dolphin result. 3) The cause in one sentence. 4) A proposed fix and its check. 5) New parking-lot items.

GOAL: Check that the last <N> commits did what they claim, and find any cheating.
READ FIRST: `git log -<N> --stat`, `CLAUDE.md`.
FENCE: Read only. Write findings to `notes/verify-<DATE>.md` only.
CHECK: From a clean clone, run `ninja` (Path B) or `tools/check.sh all` (Path A). Then search the diff for: `asm`, `#pragma`, changes to `build.sha1`, edits under `generated/` or `orig/`, new stubs, disabled tests, game addresses in shared code.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Say what you could not check.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) PASS or FAIL. 2) Proof: paste the check output. 3) Each problem with commit and file. 4) What you did not check. 5) New parking-lot items.

GOAL: Write a status report from the ledgers only.
READ FIRST: `PROGRESS.md`, `notes/functions.csv`, `build/<GAMEID>/report.json` or the last `tools/check.sh all` output.
FENCE: Edit only `PROGRESS.md`. Do not run new work.
CHECK: Run `ninja progress` (Path B), or read the last `tools/check.sh all` log (Path A). Done means every number in the report comes from that output or a file you name, and the totals match.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop. Say which ledger is missing or out of date.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) Matched and linked percent, or routes passing. 2) Change since last report. 3) Top three blockers. 4) Next three units. 5) Parking-lot items for me to decide.

GOAL: Write what the next session needs into the ledger files.
READ FIRST: This session's changes (`git diff --stat`), `PROGRESS.md`.
FENCE: Edit only `PROGRESS.md`, `notes/findings.md` and `notes/dead-ends.md`.
CHECK: Run `git status --short` and `git diff --stat`. Done means only the three ledger files changed, and `PROGRESS.md` lists the current unit, its last check output, and the next step.
BUDGET: Stop after 10 minutes.
IF BLOCKED: Stop. Say what state is only in the chat.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE or PARTIAL. 2) Files changed. 3) The next step in one sentence. 4) Dead ends added. 5) New parking-lot items.

GOAL: Tell me plainly whether <UNIT_OR_BUG> can be done with the current tools and rules.
READ FIRST: `notes/attempts/<UNIT>.md` or `notes/findings.md`, `CLAUDE.md`.
FENCE: Read only. No new attempts.
CHECK: Run the last check command from the attempts file once more and paste its output. Done means your answer names the exact blocker (instructions, missing tool, runtime gap or rule) and links each claim to a file or log line.
BUDGET: Stop after 20 minutes.
IF BLOCKED: Say 'I do not know yet' and what would answer it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) CAN, CANNOT, or UNKNOWN. 2) The blocker. 3) Two or three options with cost. 4) What you would need from me. 5) New parking-lot items.

GOAL: Ask me before you leave the fence for <TASK>.
READ FIRST: `SCOPE.md`, the task card you were given.
FENCE: Make no edits outside the original fence while you wait.
CHECK: Run `git status --short`. Done means it shows no edits outside the fence, and the request names the files you want to touch, why, the risk, and how you would check the change.
BUDGET: One short request. Then stop and wait.
IF BLOCKED: Stop. Do not work around the fence.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) BLOCKED. 2) Files and reason. 3) Risk. 4) The check you would run. 5) What happens 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 decomp or symbols.txt already exists. With one, Luigi's Mansion went from first public commit to release in nine days, after earlier work in another repo.
• How many .rel modules the game has, and whether it uses code that rewrites itself.
• Speed. Two of five DolRecomp games fell back to Dolphin's JIT, so plan profiling time.
• Middleware. CRI video, embedded Python or custom audio each need runtime work.
• For Path B, the size of the game and how much C++ it uses. The last few percent can take as long as the first half.

The facts behind these numbers

Projects reviewed (15)

The top-starred project for each of the top 12 games on RecompLauncher, plus three projects whose developers say they used AI.

What each project teaches

What we could not check

• Whether ModernGekko builds with MSVC today. The DolRecomp README says it does not, while the template README lists Visual Studio. This guide sends the reader to WSL for that route.
• When Star Fox Adventures reached 100% on decomp.dev. The page showed 100% decompiled and linked on 2026-11-13, but no date for reaching it.
• The date Animal Crossing's decomp reached 100%. A July 2026 article says it got there earlier, but gives no date.
• The date Twilight Princess reached a full GameCube match. The README states the match, but no date.
• The started month for Dusklight and Open Nectar is the month each repo was made. Their first commits come from the decomp they copied (2020-08 and 2021-09), and the real start of port work is not stated.
• That dtk disc extract writes the same sys/ and files/ folders as Dolphin's Extract Entire Disc. Its README does not show the layout.
• Whether the GameCube Loader zip built for Ghidra 12.1 installs on Ghidra 12.1.4, which GhidraMCP asks for.
• Whether dolphin-debugger-mcp works for games other than Star Fox Adventures. It reads DOLPHIN_GAMEID and a dtk config/ folder, but nobody here tested it.
• The Dolphin download page. dolphin-emu.org refused scripted requests (403) on 2026-11-13.
• Metroid Prime Port and Echoes Unbound: the repos return 404, so their method, tools and AI use are from the catalog only.
• How many hours a week any reviewed project took. No project states it, so all time ranges are estimates.
• The exact m2c target name ppc-mwcc-c. The README gives the platform-compiler-language pattern and lists ppc, mwcc and c; the full string was not run here.
• The --graphics Null value. The template README shows --headless and --graphics Vulkan; Null comes from F-ZERO GLINUX notes.
• No command, build or prompt in this guide was run by the fact-checker. Commands were checked against each tool's README and source only.
• Which AI tools wrote which parts of the projects that carry only a store flag.

Sources

• decomp-toolkit README
• dtk-template README and docs
• objdiff README
• nod and nodtool README
• Aurora README and building docs
• DolRecomp README
• ModernGekko-Template README
• ModernGekko README
• GXRuntime README
• gcn-recomp README
• m2c README
• decomp-permuter README
• Ghidra GameCube Loader
• dolphin-debugger-mcp README
• melee-harness README
• Melee decomp README
• Melee final PR #3409
• Wind Waker decomp README
• Twilight Princess decomp README
• Star Fox Adventures decomp on decomp.dev
• decomp.dev front page
• WiiBrew: DOL format
• WiiBrew: REL format
• GameCube technical specifications
• Android Authority: Pikmin decomp at 100%
• Jack Price-Burns: Star Fox Adventures decomp post
• Jack Price-Burns: Teaching a model to decompile
• Jack Price-Burns: Dolphin debugger MCP post
• Wind Waker decomp CONTRIBUTING (AI rule)
• Aurora building docs
• dtk-template getting started
• GhidraMCP README
• Melee PR #2076 (Claude Code match)
• Melee FAQ