Skip to content

Mod system overview

Jump to bottom
Artyom Zuev edited this page Dec 13, 2025 · 19 revisions

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.

mods_folder_01.png

Mod structure

Each mod gets a separate subfolder, e.g. Mods/MyMod1, Mods/MyMod2 and so on:

mods_folder_02.png

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
  • 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:

mods_folder_02.png

Mod loading

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.

This wiki is a work in progress. Please make sure to check the built-in tutorials within the SDK or the modding articles on the game wiki to supplement this page. If you get stuck or experience a bug, please don't hesitate to ask questions in the #phantom-modding channel of the official Discord server. We can't wait to see what you create!

Clone this wiki locally