Creating items with custom 3D assets
This article will go over setting up 3D assets for item models in the SDK Unity project. Make sure to read the Creating asset mods article before proceeding. Please refer to these articles for more details on 3D model structure - the following sections assume you already have a ready for use 3D model and all of its dependencies:
The rest of this tutorial will cover how to use a completed ItemVisual prefab you get from following that guide. You'll link it to a mod and export it into the game.
Before proceeding, let's check our assets to make sure we have everything in place for the next steps.
First, make sure you create a folder for your assets in Assets/User/Sources. Placing your files there will allow Unity to import them without interference from version control (this folder is ignored by Git).
Make sure your model is present in the User folder and visible in the Project view. We recommend exporting your model into the FBX format, but Unity supports a number of other formats - just make sure your file includes all the necessary data (custom vertex normals, UV1, UV2, vertex colors). Refer to the link below for more information on importing models.
Your model will automatically turned into a so-called prefab by Unity, allowing it to be used in the scene. However, that autogenerated prefab object doesn't have enough information to allow your model to be used by the game. It will not have correct components, hierarchy or materials out of the box.
Make sure you create a custom prefab per model. You can create a prefab by dragging your FBX from the Project panel into the Scene, then dragging the created instance from the Hierarchy panel back into the project. From there, you can edit your prefab by double-clicking it in project view. Refer to the Unity documentation for more information on creating prefabs and Unity objects in general.
Make sure your prefab contains the ItemVisual component attached to the root object. Refer to the manuals about armor and weapons linked above to learn how to configure this component: most importantly, ensure that the Renderers list is filled out and references every mesh in the hierarchy.
Make sure the prefab has a simple hierarchy with as few child objects as possible. Child objects should only be necessary to host MeshRenderer + MeshFilter components (visible pieces) registered in the Renderer list of ItemVisual root component, or as empty transforms referenced for effects (barrel firing points etc.). Avoid deeply nested hierarchies or hundreds of child objects.
Make sure the materials used on objects are located in the same folder as the model and the prefab. Verify the materials are using the correct shader "Hardsurface/Parts/Base (mech)". Follow the armor and weapon tutorials linked on top and verify your materials are configured as recommended.
Make sure the import settings on all textures are configured as recommended in the wiki articles. In particular, make sure that sRGB (Color Texture setting is disabled. With this checked, you're ready to proceed to export!
Make sure all .fbx objects in the Project view have Read/Write Enabled flag checked in the import settings. This is very important for allowing these meshes to be accessed by the game.
Follow the steps from "Mod config" to "Testing prefab assets" in Creating asset mods. Link the ItemVisual prefab in the Asset Bundle definition in the mod config.
We assume that any mod adding new 3D assets for items will also have config editing set up, since you'd likely want to create or modify PartPresets or SubsystemBlueprints. When you enter config editing mode with a mod that has AssetBundles pointing to ItemVisual prefabs, the SDK will scan and register the visual prefabs you reference. The visual key dropdowns in the Subsystem database will let you pick your new visual models and will let you see previews with your prefabs:
Refer to Creating asset mods to learn how to export your mod and confirm that the assets were exported correctly. If the AssetBundle export works correctly and if your item configs are set up correctly, you should be able to see your custom items in the game. Refer to [console commands reference|Reference:-Console-commands] to see the commands that can be used to quickly test your items, such as cr.inv-spawn-part.
As of writing this article, Phantom Brigade release 2.1 has several issues that can interfere with modding custom 3D assets:
- Custom visuals from AssetBundles might not appear in inventory, mech customization or combat
- Custom visuals might not correctly disappear when unequipping items or changing focus in inventory
We strongly recommend installing ModExtensions (available on Workshop and Nexus) and making it a dependency for your mod for the time being, until these issues are addressed in a future Phantom Brigade release.