¶ Preface
Due to data-driven structure with exposed config files, Phantom Brigade has always been fairly easy to modify. By modifying any file in the Configs folder, you can create a wide range of mods (altering scenarios, rebalancing equipment, adding new units or localization, etc.). However, this approach to modding has some issues and limitations:
- It requires modifying content of application directory
- Not every user has the ability to modify its contents - on some machines, the game is installed into a protected directory
- Game updates can overwrite changes like modified files, leading to lost mods
- Game updates can leave in changes like added files, leading to bugs
- It is not possible to install mods modifying the same config
- If a mod modified a file like
simulation.yaml, no other mod could modify anything reliant on that file
- If a mod modified a file like
- 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.)
¶ Intro
This new modding system is an attempt to solve all these issues. It closely follows modding systems in popular moddable Unity games. To start, you need to do the following:
- Create or download
mods.yamlfile and place it intoC:\Users\[USER]\AppData\Local\PhantomBrigade\Settingsfolder. See examples of file content above.- Ensure that
enabledequalstrue - Ensure that
loadFromApplicationPathequalsfalse - Ensure that
listis empty or matches existing folders in required format (more on that below)
- Ensure that
- Mods are unpacked into C:\Users\[USER]\AppData\Local\PhantomBrigade\Mods 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.yamlfile that provides some essential information about content of the mod to the game, allowing for loading it and for drawing of mod management UI- Version
- Identifier (more on that later)
- Name
- Description
- Included types of content (more on that later)
- Compatible versions of the game (in the format
a.b.c, for example0.14.2,0.16.0etc. - do not include any suffixes like-b3103Eyou see in build info watermark)
- When
mods.yamlhasenabledproperty set totrue, new main menu option will appear in the game - Mods menu- In this menu, you'll see a list of all detected mod folders on the left
- You can click each mod to display the details pulled from
metadata.yamlin a given folder - You can include some mods into the selected list by clicking the inclusion button (arrow pointing right).
- If any mods are included in the selected list, you'll see them in the window on the right.
- Any entry in the selected list can be activated/deactivated or moved up/down. This allows you to configure mod order or temporarily disable some mods without having to redo your list later. Any entry can also be excluded (pushed back to the left list) by clicking the associated button.
- You can directly control the list of selected mods, activation and load order by editing
listproperty inmods.yaml- the UI is just an interface modifying that property in the config. - Pressing “Reset” will load
mods.yamlfrom disk and update the UI accordingly. - Pressing “Save” will write an updated
mods.yamlto disk. - Pressing “Apply” will attempt reload of mods based on currently active config (it is recommended to restart to apply changes instead).
Warning! The game already applies mods on startup (based on config state at that point). The option to “Apply Mods” available in the menu above is not the recommended way to applying changes in mod configuration and could cause unforeseen issues. If you change something in the mod menu, e.g. disable, enable or reorder mods, we recommend to hit “Save Config” and restart the game to see the effects. Furthermore, there is no support for loading library mods (code injection mods) more than once per session, as it is impossible to undo unpredictable changes they might make to the runtime - any such mod will be skipped if the game already loaded a code mod during the current session. However, this option can be useful for quickly checking changes while developing config mods and in other such cases.
Mod directories listed in list property in mods.yaml (included and activated via mod menu or manual editing of this config) will be analyzed by the game on startup. Based on information provided in metadata.yaml , the game will check the mod for compatibility with current version and will traverse contents of its folder, attempting to load it. See subsequent sections for details on supported mod content types.
¶ Mod Content Types
Mods can include several so-called 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 will be expanded over time to include more (like localizations), but for now, the four following types are supported.
¶ 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 tags field 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
- 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.
¶ 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
- 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
- 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
- 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 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.