External projects

By default, mod projects are stored next to other user data for Phantom Brigade, at AppData/Local/PhantomBrigade/ModsSources. Often times, you might want to set up a mod project located outside that default directory. This is useful for version controlling your mod projects with Git and other advanced cases.

This tutorial is available directly in the SDK under PB Mod SDK/Getting Started/Tutorials/External projects. The SDK version can include interactive elements such as buttons automatically selecting project assets. Make sure you are in the right scene (game_main_sdk or game_extended_sdk). You should see DataModel and ModManager in the Hierarchy window. If you're unsure how to find the right scene, use the scene buttons in the Getting Started window.

Custom project folders

To start using external project folders, you need to adjust the SDK user settings. They are available on top of the Mod manager inspector, as shown on the image below. Inside them, you can set any number of additional directories that the SDK should scan to locate mod projects. Make sure you select a root folder above any individual mod project, not mod project folders themselves - as in, a folder similar to ModsSource.

Once you are done selecting a folder, make sure to click "Save settings". Your user settings are stored in the SDK folder (under ConfigsModTools/user_settings.yaml), but they are excluded from version control, so don't worry about accidentally modifying the SDK repository when you edit these settings.

Folder structure

The most common use case is linking a local Git repository to the SDK. This allows you to use all the SDK tools while having a perfect overview of every single file change in your mod. This makes updating to Configs from new versions of Phantom Brigade a breeze, makes it easy to revert changes that went wrong, etc. Refer to the image above for an example of the target folder. As we mentioned above, it should be a root folder: a location one level above project.yaml and metadata.yaml files.

Mod project subfolder

Here is how a mod project subfolder under a custom mod folder usually looks like. If you see project.yaml and metadata.yaml, you're in the right place.

Mod project subfolder

The typical way to set this up is:

• Make an empty GitHub repository. In case of this example, we named the repository PB_ModSDK_Samples
• Clone it to your machine, creating a local repostory folder, like D:/Work/UnityProjects/PB_ModSDK_Samples
• Add that folder to the SDK user settings and save them
• Create a new mod, which will appear under the default AppData/Local/PhantomBrigade/ModsSource folder
• Move that mod to your repository folder, push the changes to Git
• Reload mods in the mod manager.

Once everything is set up, your mod should be selectable in the mod manager dropdown, and you should see the path above the metadata reflect your custom project folder, like on the image above.

Setting up .gitignore

One of the common questions about setting up a Git repository is the contents of .gitignore file. Without that file, Git version control might get bloated, tracking unimportant changes to temporary files. We provide a template that could serve as a starting point. You can find the template file at Tools/Templates/template_gitignore.txt in your SDK folder. Move it to your local Git repository, rename it to .gitignore and you should have a good starting point. Make sure to check its contents in case it excludes some files you do need to track.