Arcade decomp guide

What this system is like

Arcade is not one system. It is hundreds of boards from Sega, Namco, Konami, SNK, Midway and others. Each board has its own main chip, sound chip and graphics chips. The 12 projects reviewed here use nine different main chips. So first find out which board your game runs on.

The good news is MAME. MAME is a free emulator that runs almost every board. Its code also shows how each chip behaves. Most strong projects here use MAME as the answer key. It runs the original code and your code with the same inputs, then compares each frame. Others check against a CPU interpreter or the Supermodel emulator instead.

Path A gets the game running on a PC. Most projects use static recompilation: a tool turns the game's machine code into C. A small interpreter runs any code the tool missed and checks the rest. For Neo Geo games, a recompiler toolkit already exists.

Path B turns the game into readable C. Byte matching is rare here, because many older games were written in assembly. So most projects check each function against MAME instead. Only newer boards with a known compiler, like Triforce, allow a true matching decomp.

Two paths

Path A: Get it running on PC

A recompiler turns each routine of the main program into C. A runtime stands in for the board: video chips, sound chips, inputs and timers. A built-in interpreter, often Musashi for the 68000, runs code the recompiler missed. The same interpreter replays every block and compares the results. You fix one mismatch at a time, found by per-frame hashes against MAME or the interpreter.

1. Scope the game and find its board

   You pick one game, one MAME set name and one revision. You find the board, its main chip and its sound chips. Then you look for prior work, because arcade has several toolkits and rewrites already. The result is a one-page SCOPE.md you approve.

   • Find the set name and board in MAME. Run mame -listfull <SET> and mame -listsource <SET> to see the game name and its driver file.
   • Open that driver file under src/mame/ on GitHub. Its top comment and its machine setup name the CPUs and chips.
   • Check your ROM files: mame -verifyroms <SET>. Write down each file's CRC32 from the zip.
   • Search for prior work: neogeorecomp (Neo Geo), arcade-decomp (System 32, Multi 32, Konami 68000), Supermodel (Model 3), CannonBall (OutRun), OpenGP (Triforce).
   • Write SCOPE.md with lines that start Board:, CPUs:, Set:, Technique: and Prior work:. Add the milestone, its check, and what is out of scope.
   • Read it yourself. When you agree, add a line that starts Approved: with the date. Only you write that line.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for <GAME>, MAME set <SET>, so I can approve one technique.
   READ FIRST: notes/mame-listsource.txt, notes/verifyroms.txt, the MAME driver file <DRIVER_PATH> (read only its top comment and machine setup).
   FENCE: Edit only SCOPE.md and notes/. Do not download ROMs, BIOS files or game data. Do not start any code.
   CHECK: Run `findstr /b /c:"Board:" SCOPE.md && findstr /b /c:"CPUs:" SCOPE.md && findstr /b /c:"Set:" SCOPE.md && findstr /b /c:"Technique:" SCOPE.md && findstr /b /c:"Prior work:" SCOPE.md`. Done means all five lines print and the command exits 0. The CPUs line gives each CPU's role. The Technique line gives one reason against each other technique.
   BUDGET: Stop after 45 minutes of work.
   IF BLOCKED: Stop. Do not work around it. If the board has no MAME driver or the set fails verification, say so plainly and stop.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The technique in one line, then the evidence. 3) Files changed. 4) Open questions. 5) New parking-lot items.

   Done whenThe findstr chain in the prompt exits 0 on SCOPE.md, and findstr /b /c:"Approved:" SCOPE.md finds the line you added after reading it.

   Proof this works: OutRunners Port, KOF'98 Recomp, https://docs.mamedev.org/commandline/commandline-all.html

2. Set up the repo and the one check

   You make a repo that holds only your own code. Your ROM set lives in a rom/ folder that git ignores. You write a script that checks the ROM by hash, and one check command that Claude runs after every change.

   • Install Visual Studio Build Tools with the C++ workload, CMake 3.20 or newer, SDL2, Python 3.10 or newer, and Git.
   • For a Neo Geo game, clone the toolkit as a submodule: git submodule add https://github.com/sp00nznet/neogeorecomp.
   • Add rom/, build/ and build/generated/ to .gitignore. Generated C never goes in git.
   • Write tools/verify_rom.py. It checks the CRC32 and SHA-1 of every chip file and refuses any other revision.
   • Write check.cmd. It runs cmake --build build --config Release, then ctest --test-dir build -C Release --output-on-failure, then the golden run.
   • 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 README of <TOOLKIT> (Getting Started only).
   FENCE: Edit only CMakeLists.txt, check.cmd, .gitignore and tools/. Never copy ROM files into the repo. Do not add features, refactors or tools I did not ask for.
   CHECK: Run `check.cmd`. Done means it exits 0 on a clean clone, and exits non-zero after you add a deliberate compile error. Run `python tools/verify_rom.py --rom-dir <ABSOLUTE_ROM_DIR>` and paste its output.
   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 and the ROM check. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whencheck.cmd passes on a clean clone, fails on a planted error, and verify_rom.py passes on your ROM set.

   Proof this works: KOF'98 Recomp, tmnt-port, https://github.com/sp00nznet/neogeorecomp

3. Build the reference and the input scripts

   Before any recompiling, you build the answer key. A reference runs the original code with the same inputs every time. You write small input scripts that reach each part of the game. Each run writes a hash for every frame.

   • Pick a reference. For the 68000, link Musashi as an interpreter. For other chips, use MAME itself, or MAME's CPU core inside your own runner.
   • To record with MAME, write a Lua script and run mame <SET> -autoboot_script tools/capture.lua. Use emu.add_machine_frame_notifier to save a hash of work RAM each frame.
   • Write input scripts in tests/controls/: coin and start, attract mode, one level, one boss. Use RAM pokes to start a later level.
   • Save the reference hashes for each script in build/reference/.
   • Run each script twice and confirm both runs give the same hashes. If not, find the random seed or timer first.
   Prompt for ClaudeCopy

   GOAL: Make a reference runner that plays tests/controls/<SCRIPT>.txt on the original <SET> code and writes one state hash per frame.
   READ FIRST: SCOPE.md, https://docs.mamedev.org/luascript/index.html, https://docs.mamedev.org/luascript/ref-common.html (emu.add_machine_frame_notifier), tests/controls/README.md.
   FENCE: Edit only tools/reference/ and tests/controls/. ROM files and MAME's own files are read-only. Do not start the recompiler.
   CHECK: Run the reference twice on the same script, writing build\reference\<SCRIPT>-1.txt and build\reference\<SCRIPT>-2.txt. Then run `fc /b build\reference\<SCRIPT>-1.txt build\reference\<SCRIPT>-2.txt`. Done means `fc` finds no differences, and a changed input line changes the hashes.
   BUDGET: Stop after 4 failed tries, or after 60 minutes with no new frame matching.
   IF BLOCKED: Stop. Do not work around it. If the runs differ, report the first differing frame and stop.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the `fc` or `cmp` output of the two runs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenfc /b finds no differences between two runs of the same script, and a changed input line changes the hash file.

   Proof this works: tmnt-port, The House of the Dead: ReWrithe, Super-Hang-On-Ultimate

4. Map the program and its code

   You find every routine in the main program. Static search from the reset and interrupt vectors finds only part of it. A pointer scan and a profile run find the rest. The map goes into a ledger file with a status column.

   • Load the main program into Ghidra. Pick the right chip and base address from the MAME driver.
   • Follow code from the vectors and jump tables. Then scan memory for values that look like code pointers.
   • Run each input script in a profile build that logs every entry point the interpreter had to run. neogeorecomp games do this with --dump-misses.
   • Write ledger/functions.tsv: address, size, kind (game, sound driver, copied to RAM), status.
   • Mark code that the game copies to RAM at boot. A static tool cannot see it.
   • Write tools/check_ledger.py. It prints every miss address that falls in no ledger row, then exits 1 if there are any.
   Prompt for ClaudeCopy

   GOAL: Write ledger/functions.tsv for the <CPU> main program of <SET>, with every routine found so far.
   READ FIRST: SCOPE.md, build/profile/misses.txt, the Ghidra project <GHIDRA_PROJECT> (through the MCP server if it is up).
   FENCE: Edit only ledger/, notes/map.md and tools/check_ledger.py. Do not rename anything in Ghidra yet. Do not write C.
   CHECK: Run `python tools/check_ledger.py ledger/functions.tsv build/profile/misses.txt`. Done means it prints 0 missing and exits 0. The ledger has address, size, kind and status columns, and its row count is in notes/map.md.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: Stop. Do not work around it. If the Ghidra MCP server is down, stop and ask. 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) Row counts by kind, and the miss check result. 3) Files changed. 4) Areas still unclear. 5) New parking-lot items.

   Done whenpython tools/check_ledger.py ledger/functions.tsv build/profile/misses.txt prints 0 missing and exits 0.

   Proof this works: KOF'98 Recomp, SpikeOut Recomp, The House of the Dead: ReWrithe

5. First light: recompile and boot

   You run the recompiler over the whole main program and link it with the runtime. Missing code falls back to the interpreter, so the game can boot early. The goal is a window showing the first frame, then attract mode.

   • Generate the C into build/generated/. For a Neo Geo game: cmake -S . -B build -D<GAME>_ROM_DIR=rom, then cmake --build build --config Release.
   • Stub nothing quietly. A missing chip register should log its address and stop.
   • Write tools/golden.cmd. It runs the game headless for a set number of frames with an input script and saves a screenshot.
   • Turn on the verify mode. Every recompiled block is replayed in the interpreter and compared: <GAME> --headless --verify --frames 1801 --input tests/coin_start.txt.
   Prompt for ClaudeCopy

   GOAL: Build the recompiled <SET> and reach the first attract-mode frame with no person.
   READ FIRST: SCOPE.md, ledger/functions.tsv, the recompiler docs <RECOMP_DOCS>.
   FENCE: Edit only runtime/, src/ and tools/golden.cmd. Never edit build/generated/; change the recompiler input and regenerate. No stub may return a fake value.
   CHECK: Run `tools\golden.cmd`. Done means it saves the frame <N> screenshot, exits 0, and the verify line reports 0 mismatches.
   BUDGET: Stop after 5 failed builds, or 90 minutes with no new frame reached.
   IF BLOCKED: Stop. Do not work around it. Report the last log lines and the address that stopped the run.
   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 verify line. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools\golden.cmd reaches the attract-mode frame, saves the screenshot, and the verify line says 0 mismatches.

   Proof this works: KOF'98 Recomp, https://github.com/sp00nznet/neogeorecomp

6. Fix one mismatch at a time

   Now you grind. Each unit is one mismatch: a frame where your hash differs from the reference. Claude finds the first differing frame and the first differing byte. Then it finds which code wrote that byte, and fixes the cause.

   • Run every input script on both sides and compare the hash files. The first differing frame is the bug's frame.
   • Dump RAM at that frame on both sides. Find the first differing byte and the code that wrote it.
   • Fix the recompiler or the runtime, never the generated C. Then rerun every script, not just the one that failed.
   • Record each fix in PROGRESS.md with its cause and the frame it fixed.
   Prompt for ClaudeCopy

   GOAL: Make tests/controls/<SCRIPT>.txt match the reference past frame <FRAME>.
   READ FIRST: CLAUDE.md, PROGRESS.md, build/diff/<SCRIPT>.txt, notes/findings.md.
   FENCE: Edit only the recompiler source in tools/recomp/ and runtime/. Never edit build/generated/, the reference hashes, or the check scripts.
   CHECK: Run `check.cmd`. Done means every script in tests/controls/ matches the reference hashes, including <SCRIPT> past frame <FRAME>.
   BUDGET: Stop after 3 failed fixes, or 60 minutes with no new matching frame.
   IF BLOCKED: Stop. Do not work around it. Give me the first differing frame, the byte, the code that wrote it, and your best cause.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the check summary. 3) Files changed. 4) The proven cause in one sentence. 5) New parking-lot items.

   Done whenEvery input script matches the reference hashes, and PROGRESS.md names the cause of the fix.

   Proof this works: SpikeOut Recomp, Super-Hang-On-Ultimate, Namco 22 Decompile

7. Finish the board: video, sound and input

   You replace the debug output with real video, sound and controls. Build each chip as its own library and test it alone. Check the video against MAME's picture and the sound against MAME's samples, before you judge the game.

   • Port each video chip's drawing rules from MAME's source. Keep the copyright notice and name the source file.
   • Use ymfm for Yamaha FM chips such as the YM2151, YM2610 and YM3438.
   • Use SDL2 or SDL3 for the window, sound and game pads.
   • Write a picture hash and a sound hash for every frame. Compare both against the reference. Add --video and --sound switches to check.cmd for this.
   • Pace frames by the clock if the screen ignores vsync.
   Prompt for ClaudeCopy

   GOAL: Make the <CHIP> stand-in match MAME's picture (or sound) for tests/controls/<SCRIPT>.txt.
   READ FIRST: CLAUDE.md, the MAME source file <MAME_FILE> for this chip, runtime/<CHIP>.c, build/diff/<SCRIPT>-video.txt.
   FENCE: Edit only runtime/<CHIP>.c and its header. Keep MAME's notice in any code you adapt. Do not change game logic or the reference.
   CHECK: Run `check.cmd --video --sound`. Done means every frame's picture hash and sound hash match for <SCRIPT>, and all older scripts still pass.
   BUDGET: Stop after 4 failed tries, or 90 minutes with no new matching frame.
   IF BLOCKED: Stop. Do not work around it. Save both frames as BMP files and tell me what differs.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the check summary. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whencheck.cmd --video --sound exits 0, so picture and sound hashes match the reference for every script.

   Proof this works: segasonic-port, tmnt-port, https://github.com/aaronsgiles/ymfm

8. Harden and package it

   You lock in your progress. Every input script becomes a regression test. You prove no ROM data is in the repo or the program. The player's PC builds the game from their own ROM set.

   • Run every script on a clean clone. Add a long soak run of 5 minutes or more.
   • Add a check that fails if any ROM-derived file is tracked by git.
   • Add a check that no executable holds a stretch of ROM bytes.
   • Build release packages with CI on clean machines. CI has no ROM, so game tests stay local.
   • Keep extras like widescreen behind a switch that is off by default, so the plain build still matches.
   Prompt for ClaudeCopy

   GOAL: Make a clean clone pass every check, and prove no ROM data ships.
   READ FIRST: CLAUDE.md, PROGRESS.md, tests/controls/, .github/workflows/.
   FENCE: Edit only tools/, tests/ and .github/workflows/. Do not change game behavior or reference hashes.
   CHECK: On a fresh clone, run `check.cmd`, the soak run, and `python tools/check_game_data.py`. Done means all three pass, and the game-data check fails when you stage a test file named rom/fake.bin.
   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 all three outputs and the planted failure. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenA fresh clone passes every script and the soak run, and the game-data check fails on a planted ROM file.

   Proof this works: OpenGP, tmnt-port, KOF'98 Recomp

Path B: Full decomp for porting

You turn every function into readable C that does exactly what the original does. Since most arcade games cannot be byte matched, the check is behavior. MAME's CPU core runs the original, your C runs beside it, and every frame's state, picture and sound must match. Names and types live in a text file, and a decompiler writes the C from it. When it all matches, you put the board behind an interface and port it.

1. Choose matching or behavior checks

   You decide how each function will be proven. If you know the original compiler and can run it, you can match bytes. If not, you prove behavior against MAME. Write the choice and the reason in SCOPE.md.

   • Look for a compiler mark in the program. On Triforce, mkgp2-decomp reads mw_comment_version to guess CodeWarrior 2.7.
   • If the code looks hand-written in assembly, plan for behavior checks. CannonBall's author found OutRun was 68000 and Z80 assembler.
   • Check if arcade-decomp supports your chips today: V60, V70, 68000 and Z80.
   • Check if objdiff supports your chip: PowerPC, SuperH, MIPS and x86 yes; 68000, V60 and i960 no.
   • Write the check for each kind of unit into SCOPE.md, on lines that start Check:. Start notes/compiler.md with a line Compiler: that names it or says unknown.
   Prompt for ClaudeCopy

   GOAL: Decide, with evidence, if <SET> can be byte matched or must be checked by behavior.
   READ FIRST: SCOPE.md, notes/map.md, the first 200 lines of the Ghidra listing at <ENTRY_ADDRESS>, https://github.com/cheviman/arcade-decomp, https://github.com/encounter/objdiff.
   FENCE: Edit only SCOPE.md and notes/compiler.md. Do not download any compiler. Do not write C.
   CHECK: Run `findstr /b /c:"Compiler:" notes\compiler.md && findstr /b /c:"Check:" SCOPE.md`. Done means both print and the command exits 0. The Compiler line names the compiler or says unknown, with the evidence and its addresses below it. SCOPE.md has one Check line for each unit type.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Do not work around it. If you cannot tell, say unknown. Do not guess a compiler.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Matching or behavior, in one line, then the evidence. 3) Files changed. 4) Open questions. 5) New parking-lot items.

   Done whenfindstr /b /c:"Compiler:" notes\compiler.md && findstr /b /c:"Check:" SCOPE.md exits 0.

   Proof this works: https://github.com/naari3/mkgp2-decomp, https://github.com/djyt/cannonball, OutRunners Port

2. Set up the decomp repo

   You build a repo where text files hold your knowledge and a script writes the C. Names, types and comments go in symbols.txt. The ROM stays outside git. Assets are cut from the ROM and must rebuild it byte for byte.

   • For a 68000, V60 or Z80 game, add the shared core: git submodule add https://github.com/cheviman/arcade-decomp tools/core.
   • Write tools/game_profile.py to tell the core your CPU, set name and memory layout.
   • For Triforce, start from dtk-template, run python configure.py, then ninja.
   • Write tools/verify_rom.py and tools/extract_assets.py --check. The check rebuilds the chips from the assets and compares bytes.
   • Write check.cmd and CLAUDE.md.
   Prompt for ClaudeCopy

   GOAL: Set up the decomp repo for <SET> so one command builds and checks it.
   READ FIRST: SCOPE.md, the arcade-decomp README sections 'A game's profile' and 'Using it in a game'.
   FENCE: Edit only tools/game_profile.py, tools/*.py wrappers, CMakeLists.txt, check.cmd and .gitignore. Never commit ROM files or generated C. Do not edit tools/core/.
   CHECK: Run `python tools/verify_rom.py`, `python tools/extract_assets.py --check` and `check.cmd`. Done means all three pass on a clean clone.
   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 all three outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenverify_rom.py, extract_assets.py --check and check.cmd all pass on a clean clone.

   Proof this works: tmnt-port, segasonic-port, https://github.com/cheviman/arcade-decomp

3. Build the reference and the scenarios

   You need a judge for every function. The reference runs the original program on MAME's CPU core against a model of the board. Your C runs the same input scripts. Both write hashes of state, picture and sound for every frame.

   • Use the core's reference if it fits: s32ref for System 32 and Multi 32, kref for Konami 68000 boards.
   • Otherwise, capture in MAME. Run mame <SET> -debug or a Lua script to save registers and RAM at a routine's entry and return.
   • Write scenarios that reach every area and boss. Use RAM pokes to start late areas.
   • Record which addresses each scenario ran. That tells you which scenarios test which function.
   Prompt for ClaudeCopy

   GOAL: Make the reference play every script in tests/controls/ and write per-frame hashes and executed addresses.
   READ FIRST: SCOPE.md, tools/core/<FAMILY>/reference/, https://docs.mamedev.org/debugger/execution.html.
   FENCE: Edit only tools/reference/ and tests/controls/. MAME files, ROM files and tools/core/ are read-only.
   CHECK: Run the reference twice on all scripts, into build\reference\run1\ and build\reference\run2\. Then run `fc /b build\reference\run1\*.txt build\reference\run2\*.txt`. Done means `fc` finds no differences, and each script has an executed-address list.
   BUDGET: Stop after 4 failed tries, or 60 minutes with no progress.
   IF BLOCKED: Stop. Do not work around it. If two runs differ, report the first differing frame.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Scenario count, frame count and the repeat check. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenfc /b finds no differences between the two runs, and every scenario has a list of the addresses it ran.

   Proof this works: tmnt-port, OutRunners Port, The House of the Dead: ReWrithe

4. Map every byte and check the disassembler

   You classify every byte of the program as code, data or fill. Before you trust a disassembler, you check it against MAME's at every offset. Then the static analysis must find all the code the reference ran.

   • Compare your disassembler with MAME's at every byte offset of the program ROM. The core has a script for each CPU: compare_with_mame.py (V60), compare_z80_with_mame.py (Z80) and compare_m68k_with_mame.py (68000).
   • Run python tools/coverage.py to classify every byte.
   • Put names, types and comments in symbols.txt. Give the evidence for each name.
   • Write docs/unreachable.txt: each piece of code no scenario runs, with a reason.
   • Build ledger/functions.tsv with a status column: raw, decompiled, named, proven.
   Prompt for ClaudeCopy

   GOAL: Prove the disassembler for <CPU> matches MAME's and classify every byte of the <SET> program.
   READ FIRST: CLAUDE.md, tools/core/<CPU>/, build/reference/executed.txt.
   FENCE: Edit only symbols.txt, docs/unreachable.txt and ledger/. Do not edit tools/core/ or src/.
   CHECK: Run the core's compare script for <CPU> (`compare_with_mame.py`, `compare_z80_with_mame.py` or `compare_m68k_with_mame.py` under tools/core/), then `python tools/coverage.py`, then `python tools/check_scenarios.py`. Done means 0 differences at every offset, every byte is classified, and every executed address is inside a known function.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: Stop. Do not work around it. List the first 10 offsets that differ from MAME and stop.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste both summaries. 3) Files changed. 4) Unclear areas. 5) New parking-lot items.

   Done whenThe disassembler matches MAME's at every offset, every byte is classified, and every executed address is in a known function.

   Proof this works: segasonic-port, tmnt-port, OutRunners Port

5. First light: one unit proven

   You prove the whole chain on one small unit. With behavior checks, start from a translation scaffold: one C line per instruction that already passes the scenarios. With matching, get one small function to an exact match.

   • Behavior route: build the scaffold with tools/recompile.py and run python tools/check_scenarios.py.
   • Then write the readable C for one small function with python tools/decompile.py, and check again.
   • Matching route: pick one small function, write its C, run ninja, and diff it in objdiff.
   • Break the function on purpose and confirm the check fails. Then fix it back.
   Prompt for ClaudeCopy

   GOAL: Prove one small function, <FUNCTION> at <ADDRESS>, end to end.
   READ FIRST: CLAUDE.md, symbols.txt, the reference trace for <ADDRESS>.
   FENCE: Edit only symbols.txt (and the one source file for <FUNCTION> if matching). Never edit generated C by hand. Do not touch other functions.
   CHECK: Run `python tools/check_scenarios.py --video --sound` (or `ninja` plus objdiff for matching). Done means it passes, and fails when you change one constant in <FUNCTION> on purpose.
   BUDGET: Stop after 5 tries.
   IF BLOCKED: Stop. Do not work around it. Paste the first difference and stop.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the passing check and the planted failure. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOne function passes its check, and a planted change makes the check fail.

   Proof this works: OutRunners Port, https://github.com/naari3/mkgp2-decomp

6. Decompile function by function

   Now you grind through the ledger. Each unit is one function. Claude adds names and types to symbols.txt, runs the decompiler, and checks the scenarios that ran that function. Many workers can run at once, each on a different file.

   • Pick the next functions from the ledger, smallest and most-called first.
   • Edit symbols.txt, then run python tools/decompile.py. Never edit src/ by hand.
   • Rerun only the scenarios that touched the change: python tools/select_scenarios.py --run.
   • Track readability with python tools/noise_report.py against tools/noise_baseline.txt. A rising count fails.
   • Mark each function proven in the ledger only after its scenarios pass.
   Prompt for ClaudeCopy

   GOAL: Make <FUNCTION> at <ADDRESS> readable and proven: real names, real types, no CPU leftovers.
   READ FIRST: CLAUDE.md, ledger/functions.tsv row for <ADDRESS>, symbols.txt, the current C in src/<FILE>.c (read only).
   FENCE: Edit only symbols.txt entries for <FUNCTION> and the data it touches. Never edit src/ by hand. Do not touch functions another worker owns.
   CHECK: Run `python tools/decompile.py`, then `python tools/select_scenarios.py --run`, then `python tools/noise_report.py`. Done means the selected scenarios pass and the noise count does not rise.
   BUDGET: Stop after 5 tries without progress.
   IF BLOCKED: Stop. Do not work around it. Name the first differing frame or the noise line that will not go away.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the scenario and noise summaries. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenEvery ledger row is proven: its scenarios pass and the noise report is at or below the baseline.

   Proof this works: tmnt-port, OutRunners Port, https://github.com/cheviman/arcade-decomp

7. Work the hard tail

   Some code fights back. It may be code no scenario reaches, jumps that cross in ways C loops cannot show, or math chips with odd rounding. Each hard unit gets a proven answer or a written reason.

   • Reach rare code with poked scenarios. Put the proof that the real game never gets there in the script's header.
   • For crossed jumps, allow a control flag and record why in the ledger.
   • Model math chips exactly. The House of the Dead had to copy the coprocessor's square root and the PC's 24-bit float math.
   • Work on one routine at a time. Capture its registers and RAM at entry and return in MAME. Then run your C on the same entry state.
   Prompt for ClaudeCopy

   GOAL: Prove <FUNCTION> at <ADDRESS>, which failed in bulk work, or give a proven reason it cannot be expressed as plain C.
   READ FIRST: CLAUDE.md, the ledger row and its failed-tries note, notes/findings.md, the MAME capture for <ADDRESS>.
   FENCE: Edit only symbols.txt for <FUNCTION> and notes/findings.md. Do not change the reference, the scenarios or tools/core/.
   CHECK: Run the routine compare for <ADDRESS> and `python tools/check_scenarios.py`. Done means 0 differences, or a written cause with addresses that a second session can reproduce.
   BUDGET: Stop after 6 tries that each test a different idea.
   IF BLOCKED: Stop. Do not work around it. Never call it impossible without the exact differing values.
   OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the compare output. 3) Files changed. 4) The cause in one sentence. 5) New parking-lot items.

   Done whenpython tools/check_scenarios.py passes, and each hard row in ledger/functions.tsv says proven or points to a cause with addresses in notes/findings.md.

   Proof this works: The House of the Dead: ReWrithe, tmnt-port, segasonic-port

8. Harden the whole-game check

   You make sure no old proof breaks. Every scenario runs on a clean clone. The structure of every function is checked against the program's jumps. A big-endian build runs the same scenarios.

   • Run python tools/check_scenarios.py --video --sound on a clean clone.
   • Run python tools/check_structure.py to check every function's ifs and loops against the program's jumps.
   • Run the big-endian check under qemu-ppc in WSL with python tools/big_endian_scenarios.py.
   • Store the last verified state in build/verified/ (or name a commit), so select_scenarios.py knows what changed.
   Prompt for ClaudeCopy

   GOAL: Make the full check suite pass on a clean clone, including the big-endian build.
   READ FIRST: CLAUDE.md, PROGRESS.md, the arcade-decomp README section 'What is here' (select_scenarios.py and big_endian_scenarios.py).
   FENCE: Edit only tools/ wrappers, CMakeLists.txt and check.cmd. Do not change src/, symbols.txt or the reference.
   CHECK: On a fresh clone, run `python tools/check_scenarios.py --video --sound`, `python tools/check_structure.py`, `python tools/noise_report.py` and `python tools/big_endian_scenarios.py`. Done means all four pass, and a planted constant change in one function makes check_scenarios fail.
   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 all four summaries and the planted failure. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenAll four checks pass on a fresh clone, and a planted change fails the scenario check.

   Proof this works: OutRunners Port, tmnt-port, https://github.com/cheviman/arcade-decomp

9. Port it behind a platform layer

   Now the C is proven, so you can move it. Put the window, sound and input behind a small interface. Build for the new system. Keep the faithful arcade build next to any changed version, so both stay checkable.

   • Make one folder per front end: ports/sdl2, ports/headless, and one for each new system.
   • List every function the new version replaces in one file, such as console/replaced.txt. The arcade build keeps the originals.
   • Fix 64-bit and byte-order problems with sanitizers: -fsanitize=alignment or AddressSanitizer.
   • Build device packages on the player's computer from their own ROM. Never share them.
   • Write ports/<TARGET>/check.cmd. It runs every scenario on the new system's headless build and compares each frame hash with the reference. The core's big_endian_scenarios.py is a model for this.
   Prompt for ClaudeCopy

   GOAL: Build <SET> for <TARGET_SYSTEM> and pass the same scenarios there.
   READ FIRST: CLAUDE.md, ports/PLAN.md, ports/sdl2/, console/replaced.txt.
   FENCE: Edit only ports/<TARGET>/ and the platform interface header. Do not change src/ or symbols.txt. Do not add features I did not ask for.
   CHECK: Run `ports\<TARGET>\check.cmd`, then `check.cmd`. Done means the first reports every frame hash matching the reference on all scenarios, and the desktop build still passes `check.cmd`.
   BUDGET: Stop after 4 failed builds 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 summaries. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenports\<TARGET>\check.cmd and check.cmd both exit 0.

   Proof this works: tmnt-port, OutRunners Port, segasonic-port

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 mismatch: the first frame where your hash differs from the reference. Each unit ends with every input script matching. For Path B, one unit is one function at one address. Each unit ends with its scenarios passing and the noise count not rising. Chip stand-ins are their own units, checked against MAME's picture or sound. 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.
- Never edit `build/generated/` or `src/`. Change `symbols.txt` or the generator, then regenerate.
- ROM files, reference hashes, `tests/controls/` and `tools/core/` are read-only.
- Never commit ROM data or anything made from it, including recompiled code.
- Prove every same-output claim with hashes. Never judge a frame by eye.
- Hardware reference order: MAME first, then <SECOND_REFERENCE>. Keep the copyright notice of any code you adapt.
- No stub may return a fake value. A missing register or call stops the run and prints its address.
- Enhancements default to off. The plain arcade build must still match the reference.
- Every run and every wait has a time limit. Stop a batch at its first failure.
- In a worktree, use the absolute path to the ROM folder: <ABSOLUTE_ROM_DIR>.
- Change only what was asked. Write other problems in notes/parking-lot.md and do not fix them.
- Commit only when I say so. Stage files by name, never with `git add -A`.

Keep the context small

• Give Claude one address, one ledger row and the first differing frame, not a whole trace.
• Never paste a MAME trace log. Let a subagent read it and return the first 20 lines that matter.
• Keep CLAUDE.md under one page. Point to docs/hardware-notes.md and notes/findings.md by name.
• Clear the chat after each unit. The ledger and PROGRESS.md carry the state.
• Run local sessions for game work. A cloud session starts from a fresh clone and cannot see your ROM files.

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> (MAME set <SET>) can be brought to PC, and by which technique.
READ FIRST: notes/mame-listsource.txt, notes/verifyroms.txt, the MAME driver <DRIVER_PATH> (top comment and machine setup only), notes/prior-work.md.
FENCE: Edit only SCOPE.md and notes/. Do not download ROMs, BIOS files or tools.
CHECK: Run `findstr /b /c:"Board:" SCOPE.md && findstr /b /c:"CPUs:" SCOPE.md && findstr /b /c:"Protection:" SCOPE.md && findstr /b /c:"Technique:" SCOPE.md && findstr /b /c:"Prior work:" SCOPE.md`. Done means all five lines print and it exits 0. CPUs gives each role and the video and sound chips. Protection says none or names the chip. Technique gives one reason against each other technique.
BUDGET: Stop after 60 minutes.
IF BLOCKED: If the board has no working MAME driver, or the set is encrypted with no known key, 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: Build ledger/functions.tsv for the <CPU> program of <SET>.
READ FIRST: SCOPE.md, the Ghidra project <GHIDRA_PROJECT>, build/profile/misses.txt, build/reference/executed.txt.
FENCE: Edit only ledger/, notes/map.md and tools/check_ledger.py. Do not write C. Do not rename symbols in Ghidra yet.
CHECK: Run `python tools/check_ledger.py ledger/functions.tsv build/profile/misses.txt build/reference/executed.txt`. Done means it prints 0 missing and exits 0. Each row has address, size, kind and status. notes/map.md gives the row count by kind.
BUDGET: Stop after 90 minutes.
IF BLOCKED: If the Ghidra MCP server is down, stop and ask. 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) Counts and the executed-address check. 3) Files changed. 4) Unclear areas. 5) New parking-lot items.

GOAL: Make tests/controls/<SCRIPT>.txt match the reference past frame <FRAME>.
READ FIRST: CLAUDE.md, PROGRESS.md, build/diff/<SCRIPT>.txt, notes/findings.md.
FENCE: Edit only tools/recomp/ and runtime/. Never edit build/generated/, reference hashes or check scripts.
CHECK: Run `check.cmd`. Done means every script in tests/controls/ matches, and <SCRIPT> passes frame <FRAME>.
BUDGET: Stop after 3 failed fixes or 60 minutes.
IF BLOCKED: Stop. Give me the first differing frame, the byte, the code that wrote it, and your best cause.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the check summary. 3) Files changed. 4) The proven cause. 5) New parking-lot items.

GOAL: Make <FUNCTION> at <ADDRESS> readable and proven.
READ FIRST: CLAUDE.md, the ledger row for <ADDRESS>, symbols.txt, src/<FILE>.c (read only).
FENCE: Edit only the symbols.txt entries for <FUNCTION> and the data it reads. Never edit src/ by hand.
CHECK: Run `python tools/decompile.py`, `python tools/select_scenarios.py --run` and `python tools/noise_report.py`. Done means the scenarios pass and the noise count does not rise.
BUDGET: Stop after 5 tries without progress.
IF BLOCKED: Stop. Name the first differing frame or the noise line that stays.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Paste the scenario and noise summaries. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Start <N> workers on the next <N> units from ledger/functions.tsv.
READ FIRST: CLAUDE.md, PROGRESS.md, ledger/functions.tsv, notes/parking-lot.md.
FENCE: Edit only ledger/claims.tsv. Each worker gets its own worktree under .claude/worktrees/ and one source file nobody else owns. Do not do unit work yourself.
CHECK: After the batch, merge each worker's branch one at a time and run `check.cmd` after each merge. Done means every merged unit passes on the merged branch.
BUDGET: Stop the batch at its first failed merge.
IF BLOCKED: Stop. Do not work around it. Tell me which merge failed and why.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) A table of unit, worker, result. 3) Files changed. 4) Units to retry as hard jobs. 5) New parking-lot items.

GOAL: Find the proven cause of <SYMPTOM> in tests/controls/<SCRIPT>.txt. Do not fix it yet.
READ FIRST: CLAUDE.md, the last 20 lines of build/logs/<SCRIPT>.log, build/diff/<SCRIPT>.txt.
FENCE: Edit only notes/findings.md and temporary files in build/tmp/. No code changes.
CHECK: Run `check.cmd` twice. Done means both runs report the same first differing frame, and notes/findings.md names that frame, the first differing byte or register, and the instruction that caused it, with addresses.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Tell me what you ruled out and what you need next, such as a new MAME capture.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The cause in one sentence, then the evidence. 3) Files changed. 4) A proposed fix for me to approve. 5) New parking-lot items.

GOAL: Check that the units claimed in PROGRESS.md since <COMMIT> are real.
READ FIRST: CLAUDE.md, `git diff <COMMIT>..HEAD --stat`, PROGRESS.md.
FENCE: Read only. Do not fix anything.
CHECK: On a fresh clone, run `check.cmd` and the full scenario check. Then look for edited reference hashes, removed or shortened scenarios, edited generated C, stubs that return fixed values, enhancements turned on by default, and edits outside each unit's fence.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Tell me what you could not check and why.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) PASS or FAIL. 2) Paste the check outputs. 3) Each problem with file and line. 4) Claims you could not confirm. 5) New parking-lot items.

GOAL: Report project status with numbers from the ledger.
READ FIRST: PROGRESS.md, ledger/functions.tsv, tests/controls/, notes/parking-lot.md.
FENCE: Read only. No prose padding.
CHECK: Get each count with a command, such as `findstr /c:"proven" ledger\functions.tsv | find /c /v ""`, and get the scenario count from `check.cmd`. Done means every number has the file or command beside it.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop. Say which number you could not get.
REPORT: 1) Units done, in progress and blocked, by kind. 2) Scenarios passing out of total. 3) The noise count or mismatch count against last week. 4) The top three blockers. 5) Parking-lot items for me to decide.

GOAL: Write what the next session needs into the repo files.
READ FIRST: PROGRESS.md, notes/findings.md, the current task card.
FENCE: Edit only PROGRESS.md, notes/findings.md and docs/handoff.md.
CHECK: Run `findstr /b /c:"Current unit:" docs\handoff.md && findstr /b /c:"Next step:" docs\handoff.md && findstr /b /c:"Starting prompt:" docs\handoff.md`. Done means all three print. The file also holds the last check output and what was tried and failed.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop. Say what you could not record.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) The next step in one line. 3) Files changed.

GOAL: Give me a plain answer on <TASK>: can it be done now, and how?
READ FIRST: the last task card, its report, notes/findings.md.
FENCE: Read only. Do not try again.
CHECK: Run `check.cmd` once and paste its last 20 lines. Do not change any file first. Your answer is one of DONE, PARTIAL or BLOCKED, with that output as proof. 'Should work' is not an answer.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Say exactly what is missing: a MAME capture, a chip document, a ROM revision, or my decision.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) What cannot be done and why. 3) Two or three options, each with its cost in time. 4) Your pick and one reason.

GOAL: Ask me before you change anything outside your fence for <TASK>.
READ FIRST: SCOPE.md, the current task card.
FENCE: Change nothing until I answer. Read only.
CHECK: Run `git status --short`. Done means it lists no file you changed, and your request names the files you want to change, why, what could break, and the check that proves it did not.
BUDGET: Stop after 10 minutes.
IF BLOCKED: Stop and wait for my answer.
OTHER PROBLEMS: Write them in notes/parking-lot.md. Do not fix them.
REPORT: 1) The change you want, in one line. 2) The files. 3) The risk. 4) The check that proves it safe. 5) What you will do if I say no.

Keep Claude on task

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

Problems other projects hit

How long it takes

What makes it faster or slower

• The board. A 68000 game with a toolkit is much faster than a 3D board with no toolkit.
• How many chips run code. Each sound chip, math chip or I/O chip needs its own translation.
• Protection and encryption. A security chip can block a project until someone models it.
• Whether MAME emulates the board well. A weak MAME driver means no good answer key.
• Program size. TMNT has 2,439 functions and OutRunners 762, while 3D games have thousands more.
• For Path B, the compiler. Assembly games need behavior checks, which need many scenarios to cover the code.

The facts behind these numbers

Projects reviewed (12)

We took the top-starred project for each of the 12 most-starred arcade games on RecompLauncher. The catalog lists 24 arcade projects for 23 games, and the store flags 17 for AI use. For Path B we also read naari3/mkgp2-decomp from outside the catalog.

What each project teaches

What we could not check

• How AI was used in most projects. Only SpikeOut Recomp publishes its agent rules. The others give one README line or nothing.
• Whether Namco 22 Decompile, SegaSonic or Super Hang-On used AI. The store flags two of them, but the repos say nothing.
• The name and code of Namco 22 Decompile's main CPU translator. Only its output is public.
• The original compiler for any reviewed V60, i960, SH-4, Model 3 or Namco game. No project names one.
• That most 1980s arcade games were written in assembly. We confirmed it only for OutRun, from the CannonBall README.
• The mkgp2-decomp compiler. Its README calls CodeWarrior 2.7 a guess still to be re-checked.
• The total hours behind any project. Most hide early work, and only VCThunder gives a rough figure.
• A reported Sonic the Fighters decomp from May 2025. The news page returned an error, so we could not read it.
• The MinGW-w64 apt install line. It comes from the VCThunder card, not from mingw-w64.org.
• That the static-recomp-av-compare skill works with MAME's -aviwrite recordings. We did not test it.
• The command-line arguments of arcade-decomp's scripts. Its README names each script and some switches (--video, --sound, --run, --big-endian), but no full usage. No script was run here.
• Which JDK Ghidra 12.1.4 needs for GhidraMCP. The Ghidra README read here is for 12.2, which asks for JDK 25.
• That check_ledger.py, golden.cmd, check.cmd switches and ports/<TARGET>/check.cmd work as described. They are scripts you write; no reviewed project ships them under these names.
• None of the commands in this guide were run on a real game here. They come from tool docs and project READMEs.
• The 1971 date. It comes from the site's shared platform table, not from a source we read.

Sources

• MAME release page (0.289)
• MAME debugger docs
• MAME execution debugger commands (trace)
• MAME Lua scripting docs
• MAME Lua reference: common (frame notifier)
• MAME Konami TMNT driver (68000 code on even and odd chips)
• MAME Sega System 32 driver (V60 and V70)
• MAME command-line options
• MAME Namco System 22 driver
• MAME Namco System 23 driver
• MAME Sega Model 2 driver
• MAME Sega Model 3 driver
• arcade-decomp README
• tmntarcade-decomp README
• outrunners-decomp README
• segasonic-decomp README
• neogeorecomp README
• mkgp2-decomp README, CLAUDE.md and AGENTS.md
• CannonBall README
• Reassembler blog, rewrite posts
• Musashi README
• Ghidra README
• GhidraMCP README
• Supermodel README
• objdiff README
• decomp-toolkit README
• dtk-template README
• dtk-template dependencies (Python, Ninja)
• mkgp2-decomp matching skill (Ghidra MCP note, objdiff)
• Python downloads
• Ninja releases
• Visual Studio downloads (Build Tools)
• CMake downloads
• uv (needed by GhidraMCP)
• ymfm README
• llvm-mingw releases
• SDL releases
• SpikeOut Recomp repo (CLAUDE.md, docs/handoff.md)
• OpenGP repo