Our modding adventures can't start without being able to load the mods, as otherwise all our work will be for nothing. First we'll need to download a compatible version of BepInEx[github.com], which is any of the releases tagged 5.4 for now. I've personally tested 5.4.22 as well as 5.4.23.1, and found that both of them work.

You will want to download the one that supports both the game (x64) and your platform (Windows, Linux, or MacOS). Then open the directory which contains the game, which can be done in Steam by right clicking on the name (or clicking the gear icon) and selecting Manage, then Browse Local Files. Extract the contents of the BepInEx .zip file here.

BepInEx comes with a Console output feature which allows developers to do printf debugging[stackoverflow.com]. This can significantly speed up finding problems or problematic mods, thus if you plan on making a mod pack or making mods, you should enable this.

Navigate to the Game directory, then to BepInEx, and then to config. In here open the BepInEx.cfg file, and under [Logging.Console] change Enabled = false to Enabled = true, and save the file. When you next launch the game, a Console window will appear, showing all Debug.Log and Console.WriteLine statements in your (and others) code.

Note: Sometimes the Steam Overlay glitches and hooks into the Console instead. This causes it to become unresponsive and extremely large, so it's best to turn it off for Mod development.

Each mod may vary in how it should be installed, but usually you extract the contents of their zip/rar/... file to the game directory. Refer to the README file in the mods zip/rar/... file, which should explain how to install it.

There's currently no centralized database for mods for the game, so we have the following two options:

• The Steam Discussions thread.
  
• Github's search[github.com]

We'll need a few things set up to make Code and Asset mods, so this section will go over every step for both.

To make Code and/or Asset mods, we will need to have the same Engine version available as the game uses. Install Unity Hub[unity.com], which allows us to install, manage and uninstall Unity Editor versions, in addtion to managing projects. Once installed and running, navigate to the Unitys archive site[unity.com], select Unity 2021.X, find 2021.2.14 and click the Unity Hub button.

This should now open Unity Hub with an installer page, where we can leave everything as it is, and click Install. It may take a while to install, so you can play games or do other work while it is doing so. Note that when you install Microsoft Visual Studio Community it is necessary to handle the popup dialogues that it shows, as Unity Hub does not have the ability to handle them. Once everything is done, we've gotten the prerequisites of creating mods.

Note: The game ships with content compiled with various Unity Engine versions, but it loads Unity Engine version 2021.2.14f1. It may be possible to use different engine versions, though it is not recommended.

Open Unity Hub and navigate to the Projects tab, which should list any known Projects. Click on New project, then in select the proper Unity Editor version at the top. Then in the larger list, find Universal 3D and download it if it is missing. Finally name your project, put it somewhere you can remember, and click Create Project. Unity will now open your project.

Once the project is open, you'll need to add a simple package to the project. In the menu bar find and click on Window, then click on Package Manager. In the new window click the large + symbol, then select Add package from git URL, and paste in and click Add. This package handles some common things, like building Asset Bundles for your mod, and you can always update it by going back into the Package Manager and clicking Update.

In your Unity project create a new directory directly under Assets named Mods, then right click on the newly created directory and select Show in Explorer. This is the directory where both Asset and Code mods will be placed, to prevent collision with the Game or Engine content, and we'll further subdivide it into mod names.

Open a shell here (Shift+RightClick, Powershell or Command Prompt will work), and type in This command downloads the necessary templates, which so far only work with DotNet SDK 7.0[dotnet.microsoft.com] due to a bug in 8.0. You'll need to have this version installed and marked as the default[stackoverflow.com] for the next steps to work.

Next is to create the Code mod based on the BepInEx 5 template, which is simply another command. In the shell you opened, type in and replace NAME and MOD with your name and your mod name respectively. This creates the necessary files, but isn't completely correct yet.

Note: To prevent name collisons with other mods, prefix your mod name with your own name or alias. As an example, I would be using xaymar.examplemod. Note that your code and asset mod will be lowercase.

We'll need to deal with a few issues from now on before we can continue:

We'll be unable to create a mod properly if we don't address this, and it's relatively easy to fix - despite Microsofts attempts to make it harder. We just need to make two modifications to our project, so first lets fix the csproj file we generated by adding: between the <PropertyGroup> ... </PropertyGroup> section. This also fixes the output name having net46 as a prefix, which we don't want.

Next is to address that MSBuild, the build system behind Visual Studio, will ignore the intermediate directory. We can address this by introducing a new file called Directory.Build.props in the same directory as the csproj file with the contents: This will make MSBuild properly place intermediate and generated files outside of the project directory. Please note that it needs to be called Directory.Build.props, not Directory.Build.props.txt - turn on showing known file extensions.

Unity loves C#, and immediately tries to compile it, only to then complain that it can't find some things - in this case BepInEx. As we don't want Unity to even consider BepInEx to exist, we need to surround any BepInEx code with a preprocessor conditional compile: While not pretty, this conditional allows you to split your BepInEx and Unity code quite clearly, and you can even open separate Visual Studio instances for either.

Adding assets is similar to how you would do it when making your own Unity game: Drag & Drop, or Copy & Paste. The only difference is that we explicitly need to set the Asset Bundle name for each Asset we want to include. The name can be anything, but it's best to just name it the same as your mod. You'll find the controls for this in the bottom right on every property inspector that supports Asset Bundles.

Note: Some asset types can't be included in your Asset Bundle, such as Code and Built-In Shaders. Unity will refuse to bundle either of these, and this is why we have two "mods" acting as one mod overall.

As neither Unity nor BepInEx load Asset Bundles automatically, we'll have to add a bit of code to the Code mod. This code should automatically detect any asset bundles next to our mods DLL file, so that we don't have to manually add every single one. This is easily achieved with these 12 lines of C# code, which you add into the Plugin.cs file after the // Plugin startup logic line:



This code first tries to find where itself is, throwing an error and thus aborting further code from loading if it fails to do so. Then it iterates over every file ending in .assetbundle, loading it synchronously, thus making it available in the game. Any assets from it can now be used by our code, and even other mods can make use of your assets - as long as your mod is loaded and a dependency of the other mod.

Thanks to all the work we've done, this step is extremely simple and consists of two tasks only. In the Unity Editor, open Guardian's Bundler (Menu Bar -> Guardian -> Bundler) and click Export. Then open the csproj file of the BepInEx plugin, and build it for Debug or Release. Prefer the latter if you want to publish it, and the former if you're testing. You should end up with a BepInEx directory next to your projects Assets directory.

If you've done step 1 correctly, then all you need to do now is copy the BepInEx directory from your Unity project directory to the game directory, and replace any files it asks about. Then start the game, and your mod should load. Unfortunately you likely won't be able to directly debug your mod, so best stick to plenty of printf debugging in your Debug builds!

This section is incomplete, as no mod manager or mod store exists yet.

For now, simply zip up the BepInEx directory and share it between friends. Maybe release them using a Github or Gitlab repository - discovery is going to be quite bad at first until a mod store appears.

https://github.com/Xaymar/CrystalGuardians-Example