HPL3/Amnesia: Rebirth/Tutorials/Inventory items - Revision history

M654: Fixed images

2020-11-12T16:22:44Z

Fixed images

M654 at 16:15, 12 November 2020

2020-11-12T16:15:17Z

M654: Simplified some code to make it easier to understand what's going on

2020-11-11T17:13:56Z

Simplified some code to make it easier to understand what's going on

M654: Added pictures

2020-11-11T17:04:56Z

Added pictures

M654: Created page with "This tutorial will explain how to create a custom item that can be picked up, added to the inventory, and used on other entities. ==Tutorial== {{ConstructionNotice|Function..."

2020-11-10T22:01:52Z

Created page with "This tutorial will explain how to create a custom item that can be picked up, added to the inventory, and used on other entities. ==Tutorial== {{ConstructionNotice|Function..."

New page

This tutorial will explain how to create a custom item that can be picked up, added to the inventory, and used on other entities.

==Tutorial==

{{ConstructionNotice|Function parameter explanations and example images coming soon|align=left|width=30%}}

===Creating an ItemType===
Let's start by creating an item type. Keep in mind that an ItemType isn't the same as the physical in-game item entity, so a single ItemType can be used with multiple different entities.

Open <code>config/Inventory.cfg</code>. This file contains a list of all ItemTypes in the game. Add a new <code><ItemType></code> tag:
<syntaxhighlight lang="xml">
<ItemType ID="ItemName">
<Inventory Icon="icon_file_name"/>
<Use OnWorld="true" CanUseOnWorldMapCallback="CanUse_ItemName" UseOnWorldMapCallback="OnUse_ItemName"/>
</ItemType>
</syntaxhighlight>

The icons for items shown in the inventory are stored in <code>graphics/inventory/items</code> and saved in the DDS format. Replace <code>icon_file_name</code> with the name of your icon file, and change <code>ItemName</code> to whatever you want to call your item type.

Setting the <code>OnWorld</code> attribute to <code>true</code> will allow this item
type to be used on other entities in-game.

<code>CanUseOnWorldMapCallback</code> and <code>UseOnWorldMapCallback</code> are functions that determine which entities the item type can interact with and what happens when it's used on an entity, respectively. We'll get back to these later.

A detailed list of Use attributes and available functions is located in the beginning of <code>Inventory.cfg</code>, but to keep things simple we'll only be using the three shown above.

===Item name and description===
Now let's give the item a name and a description that will show up when the item is moused over in the inventory. Open <code>config/lang/english.lang</code> and add two entries to the <code>Inventory</code> category: <code>ItemName</code> and <code>ItemName_Desc</code>.

<syntaxhighlight lang="xml">
<LANGUAGE>
<CATEGORY Name="Inventory">
<Entry Name="ItemName">Test Item</Entry>
<Entry Name="ItemName_Desc">This is a simple test item.</Entry>
</CATEGORY>
</LANGUAGE>
</syntaxhighlight>

===Placing the entity===
In the level editor, choose an entity to represent the item in-game. Select it, open its '''Entity''' tab and look for a section called '''Pickup'''. If it isn't there, that means that the entity is either a physics object or a static object and you won't be able to pick it up in-game. In that case, open the entity's ENT file, scroll down to the <code><UserDefinedVariables></code> tag and change the <code>EntityType</code> attribute to <code>Prop_Pickup</code>:

<syntaxhighlight lang="xml">
<UserDefinedVariables EntityType="Prop_Pickup">
</syntaxhighlight>

Now re-add the entity to the map. The '''Pickup''' section should now appear. Expand the section and set the ItemType attribute to the ID of the item type you created in <code>Inventory.cfg</code>. Now, when you click on the item in-game it will be added to your inventory.

===Item scripting===
Open the map script and add a new function called <code>CanUse_ItemName</code>:

<syntaxhighlight lang="cpp">
bool CanUse_ItemName(const tString &in asItemType, const tString &in asItemID, const tString &in asPickedEntity)
{
return asPickedEntity == "ExampleEntity1" || asPickedEntity == "ExampleEntity2";
}
</syntaxhighlight>

This is one of the functions we set in the config file, and it determines which entities the item can interact with. The <code>asPickedEntity</code> parameter contains the name of the entity the player is looking at at any given time. If the function returns <code>true</code>, the player can use the item on the picked entity. In this example, the function returns <code>true</code> if the picked entity is named <code>ExampleEntity1</code> or <code>ExampleEntity2</code> (ie. the player can use the item on either of these entities).

Finally, let's add one more function.

<syntaxhighlight lang="cpp">
bool OnUse_ItemName(const tString &in asItemType, const tString &in asItemID, const tString &in asTargetEntity, const tString &in asItemEntity, float afTimeElapsed, float afTimeStep)
{
if(asTargetEntity == "ExampleEntity1")
{
// Insert code to interact with ExampleEntity1
}
else if(asTargetEntity == "ExampleEntity2")
{
// Insert code to interact with ExampleEntity2
}

return false;
}
</syntaxhighlight>
This code runs when the player clicks on an entity while holding the item. As shown above, this time the name of the clicked entity is stored in <code>asTargetEntity</code>.

@@ Line 82: / Line 82: @@
 This code runs when the player clicks on an entity while holding the item. As shown above, this time the name of the clicked entity is stored in <code>asTargetEntity</code>.
-[[Image:CustomItemExample3.jpg|thumb|Picking up the test item|left]]
+[[Image:CustomItemExample3_reupload.jpg|thumb|Picking up the test item|left]]
-[[Image:CustomItemExample4.jpg|thumb|Using the test item on a door entity|left]]
+[[Image:CustomItemExample4_reupload.jpg|thumb|Using the test item on a door entity|left]]

@@ Line 1: / Line 1: @@
 This tutorial will explain how to create a custom item that can be picked up, added to the inventory, and used on other entities.
-[[Image:Hpl3:CustomItemExample2.jpg|thumb|An example of a custom item in the inventory|right]]
+[[Image:CustomItemExample2.jpg|thumb|An example of a custom item in the inventory|right]]
 ==Tutorial==
@@ Line 38: / Line 38: @@
 ===Placing the entity===
-[[Image:Hpl3:CustomItemEntityTab.PNG|thumb|The Entity tab|right]]
+[[Image:CustomItemEntityTab.png|thumb|The Entity tab|right]]
 In the level editor, choose an entity to represent the item in-game. Select it, open its '''Entity''' tab and look for a section called '''Pickup'''. If it isn't there, that means that the entity is either a physics object or a static object and you won't be able to pick it up in-game. In that case, open the entity's ENT file, scroll down to the <code><UserDefinedVariables></code> tag and change the <code>EntityType</code> attribute to <code>Prop_Pickup</code>:
@@ Line 82: / Line 82: @@
 This code runs when the player clicks on an entity while holding the item. As shown above, this time the name of the clicked entity is stored in <code>asTargetEntity</code>.
-[[Image:Hpl3:CustomItemExample3.jpg|thumb|Picking up the test item|left]]
+[[Image:CustomItemExample3.jpg|thumb|Picking up the test item|left]]
-[[Image:Hpl3:CustomItemExample4.jpg|thumb|Using the test item on a door entity|left]]
+[[Image:CustomItemExample4.jpg|thumb|Using the test item on a door entity|left]]

@@ Line 53: / Line 53: @@
 bool CanUse_ItemName(const tString &in asItemType, const tString &in asItemID, const tString &in asPickedEntity)
+{
-     return asPickedEntity == "ExampleEntity1" || asPickedEntity == "ExampleEntity2";
+     if(asPickedEntity == "ExampleEntity1" || asPickedEntity == "ExampleEntity2")
+}
 </syntaxhighlight>