Mod system overview

This page 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.