======Item Pickups======
This tutorial will explain how to set up map [[object|objects]] as [[item|items]] for the [[player_character|player]] to pick up, for example a key that the [[player_character|player]] can pick up by walking into/over it and then use to open a door or treasure chest.

**Note:** This tutorial assumes that you already understand the basics of using the RPG in a Box editors, in particular the [[Map Editor]] and [[Voxel Editor]].

=====Creating the Object Model=====
Open the [[New Resource Dialog]] and create a new [[object]]. Once the [[Voxel Editor]] opens for the new [[object]] model, use the [[voxel]] tools to build a key as shown below (or whatever will best visually represent the [[item]]).

{{:wiki:item_pickup_tut_model.png?nolink|}}

After the model is complete, be sure to enable the "Passable" property on the [[Model Properties]] panel. This will prevent the [[Map Editor]] from automatically removing [[navigation_and_interaction|navigation paths]] to its [[tile]] when placed into a [[map]]. Save the model if you haven't already.

{{:wiki:item_pickup_tut_passable_prop.png?nolink|}}

Before proceeding to the next section, you can optionally create a "floating" [[animation]] for the [[object]] by following the [[floating_anim_tutorial|Creating a Simple Floating Animation]] tutorial. This will give a nice effect to the [[object]] in-game and also provide a cue to the [[player_character|player]] that it's an [[item]] pickup.

=====Defining the Item=====
In addition to the [[object]] model, you'll also need to define the corresponding [[item]] that the [[player_character|player]] will receive in their [[inventory]]. Go to the [[Item Editor]] tab and add a new [[item]], then enter a name, description, and image to use.

{{:wiki:item_pickup_tut_define_item.gif?nolink|}}

Remember the name you used for your item (including case) as it will be referenced in a [[quick script]] later on. Click the "Save" button ({{:wiki:disk.png?nolink|}}) to save the changes you've made to the [[item]] database.

=====Creating a Sound Effect=====
Optionally, you can create a [[sound|sound effect]] for the game to play when the [[item]] is picked up by the [[player_character|player]]. To do so, click the [[Sound FX Generator]] button at the top, then click one of the presets along the left to find a [[sound]] that goes well with the [[item]]. In this example, the "Pickup/Coin" preset should work well.

{{:wiki:item_pickup_tut_sfx.gif?nolink|}}

Once you are happy with the [[sound]], click the "Save Sound" button ({{:wiki:disk.png?nolink|}}) and enter a name. Remember this name (including case) as it will also be referenced in our [[quick script]] later on.

=====Setting Up the Object in a Map=====
Open the [[map]] where you'd like to have the [[item]] pickup. Select the [[object]] model you created earlier from the resource container on the right, then place the [[object]] onto an open [[tile]] in the [[map]].

{{:wiki:item_pickup_tut_place_object.gif?nolink|}}

Switch into "Edit" mode, then either double-click the [[object]] (or right-click on it and select "Properties") to open the [[Entity Properties]] dialog. Enter a unique ID into the "Entity ID" box. I'm using "key_01" for this example since my map will contain multiple keys ("key_02", "key_03", etc.). This ID will also be referenced in our [[quick script]] in the next step. Click OK to close the dialog. 

{{:wiki:item_pickup_tut_assign_id.gif?nolink|}}

Double-click the [[tile]] underneath the [[object]] (or right-click on it and select "Properties") to open the [[Entity Properties]] dialog for the [[tile]]. From the "Script" dropdown, select "Quick Script" then click the "Edit" button ({{:wiki:pencil.png?nolink|}}) to edit the [[script]].

Copy and paste the [[script]] source code below into the dialog as shown. You may need to make a few adjustments according to the names you chose earlier on, in particular the entity ID for the [[object]] ("key_01"), the [[sound]] name ("give_key"), and the [[item]] name ("Gold Key"). These are all case-sensitive.

<code lua>
set_entity_script(self, "");
remove_entity(entity["key_01"]);
play_sound("give_key");
give_item("Gold Key")
</code>

{{:wiki:item_pickup_tut_assign_script.gif?nolink|}}

To better understand what the [[script]] is doing, I've included explanations for each line.

<code lua>
set_entity_script(self, "");
</code>

This line removes the [[script]] from the [[entity]] that activated it ("self"), in this case the [[tile]] that the [[player_character|player]] stepped onto. This is to prevent the [[script]] from being activated more than once after it's triggered the first time. The pair of double quotes (i.e. an empty [[string]]) indicates that the [[script]] should be removed/set to nothing.

<code lua>
remove_entity(entity["key_01"]);
</code>

This line removes the physical key [[object]] from the scene by referring to the unique [[entity]] ID we assigned to the key earlier on in the [[Map Editor]]. The ID inside the quotes should exactly match the ID that was assigned to the [[object]] from its [[Entity Properties]] dialog.

<code lua>
play_sound("give_key");
</code>

This line plays the [[sound|sound effect]] named "give_key". The name inside the quotes should exactly match the name given to the [[sound]] when it was saved from the [[Sound FX Generator]]. To prevent any errors, this line should be deleted from the [[script]] if you skipped the optional step of creating a [[sound|sound effect]].

<code lua>
give_item("Gold Key")
</code>

This line puts the [[item]] named "Gold Key" into the [[player_character|player's]] [[inventory]]. The name inside the quotes should exactly match the name defined in the [[Item Editor]]. Note that this line doesn't have a semicolon at the end since semicolons are used as line separators in the RPG in a Box scripting language and this is the last line of code.

Click the "Validate" button and then OK once the [[script]] has been validated, then save the [[map]].

=====Testing the Pickup In-Game=====
[[exporting_your_game|Export the game]] to try out your new [[item]] pickup. The [[player_character|player]] should now receive a Gold Key in their [[inventory]] when walking onto the [[tile]] that contains the key [[object]]!

{{:wiki:item_pickup_tut_ingame.gif?nolink|}}