Show HN: Decomp Academy – Learn to decompile GameCube games into matching C
decomp-academy.dev178 points by jackpriceburns 17 hours ago
178 points by jackpriceburns 17 hours ago
Over the past few months I've been heavily involved in the decompilation community. I've been hands-on decompiling a beloved game from my childhood (Star Fox Adventures). I started this journey with zero prior decomp experience—and to make things worse I had never really touched C nor assembly either.
Learning how to decompile was challenging. It's difficult to find any good learning resources for it and any open-source projects for this are inactive and/or contain little actual learning material.
So I put together Decomp Academy! Decomp Academy is an interactive way to learn how to decompile PowerPC assembly back into C. The site runs a live Metrowerks CodeWarrior GC/2.0 compiler, converts your C into assembly, and then checks how close your assembly matches the target. If even 1 instruction or bit is off, that's a fail. This is the gold standard for video game decompilation and this is much stricter than a normal decompile.
As of writing there are 250+ lessons on the site and the lessons start at the very basics so anyone with a little programming experience should be able to jump straight in, even if you're not a C expert. Some lessons also have real functions taken from live open source decomp projects (Star Fox Adventures, Mario Party 4, Pikmin, Metroid Prime). The idea being you learn everything you need to know to be able to jump in and contribute to a real decompilation project when done.
The site is completely free, open source and you have access to all lessons without having to sign up. All lessons are stored in markdown in the repo (src/curriculum), it's trivial to add or modify lessons. The site is very new and the lessons are rapidly changing every day with a whole C++ section on the way. The site has already been well received by the decomp community and I'm happy to share it with HN. I'm very keen on others to contribute to this project and I hope this becomes the best resource on the internet for learning the art of decompilation. Please let me know what you think!
Source: https://github.com/JackPriceBurns/decomp-academy-fe
This was interesting, but actually trying to contribute to decomp.me was still really hard! I found a lot of code that seemed perfect except for instructions slightly out of order, or dead pop statements after the logical end of the function. I wasn't able to actually fix anything :( Also, I wish there were a guide about how to start from nothing on a new GC game. That's more interesting to me than putting the finishing polish on a decomp project that already "works" functionally. There will deffo be a lesson on how to setup a decomp project from scratch! This is far from finished, there's opportunity to add so much more. I'd argue that I'd rather teach the user the basics of matching first before diving into setting a project, as setting up the splits.txt or symbols.txt might be quite a leap for a beginner. Feel free to keep checking in once a week and the lesson will appear :) I've honestly think "beginner" is the wrong target anyway. If you're interested in contributing to a decomp, assembly basics are table stakes. Focus on the things that someone who already knows assembly won't just know. I'd love it if there was some way to contribute to ongoing game decompilation projects, with a similarly streamlined web interface - it's something I'd be willing to dedicate some brain time to every so often, but setting up the toolchain etc. feels too much like work. By the way, I was able to "cheat" on the second lesson with That's what decomp.me is for, when I'm stuck on a function in my own projects I usually set it up on there and link it in the codebase so anyone can pick it up. Sometimes I like to browse the front page and hope I know enough to silently match somebody else's function (usually stays as a hope though...) decomp.me is also a great tool! The playground section of the site allows you to turn the code into a decomp.me scratch.
I also use the objdiff wasm on the frontend for the assembly diffing. I don't see much point in reinventing the wheel and these tools are already great, so I'll deffo be leaning on them when I can I was thinking of something similar as well, perhaps a section of this site after you've completed the course where we show functions from popular decomp projects that aren't 100% matched, and you can match it. Doing so will magic up a PR or something.. It's a great idea! As for cheating, the community calls this a fake match. I don't check that the code you submit conforms to what I expect, I only check if the assembly matches. You can do interesting things where you do a series of bit shifts and bit masks, and you can replicate an equality operator `a == b` or a low clamp `x < 0 ? 0 : x`. I'm not sure if I'll lock this down or not, for people who have accounts, I can see their submissions so I think I'll play it by ear and see what happens. If it looks like people are constantly fake matching, I can look at tweaking the lessons or locking it down more The browser-first approach is a bigger deal than it sounds. Every time I've looked at reverse engineering, I got stuck somewhere between "install this ancient compiler" and "patch this SDK". Being able to just open a tab and start experimenting removes a huge amount of friction. Dumb question about reverse engineering binaries: is there a way to only do it piecemeal? I'm eventually waiting for LLMs and harnesses to get good enough to reverse engineer BFME (old Lord of the Rings game that still has an active modding community), but it's a multi GB sized game that would have to be done in bite-sized pieces. Basically; can you reverse engineer in bite sized pieces, and recompile/customize their behavior, without needing to do it all at once? Most decomp projects (that I know of) are Ship of Theseus style projects where the minimum unit is a function, give or take alignment requirements and quirks of the compiler. On the MIPS side, tools like Splat and SPIM can help identify function and even source file boundaries, generate inline ASM C files[0], and write linker scripts to build a matching binary. You can then go through and replace the ASM functions one at a time until you just have C left. 0 - for example: https://github.com/Xeeynamo/sotn-decomp/blob/master/src/boss... Interesting when you mention Ship of Theseus, I never thought of that but I wonder if that is where the name “Ship of Harkinian” comes from? It has a double meaning actually! The ship of Theseus reference like you noted and the “Harkinian” part being the name of the king of Hyrule from the CDI games. One of his lines is “Enough! My ship sails in the morning” [0] so the project is also a reference to his actual ship. (Referenced in the projects FAQ [1]) Yes, quite easily. It requires some setup, but the basic idea is that you create a DLL and a simple loader program which injects it into your target process. You can then use a hooking library like MinHook to replace individual functions with your own implementations. If the target application is in C++, you can additionally do vtable hooking and replace functions even easier (though it will always be a combination of the two techniques). There’s also fun stuff like VEH hooking and SLAT hooking, though SLAT hooks are not very useful in this case. Most of those GB are probably data rather than executable code, it might not be quite as bad as you're imagining. Have you tried? I've haven't tried anything huge but I've had LLMs decompile SNES ROMs for me. Love the idea! Assembly has been on my forever-list to eventually learn. I have worked through the warmup exercises, but I doubt I'll have the time to continue much past that. A few points of note: - Not a fan of the purple theme, it screams "AI-generated". It's not a deal breaker, you can keep it if you have more important concerns, but just something to point out - It would be nice to have a "Chapter 0" for a primer on assembly syntax. Does not have to be interactive, a few toy examples I can work out on paper would be good enough - Maybe I just haven't seen it, but it would be nice to have a reference of all the various instructions. Your lessens explain them well enough, but I would like to have a list of all of them at a glance so I can look up instructions from earlier chapters later. - The purple theme was a conscious choice, not an AI's decision. I wanted to match the colour theme of the GameCube. You can see the current colour pallete here: https://decomp-academy.dev/brand/brand-sheet this will likely go through changes in the near future but I'd like to stick to the purple theme as a nod to the GameCube - I've just added some new lessons before the first lesson to explain assembly syntax! - I believe there are around 200-odd instructions, and a lot of them I'm not sure you'll ever see, but I can certainly look at adding something like this The purple theme seems fine and appropriate to me, given the GameCube’s color scheme - and some of the site feels almost Slippi-esque so there’s a bit of that angle too. Is "the layout scream AI generated" the new Bootstrap ? I.e what people use to quickly convey their ideas (bad or good) Ironically, for myself at least, the least it looks AI, the more I've spent time prompting for it to not look AI. Damn this is next level. Congratulations on your achievements! When Fable was around I thought i'd test it by taking an old piece of Windows software from the late 90s/2000s(ModPlug Player) and seeing how well it could convert it to being a native Mac application. I was blown away at how it got 85% of the way there in one prompt. Things such as writing a PE extractor, recovering the complete skin, menu tree, full accelerator table, all dialogs, and then it delved into the registry value names as well. Some more prompts got it to 99%(I was happy with that and stopped) I then took an old 1999 DOS demoscene and yet again it did wonderful magic and got me a native mac build. I dropped everything I was doing and just started going through all these old apps that I couldn't easily enjoy since im on a Mac. It got to the point where I was losing sleep over it(was just so excited). The fun ended when I was stopped mid-project with the Fable ban. Opus just does not compare and essentially killed all the enthusiasm after the nth failure of it to complete the task. It made me realize that among the efforts of the RE community, and the emerging capabilities of these frontier models, in the future we could have the possibility living in a renaissance of open computing if we want any software we see on the market to be forever remixed and tailored to our uses and completely open. I don't know how the business and legal side will deal with this. There needs to be new frameworks and ways of thinking about this stuff. I'm just happy that hopefully no code will ever be lost to the sands of time ever again. AI is being used in many retro game decomp projects! One of the reasons I went down the path of learning decomp myself was because AI had hit a wall. Matching decomp is quite a bit harder than just normal decomp as even simple things like using an if/else instead of a terney actually change the assembly. AI did an amazing job of getting to 95% matches on nearly all functions, but once it got to that tail end, it started to struggle quite a lot and would often just claim "it's impossible". So that's when I pivoted and started learning actual decomp myself so that I could prompt AI better and finish off the star fox adventures decomp! I say this every time it comes up, but polluting a decomp project with AI generated code is risky, imho. What makes decomp legal (in the US) is that it’s a creative transformation performed by a human and the resulting copyright of the code that just happens to compile to the same binary is owned by the person doing the decompiling. USPTO and court precedent is leaning heavily toward LLM output not being transformative on its own, making it mechanical, and no longer fair use and in violation of copyright. This puts a legal gray cloud on a project where most contributors couldn’t defend themselves if a rights holder goes after it, and there’s a high likelihood that they would succeed. On the other hand there’s enough case law protecting human decompilation that even the most litigious game companies don’t go after decomp projects that have historically been done by humans. (I’m not a lawyer, I’m not your lawyer, this is not legal advice, etc., etc.) Does it being a creative transformation rob the derivative work status? Personally, I'd liken the process of decompilation to that of translating a book from one language to another - the copyright on the original work does not become void merely because the process of translation requires extensive creativity. Nicalis and Take-Two have both gone after decompilation projects, also. In particular, Nicalis has gone after a decompilation of Cave Story, but not a black box reimplementation of the same, while Take-Two ended up suing a decompilation developer (albeit settled out of court). However, in some jurisdictions, even clean reimplementations have failed - see Tetris v. Xio. (I am not a lawyer either, etc etc, but that's my understanding) The RE3 devs were distributing binaries. This is known to be an issue. The source code is theirs, binaries mixed with other copyrighted content is not. They also allegedly violated a EULA, but I haven’t looked closely into that. CSE2 was distributing binaries as well. So was SM64 decomp and Nintendo told them to stop, they did and continued to share their source code. Tetris v. Xio is unrelated to reverse engineering or decompilation. > The source code is theirs, binaries mixed with other copyrighted content is not. Distributing binaries should not matter. If the binary is just compiled from the source code, the binary is just an (non-)infringing as the source code. > They also allegedly violated a EULA Meaningless. EULAs are not the law. If the sources produce significant sequences that match the original binary, that binary is probably infringing. The community gets around this by distributing binary patches instead. In some cases the EULA is what gives you access to the original binary to begin with (often the case with digital marketplaces, but also true of some physical media after 2010 or so). These have little to do with copyright, but whether someone could access the binary on the first place. To the best of my knowledge this contract law has largely been considered valid, but I try to avoid working on things with EULAs, so haven’t looked into it in depth. These decomp projects are already violating copyright by distributing the decompiled source code. Using LLMs is less risky than sharing the code. Before the advent of LLMs, ML was used in upscaling the assets and pre-rendered backgrounds of the first 3 classic Resident Evil games: https://www.reshdp.com Matching decomp would require the same compiler and flags as the original game, right? How is that determined? Experimentally, I think. There's only a few dozen options, and you can winnow it down to just a few pretty quickly. Makes one wonder, why should anyone embark on learning this intricate and time-consuming art of reverse engineering when LLMs are on their way to automate it in seconds... You can tell this basically about anything software related these days. Yet when human is in the loop, the insight is still needed. I recently heard that Super Mario 64 (N64) modding community reverse engineered the game enough to recreate more-or-less accurate C code that can be compiled in binaries to execute on many popular target architectures.
Have you managed to get beloved games into modifiable C code? Or is it more common to invest a lot of work to document assembly language functions? I know some old assembly but no idea what is involved at a high level. Maybe you explain in your lessons? Also, how to folks obtain binaries? Presumably unless there is a source code breach or vulnerability, source never gets exposed, is thst correct? Mario 64 was byte for byte decompiled to C. It was helped by using the Debug symbols accidentally(?) compiled into the final version of the game. Otherwise they reference rips of the original game. > It was helped by using the Debug symbols accidentally(?) compiled into the final version of the game. Don't think this was the case, what helped was it being compiled without optimizations. Most games will have been written in a higher level language first (like C or C++) and then compiled into assembly. With matching decomp, we write C, compile it to assembly, and see how much it matches the retail assembly. Using this we can write C that we theorise is almost identical to how it would have been written originally.
There are things lost during the compilation process (like comments, function names, etc) these we have to name manually and it's a long process to do! But yes, the goal is to have C at the end and once you have C you can recompile using a different compiler and target any architecture you like I suspect LLMs would do a good first pass with function naming. They do an alright job, but they deffo need human-in-the-loop for the best results. I wrote on my blog about how I wrote an MCP to communicate with the Dolphin emulator. Allows Claude Code to set breakpoints, read the memory, write the memory, etc. It was a super fun way to work with Claude and has made naming functions/structs/fields/etc much easier! https://jpb.dev/blog/dolphin-debugger-mcp/ The backend is closed source, but it runs all on AWS Lambda/DynamoDB/APIGateway and is written in Rust. Getting the compiler running in a Lambda was an adventure of it's own I’d be interested in hearing more detail on that. I’m actually surprised you were able to get the compiler, I assumed it would be expensive and proprietary. Hi OP, I would be careful if you profit from this project in anyway. Nintendo is not a company that takes reverse engineering of their hardware or games lightly. You will probably hear from their lawyers next week :( Dumb question — can LLM be used to reverse-engineer firmware blobs or binary only drivers for Linux, to create open-source drivers, for example, for unsupported smartphones? That is already happening for old games, and while they usually run on simpler CPUs than modern ones, I don't see why this couldn't be possible for binary Linux drivers. The toolchain would also be easier to match, unless they were using some proprietary compiler you can't get your hands on. Just lookup how they match the toolchain, and find an agent harness to do decompilation. I wonder if doing this kind of stuff with more recent software will cause more legal problems though. I am not really sure of the legal status of the resulting code. Most likely, this (reverse engineering) is one of the numerous things these LLM companies target. You can also assume all of the internet has been slurped up in to any frontier model. That doesn't mean what you want will be a one shot prompt though... As I'm working in this area, I can say that the biggest problem isn't binary only drivers but spotty mainline support of core features (provided that we're talking about Android phones, not iPhones or old Windows mobile stuff) From where you're standing, what does the path to improving mainline support of core features look like? Aside from sheer volume of work are there other major challenges or opportunities? In the past I've hacked around adding stuff to Armbian kernels, but navigating a path to mainline seemed like a whole other job. It really depends of your device but some SOC have very poor mainline support and are essentially living in a forked repo with nothing sent to lkml, others have partial support in mainline but with some of the core features being broken. Drivers can also be partially implemented / buggy depending on the device. (And I'm not talking about closed source stuff, even things like usb or touch screen drivers). I would say that the major blocker is that nobody really cares about these devices and the task itself to mainline them is gigantic. Most SOC have 3 or maybe 4 contributors maximum and the phonedev kernel mailing list gets a new patch only every 2 days.
The whole phone mainlining community is probably less than 60 people. Is there something similar to learn ARM decompiling? I'm not aware of anything that's similar to this for ARM.. but in the future there is certainly room to add this. For now I'm focusing on getting the current set of lessons up to scratch as a lot of them need improvement. Then I think I want to add C++ as a language and allow you to change which version of MWCC you can run I'd enjoy having something like this but for x86/64 :) The lessons taught in this can be applied to x86/64, but can deffo look adding different instruction sets in the future > If even 1 instruction or bit is off, that's a fail. Does this assume having access to the exact version of the compiler use, or can it be done with a different compiler in practice? And do you care about things like binary layout, or just instruction match? (Does that ever matter in practice?) Yes, exact version of the original compiler is required. Generally bit-for-bit equivalence to the original executable is expected. However I think for some cases where the original executable included debug info (eg. PS2 ELFs) then the unused-at-runtime sections need not match. Interesting exercise. Why does 1/1 matching to original asm matter, though? Maintaining same timing as original game? Having a baseline "this builds XYZ exactly as it shipped" is just the strongest possible guarantee that it's a fully accurate decomp with no surprises or bugs. Obviously you can have an interesting, useful decomp that works either way but it's much harder to prove that it's perfectly faithful. Being absolutely sure that your code behaves the same as the original game, so that you have a strong baseline to go from. This is cool as hell. On the first lesson, it tells me there's a target on "the right". There isn't anything to the right, I've in clue where to look. Are you on mobile? You'll need to switch to the code/review tab to see. I think mobile support is a bit funky, I'll look at fixing that as soon as I can! I switched to desktop view, still couldn't tell where I was supposed to be looking. Seems like a cool idea, but I can't even complete the first task. The compiler service seems to be broken, since in both lessons and the playground I just get "Could not write source: No space left on device (os error 28)". Just deploying a fix for this right now! Didn't expect this to be so popular haha I like decomp, but it makes me nervous. Like how safe is it to decompile a game and publish it to like github with all the symbols, addresses, etc.. Quite safe in practice, even Nintendo games have had no issues. GTA 3 / Vice City decompilers did get sued though, but IIRC mainly because they did not comply with DMCA requests at all. The risk is low assuming you respect a potential take down notice that comes in. That's awesome! I have been playing with the idea of doing a Tales of Symphonia decomp. More than 10 years ago I started the high-res texture pack, which the community has now carried further than I ever did. But it would be totally awesome to be able to mod the game further and run it on other consoles without the godawful framerate downgrade.
StilesCrisis - 7 hours ago
jackpriceburns - 4 hours ago
StilesCrisis - an hour ago
Retr0id - 17 hours ago
I gave up at https://decomp-academy.dev/lesson/workflow-what-matching-mea... when I was presented with a wall of LLM-flavoured text void identity(void) { return; }
someone2639 - 16 hours ago
jackpriceburns - 16 hours ago
jackpriceburns - 16 hours ago
nativeforks - 5 hours ago
OsrsNeedsf2P - 15 hours ago
jonhohle - 15 hours ago
low_tech_love - 10 hours ago
jevndev - 3 hours ago
paavohtl - 11 hours ago
not_a9 - 7 hours ago
Retr0id - 4 hours ago
charcircuit - 13 hours ago
HiPhish - 9 hours ago
jackpriceburns - an hour ago
Klonoar - 6 hours ago
allan_s - 8 hours ago
saturn8601 - 16 hours ago
jackpriceburns - 16 hours ago
jonhohle - 15 hours ago
asiekierka - 14 hours ago
jonhohle - 13 hours ago
paavohtl - 11 hours ago
jonhohle - an hour ago
charcircuit - 12 hours ago
ducktective - 15 hours ago
koala_man - 12 hours ago
StilesCrisis - 7 hours ago
ducktective - 15 hours ago
hsuduebc2 - 15 hours ago
sciencejerk - 14 hours ago
xahrepap - 14 hours ago
Randomno - 4 hours ago
jackpriceburns - 14 hours ago
teaearlgraycold - 14 hours ago
jackpriceburns - 14 hours ago
jackpriceburns - 17 hours ago
rybosome - 16 hours ago
__alexander - 6 hours ago
oneshtein - 12 hours ago
LelouBil - 11 hours ago
tudelo - 11 hours ago
realusername - 9 hours ago
RossBencina - 9 hours ago
realusername - 9 hours ago
supaflybanzai - 10 hours ago
jackpriceburns - 10 hours ago
bpavuk - 7 hours ago
jackpriceburns - 4 hours ago
dataflow - 9 hours ago
dezgeg - 6 hours ago
not_a9 - 6 hours ago
StilesCrisis - 6 hours ago
Philpax - 6 hours ago
nosioptar - 16 hours ago
jackpriceburns - 16 hours ago
nosioptar - 7 hours ago
soxfox42 - 13 hours ago
jackpriceburns - 13 hours ago
bottlepalm - 14 hours ago
dezgeg - 6 hours ago
charcircuit - 13 hours ago
rowanG077 - 6 hours ago