Technique:Matching decompilation
| On this wiki | Facts · Code · Notes · Topics |
|---|
Rewriting a program's machine code as source code that, built with the original compiler and flags, produces a byte-identical binary. The match is a mechanical proof that the source is equivalent to the original, so the structure layouts, globals and memory maps that such projects publish are exact for the build they target.
Overview
A matching decompilation is checked function by function and file by file against the original binary: the build hashes its output and compares it with the hashes of the retail files. Unmatched functions stay as included assembly, so the project always builds and the hash check stays meaningful.
Workflow
- Split the binary into sections, files and functions with a configuration that lists segment offsets, load addresses and symbol names (splat for MIPS/PlayStation/N64 projects, where the first code segment starts at ROM offset
0x1000and is linked at the header's entry point, see Platform:Nintendo 64#Boot sequence; decomp-toolkit/dtk for GameCube and Wii). The configuration and symbol files of a project are a ready-made memory map of the target build. - Draft C for one function with a decompiler aimed at matching (m2c for MIPS and PowerPC), with a context file of the project's headers.
- Rebuild and compare with the original toolchain (e.g. GCC 2.x
cc1plus an assembler shim for PlayStation, Metrowerks CodeWarrior for GameCube/Wii and PSP) and a differ (asm-differ, objdiff). - Fix the last differences (register allocation, instruction order) by hand or with decomp-permuter; share scratches on decomp.me.
Using a matching decompilation for reverse engineering
- Exact for one build only. Addresses and sizes come from that build's files; the project's hash list (often a
.sha1file) names the exact files. A different region or revision needs its own map. - Names are the contributors' choices, not original symbols, unless the project says debug symbols were available. Names like
func_800EA5E4orD_800A21B8mean unnamed. Layouts and sizes are proven by the match; meanings of fields are interpretations. - Struct headers (
include/*.h) usually annotate each field with its offset, which makes them directly importable into Ghidra or IDA. - Non-matching functions are marked (
NON_MATCHING,INCLUDE_ASM); their C is a hint, not proof. - Assets are not in the repository: they are extracted from the user's own copy at build time.
Known projects
Where to find the ground truth in each repository (paths as read in the pinned commits listed under Code & repositories; "not checked" means the location was not looked at).
| Game | Platform | Repository | Hash file (original files) | Symbol / split files | Wiki page |
|---|---|---|---|---|---|
| Super Smash Bros. Melee (GALE01) | GameCube | doldecomp/melee (no license: facts only) | config/GALE01/build.sha1, config.yml hash: |
config/GALE01/symbols.txt, splits.txt (decomp-toolkit syntax) | Software:Super Smash Bros. Melee |
| Pikmin 2 (GPVE01, GPVJ01, GPVP01, debug builds) | GameCube | doldecomp/pikmin2 (CC0) | config/<GAMEID>/build.sha1 | config/<GAMEID>/symbols.txt, splits.txt (names from a linker map) | Software:Pikmin 2 |
| Super Mario Sunshine (GMSE01, GMSJ01, GMSP01) | GameCube | doldecomp/sms (CC0) | config/<GAMEID>/build.sha1 (executable named mario.dol) | config/<GAMEID>/symbols.txt, splits.txt (from the original .MAP) | Software:Super Mario Sunshine |
| The Legend of Zelda: The Wind Waker | GameCube | zeldaret/tww (CC0) | config/<GAMEID>/build.sha1 | config/<GAMEID>/symbols.txt, splits.txt | Software:The Legend of Zelda: The Wind Waker |
| Super Mario 64 (jp, us, eu, sh, cn) | Nintendo 64 | n64decomp/sm64 (CC0) | sm64.<version>.sha1 in the root | no symbol list in the repository: names are in the C sources; the linker map is a build output | Software:Super Mario 64 |
| Sly Cooper and the Thievius Raccoonus (SCUS_971.98) | PlayStation 2 | TheOnlyZac/sly1 (CC0) | config/checksum.sha1 | config/symbol_addrs.txt (about 5,400 names), config/sly1.yaml (splat segments) | Software:Sly Cooper and the Thievius Raccoonus |
| Pokemon Emerald (BPEE) | Game Boy Advance | pret/pokeemerald (no license: facts only) | rom.sha1 | ld_script.ld (link order), sym_ewram.txt / sym_bss.txt / sym_common.txt (order of RAM variables, no addresses); addresses come from the built map | Software:Pokémon Emerald |
| Castlevania: Symphony of the Night (US SLUS-00067) | PlayStation | Xeeynamo/sotn-decomp (AGPL-3.0) | config/check.us.sha (SHA-1 of every original file; also check.hd.sha, check.pspeu.sha, check.saturn.sha) | config/symbols.us.txt (994 lines, boot EXE and library names), one config/symbols.us.<overlay>.txt and splat.us.<overlay>.yaml per overlay | Software:Castlevania: Symphony of the Night |
| The Legend of Zelda: The Minish Cap | Game Boy Advance | zeldaret/tmc (license unknown) | tmc*.sha1 in the root, INSTALL.md | not checked | none yet |
| The Legend of Zelda: Twilight Princess (GZ2E01/P01/J01 GameCube; RZDE01_00, RZDE01_02, RZDP01, RZDJ01 Wii; Shield) | GameCube, Wii | zeldaret/tp (CC0) | config/<GAMEID>/build.sha1 (one line per DOL and REL), config.yml hash: |
config/<GAMEID>/symbols.txt, splits.txt and config/<GAMEID>/rels/<module>/symbols.txt | Software:The Legend of Zelda: Twilight Princess, Platform:Nintendo Wii |
| Paper Mario (us, jp, pal, ique) | Nintendo 64 | pmret/papermario (no license: facts only) | ver/<version>/checksum.sha1, README table | ver/<version>/symbol_addrs.txt (splat syntax), splat.yaml | Software:Paper Mario |
| Metroid Prime (GM8E01_00/01/02/48, GM8EAB_00, GM8J01_00/DD, GM8P01_00, R3IJ01_00, R3ME01_00, R3MP01_00) | GameCube, Wii | PrimeDecomp/prime (CC0-1.0 as reported by the symbol importer; the Metroid Prime page said none was detected earlier) | config/<GAMEID>/build.sha1 (main.dol and a REL), config.yml hash: |
config/<GAMEID>/symbols.txt, splits.txt | Software:Metroid Prime |
| Animal Crossing (GAFE01_00, GAFU01_00) | GameCube | ACreTeam/ac-decomp | config/<GAMEID>/build.sha1 (static.dol, foresta.rel) | config/<GAMEID>/symbols.txt, splits.txt, foresta/ module folder | Software:Animal Crossing |
| Mario Party 4 (GMPE01_00/01, GMPJ01_00, GMPP01_00/01/02) | GameCube | mariopartyrd/marioparty4 | config/<GAMEID>/build.sha1 (main.dol plus many RELs) | config/<GAMEID>/symbols.txt, splits.txt, rels/ per-module files | Software:Mario Party 4 |
| SpongeBob SquarePants: Battle for Bikini Bottom (GQPE78) | GameCube | bfbbdecomp/bfbb | config/GQPE78/build.sha1 (main.dol only) | config/GQPE78/symbols.txt, splits.txt, ldscript.tpl | Software:SpongeBob SquarePants: Battle for Bikini Bottom |
| The Legend of Zelda: Breath of the Wild (v1.5.0 main NSO) | Nintendo Switch | zeldaret/botw (no license file: names and addresses only) | SHA-256 in tools/setup.py (uncompressed 1.5.0: d9fa308d...c106) | data/uking_functions.csv (Address,Quality,Size,Name; 113k rows, address = 0x7100000000 + offset), data/data_symbols.csv | Software:The Legend of Zelda: Breath of the Wild, Format:NSO |
| Super Mario Odyssey (1.0.0 main NSO) | Nintendo Switch | MonsterDruide1/OdysseyDecomp (no license file: names and addresses only) | SHA-256 in tools/setup.py (uncompressed: 18ece865...b4eb) | data/file_list.yml (offset, size, label, status), data/data_symbols.csv, data_strings.csv; no function CSV | Software:Super Mario Odyssey, Format:NSO |
| Minecraft: Nintendo Switch Edition (1.0.17 main NSO) | Nintendo Switch | GRAnimated/MinecraftLCE (no license file: names and addresses only) | SHA-256 in tools/setup.py (uncompressed: f408dbfb...cef8) | data/mcswitch_functions.csv (Address,Quality,Size,Name; 58k rows, 21k named), data/data_symbols.csv | Software:Minecraft: Nintendo Switch Edition, Format:NSO |
| Chrono Cross (JP SLPS_023.64) | PlayStation | jdperos/chrono-cross-decomp (no license file) | sha1: in config/slps_023.64.yaml (config/checksum.sha has a SHA-256 of the rebuilt file) |
config/symbol_addrs.slps_023.64.txt (838 lines) | Software:Chrono Cross |
| Ridge Racer (JP SLPS-00001) | PlayStation | kazuyette/rr-decomp (MIT) | sha1: in rr.yaml and README |
symbol_addrs.txt (328 lines), undefined_syms.txt | Software:Ridge Racer |
| King's Field: The Ancient City (US SLUS-20318) | PlayStation 2 | Voicedrew11/kfiv-decomp (MIT) | config/sha1sums.txt (ELF and loaded image) | config/symbol_addrs.txt (about 4,500 lines) | Software:King's Field: The Ancient City |
| God Hand (US SLUS-21503) | PlayStation 2 | LucasPicoli/god-hand-decomp (MIT) | config/versions.json (elf_sha256, rom_sha1) | config/symbol_addrs.txt (about 50,000 lines, mostly Ghidra-seeded placeholders; not imported) | Software:God Hand |
| Snowboard Kids (North America) | Nintendo 64 | tenry92/sbk-decomp (no license file) | sha1: in snowboardkids.yaml |
symbol_addrs.txt (43 lines) | Software:Snowboard Kids |
| Mario Kart 64 (USA, EUR 1.0, EUR 1.1) | Nintendo 64 | n64decomp/mk64 (no license file) | mk64.us.sha1, mk64.eu.v10.sha1, mk64.eu.v11.sha1 in the root | no symbol list found in the root (undefined_syms.txt holds libultra and hardware symbols) | Software:Mario Kart 64 |
| Banjo-Kazooie (US 1.0, US 1.1, JP, PAL) | Nintendo 64 | n64decomp/banjo-kazooie | README "Baserom checksums" (decompressed.<ver>.yaml has a different sha1:) |
symbol_addrs.<ver>.txt (about 60 lines), level_symbols and manual_syms files | Software:Banjo-Kazooie |
| LEGO Island 1.1 English (ISLE.EXE, LEGO1.DLL, CONFIG.EXE) | Windows x86 (MSVC 4.2) | isledecomp/isle | sha256 per target in reccmp-project.yml, md5 list in README.md | no symbol file: addresses are // FUNCTION: LEGO1 0x10001000 comments in ISLE/, LEGO1/, CONFIG/ (names extracted with a script, see the Build) |
Software:LEGO Island, Tool:Reccmp |
| Colin McRae Rally 2.0 (CMR2.exe) | Windows x86 (MSVC 6.0 SP3) | pablocpas/CMR2Decomp (GPL-3.0 file, heavily AI-assisted) | sha256 in reccmp-project.yml | // FUNCTION: CMR2 0x... and // GLOBAL: CMR2 0x... comments in CMR2Decomp/ (3364 and 3227 by grep) |
Software:Colin McRae Rally 2.0, Tool:Reccmp |
| LEGOLAND (legoland.exe) | Windows x86 (MSVC 6.0, C) | marijnvdwerf/legoland (no license file) | sha256 in reccmp-project.yml | // FUNCTION: LEGOLAND 0x... comments in src/legoland/ (about 825 with real names; the rest are FUN_ placeholders) |
Software:LEGOLAND, Tool:Reccmp |
Versions registered as builds on this wiki with their symbols.txt imported (SHA-1 from build.sha1): Metroid Prime GM8E01_00, GM8E01_01, GM8E01_02, GM8E01_48 (USA), GM8EAB_00, GM8J01_00, GM8J01_DD (Japan), GM8P01_00 (PAL, two NES-emulator RELs); Super Mario Sunshine GMSE01, GMSJ01, GMSJ01_01, GMSP01, GMSP01_NX; Pikmin 2 GPVE01, GPVJ01, GPVP01 (the repository also has GPVE01_D17 and GPVE01_D18 debug-build folders, not registered); Twilight Princess GZ2E01, GZ2P01, GZ2J01 (main DOL only; the Wii versions are listed next; the RELs are not imported); BFBB GQPE78 (the repository has only that version); Melee: doldecomp/melee has only config/GALE01. Metroid Prime Wii (Trilogy) versions R3ME01_00, R3MP01_00 and R3IJ01_00 are registered as Nintendo Wii builds (SHA-1 of the main DOL from build.sha1) with symbols.txt imported, as are the Twilight Princess Wii main DOLs RZDE01_00, RZDE01_02, RZDP01 and RZDJ01 (REL modules not imported). Pinned commits: pikmin2 f8e0ee39ae, sms a4f61f10bb, tp c8fa8c9e2a, prime 4ae7e0a328. Names come from the same repository at the pinned commit shown on each build page, so names differ slightly between regions (the PAL and JP symbol files are 25-27k lines each).
Pattern: projects that use Tool:Decomp-toolkit keep build.sha1, symbols.txt and splits.txt per game ID under config/; splat projects (Tool:Splat) keep a YAML segment file plus a symbol_addrs.txt; the older N64 and GBA projects (sm64, pokeemerald) have only a hash file and rely on the source tree and linker script. Only a symbol file that came from an original linker map carries original names; in the others names are the contributors' choices.
Code & repositories
- {{Repo|url=https://github.com/doldecomp/melee%7Ccommit=f0cdbb0a7046aea44c7177fd72abf33c3d2af4d4%7Clicense=none%7Cdescription=Matching decompilation of GALE01 with decomp-toolkit config, symbols.txt and splits.txt|tested_on=source read, not run: not built; read config files only|checked=checked 2026-10-18; last activity 2026-10-16; no license: not reusable}}
- {{Repo|url=https://github.com/doldecomp/sms%7Ccommit=b2350a119b0e113e6cebc389fda9af00328ee85e%7Clicense=CC0-1.0%7Cdescription=Matching decompilation of Super Mario Sunshine (GMSE01, GMSJ01, GMSP01)|tested_on=source read, not run: read config files only|checked=checked 2026-10-18; last activity 2026-10-17}}
- {{Repo|url=https://github.com/doldecomp/pikmin2%7Ccommit=f8e0ee39aec178f6d87bf7edb60c213b58144c5f%7Clicense=CC0-1.0%7Cdescription=Matching decompilation of Pikmin 2 (GPVE01, GPVJ01, GPVP01 and debug builds)|tested_on=source read, not run: read config files only|checked=checked 2026-10-18; last activity 2026-10-14}}
- {{Repo|url=https://github.com/TheOnlyZac/sly1%7Ccommit=ea5e2d77ac2a083df1efeafcee178f895943b13d%7Clicense=CC0-1.0%7Cdescription=Matching decompilation of Sly Cooper and the Thievius Raccoonus (NTSC-U SCUS_971.98) for PS2. Useful without building: config/sly1.yaml (splat segments), config/symbol_addrs.txt (about 5,400 names and addresses), config/checksum.sha1, docs/mips_ps2_cheatsheet.md, configure.py (ee-gcc 2.95.2 flags).|tested_on=source read, not run: Read at commit ea5e2d7: config files, README, configure.py; not built (needs the game disc)|checked=checked 2026-10-18; last activity 2026-10-11}}
- {{Repo|url=https://github.com/zeldaret/tmc%7Ccommit=6fb6dfb4a7efbe24d0fd1dda5097af6131faacde%7Clicense=unknown%7Cdescription=Matching decompilation of The Legend of Zelda: The Minish Cap for the GBA (USA, EU, JP, USA demo, JP demo). INSTALL.md and the tmc*.sha1 files list the SHA-1 of each ROM.|tested_on=source read, not run: Read at commit 6fb6dfb: INSTALL.md, sha1 files; not built|checked=checked 2026-10-18}}
- {{Repo|url=https://github.com/n64decomp/sm64%7Ccommit=9921382a68bb0c865e5e45eb594d9c64db59b1af%7Clicense=CC0-1.0%7Cdescription=Matching decompilation of Super Mario 64 (jp, us, eu, sh, cn). Useful without building: README and sm64.*.sha1 (SHA-1 of every ROM), Makefile (IDO 5.3 flags, per-file overrides, iQue egcs), assets.json.|tested_on=source read, not run: Read at commit 9921382: README, Makefile, sha1 files; not built|checked=checked 2026-10-18; last activity 2024-02-04}}
- {{Repo|url=https://github.com/ethteck/splat%7Ccommit=7548b9771e6f8418507b23434187fb07741af6d4%7Clicense=MIT%7Cdescription=Binary splitter for N64, PSX, PS2, PSP and GBA decompilation projects: YAML config, symbol_addrs.txt and linker script generation.|tested_on=source read, not run: Read the README and the configs of three projects that use it; not run|checked=checked 2026-10-18; last activity 2026-10-10}}
- {{Repo|url=https://github.com/zeldaret/botw%7Ccommit=28de09ade7a2ac4c9fc22c82edad348555617181%7Clicense=none%7Cdescription=Work-in-progress decompilation of Breath of the Wild 1.5.0: data/uking_functions.csv (Address,Quality,Size,Name), data_symbols.csv, tools/setup.py with the NSO SHA-256 hashes.|tested_on=source read, not run: Breath of the Wild 1.5.0 (Switch)|checked=checked 2026-10-18; last activity 2026-10-18; no license: not reusable}}
- {{Repo|url=https://github.com/MonsterDruide1/OdysseyDecomp%7Ccommit=696db2ff5ed558b053c753de420504b8682f24b0%7Clicense=none%7Cdescription=Work-in-progress decompilation of Super Mario Odyssey 1.0.0: data/file_list.yml (per-function offsets and status), data_symbols.csv, data_strings.csv, tools/setup.py with the NSO SHA-256 hashes.|tested_on=source read, not run: Super Mario Odyssey 1.0.0 (Switch)|checked=checked 2026-10-18; last activity 2026-10-12; no license: not reusable}}
Pitfalls
- A function can match while a nearby global is misnamed or its size is wrong (data that nobody has typed yet). Check the referencing code before relying on a data size.
- Overlays linked to the same address appear in several configuration files with overlapping addresses; always note which overlay an address belongs to.
- Symbol maps on this wiki keep names that share an address apart by the splat
rom:0x...offset (each becomes overlayrom:0x...), so overlay names are kept by ROM offset instead of only the first name at an address.
Examples
- Software:Castlevania: Symphony of the Night (Platform:PlayStation, PSP, Saturn): splat + m2c + maspsx + GCC 2.6
cc1. - Software:The Legend of Zelda: The Wind Waker (Platform:Nintendo GameCube): decomp-toolkit + Tool:Metrowerks CodeWarrior GC/1.3.2 + objdiff.
config/<GAMEID>/build.sha1names the exact DOL and RELs,symbols.txtlists every symbol asname = .section:0xADDRESS; // type:function size:0x..andsplits.txtgives each source file's address range, so library code (Library:Dolphin SDK, Library:JSystem) is delimited exactly. Its symbol names come from an original linker map, not from contributors.