DOCSEARCHbyAlgolia
Submit Docs

Il2CppDumper

repository·master·Indexed 27 days ago

https://github.com/perfare/il2cppdumper

A reverse engineering tool for Unity games using the il2cpp scripting backend. It restores DLL metadata and generates analysis scripts for IDA, Ghidra, and Binary Ninja. Supports ELF, ELF64, Mach-O, PE, NSO, and WASM formats for Unity versions 5.3 through 2022.2. The tool can be operated via a GUI or command-line interface to produce DummyDlls, header files, and dumped method/field information.

Tokens
1.4K
Snippets
2
Records
6
Agent score
44%

What's inside Il2CppDumper

  1. Run Il2CppDumper via GUI or Command-line

    master

    GUI Mode

    Run Il2CppDumper.exe and follow the prompts to select the il2cpp executable file and the global-metadata.dat file.

    Command-line Mode

    You can run the dumper directly from the terminal by providing the executable, the metadata file, and an optional output directory.

    Il2CppDumper.exe <executable-file> <global-metadata> <output-directory>
    Il2CppDumper.exe <executable-file> <global-metadata> <output-directory>

  2. Use Il2CppDumper via GUI or CLI

    master

    Il2CppDumper is used for Unity il2cpp reverse engineering to restore DLL files (without code) and extract MonoBehaviour and MonoScript information. It supports ELF, ELF64, Mach-O, PE, NSO, and WASM formats for Unity versions 5.3 through 2022.2.

    GUI Usage

    1. Run Il2CppDumper.exe.
    2. Select the il2cpp executable file when prompted.
    3. Select the global-metadata.dat file when prompted.
    4. Follow the on-screen prompts to complete the process.

    CLI Usage

    Run the executable with the following arguments: Il2CppDumper.exe <executable-file> <global-metadata> <output-directory>

    Il2CppDumper.exe <executable-file> <global-metadata> <output-directory>

  3. Configure Il2CppDumper via config.json

    master

    You can customize the dumping behavior using the config.json file. Key configuration options include:

    Dump Content Control

    • DumpMethod, DumpField, DumpProperty, DumpAttribute, DumpFieldOffset, DumpMethodOffset, DumpTypeDefIndex: Boolean flags to determine if these specific items are included in the dump.cs output.
    • GenerateDummyDll: Whether to generate the DummyDll folder.
    • GenerateScript: Whether to generate IDA/Ghidra scripts.
    • DummyDllAddToken: Whether to add tokens to the DummyDll files.

    Version and Protection Overrides

    • ForceIl2CppVersion: If true, the program uses the version specified in ForceVersion to read the executable (metadata version is still read from its header). This is useful for older il2cpp versions (e.g., setting ForceVersion to 16 for certain Android 20 environments).
    • ForceVersion: The version to use when ForceIl2CppVersion is enabled.
    • ForceDump: Forces the file to be treated as a dump file.
    • NoRedirectedPointer: If true, treats pointers in the dump file as unredirected. This is required for files dumped from certain devices.

    General

    • RequireAnyKey: Whether to wait for a key press before exiting the program.

  4. Troubleshoot common Il2CppDumper errors

    master

    ERROR: Metadata file supplied is not valid metadata file.

    Cause: The global-metadata.dat file is encrypted. Solution: You must decrypt the metadata file first. Alternatively, if you have a rooted Android device, use Zygisk-Il2CppDumper to bypass encryption.

    ERROR: Can't use auto mode to process file, try manual mode.

    Cause: The tool failed to automatically identify the executable. Solution: Ensure you are providing the correct executable (e.g., GameAssembly.dll or *Assembly.dll on PC). If the error persists, manual mode may be required.

    ERROR: This file may be protected.

    Cause: The executable has protection/anti-dump measures. Solution: Use a tool like GameGuardian to dump libil2cpp.so directly from the game's memory, then use that dumped file with Il2CppDumper. For rooted Android devices, Zygisk-Il2CppDumper can bypass almost all protections.

  5. Reference the Il2CppDumper output files

    master

    After running Il2CppDumper, the following files are generated in the output directory:

    • DummyDll/: A folder containing restored DLL files. Use tools like dnSpy or ILSpy to view information. These are useful for extracting Unity MonoBehaviour and MonoScript using tools like UtinyRipper or UABE.
    • ida.py: Script for IDA.
    • ida_with_struct.py: Script for IDA that reads il2cpp.h to apply structure information.
    • il2cpp.h: Header file containing structures.
    • ghidra.py: Script for Ghidra.
    • ghidra_wasm.py: Script for Ghidra, designed to work with ghidra-wasm-plugin.
    • Il2CppBinaryNinja: Script for BinaryNinja.
    • script.json: JSON file used by IDA and Ghidra scripts.
    • stringliteral.json: Contains all stringLiteral information.

  6. Review Il2CppDumper output files

    master

    After running Il2CppDumper, the following files and directories are generated in the current working directory:

    • DummyDll/: A folder containing restored .dll files. These can be viewed using .NET decompilers like dnSpy or ILSpy. They are useful for extracting Unity MonoBehaviour and MonoScript components for tools like UtinyRipper or UABE.
    • ida.py: Script for IDA.
    • ida_with_struct.py: Script for IDA that reads the il2cpp.h file to apply structure information.
    • il2cpp.h: Header file containing structure information.
    • ghidra.py: Script for Ghidra.
    • ghidra_wasm.py: Script for Ghidra, compatible with ghidra-wasm-plugin.
    • Il2CppBinaryNinja: Script for Binary Ninja.
    • script.json: Configuration file used by ida.py, ghidra.py, and Il2CppBinaryNinja.
    • stringliteral.json: Contains all stringLiteral information.
    • dump.cs: (Generated based on config) Contains dumped method, field, and property information.