Nintendo Switch 2 decomp guide

What this system is like

Switch 2 games run on a 64-bit ARM chip, like the first Switch. In the weeks around November 2026, people built native PC versions of nine Switch 2 games. Nearly all of them used static recompilation. A tool turns the game's machine code into C, and you write a stand-in for the console around it.

Most projects did not start from zero. They copied a Switch 1 recomp, such as TotK Recomp, and added the Switch 2 parts. Only three wrote their own lifter: Space Animals Recomp, Kart Recomp and TOoT:R. Later projects copied a Switch 2 recomp, such as DKB Recomp. One fork reached the title screen on its first day.

The new hard part is graphics. Switch 2 games use NVN 2, a new version of Nintendo's private graphics API. Their shaders are machine code for an NVIDIA Ampere chip. Many projects first convert them to the older Switch 1 shader code, then to Vulkan. Shaders that fail to convert are the most common blocker.

A full decomp is far off. We found one attempt, for Fire Emblem: Fortune's Weave. It checks behavior in an emulator and matches no bytes yet. Nobody has byte-matched any Switch 2 code. To match bytes you need the compiler version Nintendo used, and no project has named it yet.

Two paths

Path A: Get it running on PC

You fork a working Switch 2 recomp and point it at your game. A Python lifter turns each ARM function into C or C++. A runtime stands in for Horizon OS and answers the NVN 2 calls with Vulkan. Shaders are lowered from Ampere to Maxwell and then turned into SPIR-V. You then fix one crash or glitch at a time.

1. Pick the game, the version and a base

   You choose one exact game version and one recomp to fork. You note the hashes that prove the version. You look for a sibling project on the same engine. You write it all in SCOPE.md.

   • Dump your own game and update. Keep the .nup file outside the repo, for example in D:/dumps/<game>.
   • Write down the title ID and the update version. TOoT:R supports only update v131072. Most reviewed projects refuse any version they were not built for. Kart Recomp and MKW Recomp take two versions, 1.0.0 and 1.8.0.
   • Get the SHA-256 of exefs/main once it is extracted, with Get-FileHash. ocarina-recomp checks this hash before it builds.
   • Search RecompLauncher and GitHub for a recomp of a sibling game. Compare the engine, such as Unreal Engine 5 in Yoshi.
   • Choose a base family. DKB Recomp uses MSYS2 Clang, uv and Ninja. nxrecomp uses clang-cl, CMake and Ninja. Check each licence. DKB Recomp is GPL-3.0-or-later, nxrecomp is GPL-3.0 and TotK Recomp is MIT. NX2navi keeps its own changes all rights reserved, so you may read it but not copy it.
   • Write SCOPE.md: goal, version, hashes, base, first milestone and its check, what is out of scope, and files Claude must never edit.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a static recomp of <GAME> update <VERSION> on Switch 2, and recommend one base project to fork.
   READ FIRST: The README and AGENTS.md of <BASE_A> and <BASE_B>, the hash list I give you in <HASH_FILE>, and `notes/prior-work.md` if it exists.
   FENCE: Write only `SCOPE.md` and `notes/scope-research.md`. Do not clone, build or change anything else. Never copy any game file into the repo.
   CHECK: Run `(Get-FileHash <DUMP_DIR>\exefs\main -Algorithm SHA256).Hash`. Done means it equals the hash in `SCOPE.md`, and `SCOPE.md` also names the title ID, the update version, the chosen base with its licence, and the first milestone with its check. Each number shows the command or file it came from.
   BUDGET: Stop after 45 minutes or 3 failed tries to read a file.
   IF BLOCKED: Stop. Do not guess a value. Tell me which fact you could not get and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not act on them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The numbers with their sources. 3) Files written. 4) Open questions for me. 5) New parking-lot items.

   Done whenGet-FileHash on exefs\main gives the same SHA-256 that SCOPE.md lists. SCOPE.md also names the title ID, version, base, licence and first milestone, and you approved it.

   Proof this works: ocarina-recomp (hash gate on exefs main), TOoT:R (only update v131072 accepted), yoshi4pc and HWAoI (forks of DKB Recomp), Kart Recomp and MKW Recomp (versions 1.0.0 and 1.8.0), https://github.com/drakolordx7/nxrecomp, NX2navi README, License section

2. Fork the base and set up the tools

   You fork the base and install its tools on Windows. You add the content guard so no game file is ever committed. You write CLAUDE.md and the progress files.

   • Install MSYS2 to C:\msys64. In the UCRT64 shell run pacman -Syuu twice. The first pass updates the core and exits.
   • Then run pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-{clang,lld,ninja,gcc,make,pkgconf,sdl3,opus,libvpx,zstd,vulkan-devel,vulkan-memory-allocator,vulkan-validation-layers,shaderc,spirv-tools} base-devel git unzip. This is the list in DKB's docs/building.md.
   • Install Visual Studio Build Tools with the C++ workload: winget id Microsoft.VisualStudio.BuildTools, with --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended. The shader translator's build calls its linker.
   • Add C:\Program Files (x86)\Microsoft Visual Studio\Installer to your PATH. The translator build needs vswhere.exe from there.
   • Install the .NET 10 SDK with winget install Microsoft.DotNet.SDK.10. The shader translator needs it.
   • Install Git for Windows with winget install Git.Git, as ocarina-recomp does, so git works in PowerShell.
   • Make the Python venvs: uv venv --python 3.12 .venv, then uv pip install --python .venv/Scripts/python.exe -r tools/requirements.txt. Do the same with --python 3.14, .venv-py314 and tools/requirements-py314.txt. The extract scripts need Python 3.14.
   • Run git config core.hooksPath .githooks so the content guard runs before each commit.
   • Put your dump and key paths in config.local.toml, which git ignores.
   • Build the shader translator: .venv/Scripts/python tools/build_xlate.py.
   • Copy the base's AGENTS.md. Add one line to CLAUDE.md: @AGENTS.md. Create notes/PROGRESS.md and notes/parking-lot.md.
   Prompt for ClaudeCopy

   GOAL: Make the forked repo build its tools and pass the content guard on this PC.
   READ FIRST: `SCOPE.md`, `AGENTS.md`, `docs/building.md`, and the README section on building.
   FENCE: Edit only `config.local.toml`, `notes/`, `CLAUDE.md` and setup scripts under `tools/setup/`. Do not change `recomp/`, `runtime/` or `.github/`. Do not run the game.
   CHECK: `python tools/check_content.py` exits 0. `.venv/Scripts/python tools/build_xlate.py` ends with `build/xlate/totk_xlate.exe` present. On a DKB-line base, `.venv/Scripts/python tools/test.py --tier 0-1` shows no FAIL. Paste all outputs.
   BUDGET: Stop after 3 failed installs of the same tool, or 60 minutes.
   IF BLOCKED: Stop. Do not install a different tool version than `docs/building.md` names. Tell me what failed and the exact error.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/check_content.py exits 0, build/xlate/totk_xlate.exe exists, and tools/test.py --tier 0-1 shows no FAIL.

   Proof this works: DKB Recomp docs/building.md (toolchain table, pacman line, PATH notes, test tiers), ocarina-recomp (winget and pacman lists), yoshi4pc (two uv venvs, core.hooksPath), NX2navi (config.local.toml, build_xlate.py), DKB Recomp (check_content.py in CI)

3. Survey the dump before you lift

   You extract the code and learn its shape first. You count modules, imports, NVN 2 calls and shaders. You find what the base does not support yet. This saves days of blind fixes later.

   • Extract the newest update from your .nup: .venv-py314/Scripts/python tools/extract_nup.py <game.nup> --select latest --pack --out build/extracted/<ver>.
   • If main is ZBIC-packed, unpack it. ocarina-recomp uses kinnay's zbic code for this.
   • Run a scan of imports, relocations, NVN 2 procs and SM86 shader opcodes. MTF ShadowRacket has tools/universal_ns2_to_pc.py scan --exefs <exefs> --romfs <romfs>.
   • Write the expected-hash file: .venv/Scripts/python tools/dkb_expected.py --exefs <exefs> --name <ver> --display <VERSION>.
   • Count the shader stages in the RomFS. DKB Recomp runs .venv/Scripts/python tools/dkb_shader_census.py --version <ver> --out build/<ver>. For its game that found about 18,800 stages.
   • Optional: open the module in Ghidra with the Switch loader to read code by address.
   • Save the results in notes/survey.md: modules with sizes, missing imports, new NVN 2 calls and the shader count.
   Prompt for ClaudeCopy

   GOAL: Write `notes/survey.md` with the facts about <GAME> <VERSION> that the base does not cover yet.
   READ FIRST: `SCOPE.md`, `notes/PROGRESS.md`, the scan output in `build/scan/`, and `docs/architecture.md`.
   FENCE: Write only `notes/survey.md` and `tools/data/expected-<VER>.json`. Do not edit `recomp/` or `runtime/`. Never print key values.
   CHECK: `notes/survey.md` lists every module with its size and build ID, the imports the runtime lacks, the NVN 2 procs the runtime lacks, and the count of shader stages. Each list names the command that made it. Re-run each named command. Done means every count matches.
   BUDGET: Stop after 60 minutes or 3 failed tool runs.
   IF BLOCKED: Stop. Tell me which tool failed and the exact error.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The counts. 3) Files written. 4) The three biggest gaps you see. 5) New parking-lot items.

   Done whennotes/survey.md lists modules, missing imports, missing NVN 2 calls and a shader count, each with the command that made it.

   Proof this works: MTF ShadowRacket (scan before init and build), yoshi4pc (extract_nup.py, expected hash manifest), DKB Recomp (dkb_expected.py), DKB Recomp docs/dkb-testing.md (dkb_shader_census.py), https://switchbrew.org/wiki/NSO

4. Lift and link the whole game

   You run the lifter over every module and build the program. Nothing has to run yet. You only need a clean link and passing lifter tests. New instruction kinds get their own tests now.

   • Lift: .venv/Scripts/python recomp/gen.py --exefs <exefs> --out generated/<ver> --modules main,sdk --patches recomp/patches-<ver>.txt. That is DKB's line. If your game has subsdk0, add it to --modules, as ocarina-recomp does.
   • Build: .venv/Scripts/python tools/build_game.py --version <ver> --expected tools/data/expected-<ver>.json --exefs <exefs> --romfs build/extracted/<ver>/romfs.
   • Run the lifter's differential tests against Unicorn. On the DKB line they are tests/diff/simd.py, tests/diff/atomic.py, tests/diff/lift.py, tests/diff/func.py and tests/jumptables_check.py. Run each with .venv/Scripts/python. The last must report 0 disagreements.
   • For each new instruction kind, add a test first. yoshi4pc added tests/yoshi_udot_check.py with 400 cases for UDOT.
   • Put game-only fixes in the patch file, never in generated/. ocarina-recomp uses recomp/patches.py and tools/oot/patch_generated.py.
   Prompt for ClaudeCopy

   GOAL: Lift all modules of <GAME> <VERSION> and link the exe with no errors.
   READ FIRST: `SCOPE.md`, `notes/survey.md`, `AGENTS.md`, and `recomp/README.md` if it exists.
   FENCE: Edit only `recomp/`, `tests/` and `recomp/patches-<VER>.txt`. Never edit `generated/` by hand. Do not touch `runtime/` in this task.
   CHECK: `tools/build_game.py --version <VER>` ends with the exe linked. Then run the Unicorn tests: on the DKB line `tests/diff/simd.py`, `tests/diff/atomic.py`, `tests/diff/lift.py`, `tests/diff/func.py` and `tests/jumptables_check.py`. Done means each passes and the last reports 0 disagreements. Paste the last 20 lines of each.
   BUDGET: Stop after 5 failed builds or 90 minutes.
   IF BLOCKED: Stop. Do not stub out an instruction to get a link. Tell me the instruction, the address and the error.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) New instruction kinds and their tests. 5) New parking-lot items.

   Done whenThe exe links, and the Unicorn lifter tests report 0 mismatches.

   Proof this works: DKB Recomp (gen.py and build_game.py commands in the README; Unicorn test list in docs/building.md), ocarina-recomp (--modules main,sdk,subsdk0), yoshi4pc (UDOT differential check), NX2navi (tests/diff, jumptables_check.py), Space Animals Recomp (Unicorn bench for every module)

5. Boot to the first frame

   You run the game with no person at the controls. You fix the first crashes in order. You stop when a scripted run shows the first real picture. Count shader failures now, before you chase gameplay.

   • Run with input turned off so your keyboard does not move the game. ocarina-recomp uses TOTK_INPUT=none.
   • Start each run from an empty save folder. On the DKB line, set TOTK_PROFILE_DIR=<scratch folder>.
   • Save a picture with no person at the keys. On the DKB line, TOTK_DUMP=<frame> writes that frame's render targets as PNG files to dump\. Never publish them.
   • The DKB line has no single scripted-run command. Write tools/scripted_run.ps1 that sets these variables, starts the exe, waits, and copies the PNG and the last log lines. Kart Recomp's HOST_INPUT_SCRIPT and HOST_RENDER_HIDDEN show the same idea.
   • Read the log next to the exe. Fix the first crash only, then run again.
   • Check the NVN 2 API version the runtime reports. Ink Raiders crashed because it reported 30 and the game wanted 39 or higher. DKB Recomp has tests/nvn_version_test.py for this.
   • Count shader stages that fail to lower. yoshi4pc's tools/dkb_lower_test.cpp found 86 of 378 failing.
   • Save a screenshot from the scripted run in notes/boot-log.md, with the commit hash.
   Prompt for ClaudeCopy

   GOAL: Make <GAME> boot to <FIRST_SCREEN> in a scripted run with no input.
   READ FIRST: `notes/PROGRESS.md`, `notes/boot-log.md`, the last run's log at <LOG_PATH>, and `docs/maxwell.md`.
   FENCE: Edit only `runtime/` and `recomp/patches-<VER>.txt`. Never edit `generated/`. Do not hide a draw or skip a shader to make a picture.
   CHECK: Run `<SCRIPTED_RUN_COMMAND>` (for example `tools/scripted_run.ps1`) with `TOTK_INPUT=none` and a fresh `TOTK_PROFILE_DIR`. Done means the saved frame shows <FIRST_SCREEN> and the log has no fatal line. Paste the screenshot path and the last 20 log lines.
   BUDGET: Stop after 5 runs with no new progress, or 2 hours.
   IF BLOCKED: Stop. Tell me the faulting address, the last log lines and what you ruled out.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: screenshot path and log lines. 3) Files changed. 4) The crash list in order. 5) New parking-lot items.

   Done whenA scripted run with no input saves a screenshot of the first real screen, and the log has no fatal line.

   Proof this works: ocarina-recomp (TOTK_INPUT=none), Project: Ink Raiders (NVN2 minor version 30 versus 39), yoshi4pc (title screen on day 1, shader census), Kart Recomp (HOST_INPUT_SCRIPT and HOST_RENDER_HIDDEN runs), DKB Recomp docs/dkb-testing.md (TOTK_PROFILE_DIR, TOTK_DUMP)

6. Fix one crash or glitch at a time

   This is the long grind. Each unit is one crash, one missing call or one wrong picture. Prove the cause before the fix. Compare with a Switch 2 emulator that runs the game.

   • Capture a whole frame, then bisect by a stable shader hash. Program numbers change every launch, as MKW-THWOMP found.
   • Compare draws with a reference emulator. ocarina-recomp compared against Lichii's draw trace. DKB Recomp reads Eglantine first.
   • Fix shader bugs in the translator, not in the game. MKW-THWOMP traced phantom plants to badly translated culling shaders.
   • Re-run the Unicorn tests after any lifter change.
   • Write each dead end in notes/PROGRESS.md, like MKW-THWOMP's 'Do not repeat these' table.
   Prompt for ClaudeCopy

   GOAL: Find and fix the cause of <BUG> seen at <PLACE_IN_GAME>.
   READ FIRST: `notes/PROGRESS.md` (dead ends), the capture at <CAPTURE_PATH>, `docs/maxwell.md`, and the matching code in the reference emulator under `refs/`.
   FENCE: Edit only <FILES_FOR_THIS_BUG>. `refs/` and `generated/` are read-only. Do not skip draws, drop resolution or turn off effects to hide the bug.
   CHECK: Run `<SCRIPTED_RUN_COMMAND>` to <PLACE_IN_GAME>. Done means the screenshot shows the fix and `<LIFTER_TEST_COMMAND>` still passes. Paste both.
   BUDGET: Stop after 3 failed fixes or 2 hours. Prove the cause before each fix.
   IF BLOCKED: Stop. Tell me the evidence you have, the causes you ruled out, 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: the cause with addresses, and screenshot paths. 3) Files changed. 4) Dead ends to record. 5) New parking-lot items.

   Done whenThe scripted run shows the fix, the lifter tests pass, and the cause is written in notes/PROGRESS.md.

   Proof this works: MKW-THWOMP (frame capture, bisect by shader hash, dead-end table), ocarina-recomp (Lichii draw trace), DKB Recomp (Eglantine as the reference), MKW Recomp (capture once, replay against the game's image)

7. Build a regression set

   Old fixes must stay fixed. You save scripted runs, captures and tests that run without you. A fresh session can then check any change in minutes.

   • Record a frame capture once and replay it after each graphics change. MKW Recomp uses MKW_CAPTURE=1 and tools/test/replay.sh.
   • Keep three to five scripted runs that reach known places. Kart Recomp uses HOST_INPUT_SCRIPT with a hidden window.
   • Run Vulkan validation layers on each run and count the errors. DKB Recomp and HWAoI Recomp do validation-layer runs. Kart Recomp turns them on with HOST_VK_VALIDATION.
   • Make one test command. DKB Recomp has tools/test.py, which runs every check in tests/manifest.toml and writes build/test/runner/report.json.
   • Measure speed inside one run by switching settings back and forth. MKW Recomp found separate runs differ by up to 12 ms per frame.
   Prompt for ClaudeCopy

   GOAL: Build `tools/regress` that runs <N> scripted runs, the frame replays and the lifter tests, and prints one PASS or FAIL line each.
   READ FIRST: `notes/PROGRESS.md`, `notes/boot-log.md`, and the input scripts in <SCRIPTS_DIR>.
   FENCE: Edit only `tools/regress*`, `tests/` and <SCRIPTS_DIR>. Do not change `runtime/` or `recomp/`. Do not lower any threshold to make a run pass.
   CHECK: `tools/regress` on a clean checkout prints PASS for every item. Then break one known fix on a scratch branch and confirm the matching item prints FAIL.
   BUDGET: Stop after 2 hours or 3 failed tries to make one item stable.
   IF BLOCKED: Stop. Tell me which item is flaky and what you saw.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) Items still flaky. 5) New parking-lot items.

   Done whentools/regress prints PASS on a clean checkout and FAIL when a known fix is reverted.

   Proof this works: MKW Recomp (capture replay, in-run A/B timing), Kart Recomp (scripted hidden-window races), DKB Recomp (tools/test.py, validation layers), HWAoI Recomp (validation-layer runs), GreenKid-MV (scripts/regress.py check --games in its agent rules)

8. Package it without game code

   Players build the game from their own dump. You ship only your code and a launcher. The launcher checks the version by hash and gives a clear message if it is wrong.

   • Check the dump against your hash table before any work. Recompia checks exefs hashes against dump_hashes.json.
   • Let the launcher run the lift, compile and shader steps on the player's PC. NX2navi's setup takes 20 to 45 minutes once.
   • Cache compiled units so an update rebuilds only what changed. Recompia's rebuild_impact.py counts the units a change touches.
   • Run python tools/check_content.py --staged before every commit, and the same check in CI.
   • List every borrowed file and its licence in THIRD_PARTY_NOTICES.md.
   Prompt for ClaudeCopy

   GOAL: Make a release zip that builds <GAME> from the player's own dump and contains no game data.
   READ FIRST: `SCOPE.md`, `tools/data/expected-<VER>.json`, `THIRD_PARTY_NOTICES.md`, and the base's installer docs.
   FENCE: Edit only `launcher/`, `installer/` and `tools/make_release*`. Do not add any file made from the game. Do not change `.github/` without asking me.
   CHECK: `python tools/check_content.py` passes on the repo. A file list of the zip shows nothing from `build/`, `generated/`, `dump/` or your game folder. A test install with a wrong-version dump stops with a clear message. A test install with the right dump reaches <FIRST_SCREEN>.
   BUDGET: Stop after 3 hours or 3 failed test installs.
   IF BLOCKED: Stop. Tell me what failed and the exact message.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output and both install results. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe content check passes, the zip holds no game-derived file, a wrong dump is refused, and a right dump builds and boots.

   Proof this works: Recompia (dump_hashes.json, rebuild_impact.py), NX2navi (launcher builds on the player's PC), Space Animals Recomp (checks the .nup by index hashes), GreenKid-MV (refuses game folders inside a git repo)

Path B: Full decomp for porting

You rewrite the game as readable C and C++, one function at a time. You cannot check bytes yet, because nobody knows which compiler version to use. So each rebuilt function runs next to the original in an emulator with the same inputs. Credit goes only to code that behaved the same. Library code comes from the exact upstream sources the game links.

1. Check prior work and set the proof rule

   You check whether anyone has started your game. You accept that nobody can byte-match Switch 2 code yet. You write down exactly what earns credit. This rule is the heart of the project.

   • Search GitHub for your game name plus decomp. The only Switch 2 decomp we found is vexcited/fefw.
   • Read how fefw gives credit: only original instructions that the side-by-side runs used, with identical results.
   • Write the credit rule in SCOPE.md: which states are compared (registers, memory), how many random inputs, and what counts as used.
   • List the libraries the game links. fefw keeps PhysX 5.6.0, musl 1.1.19, Opus 1.3.1 and others as upstream sources.
   • Name what is out of scope, such as byte matching and shaders.
   Prompt for ClaudeCopy

   GOAL: Draft `SCOPE.md` for a non-matching, behavior-verified decomp of <GAME> <VERSION>.
   READ FIRST: The fefw README at https://github.com/vexcited/fefw, `notes/survey.md` from Path A, and the string list in <STRINGS_FILE>.
   FENCE: Write only `SCOPE.md` and `notes/scope-research.md`. Do not create code. Never copy game files into the repo.
   CHECK: `SCOPE.md` states the credit rule in testable terms, lists each linked library with a version and the string or symbol that proves it, and names the first milestone with its check.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Do not guess a library version. Tell me which ones you could not prove.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The library list with proofs. 3) Files written. 4) Open questions for me. 5) New parking-lot items.

   Done whenSCOPE.md has a testable credit rule and a proven library list, and you approved it.

   Proof this works: fefw (behavior-verified credit, vendored libraries), https://github.com/vexcited/fefw

2. Set up the repo and the AArch64 build in WSL

   You lay out the repo like fefw. You install a Clang that can build AArch64 code. You add the progress report so numbers come from a script, not from Claude.

   • In WSL (Ubuntu 24.04) run sudo apt install clang lld ninja-build python3-venv. Ubuntu 24.04 ships Clang 18.
   • Make the folders: src/game, src/<library>, include/, data/ledger/ and tools/.
   • Compile for the console's CPU with clang -target aarch64-unknown-linux-gnu -c <file>.c. Pick one target and keep it.
   • Set up the harness venv: python3 -m venv .venv, then .venv/bin/pip install unicorn capstone.
   • Download objdiff-cli-linux-x86_64 from objdiff release v3.8.3. Run sha256sum on it and compare with the digest GitHub lists for that file. Pin the hash in CI, as fefw's progress.yml does for v3.8.2.
   Prompt for ClaudeCopy

   GOAL: Create the decomp repo layout, the AArch64 build and an empty progress report that runs.
   READ FIRST: `SCOPE.md`, and fefw's `.github/workflows/progress.yml` and `tools/objdiff_report.py`.
   FENCE: Edit only the new repo's `tools/`, `data/`, `CLAUDE.md` and build files. Keep all game files outside the repo. Do not write any game function yet.
   CHECK: `ninja` builds an empty object for AArch64 with no errors, and `python3 tools/report.py` prints 0.0% with the module sizes from `data/baseline.json`. Paste both.
   BUDGET: Stop after 90 minutes or 3 failed installs.
   IF BLOCKED: Stop. Tell me what failed and the exact error.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files created. 4) What is left. 5) New parking-lot items.

   Done whenThe empty AArch64 build passes and the report script prints 0.0% with correct module sizes.

   Proof this works: fefw (layout, progress.yml, sha256-pinned objdiff-cli), https://github.com/encounter/objdiff/releases/tag/v3.8.3, https://clang.llvm.org/docs/CrossCompilation.html, https://packages.ubuntu.com/noble/clang

3. Build the function ledger

   You list every function with its address and size. You mark library and SDK code so nobody writes it by hand. The ledger is the single source of progress.

   • Load each module in Ghidra with the Switch loader, or as an ELF made by a tool like Kart Recomp's tools/nso.py.
   • Export one CSV per module: address,size,status,source,name. fefw keeps data/ledger/main.csv, rtld.csv, sdk.csv and subsdk0.csv to subsdk2.csv.
   • Write data/baseline.json with each module's text size and function count. fefw's main is 27,316,080 bytes and 89,170 functions.
   • Mark functions that belong to a known library. Match them by strings and symbols, not by guess.
   • Make the report refuse more credit than a module has. fefw's tools/ledger.py raises an error if it does. It also rejects unknown status values, duplicate rows, rows not 4-byte aligned, and rows with no name or source.
   • fefw's ledger.py is a library with a validate() function and no command line. Give yours a validate command, so python3 tools/ledger.py validate works as a check.
   Prompt for ClaudeCopy

   GOAL: Produce `data/ledger/<MODULE>.csv` and `data/baseline.json` for <GAME> from the Ghidra export at <EXPORT_PATH>.
   READ FIRST: `SCOPE.md`, the export, and fefw's `tools/ledger.py` for the column rules.
   FENCE: Write only `data/` and `tools/ledger.py`. Do not edit `src/`. Do not copy disassembly into the repo.
   CHECK: `python3 tools/ledger.py validate` passes. Every address is 4-byte aligned. The size sum per module is at most the text size. Paste the output.
   BUDGET: Stop after 2 hours or 3 failed exports.
   IF BLOCKED: Stop. Tell me which module or range failed and why.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: validate output. 3) Counts per module and per library. 4) Ranges you are unsure of. 5) New parking-lot items.

   Done whentools/ledger.py validate passes and every function has a module, address, size and status.

   Proof this works: fefw (data/ledger CSVs, baseline.json, ledger.py checks), https://github.com/vexcited/fefw/blob/main/tools/ledger.py, NX2navi (Ghidra 12.1.2 with Ghidra-Switch-Loader), Kart Recomp (nso.py writes an ELF for Ghidra)

4. Prove the harness on one small function

   You rebuild one tiny function and test it next to the original. Then you break it on purpose. The harness must catch the break, or it is not a check.

   • Write the harness: load the original module and your object in Unicorn, set the same random registers and memory, run both, compare.
   • Pick a short leaf function with no calls. Kart Recomp tested 2,481 integer leaf functions this way.
   • Run 1,000 random cases or more. Log which original instructions ran.
   • Change one operator in your C and confirm the harness fails. Space Animals Recomp mutated its output on purpose to prove its bench.
   • Watch for Unicorn bugs. Unicorn 2.1.4 compares some 8, 16 and 32-bit ldsmax and ldsmin results as unsigned.
   Prompt for ClaudeCopy

   GOAL: Rebuild function <NAME> at <ADDRESS> in C and prove the harness passes it and fails a broken copy.
   READ FIRST: `SCOPE.md` (credit rule), `data/ledger/<MODULE>.csv`, and the Ghidra output for <ADDRESS> in <EXPORT_DIR>.
   FENCE: Edit only `src/game/<FILE>.c`, `tools/harness/` and `data/ledger/<MODULE>.csv`. No inline assembly. Do not edit `data/baseline.json`.
   CHECK: `tools/harness/run <NAME> --cases 1000` prints PASS. A copy with one operator changed prints FAIL. Paste both.
   BUDGET: Stop after 5 failed tries.
   IF BLOCKED: Stop. Tell me what differs: the register or address, and one failing input.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) Instructions covered by the runs. 5) New parking-lot items.

   Done whenThe harness passes the rebuilt function on 1,000 cases and fails the broken copy.

   Proof this works: Space Animals Recomp (Unicorn bench, mutation test, ldsmax note), Kart Recomp (leaf functions identical on every case), fefw (credit only for exercised instructions)

5. Put library code in first

   Much of the binary is open-source libraries. You add their exact upstream sources, unchanged. Then you test those functions with the harness. This gives cheap, honest progress.

   • Add each library at the proven version under src/<library>, unchanged. fefw keeps musl 1.1.19 and libc++ 18.1.8 this way.
   • If a change is needed to match the shipped build, write it in src/<library>/MODIFIED.md.
   • Map each library function to its ledger row by symbol or string.
   • Run the harness on all library rows and credit only what passes.
   Prompt for ClaudeCopy

   GOAL: Add <LIBRARY> <VERSION> under `src/<LIBRARY>` and credit the ledger rows that pass the harness.
   READ FIRST: `SCOPE.md` (library list and proofs), `data/ledger/<MODULE>.csv`, and the upstream release at <UPSTREAM_URL>.
   FENCE: Edit only `src/<LIBRARY>/` and the matching ledger rows. Keep upstream files byte-identical. Any change goes in `MODIFIED.md` with a reason.
   CHECK: `tools/harness/run --library <LIBRARY>` prints PASS or FAIL per function. Only PASS rows change status. `python3 tools/ledger.py validate` passes.
   BUDGET: Stop after 3 hours or when 20 functions in a row fail.
   IF BLOCKED: Stop. A run of failures may mean a wrong version. Tell me the evidence.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Pass and fail counts. 3) Files changed. 4) Suspect version issues. 5) New parking-lot items.

   Done whenThe library is in src/ unchanged or with MODIFIED.md, and only harness-passing rows are credited.

   Proof this works: fefw (15 vendored libraries, MODIFIED.md rule)

6. Grind game functions in parallel

   Workers take one source file each, in their own worktree. Each function must pass the harness before it is credited. Hard ones go to a queue with notes.

   • Give each worker one file and its ledger rows. One writer per file.
   • Start with small leaf functions, then their callers.
   • Commit each passing function with its harness output in the message.
   • Mark doubtful rows disputed, as fefw does, instead of deleting them.
   • Send functions that fail five tries to notes/hard-queue.md with the failing input.
   Prompt for ClaudeCopy

   GOAL: Rebuild the functions listed for `src/game/<FILE>.c` until each passes the harness or is queued as hard.
   READ FIRST: `CLAUDE.md`, the ledger rows for <FILE>, the Ghidra output in <EXPORT_DIR>, and three passing functions from nearby files.
   FENCE: Edit only `src/game/<FILE>.c`, its header in `include/game/`, and its ledger rows. No inline assembly. Work only in this worktree; use absolute paths for the dump.
   CHECK: `tools/harness/run --file <FILE>` prints PASS for each credited function. `python3 tools/ledger.py validate` passes.
   BUDGET: 5 tries per function. Stop the file after 3 hours.
   IF BLOCKED: Move the function to `notes/hard-queue.md` with one failing input. Do not weaken the harness.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Table: function, result, proof line. 3) Files changed. 4) Hard-queue items. 5) New parking-lot items.

   Done whenEvery function in the file passes the harness or sits in the hard queue, and the ledger validates.

   Proof this works: fefw (disputed status, per-function ledger), https://github.com/vexcited/fefw

7. Verify the numbers from outside

   A score Claude reports is a claim. A fresh session re-runs the harness and reads the diffs. It hunts for cheats: weak tests, edited baselines and copied bytes.

   • Run the progress report in CI from the ledger, as fefw's progress.yml does.
   • Have a fresh session re-run the harness on a random 5% of credited rows.
   • Check that data/baseline.json and the harness did not change in worker branches.
   • Search for inline assembly and embedded byte arrays in src/game/.
   Prompt for ClaudeCopy

   GOAL: Audit the last <N> credited functions and report any that do not truly pass.
   READ FIRST: `SCOPE.md` (credit rule), `git log` since <COMMIT>, and the ledger diff.
   FENCE: Read-only. Write only `notes/audit-<DATE>.md`. Do not fix anything.
   CHECK: Re-run `tools/harness/run` on each audited function. Done means a table of function, claimed result, re-run result, and any cheat found.
   BUDGET: Stop after 2 hours.
   IF BLOCKED: Stop. Tell me what you could not re-run.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The table. 3) Files written. 4) Rows that should be `disputed`. 5) New parking-lot items.

   Done whenThe audit table shows every re-run result, and failed rows are marked disputed.

   Proof this works: fefw (CI progress report, disputed rows), ai-decomp-practice research, section C3 (cheats seen)

8. Port: swap decompiled code into the recomp

   A decomp becomes a port by running it. The realistic route is your Path A build. Replace lifted functions with decompiled ones by name, a few at a time. The game must still pass the regression runs.

   • Use the runtime's replace-by-name hook. MKW Recomp replaces Nintendo SDK functions by name. ocarina-recomp keeps overrides in runtime/ov_*.c.
   • Swap in one source file at a time.
   • Run tools/regress from Path A after each swap.
   • When most game code is swapped, build for a new system. Fix 64-bit pointer and Windows long issues. Windows long is 32 bits.
   Prompt for ClaudeCopy

   GOAL: Replace the lifted versions of the functions in `src/game/<FILE>.c` with the decompiled ones in the Path A build.
   READ FIRST: `notes/PROGRESS.md`, the runtime's override docs, and `tools/regress` output from the last good run.
   FENCE: Edit only the override list and the build files that add <FILE>. Never edit `generated/`. Do not change decompiled code to pass; report instead.
   CHECK: `tools/regress` prints PASS for every item with the swap in place. Paste it.
   BUDGET: Stop after 3 failed regress runs.
   IF BLOCKED: Stop. Tell me which item failed and which function you suspect, with evidence.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: regress output. 3) Files changed. 4) Functions that broke the game. 5) New parking-lot items.

   Done whentools/regress passes with the file's decompiled functions in place of the lifted ones.

   Proof this works: MKW Recomp (SDK functions replaced by name), ocarina-recomp (runtime/ov_*.c overrides, Windows long is 32 bits)

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 units are one crash, one missing NVN 2 call, one shader group or one wrong picture. Each has a scripted run with a screenshot or log line as its check. Lifter changes are their own units and must pass the Unicorn tests. Path B units are one function, or one source file per worker. Keep notes in files so the next session can read them.

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 `notes/PROGRESS.md` before any work. Only the owner changes `SCOPE.md`.
- Generated C is never edited by hand. Change the generator in `recomp/` or the patch file, then regenerate.
- Every lifter change passes the Unicorn differential tests: `<LIFTER_TEST_COMMAND>` must report 0 mismatches. On the DKB line that means `tests/diff/*.py` and `tests/jumptables_check.py`.
- Pass the keys file path to tools. Never print, log or copy key values.
- Game files, extracted data, shaders and generated code stay in `build/` and `generated/`. Run `python tools/check_content.py --staged` before proposing a commit.
- `refs/` and `tools/vendor/` are read-only. Cite upstream code by project, file and function, not line number.
- Do not hide a bug to clean a screenshot: no skipped draws, lower resolution or disabled effects.
- A fix counts only when seen in a scripted run: paste the screenshot path or log line. A clean build is not proof.
- Before you say a fix failed, compare the exe's modified time with the log's time.
- Ask before any long headless run or batch of screenshots. Never close a game the user is playing.
- Do not change `.github/` checks or tests to make them pass. Fix the code instead.
- In a worktree, use absolute paths for the dump, `build/` and `generated/`.
- Record dead ends in `notes/PROGRESS.md`: what was tried and why it failed.
- Report generation, compile, link, boot and play as separate milestones. Claim only the ones you saw.
- Path B: no inline assembly or byte arrays. Credit a function only after `tools/harness/run` prints PASS.

Keep the context small

• Never paste whole logs. Ask Claude to find the crash line and the 30 lines before it.
• Point Claude at file and function names, not line numbers. Code in refs/ moves, as DKB's agent rules warn.
• Keep AGENTS.md short and load it from CLAUDE.md with one @AGENTS.md line, as DKB and NX2navi do.
• Send Ghidra reading and shader dumps to a subagent and ask for a short report with addresses.
• Start each unit with /clear. The notes files carry state, not the chat.
• Forked docs often describe the parent game. Tell Claude which docs are current, or delete the stale ones.

More prompts for this system

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

GOAL: Tell me if <GAME> <VERSION> on Switch 2 can reach a first frame with a static recomp, and which base to fork.
READ FIRST: The RecompLauncher entries and GitHub repos I list in <LINKS_FILE>, and the READMEs of DKB Recomp and nxrecomp.
FENCE: Read only. Write only `notes/feasibility.md`. Do not clone or build anything.
CHECK: The note names any sibling project on the same engine, the base you pick, its licence, and the three biggest risks. Each claim has a link. Run `curl -sIL -o /dev/null -w "%{http_code}" <LINK>` on every link. Done means each prints 200.
BUDGET: Stop after 45 minutes.
IF BLOCKED: Stop. Say plainly if this game is not a good first target and why.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Yes, no or not yet, with reasons. 3) Files written. 4) What you need from me. 5) New parking-lot items.

GOAL: List the imports, NVN 2 procs and shader opcodes in <GAME> that the runtime does not handle yet.
READ FIRST: `notes/survey.md`, the scan output in `build/scan/`, and the runtime's import table at <IMPORT_TABLE_FILE>.
FENCE: Read only, except `notes/gaps.md`. Do not edit `runtime/`.
CHECK: `notes/gaps.md` has three tables with a count each. Every row names the module and the address or proc name. Re-run the scan command named in `notes/survey.md`. Done means its counts match the tables.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Tell me which input file is missing.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The three counts. 3) Files written. 4) The gaps you would fix first. 5) New parking-lot items.

GOAL: Fix crash <CRASH_ID> at address <ADDRESS> in <MODULE>.
READ FIRST: `notes/PROGRESS.md` (dead ends), the crash log at <LOG_PATH>, and Ghidra output for <ADDRESS>.
FENCE: Edit only `runtime/` and `recomp/patches-<VER>.txt`. Never edit `generated/`. No stub without the proven cause in a comment.
CHECK: `<SCRIPTED_RUN_COMMAND>` passes the place where it crashed, and `<LIFTER_TEST_COMMAND>` still passes. Paste the screenshot path and the log line.
BUDGET: Stop after 3 failed fixes or 90 minutes.
IF BLOCKED: Stop. Tell me the cause you suspect, the proof you have, and what you ruled out.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof. 3) Files changed. 4) Dead ends to record. 5) New parking-lot items.

GOAL: Rebuild <FUNCTION> at <ADDRESS> in `src/game/<FILE>.c` so it passes the harness.
READ FIRST: The ledger row, Ghidra output for <ADDRESS>, and two passing functions that call or are called by it.
FENCE: Edit only `src/game/<FILE>.c`, its header and its ledger row. No inline assembly or byte arrays. Do not edit the harness or `data/baseline.json`.
CHECK: `tools/harness/run <FUNCTION> --cases 1000` prints PASS. Paste it.
BUDGET: 5 tries.
IF BLOCKED: Add it to `notes/hard-queue.md` with one failing input and stop.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof. 3) Files changed. 4) Instructions the runs covered. 5) New parking-lot items.

GOAL: Pick the next <N> units from <LEDGER_FILE> and start one worker per unit, each in its own worktree.
READ FIRST: `SCOPE.md`, <LEDGER_FILE>, `notes/claims.md` and `notes/PROGRESS.md`.
FENCE: You edit only `notes/claims.md` and `notes/PROGRESS.md`. Each worker edits only the files its unit names. Only one worker may run the game at a time.
CHECK: Re-run each worker's check yourself with `<UNIT_CHECK_COMMAND>`. Done means every merged unit passes, and `<FULL_CHECK_COMMAND>` passes on the main branch after merging.
BUDGET: Stop the round after <N> units or 3 hours.
IF BLOCKED: Stop that worker and move its unit to `notes/hard-queue.md` with the evidence.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Table: unit, worker, result, proof line. 3) Branches merged. 4) Units sent to the hard queue. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> without changing any code.
READ FIRST: `notes/PROGRESS.md`, the frame capture at <CAPTURE_PATH>, the validation layer log at <VK_LOG>, and `docs/maxwell.md`.
FENCE: Read only. You may add logging on a scratch branch. Write findings only to `notes/debug-<ID>.md`.
CHECK: The note names the shader by stable hash or the function by address, shows the wrong value, and shows where it came from. Re-run `<SCRIPTED_RUN_COMMAND>` on the scratch branch. Done means the log shows the same wrong value at the place the note names. Compare with Lichii if it runs the scene.
BUDGET: Stop after 2 hours.
IF BLOCKED: Stop. List what you ruled out and the next test you would run.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The cause with evidence. 3) Files written. 4) A proposed fix, not applied. 5) New parking-lot items.

GOAL: Check that the work in <BRANCH> is real and inside its fence.
READ FIRST: The task card for that work, `git diff <BASE>..<BRANCH>`, and its REPORT.
FENCE: Read only. Write only `notes/verify-<BRANCH>.md`. Do not fix anything.
CHECK: Re-run the card's check yourself. Search the diff for skipped draws, new stubs, edits in `generated/`, changed hash files, changed tests or CI, and lowered settings. Done means a pass or fail line for each.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Tell me which check you could not run.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Your re-run output. 3) The cheat checklist with results. 4) Files outside the fence. 5) New parking-lot items.

GOAL: Write a status report with numbers only from the ledger files and test output.
READ FIRST: `notes/PROGRESS.md`, `notes/boot-log.md`, the ledger in `data/ledger/` if any, and the last `tools/regress` output.
FENCE: Write only `notes/status-<DATE>.md`. Run only read-only commands and `tools/regress`.
CHECK: Every number in the report names the file or command it came from. No estimate is shown as a fact. Run `tools/regress` once more. Done means its PASS and FAIL lines match the report.
BUDGET: 30 minutes.
IF BLOCKED: Stop. Say which number you could not get.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Milestones reached, as separate lines. 3) Open bugs by count. 4) Top three risks. 5) New parking-lot items.

GOAL: Update the notes so a fresh session can continue without this chat.
READ FIRST: `notes/PROGRESS.md`, `git status` and `git log -5`.
FENCE: Edit only `notes/PROGRESS.md` and `notes/HANDOFF.md`. Do not change code.
CHECK: `notes/HANDOFF.md` lists the current task, the last check output, the files touched, the dead ends found today, and the next three steps. Every path is absolute. Run `git status --short`. Done means every changed file it lists is named in `notes/HANDOFF.md`.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Tell me what you could not write down.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The handoff text. 3) Files changed. 4) Uncommitted work. 5) New parking-lot items.

GOAL: Give me a plain answer about <TASK>: can it be done now, and what would it take?
READ FIRST: `notes/PROGRESS.md`, `notes/hard-queue.md` and the last three reports on this task.
FENCE: Read only. Write only `notes/blocked-<ID>.md`.
CHECK: `Get-Content notes/blocked-<ID>.md -TotalCount 1` prints CAN, CANNOT or NOT YET. The note lists every option with its cost in sessions and what it needs from me.
BUDGET: 30 minutes.
IF BLOCKED: Say so in the first line and why.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The one-word answer. 3) The options. 4) Your pick and why. 5) New parking-lot items.

GOAL: Ask me before you leave the fence for <TASK>.
READ FIRST: `SCOPE.md` and the task card you were given.
FENCE: Do not make the change. Write only `notes/scope-request-<ID>.md`.
CHECK: The request names the files or rules it would break, why the task needs it, the smallest change that would do, and how to check it.
BUDGET: 15 minutes.
IF BLOCKED: Stop and wait for my answer.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) BLOCKED until I answer. 2) The request. 3) Files written. 4) What you will do if I say no. 5) New parking-lot items.

Keep Claude on task

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

Problems other projects hit

How long it takes

What makes it faster or slower

• Whether a recomp exists for a game on the same engine. A fork of DKB Recomp reached a title screen on its first day.
• How many shader stages fail to lower. yoshi4pc stalled on 86 of 378.
• How many new NVN 2 calls, services and movie formats your game uses that the base lacks.
• How many GPUs you can test on. Device-lost faults differ by vendor and driver.
• For Path B, the size of the game. fefw's main alone has 89,170 functions.

The facts behind these numbers

Projects reviewed (18)

Every project we found. There are fewer than 10 games on RecompLauncher for Switch 2: 14 projects for 6 games. We added 4 projects from outside it, for 4 more games. That makes 10 games, with no spare. Two RecompLauncher repos are gone (404). Two other entries, pokopia-recomp and Recompia, now lead to the same repo.

What each project teaches

What we could not check

• The original compiler and its version. The libc++ 18.1.8 and 21.1.8 headers in fefw are only a hint.
• The .nup container format. We found no switchbrew page for it.
• Whether Ghidra-Switch-Loader opens ZBIC-packed NSO files. Its README does not say.
• The Path B toolchain in this guide (WSL Clang with an AArch64 target and a Unicorn harness) is our suggestion. fefw does not publish its build or name its emulator.
• fefw's 73.6% figure comes from its commit messages. It cannot be re-run without the game.
• Playability claims are the authors' own. We did not run any of these games.
• Hookshot and pokopia-native returned 404 on 2026-11-13. What we say about them comes from the review cards.
• The 16 MiB stack fact for TOoT:R comes from the review card's reading of its CMake file.
• Swapping decompiled game functions into a recomp by name (Path B, last step) is our suggestion. The reviewed projects only replace SDK functions this way.
• No project records how many hours of human work it took. Our time ranges are estimates from dates.
• The no-AI time ranges borrow from Switch 1 and other systems, because no Switch 2 project predates agents.
• No step in this guide was run here. Commands come from the projects' READMEs and docs, read on 2026-11-13.
• The Unicorn test list, tools/test.py and the knobs TOTK_PROFILE_DIR and TOTK_DUMP come from DKB Recomp's docs. Forks such as yoshi4pc may have changed them.
• tools/scripted_run.ps1 is our suggestion. DKB Recomp's docs name no single scripted-run command.
• Whether the Ampere census in yoshi4pc (tools/dkb_lower_test.cpp) and DKB's dkb_shader_census.py count the same thing was not checked.
• Stars come from the catalog on 2026-11-13. Live counts have since moved a little.

Sources

• DKB Recomp README
• DKB Recomp: building from source (toolchain, pacman line, checks)
• DKB Recomp: testing guide (shader census, run settings)
• yoshi4pc README (venvs, extract_nup.py, shader blocker)
• MTF ShadowRacket README (scan, init, build)
• fefw ledger checks (tools/ledger.py)
• zbic on PyPI
• Visual Studio Build Tools
• TotK Recomp README
• nxrecomp README
• MKW Recomp README
• NX2navi README
• fefw README, CI and ledger
• Switchbrew: NSO
• Switchbrew: Switch 2 Tegra T239
• Tom's Hardware: Switch 2 SoC die shot
• Lichii README and releases
• Eden emulator
• eden-nx2 fork
• Ghidra-Switch-Loader
• objdiff README
• Clang cross-compilation
• Ubuntu 24.04 clang package
• Unicorn on PyPI
• zbic
• REA
• Vulkan SDK