r2unity

A lightweight, dependency-free C tool to parse Unity's global-metadata.dat and generate radare2 scripts for analyzing libil2cpp.so binaries.

Motivation

The Unity engine, when using its IL2CPP backend, compiles C# code into C++ and then into a native library (libil2cpp.so on Android/Linux, GameAssembly.dll on Windows, etc.). To understand the original code structure, reverse engineers need to parse the global-metadata.dat file, which contains all the type information, method names, and pointers into the native library.

While powerful tools like Il2CppDumper exist, they are often written in higher-level languages (like C#) and produce generic outputs (like C++ headers or JSON files).

r2unity takes a different approach by focusing on a single goal: deep integration with radare2. It is written in plain C for maximum performance, portability, and zero runtime dependencies. The output is a ready-to-use .r2 script, allowing analysts to immediately apply this metadata within their radare2 sessions.

This project is inspired by the functionality of Il2CppDumper and the metadata parsing concepts from projects like lib-global-metadata.

Features

• Parses global-metadata.dat: Extracts classes, methods, and their relative addresses.
• Generates Radare2 Scripts: Creates .r2 files to name functions and add comments in your analysis session.
• Written in Plain C: No dependencies beyond a standard C compiler (like gcc or clang).
• Lightweight and Fast: Designed for speed and minimal memory footprint.
• Cross-Platform: Aims to be easily compilable on Linux, macOS, and Windows.

Getting Started

Prerequisites

• A C compiler (e.g., gcc, clang)
• make

Installation

git clone https://github.com/your-username/r2unity.git
cd r2unity
make

Usage

The primary goal is to generate a script that radare2 can use to annotate the libil2cpp.so binary.

1. Extract Files: Obtain the global-metadata.dat file and the main binary (e.g., libil2cpp.so) from your target application.

2. Run r2unity: Execute r2unity with the metadata file and the base address where the binary is loaded. The output will be an .r2 script.

   ./r2unity /path/to/global-metadata.dat > symbols.r2
   

3. Launch Radare2: Open the binary in radare2, sourcing the generated script with the -i flag.

   r2 -i symbols.r2 /path/to/libil2cpp.so
   

Radare2 will execute the script, defining flags (function names) for all the methods found in the metadata.

Example Output (symbols.r2)

The generated script will contain a series of radare2 commands:

# r2 script generated by r2unity
# Found 50,000+ methods in global-metadata.dat

f Some.Namespace.ClassName.MethodName @ 0x1a2b3c
CCu Method: Some.Namespace.ClassName.MethodName @ 0x1a2b3c

f Another.Class.Update @ 0x2b3c4d
CCu Method: Another.Class.Update @ 0x2b3c4d

f Player.Stats.GetHealth @ 0x3c4d5e
CCu Method: Player.Stats.GetHealth @ 0x3c4d5e

...

Philosophy

• Do One Thing Well: Focus solely on creating r2 scripts from Unity metadata.
• Native and Dependency-Free: Avoid the complexity of runtimes like .NET or Python. A single, static binary is the goal.
• Integrate, Don't Just Convert: The output should be directly consumable by the target tool (radare2) to provide immediate value.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request. As this is a C project, please adhere to a clean and readable coding style.

Acknowledgments

• The Il2CppDumper project for being the gold standard in Unity IL2CPP reversing.
• The lib-global-metadata project for its clear implementation of metadata parsing.
• The radare2 community.

License

This project is licensed under the MIT License. See the LICENSE file for details.