Creating library mods

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

Custom libraries is an extremely 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.

The tutorial will additionally cover setting up a Git repository for your code. Any code project can benefit from version control, but a public repository also a mandatory requirement for any downloadable code mod under the Modding Guidelines.

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.

Project setup

...

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.