Revision as of 12:51, 17 June 2020

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.

Credits

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

Syntax

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.

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

Items

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.

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:

Container

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

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.

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.

Changelog

v1.0 (2015-01-31)

• Release