Creating asset mods
Phantom Brigade utilizes the Asset Bundle system provided by Unity to allow mods to sideload arbitrary content (such as prefabs, 3D models, textures and materials). You can check the official Unity documentation on the system here: Introduction to AssetBundles
You can use the Mod SDK to prepare Unity content for your mod, and reference it in your mod config. If everything is set up correctly, this will allow the mod manager to generate AssetBundle files when exporting your mod. Let's go over setting up a simple AssetBundle mod.
We recommend using a simple Prefab as your first test asset. It could contain a simple cube or a random 3D model you have access to. You can try creating custom mech armor or landscapes later on, but it's good to confirm that all the fundamentals work as expected before moving to more complex assets with more potential issues. If you're unsure how to create a Prefab in the SDK project, check out the Creating Prefabs article in the Unity docs.
The important first step is to ensure that anything you are planning to include in a mod is located under the Assets folder in the SDK project, visible to Unity. We strongly recommend using the Assets/User/ folder: it is ignored by Git and files placed in it will not be flagged as a modification by version control. Here's an example of a Prefab in a correct location in the project:
To start using your custom assets, first add the Asset Bundle block to your mod project. Click the "assetBundles" option in the bottom right component dropdown.
After adding the new section, you'll see a list. Let's add a new bundle entry to it.
Each bundle is an archive with one or more assets that the game can access by name. In the new entry you have added, enter the bundle name. Try to pick one that will not cause collisions with bundles in other mods (for example, include a prefix unique to your mod). It's worth keeping the name of the bundle short (to make debugging commands and config references easier to type).
Once you're certain which assets you'd like to include in your mod, you can start linking them in the bundle definition in the mod config. Click the + button on the Files list to create new entries, then click the folder icon to open the file picker dialog. As mentioned before, make sure that the asset is located within the SDK project, ideally under the Assets/User/ folder.
Important note: if your asset consists of multiple files that are dependencies, you might not need to link these files separately. For example, if you have a prefab with a mech armor, and that prefab contains several MeshRenderer components, and these components reference meshes and materials, and these materials reference textures and shaders, etc... you do not need to individually link all of these files in the mod config. Simply link the top level prefab. The AssetBundle compilation process scans the entire project for dependencies and pulls in everything related to the selected file, no matter how long the dependency chain is.
There is nothing special you need to do to export the AssetBundles you declared in the mod config. The export might take a few minutes, but it will automatically scan the files you linked and will export the assets into your mod. We recommend testing with the Export to user option first, since that option will let you see the exported file structure and will let you test the result in the game without waiting for the Workshop to refresh. If there are no issues, you should see the AssetBundles folder in your exported mod folder:
To be certain everything is in place, verify the contents of that folder. If the export succeeded, there will always be files matching the names you have selected:
If the exports fails and you see an error in the Console similar to Type '[Assembly-CSharp]Area.AreaManager' has an extra field ... in the player and thus can’t be serialized ..., try the following:
- Save the scene (
Ctrl+S) - Save the project (
File > Save Project) - Recompile the project by selecting any .cs file in Project tab (like
Content/Code/Data/DataAttributes.cs), right clicking it and and selectingReimportin the context menu - Reexporting the mod again
If the files are in place, it's time to test the prefab asset in the game. First, make sure you're in developer mode. Check the Testing mods article if you aren't sure how to enable it. Next, confirm there are no errors displayed by the mod system on startup. Then, you can proceed to the next step: validating whether your asset is loading correctly.
Navigate to the mech customization screen, open the console and enter the command mods.asset-preview-prefab MyModName MyBundleName MyAssetName. The arguments are (in order) your mod ID, the name you gave to the bundle and the name of the prefab. If all is right, you should see the asset floating in front of the player mech, like on the screenshot below:
The assets in AssetBundles can be used for a wide variety of content, but they need to be used - on their own, they are inert. A code mod can grab any asset using the public UnityEngine.Object GetAsset (string assetBundleName, string assetName) method in ModLoadedData class. You can retrieve an instance of that class for your mod by accessing ModManager.loadedModsLookup with your mod ID.
A retrieved UnityEngine.Object can then be used for any purpose. For example, if it is a prefab, it could be cast to GameObject, instantiated via GameObject.Instantiate and parented to HQHelperRoot.ins to add a new decoration to the mobile base scene. Quick example:
var myModData = ModManager.loadedModsLookup.TryGetValue (myModID, out var v) ? v : null;
if (myModData != null)
{
var myAsset = myModData.GetAsset ("myBundleName", "myAssetName");
if (myAsset != null && myAsset is GameObject)
{
var myPrefab = myAsset as GameObject;
var holder = HQHelperRoot.ins.transform;
var myInstance = GameObject.Instantiate (myPrefab, holder);
myInstance.transform.localPosition = ...
...
}
}
The game scans every loaded asset bundle to find if any assets within match a few content types, and automatically registers suitable finds for easy use. These assets are:
- Prefabs with root
ItemVisualcomponent: unit part visuals (mech armor, weapon parts). Automatically registered in the visual system underAssetBundleName/PrefabNamekey. These keys can be used inattachmentscollections in the Subsystem database. - Prefabs with
OverworldLandscapeRootcomponent: overworld landscapes. Automatically registered in the landscape system under the key filled in thekeyfield on the component. These keys can be used in thelandscapeKeyfield in the ProvinceLandscapes database.
