Guide for using the Storm of Zehir loot system

[Tchos]

Yet more investigations into the workings of the default scripts has led me to understand the SoZ loot generation system. One reason for wanting to use this system rather than the default loot generators is that SoZ had more variety of items, and it's geared for levels around 3-18, which covers any module I'm likely to make, and since it was the last official expansion, I think its items are more likely to have fixed any bugs from the original versions and/or tuned them for best compatibility with the last patch of the game engine.

In case no one else has written an explanation of this system, or a guide for using it, I've written this guide. My search revealed none, but even if there is such a guide, I'll bet it's not this detailed.
To get it working without having to write/edit any scripts, you need the following files from the Storm of Zehir campaign to be in your campaign:

• k_mod_load: A module script. Select View Module Properties, and put it in the On Module Load field.
• kb_default_sp: Just put this in your folder somewhere. The creature's default spawn script will fire it.
• kinc_treasure: Just put this in your folder somewhere, though you only need it if you plan to edit and recompile either kb_default_sp or the treasure generation functions themselves, and can leave it out otherwise.
• nx2_loot_*.2da: The loot tables. Again, just copy them into your folder or hak.

I think that's it. It begins with k_mod_load, which goes in the module's On Module Load field. It contains these lines:

// standard script for spawn modifications for this campaign
SetGlobalString("N2_SCRIPT_SPAWN_CREATURE", "kb_default_sp" );

The default creature On Spawn In script looks for this global string, and executes the specified script before anything else. That's where the loot gets generated on the creature. When it executes kb_default_sp, it checks the creature for certain variables, and uses those to determine what kind of loot the creature carries, how much, what percentage chance there is, if there's any specific loot it should add to the table, and if you want any extra loot to spawn.

If you have those two files loaded in your module, and do nothing else, then no creatures will generate any loot, because the first thing kb_default_sp does is to disable the OC's treasure generation system by setting the creature's variable X2_L_NOTREASURE to TRUE. You need to set variables on the creature for the new system to function. Saved sets of these variables are already in the toolset ready to be used, and can be loaded on the creature using Import Properties>Variables, but I'm creating extra saved variable sets with some kinds of loot specified, since the ones that come with the toolset are blank.

kb_default_sp uses functions from kinc_treasure, which reads loot tables from the nx2_loot_*.2da files, depending on what kind of loot you tell it to generate (alchemy, ammo, gems, potions, gold, random).

Note: Some of the items in the 2da loot tables are not in the default toolset. You should read the 2das and copy the items with those resrefs from the SoZ campaign folder to your own. Or, use the brute force method and just copy everything with a .uti extension from the SoZ campaign folder. It's 1141 blueprints, amounting to 4.41 MB, and you might like to have some of those in your game anyway, to place manually or put in shops, even if they're not part of the loot table. The ones you don't need won't do any harm except to take up a little extra space.

What to set
There are three functions that the spawn script executes: GiveNX2SpecificLoot(), GiveNX2ExtraLoot(), and GiveNX2RandomLoot(). Each of these looks for 4-5 variables on the creature, listed below. They all perform independently from each other, so you don't have to include any of them that you're not using.

Random loot:

• NX2LootType: String. Valid entries are alchemy, ammo, gems, potions, gold, or random. Note: "random" will not mix types. It only picks one of the types, even if you use a quantity greater than one. So you may get two different kinds of ammo, but never one kind of ammo and one potion. The stack size of the ammo is randomised, but never less than 50. If no loot type is specified, nothing will be generated. The "alchemy" choice does not generate alchemical supplies or apparatus, but only grenade-like items such as tanglefoot bags, alchemist's fire, or holy water.
• NX2LootGrade: String. Valid entries are low, medium, high, and maximum. This determines which column will be used from the 2da. As far as I can tell, if no grade is specified, no loot will be generated, except if the loot type is gold and you specify an exact quantity of gold.
• NX2LootChance: Int, but will convert a string to an int just in case. Enter a value from 0-100, for the percentage chance a piece of loot will be generated. 0 counts as 100%, so you could leave this variable off if you want some loot no matter what. If you want no loot, you should add the variable NX2_NOLOOT = 1.
• NX2LootQuantity: Int, but will convert a string to an int just in case. This is how many pieces of random loot will be selected from the table, or how much gold will be given, if the loot type is gold. If it's left blank, but the other variables are set, it'll give 1 item, unless it's gold, which will make it use the loot grade instead to generate a random amount of gold within the chosen grade's range.

Specific loot:

• NX2SpecificLootResRef: The resref(s) of any specific item(s) that you want the creature to have a chance of dropping, using a separate chance roll than the random loot. The code looks like you can put any number of items in this variable, separated by commas with no spaces. Use this for any creature-specific, quest-specific, or area-specific items, etc.
• NX2SpecificLootQuantity: How many copies of this item or items will drop at once, if the loot chance roll succeeds. Unlike the one in the Random Loot function above, this version doesn't perform differently for gold, since it doesn't deal with loot types or grades. Strangely enough, this section of the code has an additional condition for "creature items" (special items, like claws and hides that give the creatures certain properties and abilities), which aren't meant to drop or be used by the player. If you specify one of these as your specific loot anyway, there's a 75% chance the function will destroy it. I don't know why you'd want to make such a thing drop, but if you do, I don't see the point of this random destruction.
• NX2SpecificLootVariable: This activates a counter. Set it to 1 if you want this specific loot to drop a certain number of times, and then stop dropping. This uses global variables.
• NX2SpecificLootCount: This is the count tracker itself. Set it to the number of times you want the specific loot to drop (to ever drop, on any creature that drops this specific loot). When it has dropped that number of times, the counter will be set to 0, and it will no longer drop. If NX2SpecificLootVariable doesn't exist, it has no effect. You could use this, for example, for a collection quest where you need to retrieve a certain number of stolen quest items from a large group of enemies, and you want them to drop it randomly, but you don't want them to drop more than the quest states were stolen.
• NX2SpecificLootChance: This functions essentially the same as above, NX2LootChance. One difference is that each specified item resref (separated by commas, no spaces) has an independent die roll for being generated or not, although the percentage chance specified in this variable is the same for all of them. So you may get all of the items generated, none of them, or any number in between, whereas with the Random Loot function, you get either the entire specified quantity or none of them, based on the single roll in the Loot Chance variable.

Extra loot:

• NX2ExtraLootResRef: See above, NX2SpecificLootResRef. These all function exactly like the Specific Loot variables, even using the same function to generate the loot, but having another set like this allows you to use an additional set of quantity, chance, and/or item tracking with different values for different items, if you so desire.
• NX2ExtraLootQuantity: See above, NX2SpecificLootQuantity.
• NX2ExtraLootVariable: See above, NX2SpecificLootVariable.
• NX2ExtraLootCount: See above, NX2SpecificLootCount.
• NX2ExtraLootChance: See above, NX2SpecificLootChance.

Note that if you use this treasure system, you also have access to the function from MotB that generates essences for use in crafting. In the OC, you distilled these essences from body parts dropped from creatures, but MotB basically pre-distilled them for you.

Ideas for possible modifications
Pretty much everything can be manipulated without touching the scripts, just by setting variables on the creatures, but probably the easiest thing to start modifying would be the entries in the loot 2da files, if you want certain things to be randomly generated from the main random generator, without listing them as Specific or Extra loot.

The random generator, as shown, generates only consumables or gold. No armour, weapons, or crafting items. A 2da or a few 2das could certainly be created to add that functionality to the random generator, but it can also be handled in other ways. I use an On Death script to generate crafting items, since I use the OC crafting system, but it can also be done with these Specific Loot and Extra Loot functions, as can the weapon and armour drops.