Instance Naming Rules 101

This guide is intented to pass on my knowledge regarding what I've learned of Fallout 4's Instance Naming Rules.  These are the rules that dynamically name weapons, armor and cosmetics based on what mods they have attached.  In this guide I will explain how to make a rule run for an object, how the rules process, and how to add your own rules and conditions.

Contents
1) The Basics
2) Object Instances Explained
3) Noteable Object Record Fields/Sections
4) Object Modifications
5) Instance Naming Rules Explained
6) INNR Example Flow
7) Final Notes
8) Overview of Modding Steps

The Basics
The first thing to understand about Instance Naming Rules (INNR) is that the only piece of data they use for conditions is the keywords on the object instance (more on object instances in the next section).  So for any portion of the final name, there must be a keyword on the object instance to isolate that condition.  Keywords in FO4 are used in numerous context.  The one that has a lot of visibility right now is keywords that are used to define categories and menus for crafting.  These keywords go in the FormList array, which has a limited number of entries.  Due to this limit, you will run into issues loading a lot of mods that add keywords to FormLists.  There are numerous documents related to this issue.  However, keywords used to dynamic naming do not contribute to this list and therefore you are add as many such keywords as are needed.

Starting with a basic record, we'll use a Baseball Bat, the base record has a few important fields for dynamic naming: name, INRD, keywords, and OBTE.  The importance of each is described in more detail in section 3, however, at a basic level the INRD tells the record which Instance Naming Rule to run whenever the item is regenerated.  In the Instance Naming Rule, there are a series of conditions.  The first condition that matches a keyword on the object applies to the name.  In this way, the full name of a specific object can be constructed based on what keywords it has.  I'll go into more detail about exactly how the Instance Naming Rule works in section 5.

Object Instances Explained
An important thing to understand about object is object instancing.  What this means is that every time a modifiable object (weapon, armor, cosmetics) is generated (via a leveled list, crafted item or placed item) a new unique instance of that item is created.  The game then handles this object instance seperate from all other instances of the same object.  This is how you can have one 10mm pistol with a recon scope and another 10mm pistol with standard sights for example.  Each of the 10mm pistols are a unique instance of the 10mm record.  When the object instance is generated, the instance inherits the properties of the base record.  From this moment on, the unique instance is handled independently from the base record.  This is why changes to the base record (like a name change) does not reflect on object instances that were generated before the base record change occured.  What this means is that each object instance can be changed (ie. additional keywords added) as needed in order to customize that specific instance of the object.

Noteable Object Record Fields/Sections
Let us look at some important pieces of data from a base record for the Baseball Bat.

FULL - Name: obviously the name field is important, but since the Instance Naming Rule actually generates the full name, this field may or may not be referenced by the instance naming rule
INRD - Unknown: this field tells the engine which Instance Naming Rule to run to generate the name of each object instance
Unknown - OBTE: this section contains record sets for how objects are generated by leveled lists or when the object is crafted.  The most basic entry generates the base object with no modifications.  There can be more OBTE entries to generate the object with any combination of modifications intended for that object.  The vanilla Combat Knife, for instance, has an OBTE entry to generate a standard combat knife as well as OBTE entries to generate the combat knife with mods.  Whenever a leveled list includes the Baseball Bat base record, and calls that record to generate a baseball bat, it has the possibility to generate an object instance of any of the OBTE variants.
KWDA - Keywords: this section lists all of the keywords that apply to the base object.  All of these keywords are copied to the object instance when each instance is generated.

It is still unknown exactly what the hex in the OBTS section of the OBTE entry does.  We will likely have to wait for GECK to figure that out.  However, a standard entry of Parts A = 0; Parts B = 0; Unknown = 00 00 00 00 FF FF 01 and the second Unknown = 00 00 generates the object with the base record with no modifications.  Without this entry, the game will not run the INNR defined in the INRD field.

Object Modifications
As I mentioned before, keywords are the key to making the INNR work.  When an object is generated, the properties of the base record are copied to the object instance.  From then on, that object instance can be modified independent from the base record.  So what happens when you apply a mod to an object instance.  Let's take a look at an Object Modification record in FO4.  Going back to the example above with the Combat Knife, let's look at record mod_melee_Knife_Serrated.  On this record we see 3 main parts: a header section, a data section and the MNAM. 

MNAM is associated with a ma_* keyword which is then applied to weapons.  In this case, MNAM = ma_Knife.  So if a weapon has the ma_Knife keyword, then this mod is applicable to that weapon.  If you look back at the Combat Knife record, you'll see that it does in fact have the ma_Knife keyword in the KWDA section.

Now let's look at the Data section of mod_melee_Knife_Serrated.  You'll see it has 4 Properties.  Each one modifies the object instance in some way.  The first one, for example, says:

Value Type = Float
Function Type = Multiple
Weapon Property = AttackDamage
Value 1 - Float = 0.750000
Value 2 - Float = 0.000000
Factor = 0.000000

This says, take the object instance Attack Damage, multiply it by 0.75 and add that value to the weapon damage.  The next Property increases the sell value of the weapon if this mod is attacked.  The next property is the important one (for this guide):

Value Type = FormID,int
Function Type = Add
Weapon Property = Keywords
Value 1 - FormID = dn_HasMeleeMod_Serrated
Value 2 - Int = 1
Factor = 0.000000

This adds 1 instance of dn_HasMeleeMod_Serrated keyword to the object instance for this Combat Knife.  Now that this specific instance of Combat Knife has this new keyword, we can use that in the Instance Naming Rule.  More keywords can be added in this way in order to define identifiable information about the object for use in INNR.

Instance Naming Rules Explained
The Instance Naming Rules (INNR) work like giant if...then statements.  Each INNR is broken into a series of groups, each containing one or more conditions based on keywords.  Each group corresponds to a position in the final instance name.  The order of the item name is determined by the order of these groups.  Want the legendary title to appear after the item name?  Move the group containing all of the legendary conditions to the end.

Within each group, there are one or more keyword conditions.  These conditions act as an OR statement against each other with the rule running in order from top to bottom and accepting the first matching condition.  Once the rule finds a matching condition, it applys the WNAM for that condition to the instance name, then ignores the rest of the conditions for that group and moves on to the next group.  If no matching conditions are found, that element of the instance name is ignored and processing moves on to the next group.

Each condition can zero, one, or multiple keywords assigned.  If the condition does not have any keywords assigned, it will always be true, apply its WNAM and ignore the remaining conditions.  If the condition has multiple keywords, these always act as an AND statement.  All keywords must be found on the object instance for that condition to apply.

WNAM can be a string of text to apply to the instance name, blank, or a special character of asterisk (*).  If left blank, the INNR will skip that element of the instance name for that matching condition.  If WNAM is the asterisk character, this tells the INNR to apply the base record name (FULL) to the instance name.

INNR Example Flow
Let's revisit the Combat Knife example and pull it all together.  Let's start with the Combat Knife record.  Key pieces of information:

FULL - Name = Combat Knife
INRD = dn_CommonMelee
KWDA - Keywords: Anims1hmWeapon
  WeaponTypeMelee1H
  AnimsStabWeapon
  Anims1hmShortWeapon
  ObjectTypeWeapon
  QuickkeyMelee
  ma_Knife
 
For this example, we're going to add the Serrated Blade to the Combat Knife.  This uses the record mod_melee_Knife_Serrated which has the following key pieces of information (for this example):

MNAM = ma_Knife

There is a data property that adds dn_HasMeleeMod_Serrated keyword to the object instance as described in section 4 above.

Since the mod has ma_Knife and the Combat Knife has ma_Knife, this mod is applicable.  Knowing that we can make the new full list of keywords on the object instance:

Anims1hmWeapon
WeaponTypeMelee1H
AnimsStabWeapon
Anims1hmShortWeapon
ObjectTypeWeapon
QuickkeyMelee
ma_Knife
dn_HasMeleeMod_Serrated

Now, let's look at the dn_CommonMelee INNR since that is the one defined on the INRD of the Combat Knife record.  In the Naming Rules section, you can see that the first group has all of the legendary effects.  If you examine each one, you'll see that none of them match the list of keywords above, so after the legendary keywords, in the same group, there are 3 conditions that include ma_Baton.  Not applicable.  Moving on.  Next couple are ma_DeathclawGauntlet and ma_Ripper.  Not applicable.  Moving on.  Keep going quite a few more and you'll see on that has dn_HasMeleeMod_Serrated, but it also has dn_HasMeleeMod_Shock.  Since our instance of Combat Knife doesn't have dn_HasMeleeMod_Shock, this condition still doesn't apply.  Moving on.  You should finally see a single condition for dn_HasMeleeMod_Serrated by itself.  Since none of the other conditions above this condition were true, then this condition applies.  So we apply the WNAM to our item name.  So far our item name is simply: "Serrated"

Since we met the conditions for a rule in the first group, we move on to the second group and check those conditions.  You'll notice the second group is all dn_HasMaterial_* conditions.  None of these apply to our instance of Combat Knife, so the second group does not contribute anything to our instance name.  So far the item name is still: "Serrated"

The 3rd group has 2 conditions.  The first condition is dn_HasLogo_Swatter.  This keyword is not on our instance of Combat Knife, so doesn't apply.  The next condition doesn't have any keywords which means it applies to all items that don't meet the conditions of the first condition, which is our instance of Combat Knife.  The WNAM for this condition is an asterisk (*), which means to apply the base item FULL to our instance name.  So we add a space first, then append the base item name to what we have so far.  This now gives us an instance name of "Serrated Combat Knife".  Since there are no further conditions, this is the name that you would see in the game.

Final Notes
INNR doesn't run unless something changes on the specific object instance or the object instance is regenerated.  Therefore, any changes made to the INNR will not reflect on items in the player inventory, containers, or loot that had already been generated before the change occured.  So if you modify the INNR, you may still find NPCs using items with names that don't reflect the changes because that instance of the item was generated before the change.

You can force the INNR to run by modifying the object at the workbench.  Additionally, if you drop the item on the group when in a settlement, then enter build mode and store the item in the workshop, when you retrieve the item from the workshop it will have a regenerated name.

You can rearrange the order of the conditions within groups by rt clicking on a condition and selecting Move Up or Move Down to reorder them as needed.  You can also reorder the groups in the same manner by rt clicking the group header and selecting Move Up or Move Down.  This is how I rearranged the groups so that VIS puts the object name first, then all of the object modification tags.

Overview of Modding Steps
Knowing the importance of keywords as outlined above, here is the basic process that I would go through if I were making a weapon/armor/cosmetic mod and wanted dynamic naming to work properly.

1) Create the base object.  Make sure you define the base OBTE record as discussed above and in more detail on the AWKCR main page.
2) Include keyword(s) on the base object to identify that object as being different from other objects.  If a keyword does not exist to do so, create a new keyword within the mod.
3) For each object modification for your item, use the Add Keyword property to add the necessary keyword(s) to denote that the object modification is present.  If the needed keyword(s) don't exist, create them within the mod.
4) If all keywords used are vanilla keywords, then you can use the vanilla INNR.  If not, then you should create a new INNR.  If you make a new INNR, put that in the INRD field of your base record.
5) Modify the INNR (whether new or vanilla) to include the keywords from steps 2 and 3 with whatever word(s) you'd like it to concatenate into the dynamic name.