Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Retro Game Decompilation (+ AI)

Retro Game Decompilation (+ AI)

Let’s explore matching decompilation in retro games: the art of rewriting high-level code that, when compiled, produces a binary identical to the original one. And more: we’ll see how LLMs can help on this fantastic challenge!

Rewriting a classic game’s code accurately helps preserve its legacy and paves the way to a deeper understanding of the game, allowing for modifications that create new experiences.

Are you curious about it? Take a look at my GitHub and essay:
- Development journey: https://gambiconf.substack.com/p/development-journey-on-game-decompilation
- Pipeline runner for matching decompilation: https://github.com/macabeus/mizuchi
- VS Code extension for matching decompilation: https://github.com/macabeus/kappa

Bruno Macabeus

November 05, 2026

Transcript

172 slides
  1. preamble And they even match decompiled the game itself! The

    community completed a matching decompilation for this game!
  2. Disassembly A disassembler is a tool that does the reverse

    process of an assembler. That is, it converts a binary back into assembly. 0x23 0xF3 0x80 0xFD bl 08367610h 0x78 0x46 mov r0, r15 0x3C 0x30 Disassembly ARMv4T add r0, 3Ch (Thumb instructions) bx r0 0x00 0x47
  3. Disassembly There are some challenges that a good disassembler needs

    to handle. For example: - We might have multiple instructions set. For example, on GBA we have ARM and Thumb - Distinguish instructions and data
  4. Disassembly There are some challenges that a good disassembler needs

    to handle. For example: - We might have multiple instruction sets. For example, on GBA we have ARM and Thumb - Distinguish instructions and data
  5. Disassembly There are some challenges that a good disassembler needs

    to handle. For example: - We might have multiple instruction sets. For example, on GBA we have ARM and Thumb - Distinguish code vs. data
  6. Disassembly u32 GetActionCost(u32 action) { switch (action) { case 0:

    return 10; case 1: return 25; case 2: return 30; case 3: return 45; case 4: return 60; } return action; }
  7. Disassembly GetActionCost: push {lr} cmp r0, #4 bhi _0800003A lsls

    r0, r0, #2 ldr r1, _08000010 @ =_08000014 adds r0, r0, r1 ldr r0, [r0] mov pc, r0 _08000010: .4byte _08000014 @ table address _08000014: @ the jump table .4byte _08000028 @ case 0 .4byte _0800002C @ case 1 .4byte _08000030 @ case 2 .4byte _08000034 @ case 3 .4byte _08000038 @ case 4 _08000028: movs r0, #10 b _0800003A _0800002C: movs r0, #25 b _0800003A @ ... cases 2-4 likewise ... _08000038: movs r0, #60 _0800003A: pop {pc}
  8. Disassembly GetActionCost: push {lr} cmp r0, #4 bhi _0800003A lsls

    r0, r0, #2 ldr r1, _08000010 @ =_08000014 adds r0, r0, r1 ldr r0, [r0] mov pc, r0 _08000010: .4byte _08000014 @ table address _08000014: @ the jump table .4byte _08000028 @ case 0 .4byte _0800002C @ case 1 .4byte _08000030 @ case 2 .4byte _08000034 @ case 3 .4byte _08000038 @ case 4 _08000028: movs r0, #10 b _0800003A _0800002C: movs r0, #25 b _0800003A @ ... cases 2-4 likewise ... _08000038: movs r0, #60 _0800003A: pop {pc} Code Data Code
  9. Disassembly GetActionCost: push {lr} cmp r0, #4 bhi _0800003A lsls

    r0, r0, #2 ldr r1, _08000010 @ =_08000014 adds r0, r0, r1 ldr r0, [r0] mov pc, r0 _08000010: .4byte _08000014 @ table address _08000014: @ the jump table .4byte _08000028 @ case 0 .4byte _0800002C @ case 1 .4byte _08000030 @ case 2 .4byte _08000034 @ case 3 .4byte _08000038 @ case 4 _08000028: movs r0, #10 b _0800003A _0800002C: movs r0, #25 b _0800003A @ ... cases 2-4 likewise ... _08000038: movs r0, #60 _0800003A: pop {pc} Without a good heuristic mov r4, r2 @ table address mov r0, r5 @ case 0 mov r4, r5 @ case 1 mov r0, r6 @ case 2 mov r4, r6 @ case 3 mov r0, r7 @ case 4
  10. Disassembly Rom hacking ; adds the amount the player sold

    to their money AddAmountSoldToMoney:: ld de, wPlayerMoney + 2 ld hl, hMoney + 2 ; total price of items ld c, 3 ; length of money in bytes predef AddBCDPredef ; add total price to money ld a, MONEY_BOX ld [wTextBoxID], a call DisplayTextBoxID ; redraw money text box ld a, SFX_PURCHASE call PlaySoundWaitForCurrent jp WaitForSoundToFinish ; function to remove an item (in varying quantities) from the player's bag or PC box ; INPUT: ; HL = address of inventory (either wNumBagItems or wNumBoxItems) ; [wWhichPokemon] = index (within the inventory) of the item to remove ; [wItemQuantity] = quantity to remove RemoveItemFromInventory:: homecall RemoveItemFromInventory_ ret
  11. Disassembly Rom hacking ; Value macros DEF percent EQUS "*

    $ff / 100" MACRO bcd2 dn ((\1) / 1000) % 10, ((\1) / 100) % 10 dn ((\1) / 10) % 10, (\1) % 10 ENDM MACRO bcd3 dn ((\1) / 100000) % 10, ((\1) / 10000) % 10 dn ((\1) / 1000) % 10, ((\1) / 100) % 10 dn ((\1) / 10) % 10, (\1) % 10 ENDM ; used in data/pokemon/base_stats/*.asm MACRO tmhm ; initialize bytes to 0 FOR n, (NUM_TM_HM + 7) / 8 DEF _tm{d:n} = 0 ENDR
  12. decompilation A decompiler is a program that performs the reverse

    process of a compiler. That is, it tries to recover higher-level code, such as C, from compiled code.
  13. decompilation A decompiler is a program that performs the reverse

    process of a compiler. That is, it tries to recover higher-level code, such as C, from compiled code. Disassembler Binary Assembly Decompiler Higher-level code (e.g., C)
  14. matching decomp. Decompilation is a means to an end Decompile

    Build the level editor And what if… decompilation is the goal of a project?
  15. matching decomp. Decompilation is a means to an end Decompile

    Build the level editor Decompilation itself is the goal for the project Decompile Readable code that generates the same binary
  16. matching decomp. It’s matching decompilation! Decompilation itself is the goal

    for the project Decompile Readable code that generates the same binary
  17. matching decomp. Matching decompilation means rewriting a binary as readable

    source code that compiles to exactly the original binary. Decompilation itself is the goal for the project Decompile Readable code that generates the same binary
  18. matching decomp. Matching decompilation means rewriting a binary as readable

    source code that compiles to exactly the original binary. Decompilation itself is the goal for the project Decompile Readable code that generates the same binary
  19. matching decomp. Matching decompilation means rewriting a binary as readable

    source code that compiles to exactly the original binary. Decompilation itself is the goal for the project Decompile Readable code that generates the same binary
  20. matching decomp. OoT N64 ROM Match Game assets (texturas, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64
  21. matching decomp. OoT N64 ROM Match Game assets (textures, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64
  22. matching decomp. OoT N64 ROM Match Game assets (textures, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64
  23. matching decomp. OoT N64 ROM Match Game assets (textures, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64
  24. matching decomp. OoT N64 ROM Match Game assets (textures, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64
  25. matching decomp. OoT N64 ROM Match Game assets (textures, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64 le
  26. matching decomp. OoT N64 ROM Match Game assets (textures, models…)

    .z64 OoT Decomp Build process (how to assemble the ROM from the assets and code) OoT N64 ROM Game code fi fi github.com/zeldaret/oot (physics, logic…) .z64 le
  27. matching decomp. walkthrough glabel func_8087828C /* 0012C 8087828C AFA50004 */

    /* 00130 80878290 84820168 */ /* 00134 80878294 24010001 */ /* 00138 80878298 3C0E8016 */ /* 0013C 8087829C 1441000B */ /* 00140 808782A0 24030002 */ /* 00144 808782A4 95CEF566 */ /* 00148 808782A8 3C188088 */ /* 0014C 808782AC 27188300 */ /* 00150 808782B0 31CF0040 */ /* 00154 808782B4 15E00005 */ /* 00158 808782B8 00000000 */ /* 0015C 808782BC 24030002 */ /* 00160 808782C0 A4830178 */ /* 00164 808782C4 03E00008 */ /* 00168 808782C8 AC980164 */ .L808782CC: /* 0016C 808782CC 14620005 */ /* 00170 808782D0 3C198088 */ /* 00174 808782D4 27398300 */ /* 00178 808782D8 A4830178 */ /* 0017C 808782DC 03E00008 */ /* 00180 808782E0 AC990164 */ .L808782E4: /* 00184 808782E4 04410004 */ /* 00188 808782E8 3C088088 */ /* 0018C 808782EC 250883D4 */ /* 00190 808782F0 A4830178 */ /* 00194 808782F4 AC880164 */ .L808782F8: /* 00198 808782F8 03E00008 */ /* 0019C 808782FC 00000000 */ sw lh addiu lui bne addiu lhu lui addiu andi bne nop addiu sh jr sw $a1, 0x0004($sp) $v0, 0x0168($a0) ## 00000168 $at, $zero, 0x0001 ## $at = 00000001 $t6, 0x8016 ## $t6 = 80160000 $v0, $at, .L808782CC $v1, $zero, 0x0002 ## $v1 = 00000002 $t6, -0x0A9A($t6) ## 8015F566 $t8, %hi(func_80878300) ## $t8 = 80880000 $t8, $t8, %lo(func_80878300) ## $t8 = 80878300 $t7, $t6, 0x0040 ## $t7 = 00000000 $t7, $zero, .L808782CC bne lui addiu sh jr sw $v1, $v0, .L808782E4 $t9, %hi(func_80878300) ## $t9 = 80880000 $t9, $t9, %lo(func_80878300) ## $t9 = 80878300 $v1, 0x0178($a0) ## 00000178 $ra $t9, 0x0164($a0) ## 00000164 bgez lui addiu sh sw $v0, .L808782F8 $t0, %hi(func_808783D4) ## $t0 = 80880000 $t0, $t0, %lo(func_808783D4) ## $t0 = 808783D4 $v1, 0x0178($a0) ## 00000178 $t0, 0x0164($a0) ## 00000164 jr nop $ra $v1, $zero, 0x0002 $v1, 0x0178($a0) $ra $t8, 0x0164($a0) ## $v1 = 00000002 ## 00000178 ## 00000164
  28. matching decomp. walkthrough s16 func_8087828C(void* arg0, s32 arg1) { if

    (arg0->unk168 == 1) { if ((*(void *)0x8015F566 & 0x40) == 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } } if ((u16)2 == arg0->unk168) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } if (arg0->unk168 < 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_808783D4; } return arg0->unk168; }
  29. matching decomp. walkthrough s16 func_8087828C(void* BgGateShutter* arg0, s32 arg1) {

    if (arg0->unk168 == 1) { if ((*(void *)0x8015F566 & 0x40) == 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } } if ((u16)2 == arg0->unk168) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } if (arg0->unk168 < 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_808783D4; } return arg0->unk168; }
  30. matching decomp. walkthrough s16 func_8087828C(void* BgGateShutter* arg0, s32 arg1) {

    if (arg0->unk168 == 1) { if ((*(void u16*)0x8015F566 & 0x40) == 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } } if ((u16)2 == arg0->unk168) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } if (arg0->unk168 < 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_808783D4; } return arg0->unk168; }
  31. matching decomp. walkthrough s16 func_8087828C(void* BgGateShutter* arg0, s32 arg1) {

    if (arg0->unk168 == 1) { if ((*(void u16*)0x8015F566 & 0x40) == 0 (!(gSaveContext.inf_table[7] & 0x40)) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } } if ((u16)2 == arg0->unk168) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } if (arg0->unk168 < 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_808783D4; } return arg0->unk168; }
  32. matching decomp. walkthrough s16 static void func_8087828C(void* BgGateShutter* arg0, s32

    arg1) { if (arg0->unk168 == 1) { if ((*(void u16*)0x8015F566 & 0x40) == 0 (!(gSaveContext.inf_table[7] & 0x40)) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } } if ((u16)2 == arg0->unk168) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } if (arg0->unk168 < 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_808783D4; } return arg0->unk168; }
  33. matching decomp. walkthrough s16 static void func_8087828C(void* BgGateShutter* arg0, s32

    arg1) { if (arg0->unk168 == 1) { if ((*(void u16*)0x8015F566 & 0x40) == 0 (!(gSaveContext.inf_table[7] & 0x40)) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } } if ((u16)2 == arg0->unk168) { arg0->unk178 = (u16)2; arg0->unk164 = &func_80878300; return arg0->unk168; } if (arg0->unk168 < 0) { arg0->unk178 = (u16)2; arg0->unk164 = &func_808783D4; } return arg0->unk168; } The function is matching now!
  34. fi matching decomp. walkthrough static void func_8087828C(BgGateShutter* this, GlobalContext* globalCtx)

    { if (this->unk_168 == 1) { if (!(gSaveContext.inf_table[7] & 0x40)) { this->unk_178 = 2; this->actionFunc = (ActorFunc)func_80878300; return; } } if (this->unk_168 == 2) { this->unk_178 = 2; this->actionFunc = (ActorFunc)func_80878300; return; } if (this->unk_168 < 0) { this->unk_178 = 2; this->actionFunc = (ActorFunc)func_808783D4; } } How the function was merged at the rst time
  35. matching decomp. walkthrough void func_8087828C(BgGateShutter* this, PlayState* play) { if

    ( this->openingState == 1 && !GET_INFTABLE(INFTABLE_76) ) { this->unk_178 = 2; this->actionFunc = func_80878300; } else if (this->openingState == 2) { this->unk_178 = 2; this->actionFunc = func_80878300; } else if (this->openingState < 0) { this->unk_178 = 2; this->actionFunc = func_808783D4; } } How the function is currently on the repository
  36. matching decomp. beyond When we achieve a 100% match for

    a game, it paves the way for new possibilities
  37. AI + matching decomp. I wanted to continue working on

    Klonoa: Empire of Dreams. After building the level editor, the next challenge would be decompiling the game itself
  38. AI + matching decomp. So, as a way to learn

    the art of decompilation, I started helping decompile Sonic Advance 3.
  39. AI + matching decomp. And although I managed to decompile

    a function… …this process was very time consuming
  40. AI + matching decomp. And although I managed to decompile

    a function… …this process was very time consuming At this time, we didn’t even have support for m2c on GBA!
  41. AI + matching decomp. fi But then I realized: this

    process looks like nding patterns…
  42. AI + matching decomp. fi But then I realized: this

    process looks like nding patterns…
  43. AI + matching decomp. fi But then I realized: this

    process looks like nding patterns… and AI excels at matching patterns!
  44. AI + matching decomp. Then, I focused on prompt re

    nement: fi • Adding examples from the other enemies • Including more context in the prompt
  45. AI + matching decomp. Then, I focused on prompt re

    nement: • Adding examples from the other enemies • Including more context in the prompt fi fi But the results weren’t as good as my rst attempt…
  46. AI + matching decomp. Decompiled enemies: … Akatento My target:

    Marun Aotento Gaogao Minimole Finished after many prompts on DeepSeek R1 and a great PR review
  47. AI + matching decomp. Decompiled enemies: … Akatento Aotento My

    target: Marun Gaogao Minimole Next target, but now using Claude Sonnet 4 Kyacchaa
  48. AI + matching decomp. ffi Function CreateEntity_Kyacchaa sub_806599C sub_8065A8C sub_8065B0

    sub_8065B90 sub_8065C48 sub_8065E48 sub_8065EB0 Task_Kyacchaa sub_8065F5C sub_8065F30 sub_8065CE0 sub_8065F10 TaskDestructor_Kyacchaa Match Rate 99% 85% 95% 85% 91% 61% 90% 91% 99-100% 99-100% 99-100% 99-100% 99-100% 99-100% Di culty to Finish Easy Medium Easy Easy Hard Hard Easy Easy Easy Easy Easy Easy Easy Easy
  49. AI + matching decomp. ffi Function CreateEntity_Kyacchaa sub_806599C sub_8065A8C sub_8065B0

    sub_8065B90 sub_8065C48 sub_8065E48 sub_8065EB0 Task_Kyacchaa sub_8065F5C sub_8065F30 sub_8065CE0 sub_8065F10 TaskDestructor_Kyacchaa Match Rate 99% 85% 95% 85% 91% 61% 90% 91% 99-100% 99-100% 99-100% 99-100% 99-100% 99-100% Di culty to Finish Easy Medium Easy Easy Hard Hard Easy Easy Easy Easy Easy Easy Easy Easy
  50. AI + matching decomp. ff fi But I still had

    a lot of manual work, including nding examples, preparing context, and iterating the result with objdi .
  51. AI + matching decomp. But I still had a lot

    of manual work, including nding examples, preparing context, and iterating the result with objdi . ff fi So, let’s automate!
  52. AI + matching decomp. But I still had a lot

    of manual work, including nding examples, preparing context, and iterating the result with objdi . So, let’s automate! ff fi Kappa: The VS Code extension designed to help with matching decompilation
  53. AI + matching decomp. I spent ~3 months developing the

    extension in my spare time. It’s all cool… but I started to wonder if it might have a better approach than a VS Code extension
  54. AI + matching decomp. I spent ~3 months developing the

    extension in my spare time. It’s all cool… but I started to wonder if it might have a better approach than a VS Code extension
  55. AI + matching decomp. I started working on benchmarks. Mizuchi:

    Automates the decompilation loop, designed for benchmarking
  56. AI + matching decomp. In March, I benchmarked Sonnet 4.6

    using a dataset built from Sonic Advance 3 (GBA) and Animal Forest (N64) functions. And in July, I used the same dataset to benchmark Sonnet 4.6 vs. Fable 5
  57. AI + matching decomp. I built the following tools to

    help on this project: Transmuter
  58. AI + matching decomp. I built the following tools to

    help on this project: asmlift Transmuter gba-kit
  59. AI + matching decomp. asmlift is a programmatic decompiler heavily

    inspired by m2c. The idea behind asmlift is: instead of using AI to match a single function, let’s use AI to build a tool that matches functions programmatically.
  60. AI + matching decomp. Transmuter is a programmatic code permuter

    heavily inspired by Permuter. The idea behind Transmuter is: let’s provide capabilities for AI to drive the permutations.
  61. AI + matching decomp. gba-kit is a GBA emulator with

    rich debugger capabilities, inspired by No$GBA and other emulators. The idea behind gba-kit is: let’s provide a GBA emulator with debugging features that AI can use.
  62. AI + matching decomp. Claude Code put these tools together

    in a work ow 1. Select the 2. functions 3. asmlift produce the initial C code 4. Use gba-kit for dynamic analysis Adversarial review. Open a PR. Transmuter help to Make a report fl fi I read the report to improve the tools and the next run
  63. AI + matching decomp. Claude Code put these tools together

    in a work ow 1. Select the 2. Find a match functions 3. asmlift produce the initial C code 4. Use gba-kit for dynamic analysis Adversarial review. Open a PR. Transmuter help to nd the match Make a report fl fi I read the report to improve the tools and the next run
  64. AI + matching decomp. Claude Code put these tools together

    in a work ow 1. Select the 2. Find a match functions 3. Improve the readability asmlift produce the initial C code Use gba-kit for dynamic analysis 4. Adversarial review. Open a PR. Transmuter help to nd the match Make a report fl fi I read the report to improve the tools and the next run
  65. AI + matching decomp. Claude Code put these tools together

    in a work ow 1. Select the 2. Find a match functions 3. Improve the readability asmlift produce the initial C code Use gba-kit for dynamic analysis 4. Review and merge Adversarial review. Open a PR. Transmuter help to nd the match Make a report fl fi I read the report to improve the tools and the next run
  66. AI + matching decomp. Working with AI is a moving

    target: Earlier models fi Supplied the context Now The agent nds context though tools
  67. AI + matching decomp. Snowboard Kids was decompiled is just

    84 days. It was a great combination of: AI tools + Learnings Weekly Match Progress + Community 100% 80% 60% 40% 20% 0% 0 25 5 1 -0 6 0 8 -0 6 0 -15 6 0 0 22 6 9 -2 6 0 6 0 0 7- 0 13 7- 20 07 3 7 -2 7 0 0 0 8- 0 10 8 17 08 Read the full Chris’ post
  68. AI + matching decomp. Because how people contribute to the

    decompilation matters. AI can accelerate the process, but bad actors, that joined on the decompilation scene because AI lowered the bar, used decomp.dev as a kind-of leaderboard. Since it ampli ed bad behaviours, like hostile forks and rushed ports, it was closed. fi Read the full statement
  69. AI + matching decomp. The government provides an online simulator

    that shares the code with the real voting machine

More Decks by Bruno Macabeus

Other Decks in Programming