Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools


From Roll20 Wiki

Jump to: navigation, search
API ScriptAuthor: Jonathan Burke
Version: 1.0
Last Modified: 2015-01-31
Code: InventoryManager
Dependencies: None
Conflicts: None

This is an example of an API script listing to demonstrate the format we'd like contributors to mimic. Keeping a unified look will lower the barrier to entry for mentors just learning how to use API scripts in their games. In this space we're looking for a general description of the script and it's use. If there a specific installation instructions you should make a note of it here but detail them in the Help.txt and optionally below in it's own section.



This script was inspired by the Graphic Inventory Manager: Multidimensional GUI for characters written by John C.


There are no commands at this time.

Installation and Setup

Copy the script's code, available from the menu on the right and stored at Roll20's API GitHub Repository. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign.

You have to change the value of the default inventory token graphic inventoryTokenImage. Upload any image you wish to represent (the inside) of containers. This could be a lightly transparent square to your campaign / account and retrieve its link (see API:Objects#imgsrc_and_avatar_property_restrictions).

Then you need to setup a page in your campaign to be able to use this script. It is recommended that you setup a new campaign for this manager, so that your players can have this campaign open in another tab and always look at their inventories (else you would have to switch the page constantly).

The following paragraphs describe the different types of tokens the script can handle.

Character Area

This script expects you to have a special token for each character you want to be able to use the inventory manager. The token represents the area owned by that character. All items that get dropped inside of this area will become controlled by that character and he can freely move them around (even drop them into other character areas). This token has to have main set in its gm-notes section and should be placed on the map layer. You have to set the red bars value to the number of the player inside the script config.

Layer map
bar3_value Number of the player inside of the config
gm_notes main

Equipment Slots

After you have created a character area, you can create any amount of tokens that should represent equipment slots for that character. You can have one big slot all over the character or split them up to indicate various regions on your character. Those slots have to have worn set in their gm-notes section and should be placed on the map layer. All items placed over such an equipment slot will be recognized by the script as 'being worn'.

Layer map
gm_notes worn


Each and every item a player can hold or store is a token. The green bar of a token represents its weight, the blue bar its volume. For ease of use it is recommended that you create often used tokens and save them as handouts so that you can drag them onto a character area whenever you need a new item. You dont have to have a handout for every item, e.g. rare items would not need a handout.

Layer objects
bar1_value Weight of the item
bar2_value Volume of the item
gm_notes any modifiers (see below)

Special Items

Some items are special in that they represent container or have special properties. These properties can be identified by adding modifiers to the gm-notes section of that token. Available modifiers are:

Modifier Effect
unstowable For items that should not be stored inside of containers (e.g. greatswords)
backpack For items that represent containers (each container has its own key, see below)
constantweight For containers that have a constant weight and ignore the weight of their contents (e.g. bag of holding)
liquid For containers that store liquids (e.g. vials)
weight [number] For items that have a base-weight (primary use for liquid containers)
coins [type] For items that should represent a coin
ignore For items or tokens that should not be considered at all (e.g. visual sugar)


Container kinds are defined in the script config section. Per default are the following containers defined:

Key Max. weight in lbs Max. volume in cubic ft
backpack 30 1
quiver 1 0.1
boltcase 1.5 0.15
pouch 6 0.2
pocket 3 0.1
bagofholding 500 64
hhh 80 8
hhhside 20 2
chest 300 12
cart 600 50

You can add additional containers or change the values as you like. Keep in mind that already placed containers do not change their values.

Drop Areas

You can define special drop areas. All items that get moved over these areas will get moved to the map-layer and are not considered to be carried by that player.

Layer map
gm_notes drop

Status Marker

To display the weight, profile etc. you can create a token and place it anywhere. It should be on the objects layer or the information will not be visible (since its name contains the information). For weight and volume informations set status in its gm-notes. For total money-value carried set status3 in its gm-notes.

Layer objects
bar1_max Maximum weight this character can carry (0 for unlimited)
bar2_max Maximum volume this character can carry (0 for unlimited)
bar3_value Number of the player inside of the config
gm_notes status OR status3


v1.0 (2015-01-31)

  • Release