This is an official reference page. If you encounter inaccuracies or would like to expand the page, please message the developers in the #phantom-modding channel on BYG Discord.
¶ Overview
This page details the design of the modding system in Phantom Brigade and is intended for mod developers. If you're looking for mod installation instructions or general guidelines, please refer to the top level Modding page.
¶ Modding system
Due to data-driven structure with exposed config files, Phantom Brigade could always be modified directly. It's possible to alter scenarios, rebalance equipment, adding new units or localization, etc. by changing files in the installation folder. However, this approach to modding has some issues and limitations:
- It requires modifying content of application directory, which makes mods lost on updates or file validation, renders modding inaccessible to some user account etc.
- It is not possible to install multiple mods altering the same config
- It is not possible to modify game logic
- And a whole host of other issues (inability to control mod order, the need to duplicate a bunch of data unrelated to mod intent etc.)
The modding system is an attempt to solve all these issues. It closely follows the design of the mod systems in other popular moddable Unity games. To start modding, open the AppData/Local/PhantomBrigade/Mods folder. Versions of the game prior to 1.1 required additional manual setup (manually creating the Mods folder and Settings/mods.yaml), but this is no longer necessary.
If you can't find the folder, Windows Explorer settings might be set to hide it on your PC. Please refer to the following web page for details. View hidden files and folders in Windows - Microsoft Support
Alternatively, you can press the "Local mods" button in the Mods tab of the main menu to open the folder.
Each mod gets a separate subfolder, e.g. Mods/MyMod1, Mods/MyMod2 and so on:
In each mod folder, there should be a metadata.yaml file that provides some essential information about content of the mod to the game, allowing for loading it and for drawing of mod management UI
- Identifier
- Version
- Included types of content (more on that later)
- Compatible versions of the game (e.g. “1.0” or “1.1.2”)
- Name
- Description
The main menu allows you to see all the mods detected in the mod folder:
The game applies mods on startup. If you install, disable or re-enable a mod, you will need to restart the game to see the effects.
¶ Mod Content Types
Mods can include different content types. These are represented by subfolders in the mod folder and their presence is declared in metadata.yaml. The set of supported content types has expanded over time to include configs, localizations, images and more.
¶ Config overrides
- Metadata flag:
includesConfigOverrides - Folder:
ConfigOverrides/
This is the simplest possible type of mod content, quite similar to editing Configs folder directly.
- Duplicate parts of Configs folder hierarchy under Mods/[ModName]/ConfigOverrides and you can replace anything or add new files.
- The files you place there have to be modified copies of .yaml configs from the game, with exact same internal layout
- The changes are injected whenever database is reloaded, not just on game initialization, so they are resistant to databases loading late, databases loading multiple times etc.
- For instance, you can put new weapon at Mods/[ModName]/ConfigOverrides/DataDecomposed/Equipment/Part_Presets/my_new_weapon.yaml and the game will load it
- Another example: you can put your own version of global settings config at Mods/[ModName]/ConfigOverrides/Data/Settings/simulation.yaml and it will be the version of global settings game will start using
- Limitation: Only contents of Data and DataDecomposed folders are supported. We have some other files under Configs that can't be modified with this mod content type for the time being. Applying a mod with config overrides is not a disk operation modifying files in PB/Configs directly; it's an injection operation during loading steps of DataLinker and DataMultiLinker data managers. The files that can be overwritten, however, are what you'd usually want to modify anyway - other files are a small minority and aren't a good fit for modding (some old binary files, unused configs predating current database system etc.).
¶ Config edits
- Metadata flag:
includesConfigEdits - Folder:
ConfigEdits/
This content type allows for much more fine grained modifications resistant to multiple mods modifying the same file, file changing shape when game is updated etc.
- On the surface it looks similar to config overrides: duplicate parts of Configs folder hierarchy under
Mods/[ModName]/ConfigEditsand put your .yaml matching path/name of existing - However, the content of these files is different. Internally, these files have a different structure. Instead of duplicating real config of the same name at the same path, they store a list of changes. The edit config allows you request removal or, what's more exciting, allow you to edit individual fields and collection entries on a config of the same name.
- This is a big game changer for config mods. One of the big pain points in modding is conflicts between different mods modifying same file and the need to constantly update the modified copy of extracted file every time developers update a game. For instance, our
simulation.yamlcontains hundreds of parameters, and many different mods will definitely want to modify it, whether it's to change allowed squad size of physics settings or loot generation multipliers. - Ordinarily, the changes have to be merged manually and turned into a separate compilation mod - there is no other way to let multiple mods changing the same file coexist. With this feature, one mod can have a single line
simulation.yamlfile modifying a line calledsquadSizeand another can havesimulation.yamldescribing changes to couple other fields - and every change will be seamlessly merged. It's as if every single collection entry or field in our configs is a separate .yaml or a separate folder, allowing for very targeted changes. - Another good example is a request to change squad size frequently popping up in our modding channel. Without this feature, it requires maintaining full copies of every single scenario in the game and a copy of global simulation settings file, which is not nice and blocks an uncountable number of other possible mods related to these files. With the config edit feature, squad size mod will not conflict with much else and requires no updates when we edit simulation config or scenarios in a new release.
The format of these edit configs is relatively simple.
- Set
removedto true to remove targeted config from the game (for instance, if your mod replaces parts of the arsenal and needs to remove built-in weapons from the game) - Fill
editsfield to perform fine grained changes in targeted config- Each line must begin with
-, just like any serializedList<T>in other configs. - Each line must be wrapped in quotation marks, like so:
- 'hidden: true'. This enables you to use reserved characters anywhere within the line. - Each edit consists of two sides separated by a colon
:- left side is a path, and right side is a value- For top level fields, the path is just the field name. For instance, to modify a top level field named
squadSizeto a value of3you can just type:- ‘squadSize: 3’. - Some fields are nested within other fields - to reach them, include all steps into the path, separated by full stops
.- for instance, here is a modification to a field nested 1 level deep:- 'customPlayerSlot.spawnTagsUsed: true'. - You can even access collections as if keys in dictionaries or indexes in lists were field names, like so:
- ‘states.no_hostiles.visible: false’(no_hostilesis a dictionary key here);unitChecks.0.value: 1(0is a list index here!)
- For top level fields, the path is just the field name. For instance, to modify a top level field named
- You can repeat edits with same path multiple times, since the
editsfield is not a dictionary. For instance, it's totally fine to modify atagscollection once (e.g. removing something) and then modify it again (e.g. to add something)
- Each line must begin with
- The set of value types that can be parsed is for now limited to the following set:
string,bool,int,float,Vector2,Vector3,Vector4- For string fields, right-side value will be used as is
- For bools, it will be parsed using equality to
true - For floats and integers, refer to expected string format in C# documentation for
int.TryParseandfloat.TryParse. An example would be6,8.62etc. - For vectors, the expected format is a correct number of floats in expected float format, separated by commas and wrapped by parentheses. An example would be
(3.1, 4, 7.2)etc. - However, not every case requires parsing. For instance, what if all you want to do is fill a field with a default value, e.g. fill a reference field with a fresh instance of its type? There is a special reserved keyword for doing so,
!d(for “default”). Use it like so:- 'customExitBehaviour: !d'
- For normal fields, the following operations are supported:
- Overwriting a value with specified new value
- ‘field: 7’- overwrite field namedfieldwith value of 7
- Overwriting a value with specified new value
- For
List<T>, the following operations are supported:- Overwriting a value with specified new value
- ‘list.4: 7’- overwrite index 4 in list namedlistwith value of 7
- Adding a new value at specified index:
- ‘list.0: 7 !+’- insert value of 7 to the very beginning of the list- 'list.8: 7 !+'- insert value of 7 to index 8 (if list has more entries) or just to the very end of the list (if list has fewer entries than 8)
- Removing a specified index:
- 'list.3: !-- remove entry at index 3
- Overwriting a value with specified new value
- For
HashSet<string>, the following operations are supported:- Adding a value:
- 'tags: context_facility !+'- attempt to insert the stringcontext_facilityto the hash settags
- Removing a value:
- 'tags: context_fort !-'- attempt to remove the stringcontext_fortfrom the hash set
- Adding a value:
- For
Dictionary<T>, the following operations are supported:- Overwriting a value with specified new value
- ‘dictionary.existing_key: true’- overwrite value at keyexisting_keyin dictionary nameddictionarywith value oftrue
- Adding a new entry:
- ‘dictionary.new_key: true !+’- attempt to insert value oftruewith new keynew_keyinto the dictionary
- Removing an entry:
- 'dictionary.existing_key: !-- attempt to remove the entry with keyexisting_key
- Overwriting a value with specified new value
- Full set of supported operation tags:
!+- add new entry!-- remove entry!d- set to default value (for reference types - a new instance, not null)!n- set to null
- The set of supported operations will grow over time. However, if you encounter a case warranting large changes to the config edit system (e.g. if you need ability to parse complex data types), consider trying to implement what you're after using libraries, not config edits.
- Important limitations (to be addressed in future releases):
- Editing
Colorfields is not supported - A path needs to be entered for every edit
- There is no support for multiline edits such as declaring a whole object at once
- Editing
¶ Libraries
- Metadata flag:
includesLibraries - Folder:
Libraries/
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 ModLinkprovides an entry point to modders: you can declare an override toOnLoadmethod 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:
0Harmony.dlldownloaded from 2.1 release on Harmony website (future releases of Phantom Brigade might include it directly in the Managed folder above)Assembly-CSharp.dll,Assembly-CSharp-firstpass.dllSystem.dllandUnityEngine.dllfrom your install folder, e.g.PB/PhantomBrigade_Data/Managed/Entitas.dllfrom your install folder
- Create a
ModLink.csfile- In it, wrap everything in your own custom namespace, ideally matching the
idfield in yourmetadata.yaml, e.g.ModTest - Declare a class inheriting from type
ModLink, e.g.public class ModTestLink : ModLink- In that class, declare an override method
OnLoadwith 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
metadatafield that can tell you what folder you're working with, what mod is this library loaded in, etc; accessModManager.loadedModsto interact with other mods, access any game classes, perform custom patching procedures usingHarmonyobject passed into the method etc.
- In that class, declare an override method
- Declare 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
OnLoadoverride and comment outbase.OnLoad (harmonyInstance)call in it.
- Declare any number of subclasses annotated with Harmony patch attributes within that class, for example:
- In it, wrap everything in your own custom namespace, ideally matching the
- 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.
¶ Textures
- Metadata flag:
includesTextures - Folder:
Textures/
This content type allows you to overwrite existing textures or extend the set of available textures:
- Place your textures under under Mods/[ModName]/Textures.
- If the folder is not recognized by the game, it will be skipped (see PhantomBrigade_Data/StreamingAssets/UI to see what folders the game knows about and samples of content in them)
- If a texture doesn't match the requirements game has defined for a given folder, it will be skipped (see below or inspect textures in StreamingAssets to determine required format)
- If a texture with the same name was already loaded (for a given folder), it will be replaced. If no such name existed before, new texture will be registered under it.
- Currently supported folders:
- Textures/UI/OverworldEvents
- Images used in overworld event UI (controlled by
imagefield instepsofDataContainerOverworldEvent(in Configs/DataDecomposed/Overworld/Events) - Must have resolution of 1024x512
- Must not include an alpha channel or be opaque
- Images used in overworld event UI (controlled by
- Textures/UI/OverworldEntities
- Images used in overworld entity information UI (controlled by
imagefield ofDataContainerOverworldEntityBlueprintin (Configs/DataDecomposed/Overworld/Entities) - Must have resolution of 512x256
- Must not include an alpha channel or be opaque
- Images used in overworld entity information UI (controlled by
- Textures/UI/PilotPortraits
- Images used for pilot portraits (controlled by players customizing pilots in the base)
- Must have resolution of 256x256
- Can skip alpha channel or leave it opaque (for traditional 2D portraits fully covering the camera feed) or include alpha channel (for semitransparent overlays)
- Textures/UI/Sprites
- Images used for UI
- Max resolution 256x256, but any resolution below that is supported (e.g. 31x79px)
- Must include an alpha channel
- Textures/UI/OverworldEvents
¶ Localization Edits
- Metadata flag:
includesLocalizationEdits - Folder:
LocalizationEdits/
This type of content payload enables you to add text to the localization database. It is rare (and will be even rare in the future) that data files under Confgs/Data and Configs/DataDecomposed contain any player facing text, since storing text that way prevents the possibility of localization and easy text modification. Most of the text in the game will eventually be stored in localization database, under Configs/Text, split into versions for different languages. This poses a problem to mods, however - if you add a new item, and the text for it is not stored in the main data config, how do you add player facing text for it?
For an example, if you're adding a new thruster subsystem, you definitely want it to have a name and a description. But name and description do not come from subsystem config, since the game supports their localization - the game takes the subsystem name like internal_aux_thruster_mod, decides on localization keys based on it, like internal_aux_thruster_mod__name and internal_aux_thruster_mod__text and tries to fetch text using these keys from the appropriate text sector of the loaded language (e.g. Configs/Text/English/Sectors/equipment_subsystems.yaml. Without ability to mod these text sectors, your new item can't have a user-facing name/description.
How this type of content can be used is highlighted on the screenshot above, but just in case, here is a step by step overview:
- Lets say your mod contains a new config at
ConfigOverrides\DataDecomposed\Equipment\Subsystemscalled internal_aux_thruster_mod.yaml. Such a file doesn't exist in the base game - it's a new item, not a modified one. The game can't show any text for it. - You find an example of how other subsystems in the game are localized. The easiest two ways are:
- If you have IL inspection tools like dotPeek or Rider and know how to open game codebase, you can read ResolveText methods in a database class you're interested in, and learn what text sector and text key pattern is used for every item
- Alternatively, you can use an editor like Notepad++ or Sublime Text and search
Configs\Text\English\Sectorsin the game install folder for name of an existing subsystem, like internal_aux_thruster_hotrod, to see which sector file such text is stored in and how the text keys are structured. - You add another folder to your mod, right next to ConfigOverrides folder: LocalizationEdits. You put a file into it that declares you want to add 2 new text strings (for name and description) into English localization, into equipment_subsystems text sector, because that's where text for subsystems is stored based on your investigation.
- If you placed everything to the right folder and included the localization edits flag into your mod metadata, you're done - your new item will have new player facing text in game!
Internally, localization edits are applied every time the game loads language database and a registered per language key, which means that:
- Even if you reload a language, the changes are still applied
- Even if you switch a language, the changes are still applied
- You can even support multiple localizations and unofficial localizations loaded via other mods - for instance, you can create
MyMod\LocalizationEdits\English\equipment_subsystems.yamlfile to add text to players using English but you can also add a second file atMyMod\LocalizationEdits\Japanese\equipment_subsystems.yamlto add support for Japanese localization. Or someone can make a new mod extending your mod, containing localization for a first mod for a specific language.
Here is an example: this item doesn't exist in base game and was added by a mod, and the game properly displays custom name and description depicted in file screenshots in previous image:
¶ Localizations
- Metadata flag:
includesLocalizations - Folder:
Localizations/
This content type allows you to add entire new localizations to the game. General principle is as follows:
- Copy official English folder from game installation folder
Configs/Textinto MyMod/Localizations, rename it to the language you are localizing the game into, e.g.MyMod/Localizaions/French - Translate all text in the included files
- If a mod with localization is loaded, game settings window will have a new Language setting that will let you switch to localization language
Some additional notes:
- To test coverage of localization system, there is a console command
data.toggle-localization-debug, which will render all localized text in a different color and randomize its content - To determine which part of a game uses which portion of localization database, it's recommended to use IL inspection tools like ILSpy or dotPeek, open Assembly-CSharp from game install folder and look for methods named ResolveText in files inheriting from DataContainer class. Majority of databases in the game resolve localized text in such methods, and reading them will allow you to learn how localization keys are generated and used from data keys. This can also be useful for localization editing mods discussed above.
¶ Other Notes
Keep an eye out on game log - it will contain plenty of information from mod manager in case anything goes wrong, or confirmation of successful loading if everything goes well. Look for messages towards very beginning of the log, prefixed with “Mod Manager”. To look at the log, press Ctrl+Shift+F11 or open the log file in application data folder.
It might also be useful to enable developerMode property in debug.yaml in AppData\Local\PhantomBrigade\Settings to get access to additional options, debug information and console commands while developing a mod.
Note that no bug reports or crashes from a game in developer mode or with active mods will be processed by BYG.