User Tools

Site Tools


Item Pickups

This tutorial will explain how to set up map objects as items for the player to pick up, for example a key that the 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).

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 paths to its tile when placed into a map. Save the model if you haven't already.

Before proceeding to the next section, you can optionally create a “floating” animation for the object by following the 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 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 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.

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 () to save the changes you've made to the item database.

Creating a Sound Effect

Optionally, you can create a sound effect for the game to play when the item is picked up by the 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.

Once you are happy with the sound, click the “Save Sound” button () 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.

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.

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

set_entity_script(self, "");
give_item("Gold Key")

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

set_entity_script(self, "");

This line removes the script from the entity that activated it (“self”), in this case the tile that the 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.


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.


This line plays the 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 effect.

give_item("Gold Key")

This line puts the item named “Gold Key” into the 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

Export the game to try out your new item pickup. The player should now receive a Gold Key in their inventory when walking onto the tile that contains the key object!

item_pickup_tutorial.txt · Last modified: 2018/03/07 20:58 by justin