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.