Board Thread:Bug Reports/@comment-27219153-20160201040317/@comment-25101089-20170120033546

Alright, I'll start with an explanation of what the new weapon format actually is. Warning: long post ahead!

The vanilla equipment format only saves one held item. Since many of the LOTR NPCs switch between melee and ranged combat, they need to be able to store separate melee and ranged items. In the old days this was done by just specifying the melee/ranged weapons statically in the NPC's class file. But this wasn't ideal, because it meant they could only ever have one possible melee weapon and one ranged weapon - rather than one weapon selected from a range of possibilities and then saved specifically with that NPC, like e.g. Orcs with their various possible melee weapons.

This also meant that you couldn't use commands to summon a melee-ranged-switching NPC with a particular melee or ranged weapon. And in addition, some NPCs started to be designed with 'idle items' in addition to their melee and ranged weapons - these idle items again had to be hard-coded, and even giving an NPC 'nothing' as its idle item meant that it could no longer have a specific saved melee weapon, only a statically-coded one, for the same reason as above - because the vanilla format only saves one held item.

So to fix these problems and avoid having to reuse code I designed a new unified storage format that has slots for several held items in many different circumstances. In this new format, idle items, melee weapons, etc. are saved persistently for each NPC, and the NPC takes a copy of these saved items and places it in the vanilla 'held item' slot depending on the circumstances.

The slots, their numbers (used in commands), and their names (referenced in the code, but not used in commands) are:

0: 'IDLE_ITEM': an item to be held when not in combat.

1: 'WEAPON_MELEE': an item to be held in melee combat.

2: 'WEAPON_RANGED': for ranged combat.

3: 'SPEAR_BACKUP': if this slot is nonempty, then when the NPC has a spear in its melee slot, it will throw the spear and then move SPEAR_BACKUP into WEAPON_MELEE as the new melee weapon and clear SPEAR_BACKUP. If this slot is empty, then the NPC will use any spear in its melee slot as an ordinary melee weapon.

This is used for NPCs who can spawn with spears, so that they have an additional fallback melee weapon to use after throwing the spear. In the old days of the mod the spear backup item was also hard-coded for every NPC type.

4: 'EATING_BACKUP': when the NPC starts to eat, drink, or smoke, it will move its current held item into this slot. Once it's finished consuming, it will re-equip the eating backup.

5: 'IDLE_ITEM_MOUNTED': an item to be held when the NPC is mounted, and idle.

6: 'WEAPON_MELEE_MOUNTED': as above, with melee combat.

7: 'REPLACED_IDLE': if you give a hired unit a new melee weapon, that new weapon overrides the default idle item. The idle item is saved in this slot, to be restored if you choose to retake the replacement weapon back from the NPC.

8: 'REPLACED_MELEE_MOUNTED': as above, for a melee mounted item.

9: 'REPLACED_IDLE_MOUNTED': as above, for an idle mounted item.

10: 'BOMBING_ITEM': for Orcs, an item to be held in the right hand while using bombardier AI.

11: 'BOMB': for Orcs, the actual bomb item to be held in the left hand, which determines the strength of the bomb that will be placed. The presence or absence of an item in this slot determines whether bombardier AI or normal melee AI is used.

An important caveat is that the implementation of this storage system depends on the NPC. Many NPCs will only make use of the idle and melee slots, and have no ranged AI, so putting something in the ranged slot with commands will not make them capable of using ranged combat. Likewise, most NPCs do not use the specific mounted slots. These are only used by some NPCs, such as the Gondor Soldier, who can use lances on horseback but switch to a sword, dagger, etc. if their mount is killed.

Now, an example of how to use these in commands:

This summons a Gondor Soldier wearing dwarven armour, with a mithril ingot as his idle item, a troll bone as his melee weapon, and a mallorn bow as his ranged weapon. Note the 'NPCItemsInv' tag, and the 'Slot:0' with 0 corresponding to 'IDLE_ITEM', the 'Slot:1' corresponding to WEAPON_MELEE, and the 'Slot:2' corresponding to WEAPON_RANGED. (This is only a melee user, but the ranged weapon is included for the sake of example. To actually see the custom bow in action you would need to summon a lotr.GondorArcher instead.)

Warning: Item IDs will very possibly vary between worlds, so I would advise you to check using F3+H what the IDs of your world's items are.

But wait! That's not all! There is also the hired replaced items inventory. This works similarly to the normal NPC items inventory, but it is specialised for hired unit equipment replacement, to save the previously-equipped items so that the unit can re-equip them if you take back the replacement item. This inventory has the NBT tag 'HiredReplacedItems' instead of 'NPCItemsInv' and the following slots:

0: 'HELMET': the helmet the unit was previously wearing, before you gave it a new one. If you take the replacement helmet back, it will wear the item in this slot again.

1: 'BODY': as above, for a chestplate.

2: 'LEGS': for leggings,

3: 'BOOTS': for boots.

4: 'MELEE': for a melee weapon.

5: 'BOMB': for an Orc bomb.

6: 'RANGED': for a ranged weapon. (Not yet implemented.)

Now, if you were paying attention through all that, you may wonder why the REPLACED_IDLE and REPLACED_MELEE_MOUNTED and REPLACED_IDLE_MOUNTED slots are in the NPCItemsInv, instead of the HiredReplacedItems where they would seem to belong. The answer: the equipment replacement screen has no inventory slots for idle items, mounted melee weapons, or mounted idle items. Only those replaced items which have corresponding GUI-inventory slots are in the HiredReplacedItems - which makes it much simpler to associate to an actual GUI-inventory - and the other replaced items are stored in the unseen NPCItemsInv.

I can't imagine why anyone would ever want to use the HiredReplacedItems in commands, unless they are designing a very specific scenario where you meet an already-hired unit and have to relieve him of his weapons and armour and discover that he is actually wearing mithril underneath, or something bizarre.