Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Technique:Matching decompilation

From ReverseEngineering.wiki
Technique
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

  1. 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 0x1000 and 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.
  2. 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.
  3. Rebuild and compare with the original toolchain (e.g. GCC 2.x cc1 plus an assembler shim for PlayStation, Metrowerks CodeWarrior for GameCube/Wii and PSP) and a differ (asm-differ, objdiff).
  4. 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 .sha1 file) 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_800EA5E4 or D_800A21B8 mean 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

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 overlay rom:0x...), so overlay names are kept by ROM offset instead of only the first name at an address.

Examples