Runtime metadata dumper for Unity IL2CPP games packaged as a Theos iOS tweak.
This fork is packaged for MobileSubstrate/Substitute and starts from a tweak constructor inside the target app process.
- Waits for the IL2CPP runtime to become available in the target app.
- Resolves IL2CPP exports with
dlsymfrom the current process. - Attaches the worker thread with
il2cpp_thread_attachwhen available. - Writes static C#-shaped metadata dumps and AI-friendly line-tagged dumps.
- Can optionally write live scene, camera, mesh collider, and targeted class scan dumps.
By default, files are written inside the target app sandbox:
$HOME/Documents/IL2CPP-Dumper
Set IL2CPP_DUMPER_OUTPUT in the target process environment to override it.
Static outputs:
IL2CPP_Dump_Normal/<assembly>.csIL2CPP_Dump_AI/<assembly>.csIL2CPP_Dump_Strings.txtIL2CPPDump_Log.txt
Optional live outputs:
IL2CPP_World_Dump_<timestamp>.txtIL2CPP_Camera_<timestamp>.txtIL2CPP_MeshColliders_<timestamp>.txtIL2CPP_MeshColliders_<timestamp>.binIL2CPP_Scan_<timestamp>.txt
Edit IL2CPPDumper.plist and replace:
com.example.unitygame
with the target app bundle identifier.
The Linux build helper can do this automatically:
TARGET_BUNDLE_ID=com.company.game ./scripts/build_linux.shRun:
./scripts/build_linux.shThe script installs host build tools when it recognizes the package manager, clones Theos, downloads Theos iPhoneOS SDKs, links the selected SDK into Theos, and runs:
make clean package FINALPACKAGE=1Environment variables:
TARGET_BUNDLE_ID: replaces the placeholder filter bundle id.IOS_SDK_VERSION: selects a specific SDK, for example16.5. Defaults to16.5. The build helper installs the larger Swift 5.8 iOS toolchain because the smaller clang-11 toolchain cannot reliably link newer.tbdstubs.THEOS: uses an existing Theos checkout instead of.deps/theos.
The resulting Debian package is written under packages/.
Static dumping runs automatically after IL2CPP is ready.
Set these environment variables in the target process to enable extra runtime passes:
IL2CPP_DUMPER_SCENE=1: run camera, scene, and mesh collider dumps once.IL2CPP_DUMPER_DEEP_SCENE=1: include MonoBehaviour field values during the scene pass.
For targeted class scans, place IL2CPP_ScanList.txt in the output directory
with one fully-qualified class name per line.
- The old Windows structured exception handling was removed. The compatibility
wrappers compile as normal C++
try/catch, but invalid raw IL2CPP pointers can still crash the target process on iOS. - The tweak expects exported IL2CPP symbols. If a game strips or hides them, a symbol-offset resolver must be added for that title.
- Keep the tweak filter narrow. Injecting into unrelated apps is noisy and may crash them.
MIT.