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

Personal tools

Difference between revisions of "Script:Backpack"

From Roll20 Wiki

Jump to: navigation, search
(enigmas)
(enigmas)
Line 163: Line 163:
 
enigma:({{token|enigma name}};{{token|enigma description}})<br>
 
enigma:({{token|enigma name}};{{token|enigma description}})<br>
 
<br>
 
<br>
{{token|enigma name}} {{rarr}} A name that masks the [[Script:Backpack#Item_Definition|item definition]]'s true name<br>
+
{{token|enigma name}} {{rarr}} A name that masks the [[Script:Backpack#Item_Definitions|item definition]]'s true name<br>
 
{{token|enigma description}} {{rarr}} The description of the enigma'd item
 
{{token|enigma description}} {{rarr}} The description of the enigma'd item
 
}}
 
}}

Revision as of 20:01, 26 June 2015

API Script Author: Ken L.
Version: 1.25
Last Modified: 2015-6-24
Code: NA
Dependencies: None
Conflicts: Unknown

Contents

Backpack is a journal based inventory system that updates the 'bio' section of a journal to represent a graphic inventory interface. This allows GMs whom implement this script to allow players to manage a graphic representation of their inventory. Once setup, you can move, give, drop, and pickup items through the use of the API button interface as well as buy and sell from shops and stores should they be prepared.

To use this script requires quite a bit of setup on the part of the GM preparing the asset and item databases. The asset database is simply a list of available item types/subtypes and their associated images. The item database is a list of parsable item definitions which can be short hand written to loot drops or any backpack compatible journal entry.


Getting Started

Once you load the backpack.js and backpack_tmp.js scripts into your campaign, you'll need to at least create an asset database.

After creating an asset database, you're ready to populate backpack compatible journal entries as inventories, stores, or loot cache drops.

General Use

TODO

Item Definitions

Item definitions are the format in which entries of items are parsed into the script. They consist of several parts.

[quantity] <name>;<type> [weight] [value] [description] [use] [maxcharge] [enigma]
Formally:

[quantity] name

type
[optionals] 

[quantity] name

type
subtype
[optionals] 


name

→ Name of the item, see name

type

→ Existing type in backpack_tmp.js, see type

sybtype

→ Existing subtype defined in the asset database, see subtype

quantity

Optional quantity of the item, see quantity

weight

Optional weight of the item in lbs, see weight

value

Optional value of the item, see value

description

Optional description of the item, see description

use

Optional use argument to be executed, see use

maxcharge

Optional max charges of the item, see charges

enigma

Optional enigma arguments, see enigmas

name

The name parameter is essential to the item definition and must be unique for this item. Names of items are case insensitive and considered first class citizens along with enigma names. Names can contain any character including numbers but cannot start with a number else that number will be considered a quantity.

Names have a special suffix case where if it has a suffix of [<number>] it can denote charges. In this case the name of the item is everything preceding this suffix. For the example of 'Wand of Bless[50]', 'Wand of Bless' is the base item name, and '[50]' is parsed out as the number of charges this item has. This is such that items of the same charge amount can stack and separate in quantity as they're used. Clearly an item named 'Staff of bolts' and 'Staff of bolts[10]' would be seen as the same item; but one definition denotes that the item has charges, and the other does not, 'Staff of bolts' is not the same as 'Staff of bolts[0]' despite having the same name identifier. For the purposes of charging this item, 'Staff of bolts[0]' could be charged and 'Staff of bolts' could not.

If there are multiple items with the same name identifier the combined result of the receiving location will have its quantity increased even if the donating location's item definition is different in other areas from the receiving location's definition.

An example would be moving a 'flute' from AB where say A has 5 flutes and B has 2 flutes. The difference between A and B's flutes despite having the same name is that they have different descriptions or weights despite having the same primary identifier as 'flute'. If you move 1 flute AB then B would have 3 flutes and A 4 as expected, but B will simply have it's quantity altered, as opposed to another 'flute' item being generated matching A's flute definition.

A simple resolution to this to have the name be more descriptive such as 'Alfreds Flute' and 'Bernard's Flute'. Special care must be taken such that these names do not conflict with introduced enigma names

type

The type parameter is essential to the item definition as it connects the item definition to a display template that exists in backpack_tmp.js as well as an image for the type. A legal type is defined within the script, therefore only a fixed number of types exist. This can be extended upon by editing backpack_tmp.js, see customizing for details. All types are case sensitive and can only include characters [A-Za-z] plus '-' and '_'.

Type name Description
potion template for potions
weapon template for weapons
armor template for armor
wand template for potions
staff template for staves
ring template for rings
scroll template for scrolls
misc template for miscellaneous
food template for food
treasure template for treasure
gem template for gems

No item definition can exist without a valid type, compared to subtypes which are optional, and enumerable within the asset database.

Some types are associated with one or more categories which can add special behaviors to all items of this type, implicitly including all of its subtypes. Categories are assigned to types within the asset database.

subtype

The subtype is not essential to to the item definition so long as the type it branches off exists. Subtypes exist primarily for the purpose of image enumeration categorized by type. For example from scroll:scroll_ancient we can extract scroll as the type and scroll_ancient as the subtype. scroll:scroll_ancient could refer to a withered image of parchment where as scroll:scroll_empowered could refer to an image of a glowing scroll. There are no naming conventions other than what is a legal type name so weapon:greataxe is valid as well.

Types (type and subtype) as presented by this script are used to

A.) Provide a template for the item
B.) Allow propagation for item images related to the base type

quantity

The quantity of an item is optional to the item definition but is never left undefined. If not provided it represents an infinite pool of the item for backpack journals configured as stores, but otherwise defaults to 1 for all other purposes (loot caches, inventories). If defined, the quantity is defined before the item name, typically a white space separating the two.

weight

The weight of an item is optional and considered 0, or weightless if not provided. Weight is parsed as a number immediately followed by lb or lbs. Valid examples are:

45lbs
0.5lb
100lb

Correct plurality for lb isn't a factor.

value

The value of an item is represented as the combination of numbers followed by short-hand names of the currency denominations defined in the script's design section. By default these denominations are platinum, gold, silver and copper. Their respective short names are thus 'pp', 'gp', 'sp', and 'cp'. Therefore the value of an item can be represented by the examples:

10gp 2sp 1cp
35pp 353gp
42098gp 2004sp 350000cp

Internally, when the script processes the item definition, it unifies the value into a single total and upon display, will divide this unified value into the minimum of each denomination required. Upon saving this item definition this minimum coinage value is recorded as opposed to the original representation.

The denomination values are defined internally in the script's design section. This and currency names can be altered as explained in customizing.

description

The description argument is optional, typically containing some textual information regarding the item. It follows the syntax desc:(<text>) where <text> is anything except parenthesis. Valid examples include:

desc:(This old hat was once worn by haggard the great)
desc:(This artifact was one of the 4 shards spread across the continent. It radiates a dim red light around its edges..)

use

The use argument is optional, but if defined will configure the item as 'usable'. Then the item is 'used' it will output the use content that was stored in the use argument. Valid examples are:

use:(Healing [[1d8+1]])
use:( )
use:(DC 15 Reflex save or blinded!)

By default, if a usable item is used without a set quantity, it will execute the use argument once; else it will execute the use argument as many times as the quantity requested unless this behavior is altered by a category on the item's type.

charges

Charges, if an item has them, are defined as a suffix of the item name (non-inclusive of the name) ending in [<number>] where <number> is the amount of charges an item has. An item that 'has' charges, in that it contains this suffix, can be used if the use argument is present to decrease the number of charges. By default, the script will use a single charge if no exact number is given. The auto-generated macro for the use button specifically asks the number of charges to use.

Depending on the category associated with the type as defined in the asset database, when the item is used, it can output its use argument in several ways.

enigmas

Enigmas are a special optional item argument that essentially masks the true item's identity; and is itself a mini item definition comprising of an enigma name and an enigma description.

enigma:(<enigma name>;<enigma description>)
Formally:

enigma:(enigma name

enigma description

)

enigma name

→ A name that masks the item definition's true name

enigma description

→ The description of the enigma'd item

Asset Database

The asset database is a journal entry that contains within its gmnotes section the library of images to be used for item definitions through their type and subtype

The asset database has a simple format where each line is a single asset entry (blank lines between groups of entries are fine).

Each asset entry is in either of the following formats:

<type>:<link>
<type>:<subtype>:<link>
Formally:

type

subtype
link


type

link



type

→ Existing type in backpack_tmp.js

sybtype

→ Anything except ε

link

→ HTML link to the image source, must start with 'http' case insensitive

category

A category is an additional layer of logical classification for an item type outside of defining a template and enumerating subtypes.

Categories are currently built into the script to have certain meanings and the only flexibility granted by assigning them in the asset database is that you're attaching the behavior associated with this category to the type. All categories grant a certain behavior to items that are defined as follows:

Category name Description
VARIABLECHARGE Declares that the type is variable charge in that when multiple charges are used, it does not mean that the it was used that number of times. Using 5 charges does not indicate that the use argument is replicated 5 times as perhaps 5 charges were used to activate a secondary effect. The use argument is only displayed once and the number of charges decremented from the total charge.
CONSUMABLE Declares that the type when used will remove itself from inventory after use if usable. If there is a certain quantity of this item, this quantity will be reduced. If this item has charges, it will be removed when there are no charges remaining.
CHARGEABLE Declares that the type is chargeable, where charges can be added back to the item if it has charges. This will add the 'charge' button to the item. If the item has a defined 'maxcharge' then it cannot exceed this maximum and will set itself to maximum if charged over this limit.

All currently defined categories can overlap in the behaviors they grant without conflict.

Item Database

TODO

Customizing

TODO

Changelog

TODO