How to Mod IL2CPP games with CPP2IL

This is a quick tutorial on how I go about modding Muse Dash, a game that's exported into IL2CPP.

Notes:

• This tutorial assumes you are working with Windows.
• This guide will be working with Melon Loader (Github: https://github.com/LavaGang/MelonLoader)
  • This should still be relevant to Bepinex. But extra work may need to be done.
• This tutorial also assumes you'll be using dotPeek to view the dll files. There are other tools, and they should provide the same or even more functionality.

Tutorial

Installation

1. Make sure you have installed .net 6 to your system and have configured your favourite IDE to work with it. .net 6 Downloads
   • You will be needing the SDK to build for Melonloader.
2. Install Melon Loader to the game. Recommend using the Automated Installation method.
   • I recommend the latest version, unless there are issues running it.
3. Run the game once after installing Melon Loader so it create dll files.
4. Work through Melon Loader Quick Start Tutorial.
   • As this is a tutorial for IL2CPP games. You want to make a Class Library with .net 6. How to go about this depends on your IDE however.

Opening the DLL

At this point, you should have a melon loader mod. You will likely want to add a reference to the dll at [Game_Path]/MelonLoader/Il2CppAssemblies/Assembly-CSharp.dll as this should include most of the core classes used within the game.

Your IDE should be able to see the majority of classes within the game now, and all the functions and parameters within them. However you likely will need to guess class names to get anywhere at this point.

So lets open the above dll in dotPeek.

This ends up showing all of the classes and namespaces similar to how a typical c# project is structured. This should let you find similar files, and also lets you do a basic search.

That being said... if you try to go to any class, you will find that once decompiled, the classes will be hard to read.

(Above shows 3 properties and all the functions, but does not show the types, and the names can be hard to parse.)

Getting Readible Code

Note: This step seems to require having Melon Loader be run first. Unsure if Bepinex can also run this step as is. It likely can however

1. Download CPP2IL exe and move it into a folder on its own.
   • Note: This tutorial is working with Milestone 2022.0.7. Newer versions are rewriting code, and thus do not have exactly the same steps to get readible code. (If its possible yet.)
2. Open a command prompt and navigate to the folder.
   • In Windows 10 you can shift+right click the folder and select Open Powershell Window here.
3. Type the following prompt out: .\Cpp2Il-2022.0.7-Windows.exe --game-path "Path To Folder container Game.exe here" --experimental-enable-il-to-assembly-please --throw-safety-out-the-window
   • The command .\Cpp2Il-2022.0.7-Windows.exe --game-path "Path To Folder container Game.exe here" --just-give-me-dlls-asap-dammit should also work (and is faster), but is also possibly more unstable.
   • Note you can avoid typing out the exe name by using tab to Auto complete it after a couple letters.

After letting it run for a while, if you managed to type out the correct command, it will spit out a folder next to the exe with completely new DLL files.

If you navigate into that folder you should find a new Assembly-CSharp.dll inside it. Open that up in dotPeek. (Note: Dotpeek keeps all dlls open all the time. You may want to first right click the old dll in the list view, and select remove item from list first so you don't confuse the 2 dlls.)

You should mostly see the exact same things. However when you go to see a file you should now see much cleaner decompilations!

And with this process, you get the added benefit of being able to see the code within functions within the project.

Caveats

The above system is not perfect. You will frequently run into functions like this:

Where it failed to decompile code at all. You will have to guess what the function does based on context.

The more complex a function is, the more likely it is to have issues within it. For example, some issues I have found with decompiled code are:

• For loops can go missing. Not very typical but can happen.
  • On reading this function it seems like it only deletes one, albeit weirdly with an index. However it actually deletes all files within the folder.

• If statement values can just appear out of nowhere with values such as arg1. You will have to guess where they came from.
• Sometimes code will just plain not make sense. Sadly there isn't much you can do here.

However this method should give enough information to work with code in a much more involved manor than just class names, function names and property names.