Inventory: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
Line 127: Line 127:


== Scriptsupport ==
== Scriptsupport ==
The following events are available for scripters. These events can be called on any entity (as every entity has an inventory), but I assume for 99% of the cases, you will want to use these on <tt>$player1</tt>.


To be written...
;<tt>scriptEvent float getLootAmount(float Type);</tt>
:Returns the amount of loot for the given type (e.g. LOOT_GOODS). There are a few loot constants defined in <tt>tdm_events.script</tt> file. Pass LOOT_TOTAL to return the sum of all loot types.
:*LOOT_TOTAL
:*LOOT_JEWELRY
:*LOOT_GOLD
:*LOOT_GOODS
 
;<tt>scriptEvent float changeLootAmount(float type, float amount);</tt>
:Changes the loot amount of the given Type (e.g. GOODS) by <amount>. The new value of the changed type is returned (e.g. the new GOODS value if this has been changed). Note: The LOOT_TOTAL type can't be changed and 0 is returned.
 
;<tt>scriptEvent void addInvItem(entity inv_item);</tt>
:Adds the given item to the inventory. Depending on the type, the passed entity will be removed from the game (as for loot items) or hidden. If the item couldn't be added, a warning is emitted to the console.
 
;<tt>scriptEvent float replaceInvItem(entity oldItem, entity newItem);</tt>
:Replaces the entity <oldItem> with <newItem> in the inventory, while keeping <oldItem>'s inventory position intact.
:Note: The position guarantee only applies if <oldItem> and newItem share the same category. If the categories are different, the position of <newItem> is likely to be different than the one of <oldItem>.
:Note that <oldItem> will be removed from the inventory. If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.
:Returns: 1 if the operation was successful, 0 otherwise.
 
;<tt>scriptEvent entity getNextInvItem();</tt>
;<tt>scriptEvent entity getPrevInvItem();</tt>
:Cycles the standard cursor to the next/prev inventory item.
:Returns: the item entity pointed to after the next/prev operation is complete.
 
;<tt>scriptEvent float setCurInvCategory(string categoryName);</tt>
:Sets the inventory cursor to the first item of the named category.
:Returns: 1 on success, 0 on failure (e.g. wrong category name).
 
;<tt>scriptEvent entity setCurInvItem(string itemName);</tt>
:Sets the inventory cursor to the named item.
:Returns: the item entity of the newly selected item (can be the $null_entity).
 
;<tt>scriptEvent string getCurInvCategory();</tt>
:Returns the name of the currently highlighted inventory category.
 
;<tt>scriptEvent entity getCurInvItemEntity();</tt>
:Returns the currently highlighted inventory item entity.
 
;<tt>scriptEvent string getCurInvItemName();</tt>
:Returns the name of the currently highlighted inventory item (the one defined in <tt>inv_name</tt>).
 
;<tt>scriptEvent string getCurInvItemId();</tt>
:Returns the name of the currently highlighted inventory item (the one defined in <tt>inv_item_id</tt>). Most items will return an empty string, unless the "inv_item_id" is set on purpose.
 
;<tt>scriptEvent string getCurInvIcon();</tt>
:Returns the icon of the currently highlighted inventory item.
 
;<tt>scriptEvent void changeInvItemCount(string name, string category, float amount);</tt>
:Decreases the inventory item stack count by amount. The item is addressed using the name and category of the item. These are usually defined on the inventory item entity (<tt>inv_name</tt>, <tt>inv_category</tt>). Amount can be both negative and positive.
 
;<tt>scriptEvent void changeInvLightgemModifier(string name, string category, float modifier);</tt>
:Sets the lightgem modifier value of the given item. Valid arguments are between 0 and 32 (which is the maximum lightgem value).
 
;<tt>scriptEvent void changeInvIcon(string name, string category, string icon);</tt>
:Sets the inventory icon of the given item in the given category to <icon>.
 
=== Example ===
A short example of the above script events in action is the lantern script:
// Set the icon to the "on" icon
userEntity.changeInvIcon(getKey("inv_name"), getKey("inv_category"), getKey("inv_icon_on"));
The first call is retrieving the <tt>inv_name</tt> and <tt>inv_category</tt> spawnargs from the lantern entityDef and takes them as argument for te <tt>changeInvIcon</tt> call. The <tt>inv_name</tt> and <tt>inv_category</tt> are necessary for the code to lookup the item in the player's inventory. The third parameter defines which icon the lantern inventory item should have from now on.


== Custom HUDs ==
== Custom HUDs ==

Revision as of 08:58, 18 November 2008

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).

Inventory 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/tdm_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/tdm_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. (greebo: Should be removed)
tdm_inv_loot_group | string | default "Loot"
Specifies the default category name for the loot objects. Must not be empty. (greebo: Should be removed)
tdm_inv_hud_pickupmessages | [0|1] | default is 1
If set to 1, the HUD is displaying the item the player has just picked up.
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. (greebo: Should be removed)
tdm_inv_use_on_frob | [0|1] | default is 0 (for now)
When set to '1' the code attempts to use the currently selected inventory on frob, provided the selected item supports this action.
tdm_inv_use_on_frob_visual_feedback | [0|1] | default is 1
When set to '1' the HUD is giving visual feedback when the currently highlighted item is used.

Related CVARs

tdm_hud_opacity | float [0..1]
Defines the opacity of the HUD GUIs, also affects the lightgem and the weapon HUD.

Scriptsupport

The following events are available for scripters. These events can be called on any entity (as every entity has an inventory), but I assume for 99% of the cases, you will want to use these on $player1.

scriptEvent float getLootAmount(float Type);
Returns the amount of loot for the given type (e.g. LOOT_GOODS). There are a few loot constants defined in tdm_events.script file. Pass LOOT_TOTAL to return the sum of all loot types.
  • LOOT_TOTAL
  • LOOT_JEWELRY
  • LOOT_GOLD
  • LOOT_GOODS
scriptEvent float changeLootAmount(float type, float amount);
Changes the loot amount of the given Type (e.g. GOODS) by <amount>. The new value of the changed type is returned (e.g. the new GOODS value if this has been changed). Note: The LOOT_TOTAL type can't be changed and 0 is returned.
scriptEvent void addInvItem(entity inv_item);
Adds the given item to the inventory. Depending on the type, the passed entity will be removed from the game (as for loot items) or hidden. If the item couldn't be added, a warning is emitted to the console.
scriptEvent float replaceInvItem(entity oldItem, entity newItem);
Replaces the entity <oldItem> with <newItem> in the inventory, while keeping <oldItem>'s inventory position intact.
Note: The position guarantee only applies if <oldItem> and newItem share the same category. If the categories are different, the position of <newItem> is likely to be different than the one of <oldItem>.
Note that <oldItem> will be removed from the inventory. If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.
Returns: 1 if the operation was successful, 0 otherwise.
scriptEvent entity getNextInvItem();
scriptEvent entity getPrevInvItem();
Cycles the standard cursor to the next/prev inventory item.
Returns: the item entity pointed to after the next/prev operation is complete.
scriptEvent float setCurInvCategory(string categoryName);
Sets the inventory cursor to the first item of the named category.
Returns: 1 on success, 0 on failure (e.g. wrong category name).
scriptEvent entity setCurInvItem(string itemName);
Sets the inventory cursor to the named item.
Returns: the item entity of the newly selected item (can be the $null_entity).
scriptEvent string getCurInvCategory();
Returns the name of the currently highlighted inventory category.
scriptEvent entity getCurInvItemEntity();
Returns the currently highlighted inventory item entity.
scriptEvent string getCurInvItemName();
Returns the name of the currently highlighted inventory item (the one defined in inv_name).
scriptEvent string getCurInvItemId();
Returns the name of the currently highlighted inventory item (the one defined in inv_item_id). Most items will return an empty string, unless the "inv_item_id" is set on purpose.
scriptEvent string getCurInvIcon();
Returns the icon of the currently highlighted inventory item.
scriptEvent void changeInvItemCount(string name, string category, float amount);
Decreases the inventory item stack count by amount. The item is addressed using the name and category of the item. These are usually defined on the inventory item entity (inv_name, inv_category). Amount can be both negative and positive.
scriptEvent void changeInvLightgemModifier(string name, string category, float modifier);
Sets the lightgem modifier value of the given item. Valid arguments are between 0 and 32 (which is the maximum lightgem value).
scriptEvent void changeInvIcon(string name, string category, string icon);
Sets the inventory icon of the given item in the given category to <icon>.

Example

A short example of the above script events in action is the lantern script:

// Set the icon to the "on" icon
userEntity.changeInvIcon(getKey("inv_name"), getKey("inv_category"), getKey("inv_icon_on"));

The first call is retrieving the inv_name and inv_category spawnargs from the lantern entityDef and takes them as argument for te changeInvIcon call. The inv_name and inv_category are necessary for the code to lookup the item in the player's inventory. The third parameter defines which icon the lantern inventory item should have from now on.

Custom HUDs

To be written...

Setting up Weapons

TODO


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