Work-in-progress tool to reverse unity's IL2CPP toolchain.
Work-in-progress tool to reverse unity's IL2CPP toolchain.
WIP Tool to reverse Unity's IL2CPP build process back to the original managed DLLs.
The information below almost entirely applies to the CLI application available on github releases. For documentation on using the "core" module - which the CLI is just a wrapper around - in your own projects, see README_CORE.md
Uses LibCpp2IL for the initial parsing and loading of metadata structures. LibCpp2IL is obtainable from the build artifacts if you want to do something yourself with IL2CPP metadata, and is released under the MIT license. The link above will take you to the documentation for LibCpp2IL.
The decompiled CIL is pretty messy right now, the next thing is probably pattern matching to convert il2cpp specific stuff into C# (generic ISIL should be converted into more C# specific ISIL, new object, throw, etc. instructions should be added to ISIL), but most of the times it's at least possible to see what the method does. Use ILSpy because it works with broken CIL better than dnSpy.
The entry point to decompilation is MethodAnalysisContext.Analyze(), it translates platform specific assembly into ISIL with Cpp2IlInstructionSet,
builds the control flow graph and dominator info, and the rest of the decompilation is done with IAction classes (MethodAnalysisContext.analysisActions),
these include stack analysis, simplification, applying metadata, etc. and then Ilgenerator.GenerateIl() translates the ISIL into CIL that's saved into managed dlls.
Cpp2IL has undergone a major rewrite. This branch represents work in progress, and is subject to change.
CI builds for developers can be obtained from My Nuget Feed.
The command-line interface has been simplified, going from a lot of command line options to a concept of output formats and processing layers. However, a lot of these formats and layers are not yet implemented, so functionality is limited compared to the previously released versions.
Many options, such as --analysis-level, --skip-analysis, etc, have been removed. Analysis is now off by default and can be enabled with --output-as dll_il_recovery.
Equally, options like --supress-attributes, which previously suppressed the Cpp2ILInjected attributes, have been replaced with a process layer - this one is actually implemented,
and is called attributeinjector. You can enable this layer using the --use-processor option, and you can list other options using --list-processors.
Metadata dumps and method dumps will be their own output format too, instead of both being default-on, and controlled via a dedicated option. Currently this means you'll need to run
Cpp2IL multiple times if you want both dumps, though this may change in the future if we add support for outputting to multiple formats simultaneously. Like processing layers,
output formats can be listed via the --list-output-formats option, and are selected via the --output-as option.
Under the hood, the application has been almost completely rewritten. Primarily, this was necessary due to the degree Cpp2IL was dependent on the Mono.Cecil library, which had some limitations. When we looked into switching, we realised how reliant we were on the library. This is no longer the case - the application is written around LibCpp2IL types and the new Analysis Context objects, and the Mono.Cecil library is no longer used, having been replaced with AsmResolver.DotNet.
Analysis is now based on an intermediate representation called ISIL (Instruction-Set-Independent Language), which is converted into a Control Flow Graph for more intelligent analysis.
We're also working on a Plugin system which will allow third-party developers to write plugins to add support for custom instruction sets, binary formats, and eventually load obfuscated or encrypted metadata or binary files.
The simplest usage of this application is for a windows x86 or x64 unity game. In that case you can just
run Cpp2IL-Win.exe --game-path=C:\Path\To\Your\Game
and Cpp2IL will detect your unity version, locate the files it needs, and dump the output into a cpp2il_out folder
wherever you ran the command from.
Assuming you have a single APK file (not an APKM), and are running at least cpp2il 2021.4.0, you can use the same argument as above but pass in the path to the APK, and cpp2il will extract the files it needs from the APK.
| Option | Argument Example | Description |
|---|---|---|
| --game-path | C:\Path\To\Game | Specify the path to the game folder. Required. |
| --exe-name | TestGame | Specify the name of the game's exe file in case auto detection fails (because there are other exe files in the game directory) |
| --verbose | <None> | Log more information about what we are doing |
| --list-processors | <None> | List available processing layers, then exit. |
| --use-processor | attributeinjector | Select a processing layer to use, which can change the raw data prior to outputting. This option can appear multiple times. |
| --processor-config | key=value | Provide configuration options to the selected processing layers. These will be documented by the plugin which adds the processing layer. |
| --list-output-formats | <None> | List available output formats, then exit. |
| --output-as | dll_il_recovery | Specify the output format you wish to use. |
| --output-to | cpp2il_out | Root directory to output to. This path will be passed to the selected output format, which may then create subdirectories etc. within this location. |
| --wasm-framework-file | C:\Path\To\webgl.framework.js | Only used in conjunction with WASM binaries. Some of these have obfuscated exports but they can be recovered via a framework.js file, which you can provide the path to using this argument. |
Every single commit is built to a CI build using Github Actions - the action file can be found in the .github folder, if you want to reproduce the builds yourself. Be aware these may not be the most stable - while there are tests to ensure compatibility with a range of games, sometimes things do break! These are versioned by the commit they were built from.
The release files can be downloaded from the Actions tab if you are signed into GitHub, or you can use the following links, which always point to the latest successful CI build. Note that the .NET Framework build is provided for compatibility with wine/proton.
On top of this, I manually release "milestone" release builds whenever I think a major set of improvements have been made. These are NOT marked as pre-releases on github, and should (at least in theory) be stable and suitable for use on a range of games.
From the first milestone build 2021.0, and onwards, Cpp2IL now outputs more rigidly-structured data to the console. This includes log levels (VERB, INFO, WARN, FAIL) and associated colours (Grey for VERB, Blue for INFO, Yellow for WARN, Red for FAIL).
As of milestone 2021.1, if Cpp2IL is able to detect that you're running in Wine/Proton, these ANSI colour codes are disabled, as they are not supported by wine and look awful.
VERB messages will only be logged if Cpp2IL is launched with the --verbose option, and it would be helpful if you
could report issues with this flag enabled. For normal operation, they shouldn't be needed, unless you're curious.
If you do not wish for the output to be coloured, set the Environment Variable NO_COLOR=true.
This application is built primarily using .NET 9.0, but a .NET Framework 4.7.2 build is also published for legacy purposes.
It uses the following libraries, for which I am very thankful:
(All are MIT licensed aside from XUnit which is Apache 2.0+MIT)
WasmDisassembler subdirectory.The net472 build uses the following additional libraries:
Some plugins also use additional libraries:
Cpp2IL is (very loo
No open issues yet, or sync has not completed.