Creating library mods

This article is a work in progress! Please check back later!

Custom libraries are an very powerful tool that can facilitate nearly any modification to Phantom Brigade. The game is powered by Unity/C# and reads IL (interpreted language) at runtime. The IL code is modifiable at runtime, which means that it's possible to patch game logic and execute new code from mods. This tutorial will cover the full process of creating a library mod, from setting up the project to building and exporting your mod.

Dependencies

We strongly recommend reading through the following articles before you begin:

• Mod projects
• Basics and Patching articles from the Harmony documentation
• If you're new to C# or haven't interacted with the Reflection feature before, check out Introduction to Reflection

You'll need an IDE software capable of creating and compiling solutions that are .NET 4.7.2 Class Libraries. We strongly recommend using JetBrains Rider (even if you're familiar with other IDEs). It's free for non-commercial use and features a built-in decompiler letting you explore C#/IL code in the Unity and Phantom Brigade assemblies, which is essential when developing mods.

Repository setup

First, we'll need to create a new Git repository on GitHub. It will help you keep track of the changes and give you a backup if things go south. The repository can start private but will have to be made public once you publish your mod to comply with the Modding Guidelines.

Start by following a the Quickstart for repositories tutorial from GitHub. We recommend the following settings:

You should end up with a ready to use project that looks like this, with some files already in place (like README.md and .gitignore):

Local repository

Next, we'll need to clone the project to your machine using Git. Choose an easily accessible folder close to disk root. For this tutorial, I'm going to use D:/Work/UnityProjects/PB_LibraryTutorial.

If you're not familiar with Git and are unsure how to download a project from GitHub, try installing the GitHub Desktop client and following this tutorial. You should end up with folder contents that match what you saw in the browser:

Create a subfolder with the desired mod ID within the root folder. The repository is intended to be used with the External projects feature of the SDK. Mod config and other files will be located under a subfolder to allow using the root as a target for Custom project folders in the mod project manager config. For this tutorial, I'll use PB_Library as the mod ID and solution name. This setup will also allow you to reuse the same repository for several mods:

Creating a solution

Start Rider and select File > New Solution. Select the following settings:

• Project type: Class Library
• Solution name & Project name: Same as the mod subfolder
• Solution directory: Mod subfolder (e.g. D:/Work/UnityProjects/PB_LibraryTutorial/PB_Library in our case)
• Put solution and project in the same directory: On
• Create Git repository: Off
• Target framework: v4.7.2
• Language: C#
• Type: Class Library

Confirm the project. You should end up with file hierarchy like this (solution folder within the mod folder within the root folder):

Creating a patch

...

Building

...

Setting up mod project

...

---

The article is a work in progress Old text below

• Metadata flag: includesLibraries
• Folder: Libraries/
• Refer to the Including libraries to learn about making this type of modification with the SDK.

This is a very powerful type of mod content enabled by C#/Unity's reliance on editable interpreted language (IL): ability to load libraries that can patch game logic and execute new code.

• This feature is partially enabled by a popular library called Harmony - we've already been using it, but for internal needs, like patching Unity Editor UI
• It is recommended that you read Harmony documentation if you're a programmer interested in creating a library mod.
• The mod system tries to discover all assemblies in Libraries folder, like Mods/[ModName]/Libraries/MyLibrary.dll
• It then fetches types from that assembly and tries to find a class inheriting from special type ModLink - if found, it's instantiated, filled with data, and has a special entry method invoked
• ModLink provides an entry point to modders: you can declare an override to OnLoad method in it, executing arbitrary code; you get access to full mod metadata (so you know where you are, what mod you're in, what other mods are loaded) and access to the Harmony patcher object, allowing you to modify code in PB.

General setup of a new library goes as follows:

• Create a .NET Class Library (.dll) project in Visual Studio Community, Rider or other .NET IDE, targeting .NET Framework 4.7.2
• Add the following references to it from your install folder (e.g. SteamGames/Phantom Brigade/PhantomBrigade_Data/Managed/):
  • 0Harmony.dll
  • Assembly-CSharp.dll
  • Assembly-CSharp-firstpass.dll
  • Entitas.dll
  • System.dll
  • UnityEngine.dll
• Create a ModLink.cs file
• In it, wrap everything in your own custom namespace, ideally matching the id field in your metadata.yaml , e.g. ModTest
• Declare a class inheriting from type ModLink, e.g. public class ModTestLink : ModLink
  • In that class, declare an override method OnLoad with this signature: public override void OnLoad (Harmony harmonyInstance)
  • If needed, implement any custom logic originating from this starting point. For instance, you have access to metadata field that can tell you what folder you're working with, what mod is this library loaded in, etc; access ModManager.loadedMods to interact with other mods, access any game classes, perform custom patching procedures using Harmony object passed into the method etc.
• Declare a plain class called Patches
  • Declare any number of subclasses annotated with Harmony patch attributes within that class, for example: [HarmonyPatch (typeof (PhantomBrigade.GameController), MethodType.Normal), HarmonyPatch ("Initialize")]
  • All of these patches will be applied automatically unless you declare OnLoad override and comment out base.OnLoad (harmonyInstance) call in it.
• Build the .dll, place it in Libraries folder of your mod
• You are free to get into the logic setting up scenario units and changing how they are generated. You are also free to override how post-deserialization code in some data container works, changing how weapon efficiency is explained to AI, you are free to prefix, postfix or entirely replace any method you want modified - sky's the limit. Most mods changing logic or implementing new systems in Unity games such as Rimworld, Oxygen not Included, KSP and others operate on a similar principle.