Koikatu: Modding
Most of the up-to-date modding resourced and guides are shared on the Koikatsu or IllusionSoft Discord servers. This is also where you can find most of the English speaking modders working on plugins and mods.
If you are having trouble and can't find an answer online (google is your friend) or want to try to make your own plugin/mod, feel free to ask for help in modding channels of these servers. Please at least try searching for solutions yourself before asking, most questions were already asked and answered!
This guide applies to Koikatu, Koikatsu Party, EmotionCreators, AI-Syoujyo, AI-Shoujo and other similar UnityEngine games made by Illusion.
Contents
How to compile a plugin?
The best way to learn is to compile an existing plugin and make changes to it. First find the plugin's repository, then simply clone it to your drive and use the free version of Visual Studio 2019 for C# to compile it. Keep in mind that you might need to fix references by pointing at some of your game's files. Check the following links for useful tutorials:
Condensed guide on modifying and making new plugins
First of all, environment. You need:
- Visual Studio 2017 or newer, use the free community version
- KK with BepInEx installed
- Cheat tools plugin (for the included Runtime Unity Editor, press F12)
- dnSpy for reading game and other dll source code and debugging of the game (To do debugging with dnSpy you need to set up a few things for it to work * https://github.com/BepInEx/BepInEx/wiki/dnSpy-Debugging * this is optional and you most likely won't need it until you're doing much more advanced stuff)
- Go to your in-game plugin options and enable bepinex console and all logging levels, including unity logging
Getting started
- Get to roughly know C# and how it works. There are plenty of tutorials on it.
- Grab a simple plugin, for example https://github.com/ManlyMarco/IllusionTrapMods/tree/master/KK_BecomeTrap and see how it's constructed. Try to compile it.
- You need to fix the plugin's references before you can build (point it to dlls from your game install) and build locations (right click on the project in tree view > Preferences > Build).
- Use BepInEx.Logger.Log for showing messages in console
Things to read
Critical
- https://docs.microsoft.com/en-us/dotnet/csharp/getting-started/
- https://github.com/BepInEx/BepInEx/wiki
- https://github.com/pardeike/Harmony/wiki
Optional
- https://github.com/IllusionMods/IllusionModdingAPI/wiki
- https://github.com/BepInEx/BepInEx.ConfigurationManager
- https://help.github.com/en/articles/set-up-git
- https://blogs.msdn.microsoft.com/benjaminperkins/2017/04/04/setting-up-and-using-github-in-visual-studio-2017/
- https://github.com/0xd4d/dnSpy/wiki/Debugging-Unity-Games
Tips
- KK is a Unity3D game and is written in C#, skills you gain here will apply to almost all other Unity games.
- Koikatu_Data\Managed\Assembly-CSharp.dll has most of the game code in it, open in dnSpy to read and research it.
- Check source code of other plugins to see how certain things are accomplished. Don't be afraid to post issues or submit PRs to existing repositories, that's a great way to learn!
Quick debugging tutorial using dnSpy
Running the game in debugger makes finding causes of issues and understanding how the game works much easier. To run KK in the debugger included in dnSpy you need the modified mono dlls from the dnSpy release post. You can read more here https://github.com/0xd4d/dnSpy/wiki/Debugging-Unity-Games
Open dnSpy, drop Koikatu.exe on it, click the newly added .exe, and click Start. It should start running the game and dnSpy should enter debugging mode. You can open assembly-csharp or one of your plugins, place a breakpoint at some line and make the code run in game to test it out. Locals are the variables available in the current scope, Watch contains your expressions (you can put arbitrary C# code in these and it will get executed when you hit enter). It's pretty similar to debugging in VS, just more limited.
When you recompile a plugin that is loaded in dnspy then make sure to go file > reload all. If you changed code where a breakpoint was set, then it might mess up and move the breakpoint to some different spot. You can check where all breakpoints are in the breakpoint window.
Adding or modifying items / mod making
Because of the large scope it's difficult to provide a simple step-by-step guide. A large collection of guides is available here: https://github.com/xm007/Koikatsu-Modding#koikatsu-modding-tutorial You can ask for assistance on the discord server in the #mod-modelling channel, we'll be happy to help you out!
