PC (DOS and Windows) decomp guide

What this system is like

An old PC game already runs on the same kind of chip as your PC. So you do not need to copy a console. The work is about Windows. Old games call DirectDraw, Direct3D and DirectSound in ways new Windows breaks. Many are 32-bit only, and some use copy protection.

Path A gets the game to run as a fresh, native program. The method most new projects use is static recompilation. A tool turns each function of the .exe into C. Then you write a small layer for the Windows and DirectX calls. pcrecomp, Black Ops II Recompiled and the Road Rash port all work this way.

Path B rebuilds the game as real source code. If the game was built with old Visual C++, you can match it byte for byte. The tool reccmp checks each function against the original .exe. LEGO Island is complete, and its build makes all three game files byte for byte. Carmageddon and Colin McRae Rally 2.0 are on their way.

Almost all of the work runs on Windows. You need WSL only for a few tools and for a Linux build. Many famous PC projects are not decomps at all. They are new engines, or games whose makers released the source. Check for those first.

Two paths

Path A: Get it running on PC

The game already runs on x86, so here running means a clean native build. A lifter turns each function into C. You link that C to a runtime that answers the Windows and DirectX calls. Then you fix one crash or one missing call at a time. A recorded replay that matches the original is the final proof.

1. Scope the game and check for prior work

   You pick one exact .exe and record its hash. Then you look for work that already exists. Released source, a new engine or a finished decomp can save you months. You also check for copy protection and leftover symbols.

   • Install Python, Git and pcrecomp first (see the tools list). Below, <PCRECOMP> means the folder where you cloned pcrecomp.
   • In PowerShell, run Get-FileHash <GAME>.exe and save the SHA-256 in SCOPE.md.
   • Search GitHub for the game name plus decomp, recomp and source port. Read each project's CONTRIBUTING.md and AGENTS.md before you use it.
   • Run python <PCRECOMP>/tools/pe/analyze_sections.py <GAME>.exe. It flags SafeDisc, SecuROM, UPX and other packers.
   • If the file is protected, stop. Use a DRM-free edition you own, such as a GOG copy, or pick another game.
   • Look for symbols: a .pdb, a .map file, a debug build, a demo, or a port to another system.
   • Write SCOPE.md: the goal, the hash, the technique, the first milestone, and what Claude must never edit.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for a native PC rebuild of <GAME>, version <VERSION>.
   READ FIRST: The output of `Get-FileHash <GAME_DIR>\<GAME>.exe` and `python <PCRECOMP>/tools/pe/analyze_sections.py <GAME_DIR>\<GAME>.exe`. My notes in notes/prior-work.md.
   FENCE: Edit only SCOPE.md and notes/prior-work.md. The game folder is read-only. Do not download any game files, keys or compilers.
   CHECK: Run `Select-String -Path SCOPE.md -Pattern '<SHA256>'`. Done means it prints the hash line, and SCOPE.md also names the copy protection result, every prior project with its URL and AI policy, the technique, and the first milestone with its check.
   BUDGET: Stop after 45 minutes of searching.
   IF BLOCKED: If the exe is encrypted or packed, stop and tell me. Do not look for ways to remove the protection.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the hash and the protection result. 3) Files changed. 4) Open questions for me. 5) New parking-lot items.

   Done whenSelect-String -Path SCOPE.md -Pattern '<SHA256>' finds the hash, the file holds the protection result and the prior-work list, and you approved it.

   Proof this works: Warzone 2100, nfs-most-wanted-mac, https://github.com/sp00nznet/pcrecomp

2. Set up the repo and the one check

   You make a repo that holds only your own code. The game files stay in a folder outside it. Then you write one check command that Claude runs after every change.

   • Install Visual Studio 2022 with the Desktop development with C++ workload. It includes CMake.
   • If you have not yet, run git clone https://github.com/sp00nznet/pcrecomp, then pip install capstone pefile lief unicorn cryptography, the line in its README.
   • Copy templates/CMakeLists.txt.template and templates/.gitignore.template from pcrecomp into your repo.
   • Keep the game in a folder such as D:\games\<GAME>. Add src/recomp/gen/ to .gitignore, because lifted output never goes in git.
   • Write check.cmd. It builds with cmake --build build, runs python <PCRECOMP>/tools/lift/difftest.py, then runs your own tests as you add them.
   • difftest.py compiles C with gcc, clang or cc, or with the compiler named in RECOMP_CC. Make sure one of them is on your path.
   • Write CLAUDE.md, PROGRESS.md and notes/parking-lot.md.
   Prompt for ClaudeCopy

   GOAL: Make `check.cmd` build the project and run every check in one command.
   READ FIRST: SCOPE.md, CLAUDE.md, the pcrecomp README section 'Starting a New Project'.
   FENCE: Edit only CMakeLists.txt, check.cmd, .gitignore and tools/. Do not add features, refactors or tools I did not ask for. Never copy game files into the repo.
   CHECK: Run `check.cmd`. Done means it exits 0 on a clean clone, and exits non-zero after you add a deliberate compile error.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste both check outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whencheck.cmd passes on a clean clone and fails when you break one file on purpose.

   Proof this works: OpenSC2K, https://github.com/sp00nznet/pcrecomp

3. Map the exe

   You list every function, import and class in the game. You mark the C runtime and library code, so nobody lifts it by hand. You also count unusual instructions, so you know what the lifter must handle.

   • Run python <PCRECOMP>/tools/pe/pe_analyze.py <GAME>.exe --json config/pe_analysis.json.
   • Run python <PCRECOMP>/tools/pe/extract_imports.py <GAME_DIR> to list every Windows call across the install.
   • Run python <PCRECOMP>/tools/disasm/disasm32.py <GAME>.exe --output functions.json --pe-json config/pe_analysis.json.
   • On C++ games, run python <PCRECOMP>/tools/cpp/rtti.py <GAME>.exe -o ledger/rtti.json to find classes and vtables (tables of method addresses).
   • If you have a PDB or .map, score the list: python <PCRECOMP>/tools/disasm/score_recovery.py --reference <REFERENCE> --candidate functions.json. pdb_ref.py and pdb2_ref.py in tools/pe/ make a reference from a PDB.
   • Open the exe in Ghidra and compare its function list with yours. Fix the edges before you lift.
   • Write ledger/functions.tsv with address, size, kind (game, CRT, library, thunk) and a status column.
   • Write tools/progress.py. It counts ledger rows per kind and status, and exits non-zero if a row has no kind or status.
   Prompt for ClaudeCopy

   GOAL: Produce ledger/functions.tsv for <GAME>.exe with one row per function.
   READ FIRST: SCOPE.md, config/pe_analysis.json, functions.json. Use the Ghidra MCP server for cross-checks.
   FENCE: Edit only ledger/, notes/ and tools/progress.py. The exe and the Ghidra project's original bytes are read-only.
   CHECK: Run `python tools/progress.py`. If a PDB or MAP exists, also run `python <PCRECOMP>/tools/disasm/score_recovery.py --reference <REFERENCE> --candidate functions.json`. Done means progress.py exits 0 and you report precision and recall.
   BUDGET: Stop after 90 minutes, or after 3 failed tries to fix the same function edge.
   IF BLOCKED: If the Ghidra MCP server does not answer, stop and ask me. Do not guess addresses from memory.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the counts per kind and the score. 3) Files changed. 4) Functions with unsure edges. 5) New parking-lot items.

   Done whenpython tools/progress.py exits 0 with no row missing a kind or status, and the edge score is saved in notes/.

   Proof this works: Resident Evil PC Decomp, nfs-most-wanted-mac, https://github.com/sp00nznet/pcrecomp

4. Lift the code and test the lifter

   The lifter turns every function into C. Claude never edits that C by hand. If it is wrong, you fix the lifter input and run it again. Two tests guard the lift. difftest.py checks the lifter on its own test cases. Your own test checks your game's functions.

   • From the <PCRECOMP> folder, run python -m tools <GAME_DIR>/<GAME>.exe --all --output <YOUR_REPO>/src/recomp/gen/.
   • Run python <PCRECOMP>/tools/lift/difftest.py -v. It runs the lifter's built-in cases as C and in Unicorn, and compares every register, flag and written byte.
   • Write tools/difftest_game.py for your game. Like the Need for Speed port's recomp/difftest.py, it runs one lifted function and its original bytes in Unicorn from the same state and compares.
   • Write any custom lift rules in your own run_lift.py, as the pcrecomp README says.
   • Record each lifter bug in notes/findings.md with the instruction that caused it.
   Prompt for ClaudeCopy

   GOAL: Lift <GAME>.exe to C and make both lift tests pass.
   READ FIRST: SCOPE.md, ledger/functions.tsv, the pcrecomp README parts on lift32 and difftest.
   FENCE: Edit only run_lift.py, config/, tools/difftest_game.py and notes/. Never edit files in src/recomp/gen/; change the lifter input and regenerate instead.
   CHECK: Run `check.cmd`. Done means `python <PCRECOMP>/tools/lift/difftest.py -v` and `python tools/difftest_game.py` pass every case, and the lift reports 0 errors.
   BUDGET: Stop after 3 failed tries on the same instruction.
   IF BLOCKED: Stop. Name the instruction and address that fails, and what you tried.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste both test summaries and the lift error count. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whendifftest.py -v and tools/difftest_game.py both pass, and the lift log shows 0 lift errors.

   Proof this works: nfs-most-wanted-mac, Black Ops II Recompiled, https://github.com/sp00nznet/pcrecomp/blob/main/tools/lift/difftest.py

5. Boot to the first frame

   You link the lifted C to a runtime and start it. On Windows, the native32 runtime forwards calls to real Windows. That gets you to a first frame fast. Any call that is not ready yet must stop the program with a clear error.

   • Use runtime/recomp32 and host it with runtime/native32 from pcrecomp.
   • Build with cmake --build build and run the program from the game folder.
   • Make every missing function abort with its address. Never let it return a fake value.
   • Write tools/golden.cmd. It starts the game, waits a set time, and saves a screenshot and a log line.
   • Save the first good screenshot as the reference in tests/golden/.
   Prompt for ClaudeCopy

   GOAL: Boot the recompiled <GAME> to its first frame on Windows 11.
   READ FIRST: SCOPE.md, PROGRESS.md, notes/findings.md, runtime/native32/native32.h and the pcrecomp README parts on native32.
   FENCE: Edit only runtime glue in src/host/ and tools/golden.cmd. Never edit src/recomp/gen/. No stub may return a made-up value; missing calls must abort with their address.
   CHECK: Run `check.cmd`. Done means tools/golden.cmd exits 0 and saves a screenshot of the first frame.
   BUDGET: Stop after 4 crashes with no new evidence, or 60 minutes with no progress.
   IF BLOCKED: Stop. Paste the last log lines and the crash address, 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) Paste the golden run output and the screenshot path. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/golden.cmd starts the game with no person, reaches the first frame, and saves the screenshot.

   Proof this works: Black Ops II Recompiled, https://github.com/sp00nznet/pcrecomp

6. Fix one crash or one call at a time

   This is the long middle. Each session fixes one crash, one missing Windows call, or one wrong picture. Claude must prove the cause with a log or a trace before it changes code. Honest stubs matter, because a fake answer can break the game far away.

   • Pick the next item from PROGRESS.md. Give Claude only that item.
   • Replace a game function through a hook list by address, as hooks.txt does in the Need for Speed port.
   • Copy the original's x87 settings. Direct3D 9 sets the FPU to 24-bit precision unless the game passes D3DCREATE_FPU_PRESERVE.
   • Log every place where the program falls back or aborts, so the next gap is easy to find.
   • Rerun check.cmd and the golden run after every fix.
   Prompt for ClaudeCopy

   GOAL: Fix crash <CRASH_ID> at <ADDRESS> in <GAME>.
   READ FIRST: PROGRESS.md entry <CRASH_ID>, notes/findings.md, logs/<RUN>.log. Ask the Ghidra MCP server for the function at <ADDRESS>.
   FENCE: Edit only src/host/ and hooks.txt. Never edit src/recomp/gen/. Do not change any other crash, feature or file.
   CHECK: Run `check.cmd`. Done means the golden run passes and the run gets past <ADDRESS> with no new aborts.
   BUDGET: Stop after 3 failed fixes, or 45 minutes with no new evidence.
   IF BLOCKED: Stop. Do not add a stub that returns success. Tell me the cause you proved, what you tried, and what you need.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The proven cause with the log lines, then the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe crash is gone, the golden run passes, and PROGRESS.md marks the item done with its cause.

   Proof this works: Black Ops II Recompiled, nfs-most-wanted-mac, Roadrash

7. Swap in a modern graphics and sound layer

   Old DirectDraw and Direct3D calls break on new Windows. You put them behind one small interface. Then you draw with SDL3 or Direct3D 11 and play sound with SDL3. A frame hash proves the picture did not change.

   • List every DirectX call the game uses from the import table.
   • Write one interface file, such as src/port/gfx.h, and route all drawing calls through it.
   • Get SDL3-devel-<VERSION>-VC.zip from the SDL releases page. Or, with vcpkg, run vcpkg new --application, then vcpkg add port sdl3.
   • Save a hash of the back buffer (the picture before it hits the screen) for set frames.
   • Compare those hashes with the reference frames from the old path.
   Prompt for ClaudeCopy

   GOAL: Draw <GAME> through src/port/gfx.h with the <BACKEND> backend.
   READ FIRST: SCOPE.md, notes/directx-calls.md, tests/golden/.
   FENCE: Edit only src/port/ and src/host/gfx*. Never edit src/recomp/gen/. Do not add new graphics features.
   CHECK: Run `check.cmd`. Done means the frame hashes for <FRAME_LIST> match the reference, and the golden run passes.
   BUDGET: Stop after 3 failed tries on the same draw call.
   IF BLOCKED: Stop. Name the call and the frame that differ, and show both images' paths.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the frame hash table. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe frame hashes match the reference and check.cmd passes.

   Proof this works: Resident Evil PC Decomp, OpenCMR2, Roadrash, https://github.com/libsdl-org/SDL/releases, https://github.com/microsoft/vcpkg/tree/master/ports/sdl3

8. Harden with replays and package it

   You record inputs and replay them in the original and in your build. The results must match frame for frame. Then you package the build without any game files.

   • Record a set of inputs that play the attract mode and two levels.
   • Replay them in the original game and in your build. Compare state or frames.
   • Make every replay part of check.cmd. Road Rash requires 14 matching replays before each release.
   • Run python <PCRECOMP>/tools/audit_repo.py <YOUR_REPO> to find game material in git, even in old commits.
   • Ship a setup step that reads the user's own copy and checks its hash.
   Prompt for ClaudeCopy

   GOAL: Add replay tests for <GAME> and make them pass on a clean clone.
   READ FIRST: SCOPE.md, PROGRESS.md, tests/replays/README.md.
   FENCE: Edit only tests/, tools/ and check.cmd. Never change a recorded reference to make a test pass.
   CHECK: Run `check.cmd` on a fresh clone. Done means all <N> replays match the original and `python <PCRECOMP>/tools/audit_repo.py .` finds no game material.
   BUDGET: Stop after 3 failed tries on the same replay.
   IF BLOCKED: Stop. Tell me which replay differs, at which frame, and what you tried.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the replay table and the audit output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenEvery replay matches on a clean clone and the repo audit finds no game files.

   Proof this works: Roadrash, OpenRCT2, OpenSC2K

Path B: Full decomp for porting

You write C or C++ that the original Visual C++ turns into the same bytes. reccmp scores each function against the retail .exe. When every function matches, you have true source. Then you move the Windows parts behind an interface and port it. If the compiler is too new to match, you fall back to a non-matching decomp checked by tests.

1. Find the compiler and the symbols

   Matching needs the exact compiler and its options. The Rich header inside the .exe records the Microsoft tools that built it. You also hunt for symbols, because names save weeks. Then you decide: matching or non-matching.

   • Run Get-FileHash <GAME>.exe and save the SHA-256.
   • Read the Rich header with the re-binary-recon skill or a PE tool. Note the Visual C++ version and build number.
   • Look for a .pdb, a .map, a .SYM file, a debug build, demos and ports. The Devilution team used a symbol file from Diablo's PlayStation port.
   • Check that reccmp supports the compiler. It handles old MSVC such as 4.20 today.
   • Write the compiler, flags, symbols and choice in SCOPE.md.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for a decomp of <GAME>.exe, version <VERSION>, and pick matching or non-matching.
   READ FIRST: The Rich header dump in notes/rich.txt, the reccmp README, notes/prior-work.md.
   FENCE: Edit only SCOPE.md and notes/. The game folder is read-only. Do not download compilers, symbols or game files.
   CHECK: Run `Select-String -Path SCOPE.md -Pattern '<SHA256>','<COMPILER>'`. Done means both are found, and SCOPE.md names the build number, the likely flags, every symbol source with its path, and a matching or non-matching choice with one reason.
   BUDGET: Stop after 45 minutes.
   IF BLOCKED: If the compiler cannot be identified, stop and say so. Do not guess a version.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the Rich header lines you used. 3) Files changed. 4) Open questions. 5) New parking-lot items.

   Done whenSelect-String -Path SCOPE.md -Pattern '<SHA256>','<COMPILER>' finds both, the file names the flags, symbol sources and technique, and you approved it.

   Proof this works: DevilutionX, Dethrace, SpaceCadetPinball, https://github.com/pablocpas/CMR2Decomp

2. Set up the old compiler and reccmp

   You build with the same old compiler the game used. It runs on Windows 11, so you do not need WSL here. reccmp makes the project files and the first comparison. The original .exe stays outside the repo.

   • Get the original Visual C++ version from a copy you have the right to use. Keep it in a path with no spaces.
   • Open cmd, run its BIN\VCVARS32.BAT x86, then run cmake <SRC> -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo.
   • Build with nmake && nmake, as the LEGO Island README advises.
   • Make a Python 3.11 or newer virtual environment, as the reccmp README advises. Then run pip install reccmp.
   • Run reccmp-project create --originals <GAME_DIR>\<GAME>.exe --cmake-project.
   • Build into a build folder. Run every reccmp- command from there, because reccmp-build.yml lives there.
   • Write check.cmd: build, cd build, then reccmp-reccmp --target <TARGET>. You add --diff base.json in step 4.
   Prompt for ClaudeCopy

   GOAL: Make `check.cmd` build <GAME> with <COMPILER> and print a reccmp report.
   READ FIRST: SCOPE.md, the reccmp README 'Fresh project' section, CLAUDE.md.
   FENCE: Edit only CMakeLists.txt, check.cmd, reccmp-project.yml and tools/. Never copy the original exe or the compiler into the repo.
   CHECK: Run `check.cmd`. Done means it builds and `reccmp-reccmp --target <TARGET>`, run in build/, prints a function list with scores.
   BUDGET: Stop after 3 failed tries at the same error.
   IF BLOCKED: Stop. Do not swap in a newer compiler. Tell me what failed and what you need.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the first 20 lines of the report. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whencheck.cmd builds with the old compiler and reccmp prints a score list.

   Proof this works: Dethrace, https://github.com/isledecomp/isle, https://github.com/isledecomp/reccmp

3. Map and triage every function

   You list every function in the .exe and sort it. Game code gets matched. C runtime, compiler glue and import thunks are marked out of scope. This keeps the done count honest.

   • Open the exe in Ghidra. Connect GhidraMCP so Claude can list, decompile and rename.
   • Export the function list to ledger/functions.tsv with address, size, kind and status.
   • Mark CRT, exception handling and thunk functions as out of scope. The Resident Evil project set aside 290 CRT functions.
   • Have Claude rename functions in Ghidra as it learns them, so the next session sees the names.
   • Write tools/progress.py. It counts done functions from the ledger and fails on a row with no kind or status.
   Prompt for ClaudeCopy

   GOAL: Build ledger/functions.tsv for <GAME>.exe and triage every function.
   READ FIRST: SCOPE.md. Use the Ghidra MCP server for the function list and names.
   FENCE: Edit only ledger/, notes/, tools/progress.py and names inside the Ghidra project. Do not write any C yet.
   CHECK: Run `python tools/progress.py`. Done means every function has a kind (game, CRT, SEH, thunk, library) and a status, and the totals add up to the Ghidra count.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: If the Ghidra MCP server is not reachable, stop and ask me. Do not guess code from memory.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the totals per kind. 3) Files changed. 4) Unsure functions. 5) New parking-lot items.

   Done whenpython tools/progress.py prints a total equal to Ghidra's function count, and no row lacks a kind or status.

   Proof this works: Resident Evil PC Decomp, https://github.com/LaurieWired/GhidraMCP

4. Match one function end to end

   You prove the whole chain on one small function. Then you prove the check can fail. A check that never fails is not a check.

   • Pick a small leaf function, one that calls nothing.
   • Write it in C with the note // FUNCTION: <TARGET> 0x<ADDRESS> above it.
   • Run reccmp-reccmp --target <TARGET> --verbose 0x<ADDRESS>. It must show 100%.
   • Break one line on purpose and confirm the score drops. Then undo it.
   • Save reccmp-reccmp --target <TARGET> --json base.json --silent as the first baseline.
   • Add --diff base.json to the reccmp-reccmp line in check.cmd.
   Prompt for ClaudeCopy

   GOAL: Make <FUNCTION> at 0x<ADDRESS> match 100% in reccmp.
   READ FIRST: SCOPE.md, CLAUDE.md, the Ghidra decompile of 0x<ADDRESS>.
   FENCE: Edit only src/<FILE>.cpp, and only this function. Do not add inline assembly, naked functions or embedded bytes.
   CHECK: Run `reccmp-reccmp --target <TARGET> --verbose 0x<ADDRESS>`. Done means 100%, and a deliberate one-line break makes it drop.
   BUDGET: Stop after 10 tries with no gain.
   IF BLOCKED: Stop. Paste the best diff and say which lines still differ.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the 100% line and the failing-test line. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOne function shows 100% in reccmp, and a deliberate break makes the score drop.

   Proof this works: Dethrace, https://github.com/isledecomp/reccmp

5. Run the matching loop in parallel

   Now workers match functions one at a time, easy ones first. Each worker owns one file in its own git worktree. Every result is compared with the saved baseline, so a new match cannot break an old one.

   • Sort the ledger by size and pick the smallest open functions first.
   • Give each worker one function and its own worktree.
   • Before editing, map the locals to stack slots, as Dethrace does with get_stack_slots.py.
   • Change one thing at a time and rerun the diff. Undo any change that lowers the score.
   • Merge only when reccmp-reccmp --target <TARGET> --diff base.json shows no drops. Then save a new baseline.
   Prompt for ClaudeCopy

   GOAL: Match <FUNCTION> at 0x<ADDRESS> in <FILE>.
   READ FIRST: CLAUDE.md, ledger/functions.tsv row for 0x<ADDRESS>, notes/compiler-quirks.md, two matched functions near it.
   FENCE: Edit only the body of <FUNCTION> in src/<FILE>.cpp. Do not rename or add variables, change the signature, or touch any other function. No inline assembly, goto or volatile tricks.
   CHECK: Run `check.cmd`. Done means <FUNCTION> shows 100% and `--diff base.json` shows no other function dropped.
   BUDGET: Stop after 10 tries with no gain. Stop at once if the stack size differs.
   IF BLOCKED: Stop. Save the best attempt, paste its diff, and name the kind of difference left.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the score line and the diff summary. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe ledger shows the batch matched and --diff base.json shows no drops on the merged branch.

   Proof this works: Dethrace, https://github.com/pablocpas/CMR2Decomp, https://momo5502.com/posts/2026-10-09-game-decompilation/

6. Work the hard tail

   Some functions resist. Before more tries, you find out why. Some diffs are compiler noise that no C can fix. Those get marked and parked, not forced.

   • Run reccmp-stackcmp --target <TARGET> 0x<ADDRESS> to compare stack layouts.
   • Use the wall-identifier skill to name the cause before you spend more tries.
   • Check rounding rules. Visual C++ 6 with /QIfist rounds float to int differently from a plain cast.
   • Mark x87 order diffs as compiler noise, as Dethrace's rule sheet does. Do not force them.
   • Record each trick that worked in notes/compiler-quirks.md.
   Prompt for ClaudeCopy

   GOAL: Find why <FUNCTION> at 0x<ADDRESS> stops at <SCORE>% and try the fix.
   READ FIRST: notes/compiler-quirks.md, the saved attempts in scratch/<FUNCTION>/, the output of `reccmp-stackcmp --target <TARGET> 0x<ADDRESS>`.
   FENCE: Edit only <FUNCTION> in src/<FILE>.cpp and notes/compiler-quirks.md. No inline assembly, pragmas or changes to the check.
   CHECK: Run `check.cmd`. Done means 100%, or a written cause backed by the exact differing instructions.
   BUDGET: Stop after 15 tries, or after 3 tries with no new idea.
   IF BLOCKED: Stop. Say whether it is compiler noise, a wrong type, or a wrong function edge, with proof.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the diff lines that remain. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenpython tools/progress.py shows each hard function as matched, or parked with a written, proven cause.

   Proof this works: Dethrace, OpenCMR2

7. Harden the whole-binary check

   One function's score is evidence. The whole binary is the verdict. You check data, vtables and the full file, and you run this on every change.

   • Run reccmp-datacmp --target <TARGET> and reccmp-vtable --target <TARGET>.
   • Generate a full report with reccmp-reccmp --target <TARGET> --html report.html.
   • Run the full report in CI on every pull request. Dethrace posts it as a comment and warns on drops.
   • Hash the check script and store the hash where Claude cannot edit it. Heumann's team kept it in a CI secret.
   • Add differential tests that run original and rebuilt code side by side, as CMR2Decomp does.
   Prompt for ClaudeCopy

   GOAL: Make CI run the full reccmp report and fail on any drop.
   READ FIRST: CLAUDE.md, check.cmd, .github/workflows/.
   FENCE: Edit only .github/workflows/ and tools/ci/. Never change base.json, expected hashes or the scoring rules.
   CHECK: Run the workflow on a test branch. Done means it passes on main, and fails on a branch where you lowered one function on purpose.
   BUDGET: Stop after 3 failed CI runs on the same error.
   IF BLOCKED: Stop. Paste the CI log lines and say what you need.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Links to the passing and failing runs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenCI passes on main, fails on a planted drop, and datacmp and vtable show no errors.

   Proof this works: Dethrace, https://github.com/isledecomp/isle, https://github.com/pablocpas/CMR2Decomp, https://momo5502.com/posts/2026-10-09-game-decompilation/

8. Port it behind a platform layer

   You keep the matched code close to its source. Only functions that call Windows or DirectX get rewritten against a small interface. Then you build it for 64-bit and Linux. Physics and frames must still match the original.

   • Keep the port in a separate repo or branch, as DevilutionX and OpenCMR2 do.
   • Write src/port/ headers for graphics, audio, input, files and network. Mark every change with a PORT: comment.
   • In its own task, write tests/check_platform_boundary.py. It fails if game code includes windows.h, like the Resident Evil decomp's script.
   • Audit raw memory access for 32-bit pointer assumptions before the 64-bit build.
   • In WSL, use Ubuntu 26.04 LTS: wsl --install -d Ubuntu-26.04. Ubuntu 24.04 has no libsdl3-dev package.
   • In that Ubuntu, run sudo apt install cmake libsdl3-dev, then build the Linux target with cmake.
   • Replay recorded inputs in the original and in the port. Compare state each tick.
   Prompt for ClaudeCopy

   GOAL: Move <SUBSYSTEM> calls in <GAME> behind src/port/<SUBSYSTEM>.h and build on <TARGET_OS>.
   READ FIRST: SCOPE.md, docs/ARCHITECTURE.md, ledger/platform-calls.tsv.
   FENCE: Edit only src/port/, src/platform/ and the functions listed for <SUBSYSTEM>. Mark each change in game code with `// PORT:`. Do not fix original game bugs.
   CHECK: Run `check.cmd` and `python tests/check_platform_boundary.py`. Done means both pass and the parity replay <REPLAY> matches the original bit for bit.
   BUDGET: Stop after 3 failed tries on the same call.
   IF BLOCKED: Stop. Name the call and the first tick that differs.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste both check outputs and the parity result. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe port builds on the new system, the boundary check passes, and the parity replay matches.

   Proof this works: OpenCMR2, DevilutionX, Resident Evil PC Decomp, https://github.com/isledecomp/isle, https://packages.ubuntu.com/search?keywords=libsdl3-dev&searchon=names&suite=all&section=all

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

For Path A, one unit is one crash, one missing Windows call, or one wrong frame. Each unit ends with the golden run and the replays passing. For Path B, one unit is one function at one address. Each unit ends with reccmp showing 100% and no drop against base.json. The ledger, not the chat, says what is next.

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.
- Run `check.cmd` after every change. If it fails, the task is not done.
- Run every `reccmp-` command from the `build` folder. Run `pcrecomp` scripts from `<PCRECOMP>`.
- Never edit files in `src/recomp/gen/`. Change the lifter input and regenerate.
- The game folder, the original exe and `base.json` are read-only.
- Match only the function named in the task. Do not rename variables or change its signature.
- No inline assembly, naked functions, embedded bytes, goto or volatile tricks to force a match.
- No stub may return success. A missing call aborts and prints its address.
- If the Ghidra MCP server is down, stop and ask. Do not guess code from memory.
- Comment every function with its original address: `// FUNCTION: <TARGET> 0x<ADDRESS>`.
- Never state that a check passed unless you ran it and pasted the output.
- In a worktree, use absolute paths to the game folder and the compiler.
- Write side ideas and other bugs in notes/parking-lot.md. Do not act on them.

Keep the context small

• Give Claude one address and the ledger row, not a whole Ghidra export.
• Let a subagent read big decompiler output and return a short summary.
• Keep CLAUDE.md under one page and point to notes/compiler-quirks.md by name.
• Paste the last 20 log lines of a crash, not the whole log.
• Clear the chat after each unit. The ledger carries the state.

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> (<EXE>, SHA-256 <HASH>) can be rebuilt, and by which technique.
READ FIRST: notes/rich.txt, the output of `python <PCRECOMP>/tools/pe/analyze_sections.py <EXE>`, notes/prior-work.md.
FENCE: Edit only SCOPE.md and notes/. Do not download game files, compilers or symbols.
CHECK: Run `Select-String -Path SCOPE.md -Pattern '<HASH>'`. Done means it finds the hash, and SCOPE.md lists the compiler and build number, protection status, symbol sources, prior projects with URLs and AI policies, and a recommended technique with one reason against each other technique.
BUDGET: Stop after 60 minutes.
IF BLOCKED: If the exe is protected or the compiler is unknown, stop and say so plainly.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Your recommendation in one line, then the evidence. 3) Files changed. 4) Open questions. 5) New parking-lot items.

GOAL: Fill ledger/functions.tsv for <EXE> with address, size, kind and status for every function.
READ FIRST: SCOPE.md, config/pe_analysis.json, functions.json. Use the Ghidra MCP server.
FENCE: Edit only ledger/ and notes/. The exe is read-only. Do not write C.
CHECK: Run `python tools/progress.py`. Done means the total equals Ghidra's function count and no row lacks a kind.
BUDGET: Stop after 90 minutes.
IF BLOCKED: If the counts do not agree, stop and list the addresses that differ.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the totals per kind. 3) Files changed. 4) Unsure rows. 5) New parking-lot items.

GOAL: Make the recompiled <GAME> get past abort <ADDRESS> in run <RUN>.
READ FIRST: PROGRESS.md item <ID>, the last 20 lines of logs/<RUN>.log, notes/findings.md.
FENCE: Edit only src/host/ and hooks.txt. Never edit src/recomp/gen/. No stub may return a fake success.
CHECK: Run `check.cmd`. Done means the golden run passes and the new run reaches <NEXT_POINT>.
BUDGET: Stop after 3 failed fixes or 45 minutes with no new evidence.
IF BLOCKED: Stop. Give the proven cause, or say the cause is not proven yet.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Cause with log lines, then check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Make <FUNCTION> at 0x<ADDRESS> match 100%.
READ FIRST: CLAUDE.md, the ledger row, notes/compiler-quirks.md, the Ghidra decompile of 0x<ADDRESS>.
FENCE: Edit only the body of <FUNCTION> in src/<FILE>.cpp. No new variables, no signature change, no inline assembly.
CHECK: Run `reccmp-reccmp --target <TARGET> --verbose 0x<ADDRESS>`, then `check.cmd`. Done means 100% and no drop against base.json.
BUDGET: Stop after 10 tries with no gain. Stop at once if the stack size differs.
IF BLOCKED: Stop. Keep the best attempt and paste its diff.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Score line and diff summary. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Start <N> workers on the next <N> open units from the ledger.
READ FIRST: ledger/functions.tsv, PROGRESS.md, notes/parking-lot.md.
FENCE: Edit only PROGRESS.md and the claim column of the ledger. Each worker gets its own git worktree and one unit in a different file. Do not do unit work yourself.
CHECK: After all workers report, run `check.cmd` on the merged branch. Done means it passes and the ledger matches the reports.
BUDGET: Stop after one batch.
IF BLOCKED: If two units need the same file, run them one after the other and tell me.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) A table of unit, worker result and proof. 3) Files changed. 4) Units to retry as hard jobs. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> in <GAME>. Do not fix it yet.
READ FIRST: logs/<RUN>.log, the frame hash table, notes/findings.md.
FENCE: You may add temporary logging in src/host/ only. Remove it before you report. Do not change game behaviour.
CHECK: Run `tools/golden.cmd` twice. Done means the bug appears both times, and a log line or trace shows the first wrong value and where it came from.
BUDGET: Stop after 60 minutes or 5 runs with no new evidence.
IF BLOCKED: Stop. List what you ruled out and the evidence for each.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The cause, with the log lines. 3) Files changed. 4) The fix you would try. 5) New parking-lot items.

GOAL: Check that the work in branch <BRANCH> is real.
READ FIRST: `git diff main...<BRANCH>`, CLAUDE.md, SCOPE.md.
FENCE: Read-only. Do not fix anything. Do not commit.
CHECK: Run `check.cmd` yourself. Then look for edits to base.json, check.cmd, expected hashes or src/recomp/gen/; inline assembly; stubs that return success; disabled tests; and files outside the task fence.
BUDGET: Stop after 45 minutes.
IF BLOCKED: If you cannot run the check, say NOT ASSESSED, not PASS.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Your own check output. 3) Each finding with file and line. 4) A verdict: ACCEPT or REJECT. 5) New parking-lot items.

GOAL: Report project status with numbers only.
READ FIRST: ledger/functions.tsv, PROGRESS.md, the latest reccmp JSON or replay results.
FENCE: Edit only notes/status-<DATE>.md.
CHECK: Every number comes from a file or command you name. Run `python tools/progress.py` and paste it.
BUDGET: Stop after 15 minutes.
IF BLOCKED: If a number cannot be measured, write 'not measured'.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Matched or fixed count and percent, change since last report, open crashes, hard units. 3) Files changed. 4) Next three units. 5) New parking-lot items.

GOAL: Write down what the next session needs so it can continue from the files alone.
READ FIRST: PROGRESS.md, notes/findings.md, `git status`.
FENCE: Edit only PROGRESS.md and notes/handoff.md. Do not change code.
CHECK: Run `check.cmd` and paste its last 20 lines into notes/handoff.md. Done means the note also lists the current unit, what was tried, dead ends, and the exact next command.
BUDGET: Stop after 10 minutes.
IF BLOCKED: If the last check output is missing, run `check.cmd` and paste it.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste notes/handoff.md. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Tell me plainly whether <TASK> can be done, and if not, why.
READ FIRST: The attempts in scratch/<TASK>/, notes/findings.md.
FENCE: Read-only. Do not try again.
CHECK: Run `check.cmd` once and paste the lines that fail. Done means your answer names the exact blocker, with that proof or a missing tool or file.
BUDGET: Stop after 20 minutes.
IF BLOCKED: Say 'I do not know yet' and list what would tell us.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) BLOCKED or PARTIAL. 2) The blocker and its proof. 3) Files changed (none). 4) Two or three options with cost and risk. 5) New parking-lot items.

GOAL: Ask me before you leave the fence for <TASK>.
READ FIRST: SCOPE.md, the task card for <TASK>.
FENCE: Do not edit anything. Write only notes/scope-requests.md.
CHECK: Run `git status --porcelain`. Done means it lists only notes/scope-requests.md, and the request names each file to change, why, the smallest change, and what could break.
BUDGET: Stop after 10 minutes.
IF BLOCKED: If you cannot name the smallest change, say so.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) PARTIAL. 2) The request text. 3) Files changed. 4) What waits on my answer. 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

• Game size. A 1997 game has a few thousand functions. Need for Speed: Most Wanted (2005) has about 52,000.
• The compiler. Visual C++ 4.2 to 6 matches well with reccmp. Newer compilers are not fully supported yet.
• Symbols. A public PDB or a leaked symbol file saves weeks of naming.
• How many Windows and DirectX calls the game makes. Each one needs a working stand-in.
• Copy protection. A protected exe can stop the project before it starts.
• Whether a toolbox already has a runtime for that engine. Later games on pcrecomp came up fast.

The facts behind these numbers

Projects reviewed (23)

We took the top project for each of the 12 most-starred PC games on RecompLauncher. We added three that their makers say used AI. We added eight more decomp and recomp projects. The catalog lists 263 PC projects for 250 games.

What each project teaches

What we could not check

• No command in this guide was run here. Commands were read from each tool's README, docs or source on 2026-11-13.
• Few reviewed projects publish their agent setup. Dethrace and the Resident Evil decomp have rule sheets. OpenSC2K, CorsixTH and VCMI have AGENTS.md files, and CMR2Decomp has a CLAUDE.md. None publishes its prompts.
• Which AI tool, if any, wrote the Resident Evil PC decomp is not stated. Only its AGENTS.md suggests it.
• pcrecomp's README does not say if AI was used. Its sister repo xboxrecomp says it was built with Claude Code.
• Road Rash and Black Ops II hide their early history, so their start dates are not known.
• The date LEGO Island reached 100% was not read.
• tools/difftest_game.py and tools/progress.py are scripts you write. The Need for Speed port's game-level lift test is not in its public checkout.
• difftest.py needs gcc, clang or cc. Whether it works on Windows with only Visual Studio was not checked.
• py install 3.13 follows the pattern in Python's docs. That exact version tag was not tried.
• Whether objdiff handles old Visual C++ objects as well as reccmp was not tested here.
• Remill on native Windows is called experimental by its README. It was not tried here.
• The Rich header reference page (bytepointer.com) was down when the writer checked it.
• The time ranges come from few projects. Most are from 2026, and two were team efforts.
• GhidraMCP 2.0 names Ghidra 12.1.4. Whether it loads in Ghidra 12.2 was not checked.

Sources

• reccmp README
• pcrecomp README
• Ghidra README
• GhidraMCP README
• Remill README
• CMR2Decomp README
• CMR2Decomp progress on decomp.dev
• LEGO Island decompilation README
• Dethrace reccmp agent rules
• Resident Evil PC Decomp AGENTS.md
• Get-FileHash (PowerShell docs)
• PE format (Microsoft docs)
• 500+ Billion Tokens Later (Heumann)
• Resurrecting Crimsonland (banteg)
• Chromatron recompiled (Quesma)
• Black Ops II Recompiled README
• Need for Speed Most Wanted Mac ARCHITECTURE.md
• pcrecomp difftest.py source
• reccmp on PyPI
• libsdl3-dev in Ubuntu (packages.ubuntu.com)
• Install WSL (Microsoft docs)
• Using Python on Windows
• uv installation
• Git for Windows install
• SDL releases
• vcpkg sdl3 port
• objdiff README
• ReproBit (LEGO Island byte-for-byte builds)
• Select-String (PowerShell docs)