¶ Summary
The guide is specifically created to illustrate in detail how to create a new weapon based on an existing one, with different stats and properties.
¶ Disclaimer
The below methods are acquired by self-studying (with a bit of consulting) and personal testing. That being said, I will not be held responsible in case your game will stop working, save files corrupted or you get a compromised gameplay of any sort. Therefore, do it AT YOUR OWN RISK.
At the present date (March 5th, 2023 - Phantom Brigade v1.0), this guide explaining the steps needed to create a separate mod under the modding system (much easier to maintain and totally independent from the game directories as they can be loaded and removed safely). Modding System didn't exist during Early Access period and modding itself was more complex to perform compared to now.
Before starting, please take a moment to read a very detailed guide about the modding system written by Artyom Zuev, available at the link below:
https://wiki.braceyourselfgames.com/en/PhantomBrigade/Modding/ModSystem
¶ Required Tools
Since the configuration files are written in a Serialization language called YAML (Yet Another Markup Language or Ain’t Another Markup Language), a normal Notepad program is more than enough but with a good chance of altering code indents and make the mod not working correctly. For this reason, I suggest to use an advanced text application like Notepad++ or Sublime Text; they are good solutions to minimize the risk of breaking the mod due to wrong indentation or code format.
¶ Location and setup
In order to create our new weapon, we need to duplicate the respective files from the following folder in order to make it appear in-game, Each one is composed at the following places and acronyms (except LocalizationEdits, which is a special folder used by the modding system);
Subsystem → the Subsystem is the component that defines base stats (like damage, concussion, heat, etc.), projectile behaviour, effects and visuals. In case of weapons, for instance, all of them are usually signed with the filename pattern such as wpn_main_xx.
Part_Preset → Defines the way the weapon will be generated with one or more additional subsystems (like rarity-based perks) and other functionality like enabling localizable text and so on. To make it simple, it describes how subsystems come together to form an actual part fully useable in-game. Can be recognized with the filename pattern of wpnxx (for example: wpn_rfile_sniper).
LocalizationEdits → Localization edits will give you a unique name and description for your weapon. Without this, it will be marked as [Unknown] as the game noticed there are no localization match for your custom subsystem/part_preset.
For more info about building a mod, see the Disclaimer section above (modding system guide). Remember that, since we are adding a new weapon de-facto, the mod must be inserted by using ConfigsOverride method.
¶ Localization – Text and description
All parts do not load any text by default. Declaring text is an optional feature that only some parts in the inheritance hierarchy are using, therefore if textName in the part preset is null, the game will not load any localization for weapon name, and weapon name will either be Unknown or pulled from a higher level parent, if localized parent exists. You must fill the optional textName field with a value. Note that the value doesn't actually contain the text, text comes from the separate database to allow localization. The only field in that optional data block that is saved directly on the part is split, which is a flag that controls whether complex concatenated names from multiple parents are combined. It's safe to leave it at true. The same is true for textDesc - if you want to enter a custom description, make sure to fill that field with an object!
There is one more way to add text to parts, this time text unique per rating (common/uncommon/rare, respectively grey/green/blue). Stock melee weapons, for instance, are a good example of how to set that and how they leave textName and textDesc with null value, but fill a different set of fields: textNameFromRating and textDescFromRating. These fields allow higher rated melee weapons to have distinct name based on their rarity ratings. This logic applies to melee weapons because of their different designs, which warranted a unique name. No need to worry about this if you keep your equipment generator config simple, like in the sample mod above
Melee weapons are actually a great example to study if you'd like to try applying complex generator steps for your mods. If you take a close look, genSteps field is under most of the melee part presets with multiple steps and checks (conditions) defined under each of them. The idea is pretty simple - depending on part rating requested from the generator, a totally different main equipment subsystem determining visuals and stats is attached to the part!
- Note 1→ Rating 0 is training/basic quality, usually encountered in the first province. It features no perks to simplify initial player experience.
- Note 2 → Rarity subsystems are special hidden subsystems never shown to the player that boost basic stats of a part at higher ratings, making rare/uncommon parts more valuable even if you have bad luck with perks.
¶ Basic Subsystem fundamentals
Once you have created the custom file, open our example weapon and let’s start to see the basic stuff we need to know. The code might be big and scary, but it is simplier than it seems.
Every weapon has the following stats:
act_count→ It determines how many shots can be fired between each use in the timelineact_duration→ Duration of a single use in the timeline (in seconds).act_heat→ How much heat weapon produces when used.mass→ The weight in mass. In poor words, how much heavy the weapon will be.scrap_value→ How many supplies can you get by scrapping a single item/weapon? put the value here.wpn_concussion→ Concussive damage caused by a projectile that can knock out pilots while in combat.wpn_damage→ Base damage of the weapon.wpn_damage_radius→ This modifies the radius which damage can be applied to nearby units. Typical property of explosive weapons.wpn_impact→ Impact inflicted onto the environment upon a weapon shot.wpn_impact_radius→ The radius of impact upon a weapon shot applied to the environment. Typical property of explosive weapons.wpn_proj_lifetime→ The lifetime of a projectile before it fades completelywpn_proj_ricochet→ The ricochet of a projectile. Higher value means the projectile will be more prone to ricochet on the ground)wpn_range_max→ The maximum range of a weapon. By going beyond the maximum range, the shot may be avoided by enemies.wpn_range_min→ The minimum range needed to make a shot effective. If less than the minimum range, the shot might miss and/or be less effective against enemies.wpn_scatter_angle→ Angle of scatter while in idle position. Scatter determines the dispersion angle of a projectile.wpn_scatter_angle_moving→ dispersion angle of bullets fired while moving; this will heavily influence a firearm precision.wpn_speed→ Projectile speed. A higher value means the projectile will travel faster (notable examples are the Railgun repeaters/splitters).
The above property values can be modified in the value: variable (under each option). This will modify the actual properties of the weapon itself, so feel free to make various tests to see what suits best for your modding needs.
Make your changes, save and proceed to the next step.
¶ Part Preset fundamentals and the Generation step
The below fundamentals seems long and scary, right? I got you covered, so let’s make things simple by
hidden→ choose to let this part be hidden from the game (and prevent users' interaction). Let it set to false;parents→ from which parent file this one is inheriting its parameters? The syntax to summon parents is with -key: parameter;ratingRange→ the rarity rating range.livery→ which kind of livery this part has at the moment. It is always blank, nothing important;comment→ A personal comment left for the file, in order to quickly understand how it works (see the screenshot below);textName (split: true/false)→ Customized title for the weapon. It works as a parent variable for the related entries contained in equipment_part_preset.yaml. The split variable let the developer the chance to create a title and only accepts booleans (true if you want to create a title, false if you won't);textDesc (split: true/false)→ Same as above, except that this entry is used for giving the weapon a brief description under the title in-game;textNameFromRating→ Customized part name based on rating;textDescFromRating→ Customized part description based on rating;sockets→ Where this weapon is attached (core, legs, etc.). No need to edit as it is usually blank;tags→ Given to “assign" the part to a particular category. We can see that this weapon can also be assigned to all of the invader's military branches (Experimental, Reserves, Army and so on), but also to another aspects of the game that there aren't much important to know at the moment;
The generator steps section of a part preset is the most important change. In this weapon, there is only one generator step unique to this weapon - attaching one possible subsystem (primary weapon subsystem wpn_main_amr_01) to one possible hardpoint (internal_main_equipment).
Note: just like all built-in weapons, the weapon inherits from several parents. In this case, it inherits from wpn_root_primary and wpn_perk_filter_gun. The latter injects additional generator steps, giving the weapon a perk hardpoint/systems and customizable module hardpoint at higher rarities.
Our modded sample weapon inherits from 2 parents. One of them is simple: wpn_perk_filter_gun. It only contains 1 step, which says:
- Trim all subsystem candidates in perk_1 hardpoint, leaving only those designed to affect weapons:
Apply changes and test our new weapon in-game. If everything has been done correctly: congratulations! you have created your first customized weapon.
¶ Conclusion
The point of inheritance system is that you really don't have to worry about more complicated generation steps if you're making a simple weapon. All you have to do is to just inherit from the same parents and you can accomplish this with only step. However, this system has a lot of flexible options and can let you design specific randomized weapons (even up to complexity of Destiny weapons, where you have multiple perk columns, each with special generation rules and other weapon enhancement).
For inspiration and studying purpose, you can download the mentioned sample mod here, already configured (/pb_modpartweapon_simple.zip).
For incorrect steps in the guide or for consultation about the matter, you can find me at BYG Discord @MiketanJP or opening a thread in #phantom-modding channel for for any kind of questions!