Mod system overview

Mod system design

This section details the design of the modding system in Phantom Brigade and is intended for mod developers interested in the internal workings of the game. We recommend using the tools provided with the SDK for most mods: manual file editing should ideally be the last resort option.

Standalone mod files

Due to data-driven structure with exposed config files, most of the Phantom Brigade can be easily modified. It's possible to alter scenarios, rebalance equipment, add new units or localization, etc. by changing the config files loaded by the game. However, we do not recommend directly modifying the files in the install directory for a number of reasons:

• Modifying content of the application directory is invisible to our bug reporter system and risks mods being reverted when the game is updated or validated. It also locks modding on user accounts with limited writing permissions.
• It is not possible to install multiple mods altering the same config when directly editing the game
• 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.)

Our 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. The core idea is to have a separate folder holding configs and additional content and sideloading that separate data on top of built-in game data. This allows for easy installation, sorting, combining multiple mods etc. This folder is in the same location as save files and game settings: C:/Users/Windows Username/AppData/Local/PhantomBrigade/Mods .

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.

Mod structure

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 (unique internal name for the mod used to confirm the game isn't loading multiple copies of the same mod, used to store settings etc.)
• Version
• Loading priority (which mods load first)
• Included types of content (more on that later)
• Compatible versions of the game (e.g. gameVersionMin: 2.0 is required for PB 2.0 to recognize and load any mods)
• Name & description

Here's an example of a metadata.yaml file featuring all the fields mentioned above:

Mod loading

The game scans the Mods folder on startup. It starts by attempting to read metadata.yaml. From there, it attempts to load content declared by the metadata. For example, if the metadata says the mod includes config overrides, the game will attempt to find the ConfigOverrides folder and load its contents. If a mod encounters an error (e.g. version incompatibility, mismatch between metadata and content or bad data), it will be recorded to make debugging easier.

You can see the list of loaded mods in the top right of the main menu and in the Mods window available through the main menu. The Mods window lets you inspect errors that might prevent a mod from loading, inspect the metadata and optionally disable mods. By default, the game considers all Workshop subscriptions and all folders under the Mods folder to be active, but disabling them through the Mods menu is a convenient way to manage them without needing to unsubscribe or delete anything.

If you install, change, disable or re-enable a mod while the game is running, you will need to restart the game to see the effects.

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.

• Duplicates 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).

Refer to the Config modifications to learn about making this type of modification with the SDK.

Config edits

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.

Refer to the Config editing system to learn about making this type of modification with the SDK.