Difference between revisions of "Script:Backpack"
From Roll20 Wiki
(→name) |
Andreas J. (Talk | contribs) m |
||
(65 intermediate revisions by one user not shown) | |||
Line 1: | Line 1: | ||
+ | {{notebox|This is an API made in '''2015''', and isn't any longer in the API one-click install menu}} | ||
+ | |||
<div style="float: {{{1|right}}}; width: 200px; padding: 5px; border: 1px solid #777; margin: 0 15px 15px 15px; background-color: #efefef;"> | <div style="float: {{{1|right}}}; width: 200px; padding: 5px; border: 1px solid #777; margin: 0 15px 15px 15px; background-color: #efefef;"> | ||
<span style="text-align:center;display:block;font-size:1.4em">API Script</span> | <span style="text-align:center;display:block;font-size:1.4em">API Script</span> | ||
Line 13: | Line 15: | ||
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. | 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. | + | 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 [[Script:Backpack#Item_Definitions|item definitions]] which can be short hand written to loot drops or any ''backpack compatible'' journal entry. |
<br clear="both"> | <br clear="both"> | ||
Line 21: | Line 23: | ||
After creating an asset database, you're ready to populate backpack compatible journal entries as inventories, stores, or loot cache drops. | After creating an asset database, you're ready to populate backpack compatible journal entries as inventories, stores, or loot cache drops. | ||
+ | |||
+ | Show pictures and animations describing how to use this script. | ||
== General Use == | == General Use == | ||
− | TODO | + | TODO Describe what defines an inventory pack |
+ | |||
+ | === Player Inventory === | ||
+ | TODO Describe a player inventory use-case | ||
+ | |||
+ | === Store === | ||
+ | TODO Describe a store inventory use-case | ||
+ | |||
+ | === Loot drop === | ||
+ | TODO Describe a loot drop / cache use-case | ||
+ | |||
+ | == Commands == | ||
+ | Many Backpack commands are automated, but there are a handful that still need to be manually invoked. | ||
+ | === GM commands === | ||
+ | ==== create ==== | ||
+ | <code>!backpack -create <name></code><br> | ||
+ | <code>!backpack -create john_inventory</code><br> | ||
+ | |||
+ | This command creates an inventory given a journal name. If there are multiple journals with the same name, then the first one chronologically it finds will be processed. Note that for the journal to be backpack compatible, it must have an attributed named <code>BACKPACK</code> with the current value set as <code>true</code> (case sensitive) | ||
+ | |||
+ | ==== load ==== | ||
+ | <code>!backpack -load <name></code><br> | ||
+ | <code>!backpack -load john_inventory</code><br> | ||
+ | |||
+ | This command loads an inventory as the 'active' pack. For stores to function, then need to be loaded as the active pack. An <b>unrecommended</b> use for it is for allowing players to use the <code>!take</code> command for an active pack by say, loading a loot_cache inventory. What's recommended instead is to use the show_active command | ||
+ | |||
+ | ==== close ==== | ||
+ | <code>!backpack -close</code><br> | ||
+ | |||
+ | This command closes the active pack if there is any. Use this command to close active stores such that player's can't buy from it. | ||
+ | ==== show_loot ==== | ||
+ | <code>!backpack -show_loot <name></code><br> | ||
+ | <code>!backpack -show_loot loot_b6</code><br> | ||
+ | |||
+ | This command is the recommended way of producing loot drops. It liquidates any currency stored in the pack and produces pick up prompts to the chat. Note that this command also sets the pack as the active pack so that if you !close the pack, it will no longer be available. | ||
+ | ==== show ==== | ||
+ | <code>!backpack -loot <name></code><br> | ||
+ | <code>!backpack -loot chest_a6_content</code><br> | ||
+ | |||
+ | This command shows the pack described by the provided pack name. It will display the items to chat formatted, but none of the contents will be takable. Useful if you want to show the contents of a pack to players but not let them take them as using load or show_loot will do. | ||
+ | |||
+ | ==== show_active ==== | ||
+ | <code>!backpack -show_active</code><br> | ||
+ | |||
+ | This command shows the currently active pack. Somewhat useful to show a store to the chat window if it is open such that players can use the !buy command. Also useful after using show_loot to show to current contents if players forget. | ||
+ | |||
+ | For the store use-case, what's recommended is to make visible the handout to the store such that players can use the buy button on the journal, and hiding the journal + closing the pack when they leave. | ||
+ | ==== single ==== | ||
+ | <code>!backpack -single <item definition></code><br> | ||
+ | <code>!backpack -single 1 Pearl Necklace;treasure 1500gp 0.1lb desc:(An elaborately crafted necklace made of mother pearl)</code><br> | ||
+ | |||
+ | Creates a single item on the fly, useful for impromptu treasure that needs to be generated on the fly, note that using short hand notation from the item database will work. Also if no quantity is provided to the item definition, it assumes only 1 quantity of the item exists. | ||
+ | ==== place ==== | ||
+ | <code>!backpack -place <player display name> <item definition></code><br> | ||
+ | <code>!backpack -place 'Ken L.' 1 Pearl Necklace;treasure 1500gp 0.1lb desc:(An elaborately crafted necklace made of mother pearl)</code><br> | ||
+ | |||
+ | Creates a single item on the fly and places it into a player inventory, similar to the single command. If the player has multiple inventories, it will prompt for which inventory it shall be placed. | ||
+ | |||
+ | ==== reload_db ==== | ||
+ | <code>!backpack -reload_db</code><br> | ||
+ | |||
+ | Reloads the asset database as well as the item database. Used when changes have been made to either such as creating a new item you wish to place in an inventory or loot drop, or adding more item assets. | ||
+ | |||
+ | === Player commands === | ||
+ | Player commands exist, but currently are automated by the button system. Only a handful of commands need to be manually invoked by the player | ||
+ | |||
+ | ==== take ==== | ||
+ | <code>!take <item name></code><br> | ||
+ | |||
+ | Attempts to pick up an item either on the ground, or the currently active pack. If the item exists on the ground as well as the active pack, then it will pick up from the ground first. Note that the take command does not specify a quantity as it takes the whole quantity. | ||
+ | |||
+ | ==== buy ==== | ||
+ | <code>!buy <quantity> <item name> </code><br> | ||
+ | |||
+ | Attempts to purchase the item if a store pack is the currently active pack. If no quantity is available, then it assumes 1. | ||
+ | |||
+ | ==== sell ==== | ||
+ | <code>!sell <quantity> <item name></code><br> | ||
+ | |||
+ | Attempts to sell the item. If the player has multiple inventories it will prompt to select from which inventory. If no quantity is available, then it assumes 1. | ||
== Item Definitions == | == Item Definitions == | ||
Item definitions are the format in which entries of items are parsed into the script. They consist of several parts. | Item definitions are the format in which entries of items are parsed into the script. They consist of several parts. | ||
+ | <!-- | ||
{{syntaxbox top|item_definition|formal=true}} | {{syntaxbox top|item_definition|formal=true}} | ||
{{API parameter|name=quantity|optional=true}} {{API parameter|name=name}};{{API parameter|name=type}} {{API parameter|name=weight|optional=true}} {{API parameter|name=value|optional=true}} {{API parameter|name=description|optional=true}} {{API parameter|name=use|optional=true}} {{API parameter|name=maxcharge|optional=true}} {{API parameter|name=enigma|optional=true}} <br> | {{API parameter|name=quantity|optional=true}} {{API parameter|name=name}};{{API parameter|name=type}} {{API parameter|name=weight|optional=true}} {{API parameter|name=value|optional=true}} {{API parameter|name=description|optional=true}} {{API parameter|name=use|optional=true}} {{API parameter|name=maxcharge|optional=true}} {{API parameter|name=enigma|optional=true}} <br> | ||
Line 32: | Line 116: | ||
{{API parameter|name=quantity|optional=true}} {{token|name}};{{token|type}} {{API parameter|name=optionals|optional=true}} <br> | {{API parameter|name=quantity|optional=true}} {{token|name}};{{token|type}} {{API parameter|name=optionals|optional=true}} <br> | ||
{{API parameter|name=quantity|optional=true}} {{token|name}};{{token|type}}:{{token|subtype}} {{API parameter|name=optionals|optional=true}} <br> | {{API parameter|name=quantity|optional=true}} {{token|name}};{{token|type}}:{{token|subtype}} {{API parameter|name=optionals|optional=true}} <br> | ||
− | |||
<br> | <br> | ||
{{token|name}} {{rarr}} Name of the item, see [[Script:Backpack#name|name]]<br> | {{token|name}} {{rarr}} Name of the item, see [[Script:Backpack#name|name]]<br> | ||
Line 46: | Line 129: | ||
}} | }} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
+ | --> | ||
+ | An Item definition at the bare minimum requires a name, and a type with the remaining optional parameters in any order (excluding subtype which branches from type) separated by at least one white space character. | ||
− | + | '''Examples:'''<br> | |
+ | |||
+ | <code>String of Beads;misc 1cp<br></code> | ||
+ | <code>498 Diamond Dust; misc:cyandust 1gp<br></code> | ||
+ | <code>7 Silver Chalice; treasure:trophy 10pp 5gp 8cp<br></code> | ||
+ | <code>1 +2 Trident; weapon:trident 40pp 8gp 3lbs<br></code> | ||
+ | <code>2 Bolt; weapon:bolt 1gp 0.1lb<br></code> | ||
+ | <code>1 Magic Spoon; weapon 500pp 0.1lb desc:(this magic spoon was once used by a Thulgar the great, a halfling of great renown)<br></code> | ||
+ | <code>7 Greatsword; weapon:greatsword 1pp 5gp 6lbs<br></code> | ||
+ | <code>1 Potion of Invisibility; potion:white 30pp 0.1lb use:( )<br></code> | ||
+ | <code>4 Potion of Cure Moderate Wounds; potion:blue 30pp 0.1lb use:(Heal <nowiki>[[2d8+3]]</nowiki>)<br></code> | ||
+ | <code>1 Wand of Cure Light Wounds[41]; wand 75pp use:((Heal <nowiki>[[1d8+1]]</nowiki>))<br></code> | ||
+ | <code>1 Staff of Life[8];staff 109400gp 5lbs use:(Heal for 1 charge, Raise dead for 5 charges)<br></code> | ||
+ | |||
+ | === 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 <u>first class citizens</u> along with [[Script:Backpack#enigmas|enigma]] names. Names can contain any character including numbers but <b>cannot</b> start with a number else that number will be considered a [[Script:Backpack#quantity|quantity]]. | The name parameter is '''essential''' to the item definition and must be unique for this item. Names of items are ''case insensitive'' and considered <u>first class citizens</u> along with [[Script:Backpack#enigmas|enigma]] names. Names can contain any character including numbers but <b>cannot</b> start with a number else that number will be considered a [[Script:Backpack#quantity|quantity]]. | ||
− | Names have a special suffix case where if it has a suffix of <code>[<number>]</code> | + | Names have a special suffix case where if it has a suffix of <code>[<number>]</code> it can denote charges. In this case the name of the item is everything preceding this suffix. For the example of <code>'Wand of Bless[50]'</code>, <code>'Wand of Bless'</code> is the base item name, and <code>'[50]'</code> is parsed out as the number of [[Script:Backpack#charges|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 <code>'Staff of bolts'</code> and <code>'Staff of bolts[10]'</code> would be seen as the same item; but one definition denotes that the item has charges, and the other does not, <code>'Staff of bolts'</code> is not the same as <code>'Staff of bolts[0]'</code> despite having the same name identifier. For the purposes of [[Script:Backpack#charges|charging]] this item, <code>'Staff of bolts[0]'</code> could be charged and <code>'Staff of bolts'</code> 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. | 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. | ||
Line 58: | Line 157: | ||
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 [[Script:Backpack#enigmas|enigma]] names | 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 [[Script:Backpack#enigmas|enigma]] names | ||
− | + | === type === | |
− | ==== subtype | + | The type parameter is '''essential''' to the [[Script:Backpack#Item_Definitions|item definition]] as it connects the [[Script:Backpack#Item_Definitions|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 <u>only a fixed number of types exist</u>. This can be extended upon by editing backpack_tmp.js, see [[Script:Backpack#Customizing|customizing]] for details. All types are ''case sensitive'' and can only include characters [A-Za-z] plus '-' and '_'. |
− | + | ||
− | + | {| class="wikitable" | |
− | + | |- | |
− | + | ! 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 [[Script:Backpack#Item_Definitions|item definition]] can exist without a valid type, compared to [[Script:Backpack#subtype|subtypes]] which are optional, and enumerable within the [[Script:Backpack#Asset_Database|asset database]]. | ||
+ | |||
+ | Some types are associated with one or more [[Script:Backpack#category|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 [[Script:Backpack#Asset_Database|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 <code>scroll:scroll_ancient</code> we can extract <code>scroll</code> as the type and <code>scroll_ancient</code> as the subtype. <code>scroll:scroll_ancient</code> could refer to a withered image of parchment where as <code>scroll:scroll_empowered</code> could refer to an image of a glowing scroll. There are no naming conventions other than what is a legal [[Script:Backpack#type|type]] name so <code>weapon:greataxe</code> is valid as well. | ||
+ | |||
+ | Types ([[Script:Backpack#type|type]] ''and'' subtype) as presented by this script are used to | ||
+ | |||
+ | '''A.)''' Provide a template for the item<br> | ||
+ | '''B.)''' Allow propagation for item images related to the base type | ||
+ | |||
+ | === quantity === | ||
+ | The quantity of an item is optional to the [[Script:Backpack#Item_Definitions|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 <code>lb</code> or <code>lbs</code>. Valid examples are: | ||
+ | |||
+ | <code>45lbs</code><br> | ||
+ | <code>0.5lb</code><br> | ||
+ | <code>100lb</code><br> | ||
+ | |||
+ | Correct plurality for <code>lb</code> 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: | ||
+ | |||
+ | <code>10gp 2sp 1cp</code><br> | ||
+ | <code>35pp 353gp</code><br> | ||
+ | <code>42098gp 2004sp 350000cp</code><br> | ||
+ | |||
+ | Internally, when the script processes the [[Script:Backpack#Item_Definitions|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 [[Script:Backpack#Item_Definitions|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 [[Script:Backpack#Customizing|customizing]]. | ||
+ | |||
+ | === description === | ||
+ | The description argument is optional, typically containing some textual information regarding the item. It follows the syntax <code>desc:(<text>)</code> where <code><text></code> is anything except parenthesis. Valid examples include: | ||
+ | |||
+ | <code>desc:(This old hat was once worn by haggard the great)</code><br> | ||
+ | <code>desc:(This artifact was one of the 4 shards spread across the continent. It radiates a dim red light around its edges..)</code> | ||
+ | |||
+ | === use === | ||
+ | The use argument is optional, but if defined will configure the item as 'usable'. Then if the item is 'used' it will output the use content that was stored in the use argument. Valid examples are: | ||
+ | |||
+ | <code>use:(Healing <nowiki>[[1d8+1]]</nowiki>)</code><br> | ||
+ | <code>use:( )</code><br> | ||
+ | <code>use:(DC 15 Reflex save or blinded!)</code><br> | ||
+ | |||
+ | 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 [[Script:Backpack#category|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 <code>[<number>]</code> where <code><number></code> is the amount of charges an item has. An item that 'has' charges, in that it contains this ''suffix'', can be [[Script:Backpack#use|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 [[Script:Backpack#use|use]] button specifically asks the number of charges to use. | ||
+ | |||
+ | Depending on the [[Script:Backpack#category|category]] associated with the [[Script:Backpack#type|type]] as defined in the [[Script:Backpack#Asset_Database|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 [[Script:Backpack#Item_Definitions|item definition]] comprising of an <u>enigma name</u> and an <u>enigma description</u>. | ||
+ | |||
+ | <!-- | ||
+ | {{syntaxbox top|enigma|formal=true}} | ||
+ | enigma:({{API parameter|name=enigma name}};{{API parameter|name=enigma description}}) <br> | ||
+ | {{Formal API command| | ||
+ | enigma:({{token|enigma name}};{{token|enigma description}})<br> | ||
+ | <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 | ||
+ | }} | ||
+ | {{syntaxbox end}} | ||
+ | --> | ||
+ | |||
+ | When an item with an enigma is added into a backpack compatible journal, its enigma name is considered a <u>first class citizen</u> for all purposes of any inventory actions (moving, giving, taking, dropping) save for specific actions such as 'use' which require identification. Therefore when one adds an item with an enigma option, they need to place special care as to the chosen enigma name so it does not conflict with other enigma names, as well as existing items. | ||
+ | |||
+ | <code>Longsword;weapon:sword 4lbs 15gp</code><br><br> | ||
+ | is considered to have the ''same'' name identifier as<br><br> | ||
+ | <code>+1 Longsword;weapon:sword 4lbs 2015gp enigma:(Longsword;This sword appears naturally light and cuts through the air with ease)</code><br><br> | ||
+ | |||
+ | Assuming an inventory had a longsword, and this enigma masked +1 Longsword was added to it, the longsword quantity would simply increase as opposed to adding a new masked enigma item of a +1 longsword. This however works well for the case of say identifying yet another potion which an inventory already has many of. | ||
+ | |||
+ | <code>Potion of Cure Light Wounds;potion 0.1lb 50gp use:(Heal <nowiki>[[1d8+1]]</nowiki>)</code><br><br> | ||
+ | <code>Potion of Cure Light Wounds;potion 0.1lb 50gp use:(Heal <nowiki>[[1d8+1]]</nowiki>) enigma:(Murky Vial;This blue vial's liquid swirls with several hues of blue)</code><br><br> | ||
+ | |||
+ | These two item definitions despite having the same name identifier can co-exist in the same inventory due to the property of enigma names. If the enigma is lifted from the Potion, then it would add itself cleanly to the quantity of the known potions. | ||
+ | |||
+ | Enigma items use the enigma template which makes the enigma image a link to a command that identifies the item within the inventory it's in. So if an unidentified ring is on the floor, one could add it to their inventory and identify it there, or identify it on the floor. Extending further, you could give this unknown item to someone else and identify it in their inventory. | ||
+ | |||
+ | One restriction to identifying enigma items is that the linked command will only work for the GM therefore it's assumed that after some RP or skill check, the GM can identify the item. It also adds an air of mystery for items not identified floating around in player inventories, as well as the unveiling when the mask is lifted, all with the click of a button. | ||
+ | |||
+ | Know that after an item has its enigma removed, the item definition will have its enigma argument stripped from it. If one wants to preserve this argument, you can save a copy of the original definition elsewhere. | ||
== Asset Database == | == 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''' | + | The asset database is a journal entry that contains within its '''gmnotes''' section the library of images to be used for [[Script:Backpack#Item_Definitions|'''item definitions''']] through their [[Script:Backpack#type|type]] and [[Script:Backpack#subtype|subtype]] |
The '''asset database''' has a simple format where each line is a single asset entry (blank lines between groups of entries are fine). | 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: | Each asset entry is in either of the following formats: | ||
+ | <!-- | ||
{{syntaxbox top|asset_entry|formal=true}} | {{syntaxbox top|asset_entry|formal=true}} | ||
− | + | {{API parameter|name=type}}:{{API parameter|name=link}} <br> | |
− | + | {{API parameter|name=type}}:{{API parameter|name=subtype}}:{{API parameter|name=link}} <br> | |
{{Formal API command| | {{Formal API command| | ||
{{token|type}}:{{token|subtype}}:{{token|link}}<br> | {{token|type}}:{{token|subtype}}:{{token|link}}<br> | ||
Line 82: | Line 303: | ||
<br> | <br> | ||
{{token|type}} {{rarr}} Existing type in backpack_tmp.js<br> | {{token|type}} {{rarr}} Existing type in backpack_tmp.js<br> | ||
− | {{token|sybtype}} {{rarr}} | + | {{token|sybtype}} {{rarr}} Any valid [[Script:Backpack#subtype|subtype]] name except {{epsilon}} |
{{token|link}} {{rarr}} HTML link to the image source, must start with 'http' case insensitive | {{token|link}} {{rarr}} HTML link to the image source, must start with 'http' case insensitive | ||
}} | }} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
+ | --> | ||
+ | |||
+ | By default, the asset database looks for the handout <u><i>'database_assets'</i></u> from which to scan for asset entries. | ||
+ | |||
+ | === category === | ||
+ | A category is an additional layer of logical classification for an item [[Script:Backpack#type|type]] outside of defining a [[Script:Backpack#Templates|template]] and enumerating [[Script:Backpack#subtype|subtypes]]. They are assigned within the [[Script:Backpack#Asset_Database|asset database]] as a prefix to a listed type of the form: | ||
+ | |||
+ | <code>{category, category}<type>:<link></code><br><br> | ||
+ | or<br><br> | ||
+ | <code>{category}<type>:<subtype>:<link></code><br> | ||
+ | |||
+ | Multiple categories can be attached to a type by separating them with a comma within the braces. | ||
+ | |||
+ | It should be noted that despite the two formats, categories are always applied to the base type, they are never applied to the subtype. In the case <code>{CONSUMABLE}wand:<nowiki>http://i.imgur.com/LGF3DHG.png</nowiki></code> and <code>{CHARGEABLE}wand:pearl:<nowiki>http://i.imgur.com/LGF8DGJF.png</nowiki></code> on separate lines would first associate the <code>CONSUMABLE</code> category with wand, then add the <code>CHARGEABLE</code> category as a side effect of adding the <code>wand:pearl</code> [[Script:Backpack#subtype|subtype]]. | ||
+ | |||
+ | 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: | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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, there is no effect, even at 0 charges. | ||
+ | |- | ||
+ | | 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 == | == Item Database == | ||
− | + | The item database, unlike the asset database, isn't essential to the operation of this script as it simply is a storage area for shorthand notation of item definitions. It's format is exactly the same as any backpack enabled journal except that the item definitions listed here are stored as known items for use in other backpack journals short-hand. | |
+ | |||
+ | For instance, if the item database includes the item definitions: | ||
+ | |||
+ | <code>Apple;food:apple 0.5lb 2cp desc:(A delicious fruit common across all of northern Elandra)<br></code> | ||
+ | <code>Grapple Hook;misc:grapplehook 2.5lbs 25sp desc:(A 4 sided hook idea for scaling the tallest cliffs)<br></code> | ||
+ | <code>50 Arrow;weapon:arrow 0.2lb desc:(A common arrow)<br></code> | ||
+ | |||
+ | Then one could populate other backpack journals with the shorthand <code>*apple;</code> or <code>*GrApplE hOOk;</code> (case insensitive) to add these items. This notation can also used for placing an item, or creating a single item. | ||
+ | |||
+ | A special note about quantity within the item database is that if the short hand notation does not include a quantity, then the 'default' quantity as defined in the item database is used. For the above example item database entries, if one put <code>*arrow;</code> within a backpack inventory, then when that inventory is generated, it'll have 50 arrows, else if <code>*2 arrow;</code> is used, then when generated it'll show 2 arrows. | ||
+ | |||
+ | Another special note about the short hand notation is that it also allows for an enigma option so one could mask common magical items such as: | ||
+ | |||
+ | <code>*2 potion of cure light wounds; enigma:(Sky blue bottle;It swirls with a tad of green mixed in..)</code> | ||
+ | |||
== Customizing == | == Customizing == | ||
− | + | ||
+ | === Templates === | ||
+ | |||
+ | === Design === | ||
+ | |||
+ | === Fields === | ||
+ | |||
== Changelog == | == Changelog == | ||
TODO | TODO | ||
+ | |||
+ | [[Category:Discontinued API Scripts]] |
Latest revision as of 23:37, 22 October 2021
This is an API made in 2015, and isn't any longer in the API one-click install menu |
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.
[edit] 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.
Show pictures and animations describing how to use this script.
[edit] General Use
TODO Describe what defines an inventory pack
[edit] Player Inventory
TODO Describe a player inventory use-case
[edit] Store
TODO Describe a store inventory use-case
[edit] Loot drop
TODO Describe a loot drop / cache use-case
[edit] Commands
Many Backpack commands are automated, but there are a handful that still need to be manually invoked.
[edit] GM commands
[edit] create
!backpack -create <name>
!backpack -create john_inventory
This command creates an inventory given a journal name. If there are multiple journals with the same name, then the first one chronologically it finds will be processed. Note that for the journal to be backpack compatible, it must have an attributed named BACKPACK
with the current value set as true
(case sensitive)
[edit] load
!backpack -load <name>
!backpack -load john_inventory
This command loads an inventory as the 'active' pack. For stores to function, then need to be loaded as the active pack. An unrecommended use for it is for allowing players to use the !take
command for an active pack by say, loading a loot_cache inventory. What's recommended instead is to use the show_active command
[edit] close
!backpack -close
This command closes the active pack if there is any. Use this command to close active stores such that player's can't buy from it.
[edit] show_loot
!backpack -show_loot <name>
!backpack -show_loot loot_b6
This command is the recommended way of producing loot drops. It liquidates any currency stored in the pack and produces pick up prompts to the chat. Note that this command also sets the pack as the active pack so that if you !close the pack, it will no longer be available.
[edit] show
!backpack -loot <name>
!backpack -loot chest_a6_content
This command shows the pack described by the provided pack name. It will display the items to chat formatted, but none of the contents will be takable. Useful if you want to show the contents of a pack to players but not let them take them as using load or show_loot will do.
[edit] show_active
!backpack -show_active
This command shows the currently active pack. Somewhat useful to show a store to the chat window if it is open such that players can use the !buy command. Also useful after using show_loot to show to current contents if players forget.
For the store use-case, what's recommended is to make visible the handout to the store such that players can use the buy button on the journal, and hiding the journal + closing the pack when they leave.
[edit] single
!backpack -single <item definition>
!backpack -single 1 Pearl Necklace;treasure 1500gp 0.1lb desc:(An elaborately crafted necklace made of mother pearl)
Creates a single item on the fly, useful for impromptu treasure that needs to be generated on the fly, note that using short hand notation from the item database will work. Also if no quantity is provided to the item definition, it assumes only 1 quantity of the item exists.
[edit] place
!backpack -place <player display name> <item definition>
!backpack -place 'Ken L.' 1 Pearl Necklace;treasure 1500gp 0.1lb desc:(An elaborately crafted necklace made of mother pearl)
Creates a single item on the fly and places it into a player inventory, similar to the single command. If the player has multiple inventories, it will prompt for which inventory it shall be placed.
[edit] reload_db
!backpack -reload_db
Reloads the asset database as well as the item database. Used when changes have been made to either such as creating a new item you wish to place in an inventory or loot drop, or adding more item assets.
[edit] Player commands
Player commands exist, but currently are automated by the button system. Only a handful of commands need to be manually invoked by the player
[edit] take
!take <item name>
Attempts to pick up an item either on the ground, or the currently active pack. If the item exists on the ground as well as the active pack, then it will pick up from the ground first. Note that the take command does not specify a quantity as it takes the whole quantity.
[edit] buy
!buy <quantity> <item name>
Attempts to purchase the item if a store pack is the currently active pack. If no quantity is available, then it assumes 1.
[edit] sell
!sell <quantity> <item name>
Attempts to sell the item. If the player has multiple inventories it will prompt to select from which inventory. If no quantity is available, then it assumes 1.
[edit] Item Definitions
Item definitions are the format in which entries of items are parsed into the script. They consist of several parts. An Item definition at the bare minimum requires a name, and a type with the remaining optional parameters in any order (excluding subtype which branches from type) separated by at least one white space character.
Examples:
String of Beads;misc 1cp
498 Diamond Dust; misc:cyandust 1gp
7 Silver Chalice; treasure:trophy 10pp 5gp 8cp
1 +2 Trident; weapon:trident 40pp 8gp 3lbs
2 Bolt; weapon:bolt 1gp 0.1lb
1 Magic Spoon; weapon 500pp 0.1lb desc:(this magic spoon was once used by a Thulgar the great, a halfling of great renown)
7 Greatsword; weapon:greatsword 1pp 5gp 6lbs
1 Potion of Invisibility; potion:white 30pp 0.1lb use:( )
4 Potion of Cure Moderate Wounds; potion:blue 30pp 0.1lb use:(Heal [[2d8+3]])
1 Wand of Cure Light Wounds[41]; wand 75pp use:((Heal [[1d8+1]]))
1 Staff of Life[8];staff 109400gp 5lbs use:(Heal for 1 charge, Raise dead for 5 charges)
[edit] 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 A → B 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 A → B 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
[edit] 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.
[edit] 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
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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..)
[edit] use
The use argument is optional, but if defined will configure the item as 'usable'. Then if 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.
[edit] 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.
[edit] 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.
When an item with an enigma is added into a backpack compatible journal, its enigma name is considered a first class citizen for all purposes of any inventory actions (moving, giving, taking, dropping) save for specific actions such as 'use' which require identification. Therefore when one adds an item with an enigma option, they need to place special care as to the chosen enigma name so it does not conflict with other enigma names, as well as existing items.
Longsword;weapon:sword 4lbs 15gp
is considered to have the same name identifier as
+1 Longsword;weapon:sword 4lbs 2015gp enigma:(Longsword;This sword appears naturally light and cuts through the air with ease)
Assuming an inventory had a longsword, and this enigma masked +1 Longsword was added to it, the longsword quantity would simply increase as opposed to adding a new masked enigma item of a +1 longsword. This however works well for the case of say identifying yet another potion which an inventory already has many of.
Potion of Cure Light Wounds;potion 0.1lb 50gp use:(Heal [[1d8+1]])
Potion of Cure Light Wounds;potion 0.1lb 50gp use:(Heal [[1d8+1]]) enigma:(Murky Vial;This blue vial's liquid swirls with several hues of blue)
These two item definitions despite having the same name identifier can co-exist in the same inventory due to the property of enigma names. If the enigma is lifted from the Potion, then it would add itself cleanly to the quantity of the known potions.
Enigma items use the enigma template which makes the enigma image a link to a command that identifies the item within the inventory it's in. So if an unidentified ring is on the floor, one could add it to their inventory and identify it there, or identify it on the floor. Extending further, you could give this unknown item to someone else and identify it in their inventory.
One restriction to identifying enigma items is that the linked command will only work for the GM therefore it's assumed that after some RP or skill check, the GM can identify the item. It also adds an air of mystery for items not identified floating around in player inventories, as well as the unveiling when the mask is lifted, all with the click of a button.
Know that after an item has its enigma removed, the item definition will have its enigma argument stripped from it. If one wants to preserve this argument, you can save a copy of the original definition elsewhere.
[edit] 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:
By default, the asset database looks for the handout 'database_assets' from which to scan for asset entries.
[edit] category
A category is an additional layer of logical classification for an item type outside of defining a template and enumerating subtypes. They are assigned within the asset database as a prefix to a listed type of the form:
{category, category}<type>:<link>
or
{category}<type>:<subtype>:<link>
Multiple categories can be attached to a type by separating them with a comma within the braces.
It should be noted that despite the two formats, categories are always applied to the base type, they are never applied to the subtype. In the case {CONSUMABLE}wand:http://i.imgur.com/LGF3DHG.png
and {CHARGEABLE}wand:pearl:http://i.imgur.com/LGF8DGJF.png
on separate lines would first associate the CONSUMABLE
category with wand, then add the CHARGEABLE
category as a side effect of adding the wand:pearl
subtype.
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, there is no effect, even at 0 charges. |
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.
[edit] Item Database
The item database, unlike the asset database, isn't essential to the operation of this script as it simply is a storage area for shorthand notation of item definitions. It's format is exactly the same as any backpack enabled journal except that the item definitions listed here are stored as known items for use in other backpack journals short-hand.
For instance, if the item database includes the item definitions:
Apple;food:apple 0.5lb 2cp desc:(A delicious fruit common across all of northern Elandra)
Grapple Hook;misc:grapplehook 2.5lbs 25sp desc:(A 4 sided hook idea for scaling the tallest cliffs)
50 Arrow;weapon:arrow 0.2lb desc:(A common arrow)
Then one could populate other backpack journals with the shorthand *apple;
or *GrApplE hOOk;
(case insensitive) to add these items. This notation can also used for placing an item, or creating a single item.
A special note about quantity within the item database is that if the short hand notation does not include a quantity, then the 'default' quantity as defined in the item database is used. For the above example item database entries, if one put *arrow;
within a backpack inventory, then when that inventory is generated, it'll have 50 arrows, else if *2 arrow;
is used, then when generated it'll show 2 arrows.
Another special note about the short hand notation is that it also allows for an enigma option so one could mask common magical items such as:
*2 potion of cure light wounds; enigma:(Sky blue bottle;It swirls with a tad of green mixed in..)
[edit] Customizing
[edit] Templates
[edit] Design
[edit] Fields
[edit] Changelog
TODO