Inventory

This article describes how to set up inventory items and how they can be given to an entity. The purpose of the inventory is, to keep track of all items that are in an entities possessions. I delibaretly use "entity" here because, in principle, all entities can have an inventory, even though it may only make sense for AI and the player to actuall have one. For future improvements it might be usefull for other purposes as well though.

Also included is a script interface, so that a mapper can interact with the inventory in a more sophisticated way, if the default implementation 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, since they are the standard way of configuring objects in Doom 3.

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. Currently there is only one error condition that can really trigger this, which is that an item is configured to not be anonymous, but has an empty inv_icon entry. Additionally to not becoming invisible, you can also look into the logfile, because there you can find an error message with the name of the entity that was causing the problem.

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 a seperate item in the inventory. An example would be normal loot like coins or golden dishes. Since they should not be stored in the inventory as seperate items, they don't need to be displayed either. In this case they only count for the total of loot and are discarded afterwards. Anonymous items also can not be dropped after they went 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. Examples are gold coins and all the other (mostly loot) items that are collected but not being used individually.

• 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 posses more than one health potion at a time and this would be indicated by the counter. 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 of different types. This also allows for dealing out i.e. fake health potions which have no effect or deal damage instead (as an example).

• Category is a classification of items, to visually group them together. 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 this category is entirely up to the mapper to decide and also is option. it doesn't has any consequence as to the playabillity and is only a convenience for the player. Categories can switched of on the HUD, so that the player can use the inventory also in the Thief style (which is the default).

• Cursor An inventory can have multiple cursors. This means that you can create objects which make use of a given inventory, by acquiring a cursor for it. 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. For any given object you can not rely to be in a particular inventory, even though you might have a cursor pointing to it. That's because it might be that some other object may have already removed that object, or added another one. Thus, you should always get the pointer to a given item, when you access it, and don't store it's position somewhere external.

Spawnargs

inv_category | string

Specifies the category that the object should be filed under. This allows for player convenience and also is needed for stackable items.

example: "inv_name" "Health Potion"

inv_name | string

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, if the inv_stackable flag is set to 1, wether this is a similar item or not. So if you create to "Health Potion" items, but with different categories, they are treated as different items.

example: "inv_name" "Health Potion"

inv_icon | D3 path to icon

Points to an icon that is to be displayed when the object is selected in the inventory. This entry also determines wether an object is to be considered anonymous or not.

inv_stackable | [0/1]

Determines wether an item is an individual or can be a stack of similar objects. An example would be the various potions. The player can pick up more than one health potion, but in the inventory he will only get one item with a counter. Keep in mind though, that a stack of gold coins is not per se stackable, because usually it will be only one model of a stack of coin with a value of i.E. 10 Gold, so this means that it is not to be confused with a single gold coin having 10 items with a value of 1 each.

inv_item_id | string

This key can be set by the mapper to an arbitrary value. This is needed if the mapper wants to implement custom behaviour and he uniquily need to identfy an item or a group of items. Normally the mapper could also use the inv_name for this key, but this doesn't allow the additional flexibillity. For example a mapper can create a fake health potion which shows up in the inventory just like a regular one, with the same name but a different map model. So if the player picks this bottle up, because he doesn't look carefull and thinks he got a health potion, he might have aquired a real one, while this one actually may deal some damage or doesn't work at all, or whatever the mapper wants it to do. This will of course only work with additional scripting, because the mapper must know what to do with it. In this case the mapper might set a flag on the callback, and the next time the player uses a health potion, the action is triggered.

inv_count | <N>

Determines the number of items this represents. This is only needed for items where stackable is 1, otherwise it is set to 0. Als the option for stackable must always precede the count, otherwise the count is set to 0.

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, since they will have no representation after they were put into the inventory.

inv_delete | [0/1]

Determines if an anonymous object can be deleted, after it was put into the inventory. This is advisable, because the entity will stay in memory and a mapper could still access it via scripting. If the mapper decides that an item will no longer be accessed after it has been acquired, this key should be set to 1. This can affect loading time of saved games, as entities, that are no longer needed, don't need to be saved and restored.

If the mapper also creates entities on the fly, with the help of scripts, it might better to set this flag on appropriate objects to free up the limited number of entities a map can hold. The usuals candidates for this flag are all the regular loot items, because they wont be used anymore after they have been found (lik coins, purses, etc.). Also note that, if dropappable is set to 1, then this key will be ignored, since droppabale items must be turned into entities again to be placed in the map.

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.

inv_loot_value | <N>

Determines the amount of loot this item accounts for. This value is ignore if it is set on an item, which is of loot_type = 0.

inv_map_start | [0|1]

Determines wether this object should be assigned to an inventory at map start.

inv_target | <entityname>

If the item should be assigned to an entity at map start, this should get the name of the entity who shold recive it. To give an item to the player, you would use "player1" as the name, because this is the name that the player entity gets by default. If inv_map_start is not set or set to 0, then this key doesn't need to be set and is ignored. Since the name can be arbitrary, this means of course, that you can also give it to an AI, which the player later on meets. This should not be confused with loot, that is to be attached to an AI though. If you attach a purse or a key to an AI, which the player can frob later on, then it doesn't need to get this set, because such things will not be stored in the inventory. You could assign such things to an chest though, to give the objects to the player when he opens it. This is not directly support though, because it is assumed that chests will be filled with real objects, like TDS did it. However the T1/T2 style chests are still possible to do with some scripting.

inv_hud | <hudfilename>

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 loot.hud, which implements a custom hud that does not use the normal display for items. 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 write a script and assign this script to the key "scriptobject" on the entity. This will automatically launch that script when the entity is spawned,. If the messagefunctions are not implemented the item will show up as an empty slot on the inventory. A detailed description how to operate a custom hud will be described in the scripting section on this article.

inv_hud_layer | int | layernumber

If a custom hud is used for an item by setting the key "inv_hud", this key can be set to specify a layernumber that the hud should be displayed with. 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 | bool | Default is FALSE

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.

Default equipment for map start

This describes how to give items to the player at the mapstart, 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. Create brush, select the item and/or models and place it anywhere you like in the map

• Set the key inv_map_start on the object entity to the value 1.

• Set the key inv_target on the object entity to the value player1. If you want to assign this object to, as an example, a guard with the name Benny, then set it to benny, assuming the entity key "name" is also set to "benny".

The objects can really be placed anyhwere you like and it doesn't really matter. As soon as the map starts, the objects will be put in the inventory, and will vanish from the map. So you could put them right in front of the players eyes, and he still wouldn't see them, as this happens at the intialization time, before the map actually becomes visible.

That's it. Quite simple I would say. :)

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 teh 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 bcomes 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...

Updates needed

Scriptsupport and custom HUDs need to be written.