x0_i0_treasure

Library for XP1 treasure generation system.

MAIN CONCEPT:

The module builder creates some base containers and fills them with instances of the treasure items that s/he wants to appear randomly. The actual treasure containers then randomly pick from the contents of these base containers to generate their own contents.

SETUP:

Create four module-wide base containers (for low, medium, high, and unique treasure items) and place them anywhere in your module. Make sure that they are in locations inaccessible to the players, though!

Give these module-wide base containers these tags (or just use the blueprints):
X0_MOD_TREASURE_LOW - low-level treasure
X0_MOD_TREASURE_MED - medium-level treasure
X0_MOD_TREASURE_HIGH - high-level treasure
X0_MOD_TREASURE_UNIQ - unique treasure items

Fill the instances of these base containers with appropriate treasure for your module.

For any areas where you want finer control over the treasure, simply create additional base containers (you don't need all four -- any one that you skip will fall back to the module-wide version) and place them in the area. Give them these tags (same just without the "MOD"):
X0_TREASURE_LOW - low-level treasure
X0_TREASURE_MED - medium-level treasure
X0_TREASURE_HIGH - high-level treasure
X0_TREASURE_UNIQ - unique treasure items

For any treasure container, use one of the following scripts as BOTH the OnOpen and OnDeath handlers:
Any Treasure: x0_o2_any{low,med,high,uniq}
Books (book, scroll): x0_o2_book{low,med,high,uniq}
Potions: x0_o2_potn{low,med,high,uniq}
Armor (armor, shield, helm, boots, etc): x0_o2_arm{low,med,high,uniq}
Weapon: x0_o2_weap{low,med,high,uniq}
Gold: x0_o2_gold{low,med,high,uniq}

Others may also be added.

MONSTER/NPC TREASURE:

If you would like to have special monster treasure (monster treasure defaults to low treasure otherwise), you can also add any of these base chests:
X0_TREASURE_MONSTER_ - treasure found on monsters with the given tag. This will strip off any trailing digits, so for instance,
NW_KOBOLD1, NW_KOBOLD2, NW_KOBOLD005 would all end up checking the chest X0_TREASURE_MONSTER_NW_KOBOLD.
X0_TREASURE_MONSTER_ - treasure found on monsters of the given racialtype. Ex: X0_TREASURE_MONSTER_ELF and X0_TREASURE_MONSTER_UNDEAD
The spelling matches that used in the RACIAL_TYPE__* constants.
X0_TREASURE_MONSTER - generic treasure found on all monsters/NPCs in the module.

To use monster treasure, use the default OnSpawn script nw_c2_default9 or modify the OnSpawn script as follows:
- Replace #include "nw_o2_coninclude" with #include "x0_i0_treasure"
- Replace GenerateNPCTreasure(); with CTG_GenerateNPCTreasure();
- If you prefer to generate monster treasure from the general chests, you can also add a parameter to CTG_GenerateNPCTreasure(); to specify whether the treasure generated should be low/medium/high/uniq. See the comments to that function for details.

DETAILS:

Each treasure container has a script that looks for the nearest object with the tag matching the type of treasure.

When the treasure-generating scripts look for a container, they will take the nearest container in the local area, then fall back to the module-wide container. If no container can be found, they will fall back on the standard random treasure generation system.

The treasure generation system will randomly select from 1-3 items from whatever items are in the nearest container. Each item has a 50/50 chance of being replaced by a random amount of coin based on the standard treasure generation system.

IMPORTANT NOTE ON PROBABILITY:

Each item in the chest has an equal probability of being selected. To control the probability of any given item appearing, simply place multiple copies of it in the container.

Because of the stacking rules, there is a slight modification to this. Ammunition/throwing weapons will have a probability equal to the number of stacks in the chest, since the max stack size is the default stack size. Potions, scrolls, and gems, however, will be counted individually to determine the probability even if they are stacked, since their default stack size is 1.

To control the size of the stack that actually gets created, you should create a blueprint that has the appropriate stack size. You can adjust the stack size of the instance you stuff into the base container to whatever you want afterwards; the blueprint's stack size will control what There are scripts that will cause only specific types of items to be selected from the container of the specified level -- eg, only books/scrolls, or only weapons or armor, etc -- useful for bookcases or for weapon racks, & so on.

The unique treasure chest will only place each item in the chest once, will never place more than one item, and will never replace the item with coin.

Advantages of this system:
- Complete control over which items can appear in a module or in an area.
- Thematically-appropriate treasure can be placed in each area.
- Easy for module builders to set up.
- Trivial to add new items to the treasure distribution.
- Trivial to adjust probabilities of items appearing.
- Easy to have unique treasure items showing up randomly.

Disadvantages of this system:
- No level-specific treasure generation. This system is thus NOT appropriate for an area that is intended to scale to radically-different levels. Rather, it is appropriate for use where the levels of the characters are roughly known to the module designer and the treasure can be designed to match.
- No class-specific treasure generation planned for now.

For XP1, we feel this is a good tradeoff, but this should be kept in mind when deciding whether to use this system or the original treasure generation system in user-made modules.

NOTE: This file includes nw_o2_coninclude.

Constants

Name	Value	Brief Description
BK_CHANCE_OF_N0_MONSTERTREASURE	80	The percent chance that no treasure will be spawned by a creature dying.
sBaseTypeVarname	X0_BASE_TYPE_TREASURE	Variable name holding the base type of each treasure item.
sContHigh	X0_TREASURE_HIGH	Tag for the area-specific container.
sContLow	X0_TREASURE_LOW	Tag for the area-specific container.
sContMed	X0_TREASURE_MED	Tag for the area-specific container.
sContMonster	X0_TREASURE_MONSTER	Tag for the monster-specific containers.
sContUniq	X0_TREASURE_UNIQ	Tag for the area-specific container.
sGoldResRef	NW_IT_GOLD001	Gold item ResRef (blueprint).
sModContHigh	X0_MOD_TREASURE_HIGH	Tag for the module-wide container.
sModContLow	X0_MOD_TREASURE_LOW	Tag for the module-wide container.
sModContMed	X0_MOD_TREASURE_MED	Tag for the module-wide container.
sModContUniq	X0_MOD_TREASURE_UNIQ	Tag for the module-wide container.
sNumTreasureItemsVarname	X0_NUM_TREASURE_ITEMS	Variable name holding the number of treasure items.
sTreasureItemVarname	X0_TREASURE_ITEM	Variable name holding a reference to each treasure item
sTreasureGeneratedVarname	X0_TREASURE_HAS_BEEN_GENERATED	Variable name indicating that the treasure container has been filled
TREASURE_BASE_TYPE_ARMOR	13004	Special generalized base type.
TREASURE_BASE_TYPE_CLOTHING	13005	Special generalized base type.
TREASURE_BASE_TYPE_WEAPON	13000	Special generalized base type.
TREASURE_BASE_TYPE_WEAPON_MELEE	13003	Special generalized base type.
TREASURE_BASE_TYPE_WEAPON_NOAMMO	13001	Special generalized base type.
TREASURE_BASE_TYPE_WEAPON_RANGED	13002	Special generalized base type.
TREASURE_GOLD_PROBABILITY	35	Probability of an item being converted to gold.
TREASURE_PROBABILITY_1	70	Probability of a single item being generated, in percentage
TREASURE_PROBABILITY_2	20	Probability of two items being generated, in percentage
TREASURE_TYPE_HIGH	3	Major treasure category.
TREASURE_TYPE_LOW	1	Major treasure category.
TREASURE_TYPE_MED	2	Major treasure category.
TREASURE_TYPE_MONSTER	5	Major treasure category.
TREASURE_TYPE_UNIQUE	4	Major treasure category.
X0_GOLD_MODIFIER	0.50	Multiplier to use on the value of an item to convert it to gold

Functions

All functions prefixed with CTG for "Container Treasure Generation".

Name	Brief Description
CTG_CreateDefaultTreasure	Internal function. This function deliberately not prototyped. Should not be used outside this library. Generate treasure using default method.
CTG_CreateGoldTreasure	Create gold treasure in the specified container.
CTG_CreateSpecificBaseTypeTreasure	Create treasure of the appropriate treasure level and matching one of up to three different base types in the specified container.
CTG_CreateTreasure	Create random treasure items of the appropriate type in the specified container. Will typically be called by a script on a treasure container.
CTG_GenerateNPCTreasure	Create treasure on an NPC. This function will typically be called from within the NPC's OnSpawn handler.
CTG_GetIsArmor	Check if the item's base type is armor.
CTG_GetIsBaseType	Check if the item's base type is of the given base type.
CTG_GetIsClothing	Check if the item's base type is clothing.
CTG_GetIsContainerInitialized	Internal function. This function deliberately not prototyped. Should not be used outside this library. Test whether a treasure container has been initialized for specific base treasure type use.
CTG_GetIsMeleeWeapon	Check if the item's base type is a melee weapon.
CTG_GetIsRangedWeapon	Check if the item's base type is a ranged weapon.
CTG_GetIsTreasureGenerated	Test if treasure has been generated in the given object.
CTG_GetIsWeapon	Check if the item's base type is a weapon.
CTG_GetIsWeaponNoammo	Check if the item's base type is a weapon but not ammunition.
CTG_GetModuleBaseContainer	Get the module-wide base container of the appropriate type.
CTG_GetMonsterBaseContainer	Find and return the right monster container, if available.
CTG_GetNearestBaseContainer	Locate the base container of the appropriate type closest to the specified object.
CTG_GetNumItems	Get the number of items to generate.
CTG_GetNumItemsInBaseContainer	Get the number of items in a base container.
CTG_GetRacialtypeChestTag	Tack on the appropriate racialtype suffix.
CTG_GetSpecificBaseTypeTreasureItem	Starting from the specified item position, return the first item that matches one of the three base types.
CTG_GetTreasureItem	Get the specified item out of the given base container's inventory.
CTG_InitContainer	Internal function. This function deliberately not prototyped. Should not be used outside this library. Initialize a treasure container to store the items contained inside as local variables on the container.
CTG_IsItemGold	Determine whether an item should actually just be gold.
CTG_SetIsContainerInitialized	Internal function. This function deliberately not prototyped. Should not be used outside this library. Set whether a treasure container has been initialized for specific base treasure type use.
CTG_SetIsTreasureGenerated	Set whether treasure has been generated.
GetIsInteger	Internal function. Returns TRUE if the character is an integer (0 to 9).