Inventory

This article describes how to set up inventory items and how they can be given to an entity. An entity's inventory can be seen as some sort of "container" for various items. Inventory items are distinguished by their category, such as Tools, Maps, Potions and Weapons (yes, a weapon is also a special kind of inventory item). All entities can have an inventory, even though it may only make sense for AI and the player to actually have one. Also included is a script interface, so that a mapper can interact with the inventory in a more sophisticated way, if the default behaviour is not sufficient.

Definitions

The spawnargs can be either set in the def file as a default, or in the map file to override settings for specific entities. Naturaly this also means that they can be manipulated by scripts as well.

IMPORTANT!!! Normally items will vanish from the map as soon as the item is successfully put into the inventory. If this doesn't work, then the item will stay visible. This is a intentionally so, to make the mapper aware of the problem. Check the console and/or enable the inventory logclass in the darkmod.log file to see what went wrong.

There are several terms and types of items that can be used in the inventory:

• Anonymous items An anonymous object means that it will not show up as an item in the inventory. Examples are gold coins and all the other (mostly loot) items that are collected but not being used individually. In this case they only count for the total of loot and are discarded afterwards. Anonymous items also can not be dropped after they are placed into the inventory because they essentially no longer exist. For the loot count it obviously doesn't matter wether an item is anonymous or not, as all are added up into the loot categories. The same holds for ammonition (arrows). These get added to the weapon's ammo and are removed from the map.

• Stackable items These are items that can be stacked in the inventory. This means that the player can acquire multiple instances of such items, but only one entry is shown in the inventory with a counter of how many currently are available. An example would be a health potion. The player can possess more than one health potion at a time and this would be indicated by the counter on the HUD. Stackable items are identified by setting the stackable property. They also must always use the same name and category. If this doesn't match, they are considered to be different. This also allows for dealing out i.e. fake health potions which have no effect or deal damage instead (as an example).

• Category Each item has a Category, which is used to group items. This allows the player to faster scroll through the inventory because he doesn't have to cycle through all the individual items. For example a category would be 'Readables' where books and scrolls are stored, and another Category would be 'Tools' where lockpicks and other items can be stored. Note that the actual category names are entirely up to the mapper. It doesn't have any consequence as to the playability and is only a convenience for the player. The inventory category is briefly displayed on the player HUD when cycling through the items.

• Cursor (This is coding-related information) An inventory can have multiple cursors. Each cursor can point to a different place in the same inventory, and can restrict the movement to certain categories. This way, you can implement different HUDs or GUIs which can show different parts of the inventory in different places even though all the items are in one single inventory. Weapons are handled this way; a separate cursor is used which is only allowed to cycle through the weapon category.

Spawnargs

inv_name | string [required]

Specifies the name the object should display when it is activated in the inventory. Keep in mind that the display name and the category together are used to determine whether two items are of the same type. This is important to determine whether items can be "stacked". Both inv_name and inv_category must match.

Example: "inv_name" "Health Potion"

inv_category | string [required]

Specifies the category that the object should be filed under.

Example: "inv_category" "Potions"

inv_icon | string (D3 path to icon file)

Points to an icon that is to be displayed on the player HUD when the object is selected in the inventory. (This can also point to a shader name.) Note that you don't need to specify the file extension.

Example: "inv_icon" "guis/assets/hud/inventory_icons/icon_health_potion"

inv_stackable | [0/1]

Determines whether an item can be stacked on top of other items of the same type. An example would be the health potion item. The player can pick up more than one health potion, but in the inventory he will only get one item with a counter. Note that loot items need not to be stackable, they are handled separately by special code.

inv_item_id | string

This key can be set by the mapper to a value of his or her choice. This is needed if the mapper wants to address specific items or groups of items in order to implement custom behaviour, even if the inv_name is the same for this group of items. For example, a mapper can create a fake health potion which shows up in the inventory just like a regular one. If the mapper desired, he could set up a script to check for this exact potion and trigger custom behaviour when the item is used.

inv_count | integer number

Defines how many instances of an item is to be added to the inventory. Applies only to items with inv_stackable set to 1. Non-stackable items have always an item count of 1 and this argument is ignored. As an example, the mapper could set up a stack of health potions as single entity (some sort of quiver) which immediately adds 5 potions to the player's inventory.

inv_droppable | [0|1]

If set to 1 the item can be dropped into the map by the player. This will not work for anonymous items (loot, ammo), since their entity will be removed from the map after they had been put into the inventory.

inv_loot_type | [ 0 | 1 | 2 | 3 ]

• 0 = No lootitem (default)
• 1 = Jewelry/Gems
• 2 = Gold
• 3 = Goods

This has to be set in order to define what kind of item it is and if it is a loot item, which category of loot it should account for. Note: it's not possible to choose other values (e.g. loot type = 4), the code will probably crash.

inv_loot_value | integer

Determines the amount of loot this item accounts for. This spawnarg is only applicable for items with a non-zero inv_loot_type.

inv_ammo_amount | integer (default is 0)

Determines whether this item is an ammo item and how much ammonition this item represents. When this argument is 0, the item is not recognised as ammo. Ordinary ammonition items like atdm:ammo_broadhead have inv_ammo_amount set to 1, but it's perfectly valid to set it to higher values for items like quivers. Don't forget to add the inv_weapon_name spawnarg, which is needed by the code to determine which weapon this ammo belongs to.

inv_weapon_name | string

This spawnarg applies to weapon and ammo items. Each weapon must have a unique inv_weapon_name, like "broadhead" or "blackjack". This weapon name is used to determine which weapon an ammonition item is belonging to. If the inv_weapon_name is missing on ammonition, it cannot be recognised as loot (a warning is emitted to the console and the log).

inv_use_on_frob | [0|1] (default is 0)

When this spawnarg is set to 1, it can be used just by hitting the "frob" button (of course it must be selected in the inventory). The code then attempts to "use" this item on the highlighted entity in front of the player. The system is still in the works, so this information might not be fully accurate.

inv_map_start | [0|1]

Determines wether this object should be automatically moved to the inventory at map start.

inv_target | string (entityname, optional, defaults to "player1")

If the inv_map_start argument is set to "1", this defines the name of the entity that should receive it, otherwise the value is ignored. To give an item to the player, you would use player1 as the name (which is the default value anyway).

inv_hud | string (D3 path to .gui file)

If this key is set it should point to a GUI file, which defines the hud for this particular item. As an example, you can look at the file tdm_loot.hud, which implements a custom hud that does not use the regular inventory item HUD. The mapper is responsible to maintain the state for such an item on his own. In order to do this, there is an initialization message sent to the specified script and other messages as well like selecting or deselecting an item. In order to make this work, the mapper must set up the correct scriptobject and add a few events to it. An example description of how to operate a custom HUD will be described in the scripting section on this article.

inv_hud_layer | integer (layernumber)

If a custom hud is used for an item by setting the key inv_hud, this key can be set to specify a layer number the custom hud should be displayed on. Normally this value can be set to 0 or left blank when using the default screen for the player, but for huds on other objects in the map, this might be needed.

inv_persistent | [0|1] (default is 0)

If this is set to "1", the item can be taken to the next map. This is useful for designing campaigns, where important items or weapons can be taken to the next level.

inv_lgmodifier | int (default is 0, maximum is DARKMOD_LG_MAX = 32)

This can be used to modify the lightgem brightness when this item is selected in the inventory. Useful for weapons like the fire arrow.

inv_movement_modifier | float | default is 1, must be positive

This can be used to slow down the player when this item is equipped (e.g. for weapons like the shortsword). This value is multiplied on the maximum movement speed.

inv_drop_point | vector

TODO

inv_drop_angles | vector

TODO

Default equipment for map start

This describes how to give items to the player at map start time, but the same mechanism can be applied to any other AI (or entity for that matter) as well.

• First create your object in the editor, just like you would if you wanted to put it in the map. Choose Create Entity and select the inventory item of your choice (a health potion for example). Place it where you like, but not outside in the void.
• Set the key inv_map_start on the object entity to the value 1.
• (Optional) Set the key inv_target to the name of the entity you would like this item to go to.

The object will be moved to the target entity's inventory right at map start (and will be hidden or removed). The player will not be able to see the item (unless there was a mistake in the setup).

CVARs

The following cvars can be used to modify the behaviour of some inventory properties. Some of them are probably only of interest to modders, while others are also of interest to players and might be added to a customization menu.

tdm_inv_hud_file | string | default "guis/inv.gui"

Specifies the gui file that should be used for the inventory. this can be changed for mods, that wish to implement a different GUI, or provide alternative skins for the player.

tdm_inv_loot_hud | string | default "guis/loot.gui"

Specifies the gui file that should be used for the loot slot in the inventory. Since custom huds are now supported for different items, this cvar is no longer needed and might be removed later.

tdm_inv_loot_group | string | default "Loot"

Specifies the default category name for the loot objects. This is probably not used and changing it has no effect.

tdm_inv_group_mode | int | default "0"

This defines how the grouping should work. The following options are available:

• 0 = ungrouped inventory (T1/T2 style)
• 1 = grouped inventory

'ungrouped' means that you can cycle through the inventory one after the other. This does not affect the NextCategory/PrevCategory keys and you can still use them.

'grouped' means that you just cycle through one group at a time, and you have to use the NextCategory/PrevCategory keys to switch to a different category. Cyclying through the inventory will always stay in the selected group.

tdm_inv_visibility | int | default "1"

Specifies the visibility for the inventory. The following options are available

• 0 = never visible
• 1 = always visible
• 2 = temporary (not yet implemented.)

Option two will fade out the inventory after some specified time.

tdm_inv_opacity | float [0..1] | default "1"

Specifies the alphachannel for the inventory. It determines if and how much you can look through the inventory text and icons.

tdm_inv_fade_in | int | default "0"

Specifies how long it should take for the inventory until it becomes visible. 0 means that it will be immediatly visible when activated.

tdm_inv_fade_out | int | default "0"

Specifies how long it should take for the inventory until it becomes invisible. 0 means that it will be immediatly invisible when deactivated.

tdm_inv_loot_sound | string | default "sound/sfx/world/frob_loot.ogg"

Specifies the default path to the soundfile that is played when loot is aquired. Note that this can be overriden on a per item level, and wont have an effect for such items.

Scriptsupport

To be written...

Custom HUDs

To be written...

The information in this article might be out of date and needs to be updated.