weapons - MSUTeam/MSU GitHub Wiki

• Weapon Type and Categories
  • Add a new weapon type
  • Get the name of a weapon type
  • Add a type to a weapon
  • Remove a type from a weapon
  • Set a weapon's type
  • Check if a weapon has a certain type
  • Manually set weapon categories

In the vanilla game, each item contains a this.m.Categories string member which determines what is shown in the weapon’s tooltip e.g. “Sword, Two-Handed”. However, the actual type of the item is defined separately in this.m.ItemType. Therefore, it is entirely possible for someone to make a mistake and write “Two-Handed” in categories but assign this.m.ItemType as ::Const.Items.ItemType.Onehanded.

Similarly a weapon may be a Sword but someone can write “Hammer, One-Handed” in this.m.Categories and it won’t cause any errors. However, this can lead to issues in terms of player confusion and especially if any mod adds skills/perks which require a certain type of weapon e.g. if the skill should only work with Swords.

MSU eliminates the need for manually typing this.m.Categories and builds this parameter automatically using assigned WeaponType and ItemType values.

Weapon types are defined in the table ::Const.Items.WeaponType.

::Const.Items.addNewWeaponType( _weaponType, _weaponTypeName = "" )
// _weaponType and _weaponTypeName are strings

_weaponType will become a key in the ::Const.Items.WeaponType table.
_weaponTypeName defaults to _weaponType and will be used as the name of this weapon type in tooltips.

::Const.Items.addNewWeaponType(“Musical”, “Musical Instrument”)

will add a weapon type that can then be accessed and checked against using ::Const.Items.WeaponType.Musical and will show up as “Musical Instrument” in tooltips.

::Const.Items.getWeaponTypeName( _weaponType )
// _weaponType is a key in ::Const.Items.WeaponType

Returns a string which is the the associated name of _weaponType. For instance, in the above example it will return “Musical Instrument” if ::Const.Items.WeaponType.Musical is passed as a parameter. If _weaponType does not exist as a weapon type, it returns an empty string.

There are two methods of doing this. The recommended method is to use the create() function of the weapon to set its this.m.WeaponType. For example, for an Axe/Hammer hybrid weapon:

this.m.WeaponType = ::Const.Items.WeaponType.Axe | ::Const.Items.WeaponType.Hammer;

Alternatively, the following function can be used after the weapon has been created:

<weapon>.addWeaponType( _weaponType, _rebuildCategories = true )
// _weaponType is a key in ::Const.Items.WeaponType
// _rebuildCategories is a boolean

_weaponType can also be a list of | separated keys.
If _rebuildCategories is true, MSU will recreate the this.m.Categories of the weapon using its WeaponType.

<weapon>.removeWeaponType( _weaponType, _rebuildCategories = true )
// _weaponType is a key in ::Const.Items.WeaponType
// _rebuildCategories is a boolean

_weaponType can be a list of | separated keys as well.
If _rebuildCategories is true, MSU will recreate the this.m.Categories of the weapon using its WeaponType.

Removes a weapon type from the given weapon. Does nothing if the weapon does not have (all of) the given weapon type(s).

<weapon>.setWeaponType( _weaponType, _rebuildCategories = true )
// _weaponType is a key in ::Const.Items.WeaponType
// _rebuildCategories is a boolean

_weaponType can be a list of | separated keys as well.
If _rebuildCategories is true, MSU will recreate the this.m.Categories of the weapon using its WeaponType.

Sets the weapon’s this.m.WeaponType to _weaponType.

<weapon>.isWeaponType( _weaponType, _any = true, _only = false )
// _weaponType is a key in ::Const.Items.WeaponType
// _any and _only are booleans

_weaponType can be a list of | separated keys as well.
If _any and not _only returns true if _weaponType is any of the types in this.m.WeaponType.
If _any and _only, returns true if this.m.WeaponType has no types that aren't in _weaponType.
If not _any and not _only, returns true if all of the types in _weaponType are in this.m.WeaponType.
If not _any and _only, return true if _weaponType == this.m.WeaponType

This is generally discouraged, as modders are encouraged to use the WeaponType system to allow the categories to be automatically built. However, if the categories must be changed after a weapon has been created, it can be done using the following function:

<weapon>.setCategories( _categories, _rebuildWeaponType = true )
// _categories is a string
// _rebuildWeaponType is a boolean

_categories will become the new this.m.Categories of the weapon.
If _rebuildWeaponType is true, MSU will automatically rebuild the WeaponType of the weapon based on the new categories string. For this it is necessary that all /-separated strings in _categories are keys in ::Const.Items.WeaponType.