Plugins: Getting Started
Plugins allow you to extend the functionality of Il2CppInspector. For example, you can:
- add decryption and de-obfuscation for applications that are not automatically supported
- compare multiple applications via their type models
- modify any types, methods or data in an application
- create new kinds of outputs
Plugins provide the same APIs as when creating standalone applications using Il2CppInspector as a type library (see this example for details), while also allowing you to inject code into Il2CppInspector's workflow for end users using the CLI or GUI.
With plugins, you can provide a DLL which will be loaded by Il2CppInspector at runtime, avoiding the need to fork the repo or recompile Il2CppInspector itself.
Il2CppInspector maintains a global plugin repository to which you can contribute new plugins or update existing ones. If you submit plugins, they will be included in each bundled release of Il2CppInspector for everyone to use automatically. See the README.md file for that repo for plugin submission guidelines.
git clone --recursive https://github.com/djkaty/Il2CppInspectorPlugins
The top-level folder contains categories for plugin types - currently just Example and Loader.
Create a new .NET Core Class Library project as a new folder within one of these category folders. Place the solution and project files next to each other in the same folder:
(Item 1 shows the categories, Item 2 is your plugin project, Item 3 shows the solution and project files in the same folder)
You will need to add a dependency to Il2CppInspector, either by installing the NoisyCowStudios.Il2CppInspector nuget package or by cloning the Il2CppInspector repository and adding a project reference to Il2CppInspector.Common.dll.
For some workloads, you will also need to add a reference to NoisyCowStudios.Bin2Object which provides file manipulation convenience functions.
To speed up the development process, you can make the build automatically copy your plugin to the correct folder. Right-click on the project in Solution Explorer, choose Properties, then Build Events from the left pane and add a post-build command line to copy your plugin into Il2CppInspector's plugins folder:
mkdir $(SolutionDir)..\..\..\Il2CppInspector\Il2CppInspector.GUI\bin\Debug\netcoreapp3.1\win-x64\plugins\$(ProjectName)
mkdir $(SolutionDir)..\..\..\Il2CppInspector\Il2CppInspector.CLI\bin\Debug\netcoreapp3.1\win-x64\plugins\$(ProjectName)
copy /y $(TargetPath) $(SolutionDir)..\..\..\Il2CppInspector\Il2CppInspector.GUI\bin\Debug\netcoreapp3.1\win-x64\plugins\$(ProjectName)
copy /y $(TargetPath) $(SolutionDir)..\..\..\Il2CppInspector\Il2CppInspector.CLI\bin\Debug\netcoreapp3.1\win-x64\plugins\$(ProjectName)
(this assumes that you have cloned Il2CppInspector into the same folder as Il2CppInspectorPlugins. If you are using a pre-built release of Il2CppInspector, your paths will be different)
To enable debugging, ensure that the Debug build configuration is selected, then open the project properties and navigate to Debug in the left pane. Change Launch from Project to Executable and enter the path to either the CLI or GUI for Il2CppInspector:
Now you can set breakpoints and launch Il2CppInspector together with your plugin by pressing F5 from your project. Visual Studio will break execution at the breakpoints.
Il2CppInspector may throw exceptions in the normal course of execution. These exceptions are expected and should be ignored. You can prevent the debugger from breaking on these exceptions by ticking the Except when thrown from option for Il2CppInspector.Common.dll when an exception is thrown, as follows:
Add the following using statements to the top of your code:
using Il2CppInspector;
using Il2CppInspector.PluginAPI;
using Il2CppInspector.PluginAPI.V100;
using NoisyCowStudios.Bin2Object; // if using BinaryObjectStreamPlugins are created by implementing .NET interfaces. All items are optional and the default is to do nothing.
The current API version is V100. Items will be added to this API over time. If we make breaking changes to the API, the version number will be advanced by 1.
See the other articles in this section for more details on how to write plugins.