Instructions to get a useful decompilation out of an il2cpp game. Or, "I spent hours to trial and error so hopefully you won't have to"

i2cpp_ghidra.md

Decompiling IL2CPP Games with Il2CppDumper and Ghidra

This guide will walk through how to decompile/reverse engineer IL2CPP games for modding usage.

Note: expect this entire process to take upwards of an hour. Have something ready to do on the side while waiting for processing to finish.

Prerequisites

1. Download Il2CppDumper
2. Download Ghidra
   • Ghidra requires a supported installation of OpenJDK 17 - I recommend Amazon Corretto
3. Download a current version of Python. Honestly I don't even know what version is set as my default so I suspect any python3 will work.

Extracting Symbol Information

Decompiling the assembly with Ghidra will lose most symbol information by default. Fortunately, IL2CPP preserves symbol information for us as global metadata. We will use Il2CppDumper to extract the relevant metadata.

1. Open up a command line in your game folder
2. Create a directory which will hold your outputs
3. Run the following: Path/To/Il2CppDumper/Executable GameAssembly.dll GameName_Data/il2cpp_data/Metadata/global-metadata.dat Path/To/Output/Folder
4. Il2CppDumper will generate a variety of files for you.
   • In the DummyDll folder, you will find stub assemblies similar to what you would get from MelonLoader.
   • il2cpp.h contains C header files with type information.
   • script.json provides configuration info for Ghidra and IDA scripts.
   • stringliteral.json provides information of all the string literals in the program.
5. The default file generated by Il2CppDumper has compatibility issues with Ghidra, so we will have to address them. Fortunately there is an easy script to do this.
   1. Navigate to your output directory
   2. Run the following: python Path/To/Il2CppDumper/Folder/il2cpp_header_to_ghidra.py
   3. Observe that il2cpp_ghidra.h has been generated.

Decompiling the Program with Ghidra

1. Navigate to your Ghidra installation and run ghidraRun.bat
2. File -> New Project
3. Set the project name as desired (I like the format GameName_X_Y_Z where X, Y, and Z make up the version number).
4. Finish
5. Click the Code Browser (dragon head) icon.
6. File -> Import File. Select GameAssembly.dll. When prompted, the default settings should be sufficient.
   • You will be prompted to do an auto-analysis, select no as it will make Ghidra run much slower.
7. Import type data
   1. File -> Parse C Code
   2. Under Parse Configuration, select VisualStudio22_64.prf
   3. Click "Save Profile to New Name" (2nd icon in the top bar)
   4. Remove all entries from "Source Files to Parse", "Include Paths", and "Parse Options"
   5. Add the generated il2cpp_ghidra.h to the "Source Files to Parse" section.
   6. Click "Parse to Program" and then "Continue". If prompted, select "Use Open Archives". This may take a while.
      • If the parser encounters syntax errors, open the file in a text editor like Notepad++ and navigate to the line in question. Note down the line number for later and comment out the entire body of the struct where the syntax error appears. Often, the syntax error Ghidra is complaining about is not a real error so we'll just work around it until Ghidra is happy.
      • If needed, we can later use the Structure Editor in Ghidra to re-populate the struct
   7. Repeat as needed until Ghidra successfully parses the header.
   8. You can view the imported types in the data types window
8. Import function data. Open the script manager (green play icon) and run ghidra_with_struct.py. When Prompted, select the script.json that Il2CppDumper generated earlier.
   • If this is your first time, you'll have to add the Il2CppDumper scripts to Ghidra by clicking "Manage Script Directories" (third-to-last icon in the script manager top bar) and adding your Il2CppDumper install directory to the list
9. Wait patiently while Ghidra decompiles the code. You can watch the progress in the lower right corner. This will take a while.

Using Ghidra to View the Code

• Use Window -> Functions to open the function display. Here we can search for the methods we want. Start with ClassName$$MethodName or ClassName$$ if you don't know the specific method you want yet.
• Dealing with async functions and coroutines - these get generated as anonymous state machine classes. For example, they might appear in ClassName.<MethodName>d__44$$MoveNext (the numbers are compiler generated). When you decompile the original method, you should easily be able to identify the calls to these state machines, and can track them down in functions window as you normally would. Again, the MoveNext method is where the state machine is actually implemented.
• You can right click variables to rename them for easier readability.

I recommend this PR Perfare/Il2CppDumper#764

It has to be run through Ghidra but the script output from Il2CppDumper was unusable. Waited half an hour just to get error after error before getting stuck at a struct that was already commented out that still didn't work.

I used the script from that PR and it parsed correctly first try.

Is there a way to ignore syntax errors because I have to repeat the process too many times and the lines are not always good no stop

I have hit this before but it's been long enough that I don't remember what to do to resolve it, sorry

Is there a way to ignore syntax errors because I have to repeat the process too many times and the lines are not always good no stop

Open Perfare/Il2CppDumper#764, edit your script with the changes made there. Open ghidra and run the new script through the script manager to generate a new C source file and use the generated file instead.

Is there a way to ignore syntax errors because I have to repeat the process too many times and the lines are not always good no stop

Open Perfare/Il2CppDumper#764, edit your script with the changes made there. Open ghidra and run the new script through the script manager to generate a new C source file and use the generated file instead.

thanks for response i modify the code to add asm `import re

header = "typedef unsigned __int8 uint8_t;\n"
"typedef unsigned __int16 uint16_t;\n"
"typedef unsigned __int64 size_t;\n"
"typedef _Bool bool;\n"

replace_keywords = [
" alignas;",
" _Alignas;",
" alignof;",
" _Alignof;",
" _Atomic;",
" auto;",
" _BitInt;",
" bool;",
" _Bool;",
" break;",
" case;",
" char;",
" _Complex;",
" const;",
" constexpr;",
" continue;",
" _Decimal128;",
" _Decimal32;",
" _Decimal64;",
" default;",
" do;",
" double;",
" else;",
" enum;",
" extern;",
" false;",
" float;",
" for;",
" _Generic;",
" goto;",
" if;",
" _Imaginary;",
" inline;",
" int;",
" long;",
" _Noreturn;",
" nullptr;",
" register;",
" restrict;",
" return;",
" short;",
" signed;",
" _signed;",
" __signed;",
" sizeof;",
" static;",
" static_assert;",
" _Static_assert;",
" struct;",
" switch;",
" thread_local;",
" _Thread_local;",
" true;",
" typedef;",
" typeof;",
" typeof_unqual;",
" union;",
" unsigned;",
" void;",
" volatile;",
" while;",
"_asm;", # here
]

def main():
fixed_header_data = ""
h_file = askFile("il2cpp.h from Il2cppdumper", "Open")
with open(h_file.absolutePath, 'r') as f:
print("il2cpp.h opened...")
original_header_data = f.read()
print("il2cpp.h read...")
fixed_header_data = re.sub(r": (\w+) {", r"{\n \1 super;", original_header_data)
print("il2cpp.h data fixed...")
print("il2cpp.h closed.")
new_file = askFile("Choose where to save patched il2cpp.h", "Save")
with open(new_file.absolutePath, 'w') as f:
print("Patched header opened...")
f.write(header)
print("header written...")
print("Patched header common typedefs written...")
f.write(fixed_header_data)
print("fixed data written...")
print("il2cpp_ghidra.h closed.")
print("Patched header fixed data written and closed...")

if name == 'main':
print("Script started...")
main()
` but dont work its every time the same i try every method possible like spliting files dont work too

@BadMagic100 i'm attempting to decompile a il2cpp game, how exactly can i export the source code from ghidra after doing the whole process? i created a unity project for it (using the latest AssetRipper build), but anything i use to get the source code just gives me placeholder code (a.k.a returning null on everything)

The disassembled source code will be available in ghidra, it may be possible to export it but it isn't going to be the code you're looking to use in a unity project. In fact it will not be possible at all to retrieve the original c# source code.

Not to necro, but working through this gist right now. Thanks for the write-up @BadMagic100 (curious how you learned this yourself).

Re: @Thexoxo 's message: you didn't properly copy the whole diff from the linked PR. You added the replace_keywords variable, but it's not actually referenced in your version of the script. You can use this link to see what the version of the file from the PR looks like (in a regular, non-diff view): https://github.com/Perfare/Il2CppDumper/blob/9ab1e1dbbb346681a91900b3e00ba84ceed61682/Il2CppDumper/il2cpp_header_to_ghidra.py

It may be because I did things out of order (accidentally had Ghidra run analysis for a bit before cancelling), but parsing the il2cpp_ghidra.h header has been taking a long time (over 30 minutes by this point). I'll let it keep running, but I'm thinking it's possible I'm in a bad state where this operation will take an unreasonable amount of time. If it's still running by tomorrow morning, I'll try the setup again fresh.

Thanks for the write-up @ BadMagic100 (curious how you learned this yourself).

Lots of trial and error, mostly

My experience is that the running time can take multiple hours so >30 minutes is not necessarily out of the ordinary

Holy crap, it finally finished. Definitely was an issue with run order though.

My theory on the speed issue is this: From what I can tell the issue is that Ghidra is incredibly slow at deleting/replacing type definitions. When parsing il2cpp_ghidra.h fails partway through, Ghidra still stores all successfully parsed type definitions. However, trying to parse the header file again at this point leads to a bunch of replacement operations which are known to be incredibly slow in Ghidra: NationalSecurityAgency/ghidra#4431 . I tried manually deleting the definitions from the "Data Type Manager" (bottom left in Ghidra), but this too looked like it would take millenia.

The fastest way to actually retry was to (crazily enough) recreate a Ghidra project and do all of the steps from the beginning again. When I did this with a il2cpp_ghidra.h with no parse errors, parsing took only 5 minutes (vs. I had let it run for 2 hours previously and it had not terminated).

For people coming to this thread in the future: I'd recommend making sure your il2cpp_ghidra.h is completely free of parse errors before trying to parse in Ghidra to avoid this issue and having to recreate your Ghidra project. I tried messing around with gcc to do this, but I didn't find a good set of options for only giving you the fatal cases that would cause Ghidra parse errors. gcc -fsyntax-only -Wfatal-errors was close, but I think the issue is that the il2cpp_ghidra.h uses compiler directives that gcc doesn't understand. My guess is there's probably a way to properly do it with MSVC. (Edit: Yeah, seems like it's an MSVC thing. gcc was getting upset by __int8 directives: https://learn.microsoft.com/en-us/cpp/cpp/int8-int16-int32-int64?view=msvc-170)

I find the best method and its really fast lets me explaib @tenzinhl use the update version of Il2CppInspectorand with this version its will extract .h good the name is Il2CppInspector pro https://github.com/jadis0x/Il2CppInspectorPro and its work perfect https://github.com/jadis0x/Il2CppInspectorPro

I find the best method and its really fast lets me explaib @tenzinhl use the update version of Il2CppInspectorand with this version its will extract .h good the name is Il2CppInspector pro https://github.com/jadis0x/Il2CppInspectorPro and its work perfect https://github.com/jadis0x/Il2CppInspectorPro

and yeah i find a video who use this exact version https://github.com/jadis0x/Il2CppInspectorPro/releases/tag/2024.12 and your theory about ressource @tenzinhl is maybe correct

dumb question but how do you compile it back into a game. im using a exctracted apk that uses il2cpp and the tutorial works perfect i got the code i wanted to change but idk how to put it back inside and recompile. (im intending for this to work in a multiplayer game, i already got all the things i wanted to change)

You don't. You use a modloader like MelonLoader to inject and edit code at runtime

oh then, ill just use the LemonLoader fork of MelonLoader because it does not support apk.

also would be great if u edit the tutorial and maybe add a part of how to make the mod.

That's well out of scope here, I'm only aiming to demonstrate the reverse engineering process.