Fetch FILE LOCATION: My Personal Repo (until one-click submission) META SCRIPT: This script is a meta-script, and part of the ZeroFrame Meta Toolbox . It can be used on its own, or in conjunction with ZeroFrame and the other meta-toolbox scripts, to modify other scripts' API commands. ABSTRACT: Fetch provides a standardized way to retrieve sheet or token items, including token items not previously exposed to the chat interface (like the current side of a multi-sided token), and repeating elements. In addition, Fetch improves on the standard Roll20 sheet retrieval syntax by allowing you to specify a default value if the item does not exist (instead of erroring to chat). Introduction Fetch uses a standardized syntax to retrieve sheet or token items. These syntax structures are replaced with the retrieved value in the command line before the message is handed off to the intended-recipient script. Syntax Highlights The basic syntax is to use an @ (attribute or token property), % (ability), or * (repeating attribute), followed by the identifying data and default value (if desired) enclosed in parentheses. @(selected.token_id) => token id of selected @(Bob.Strength) => attribute of character @(speaker.Strength) => attribute of current speaking character @(Bob.Strength.max) => max value @(Bob|Strength|max) => pipes or periods work @(Bob.Strength) => default value if Strength doesn't exist @(Bob.Strength.max) => default value if max value of Strength doesn't exist *(Bob.spells.[name="Glitter Storm" prepared].spelllevel) => repeating attribute from spells list where the name sub-attribute
is "Glitter Storm" and the spell is prepared, returns the
spelllevel sub-attribute *(Bob.spells.[name~Glitter prepared].spelllevel.name) => where the name sub-attribute includes the text "Glitter",
return the full name of the spelllevel sub-attribute *(Bob.spells.[name~Storm name!~Glitter].spelllevel.rowid) => where the name sub-attribute includes "Storm" but not "Glitter",
whether or not the spell is prepared; return the rowid *(Bob.spells.[name~Glitter prepared].spelllevel.row$) => where name includes "Glitter" and is prepared, return the row number (i.e., $1) *(Bob.spells.[name~Glitter prepared].spelllevel.name$) => where name includes "Glitter" and is prepared, return the name using the row number *(Bob.spells.[name~Glitter prepared].spelllevel.name[not found]) => including a default value Token Information Token information can be retrieved with the basic syntax: @(token.info) (for this and all future examples, periods and pipes are interchangeable; also, see the section on Default Values to see how to include a default) In the example, "token" can be replaced with either "selected" or the ID of a given token. At this point, token names are not supported. The information that can be returned about a token is far broader than what Roll20 natively supports. Also, Fetch includes different shorthand codes to more quickly reference the data (for instance, you can use "side" instead of "currentside" to get the currentside of a multi-sided token). Consult the following table to find the easiest reference for the item you wish to return. TOKEN PROPERTY REFERENCES _cardid cardid cid _id token_id tid _pageid pageid pid _subtype subtype sub _type token_type adv_fow_view_distance adv_fow_view_distance aura1_color aura1_color aura1 aura1_radius aura1_radius radius1 aura1_square aura1_square square1 aura2_color aura2_color aura2 aura2_radius aura2_radius radius2 aura2_square aura2_square square2 bar1_link bar1_link link1 bar1_max bar1_max max1 bar1_value bar1_value bar1 bar1_current bar2_link bar2_link link2 bar2_max bar2_max max2 bar2_value bar2_value bar2 bar2_current bar3_link bar3_link link3 bar3_max bar3_max max3 bar3_value bar3_value bar3 bar3_current bright_light_distance bright_light_distance controlledby token_controlledby token_cby currentSide currentside side curside dim_light_opacity dim_light_opacity directional_bright_light_center directional_bright_light_center directional_bright_light_total directional_bright_light_total directional_low_light_center directional_low_light_center directional_low_light_total directional_low_light_total emits_bright_light emits_bright_light emits_bright emits_low_light emits_low_light emits_low fliph fliph flipv flipv gmnotes gmnotes has_bright_light_vision has_bright_light_vision has_directional_bright_light has_directional_bright_light has_directional_low_light has_directional_low_light has_limit_field_of_night_vision has_limit_field_of_night_vision has_limit_field_of_vision has_limit_field_of_vision has_night_vision has_night_vision has_nv nv_has height height imgsrc imgsrc isdrawing isdrawing drawing lastmove lastmove layer layer left left light_angle light_angle light_dimradius light_dimradius light_hassight light_hassight light_losangle light_losangle light_multiplier light_multiplier light_otherplayers light_otherplayers light_radius light_radius limit_field_of_night_vision_center limit_field_of_night_vision_center limit_field_of_night_vision_total limit_field_of_night_vision_total limit_field_of_vision_center limit_field_of_vision_center limit_field_of_vision_total limit_field_of_vision_total low_light_distance low_light_distance name token_name night_vision_distance night_vision_distance nv_dist nv_distance night_vision_tint night_vision_tint nv_tint playersedit_aura1 playersedit_aura1 playersedit_aura2 playersedit_aura2 playersedit_bar1 playersedit_bar1 playersedit_bar2 playersedit_bar2 playersedit_bar3 playersedit_bar3 playersedit_name playersedit_name represents represents reps rotation rotation showname showname showplayers_aura1 showplayers_aura1 showplayers_aura2 showplayers_aura2 showplayers_bar1 showplayers_bar1 showplayers_bar2 showplayers_bar2 showplayers_bar3 showplayers_bar3 showplayers_name showplayers_name sides sides statusmarkers statusmarkers markers tint_color tint_color tint top top width width Caveat: Asynchronous Properties Be aware, certain properties like a character's Bio, Notes, and GM Notes are meant to be accessed asynchronously. Although you can return data from these fields with Fetch, you will not get the information you are looking for (i.e., the text of the GM Notes). Instead, you will get the blob identifier from the database back-end. This is not a limitation of Fetch, but a rule imposed by Roll20 for the retrieval of data from these fields. The fields are nevertheless included in Fetch should this rule ever be lifted. Simple Character Information from Token You can use either "selected" or a token ID with this formation to ask for a piece of character information (a property or simple attribute), provided the identified token represents a character to query against. If a character can not be identified, Fetch will return either the specified default value (if one is included), or an empty string. Simple Character Information (Attribute, Ability, Property) In addition to the just mentioned method for returning simple character information using "selected" or a token ID, you can return information from the character using the character id, the character's name, or a near-approximation of the character's name (Fetch will attempt to find the closest match to the name provided). As with Roll20 standard syntax, use an @ for character attributes and a % for abilities. Also use the @ for character properties (listed below). @(Glitterbomb Gleek.InitiativeMod) Character Properties Certain properties belong to the Roll20 character object separate from the character sheet. These can be referenced using the same formation, and one of the references from the table, below. CHARACTER PROPERTY REFERENCES _defaulttoken defaulttoken _id character_id char_id _type character_type char_type archived archived avatar avatar controlledby character_controlledby char_cby character_cby char_controlledby inplayerjournals inplayerjournals name character_name char_name The same caveat applies regarding asynchronous properties for the character as it did for the tokens. These properties are included for completeness and against the possibility that Roll20 will change the restriction to retrieve them in only an asynchronous fashion. Repeating Items Repeating items are different from standard attributes in that they are groups of related sub-attributes. One sub-attribute typically serves as the name of the item as it would appear on the sheet, while others track various measurements and data about that element. To return a given piece of data from a given row element, you often have to supply various parameters which, taken together, let you arrive at a unique repeating item. The basic formation for retrieving information from a repeating item is: *(character.list.[pattern].returned_attr) Where character can be "selected" (referring to the selected token), "speaker" (see below for notes on using the current speaker), a token id, a character id, a character name, or a near-approximation of a character name. list refers to the list housing the repeating elements. Examples might include "spells", "skills", "cantrips", etc. pattern refers to the various sub-attributes which help you narrow down a unique item from the given list. See below for more information. returned_attr refers to the actual sub-attribute whose value you wish to return. For instance, given a spell named "Fireball", perhaps you want to return the sub-attribute "spelllevel". Using the Pattern: Using Information from Sub-Attributes When we're talking about repeating attributes, their naming follows the pattern: repeating_list_rowid_sub_attribute The list might be "spells", and each item in the list will have a unique rowid . All of the sub-attributes of that entry will share that rowid in their name, and then they will continue with their own, differentiated field name (i.e, "spelllevel", "spellpoints", "preparation_time", etc.). Sub-attributes are the only part of the name of a repeating element where you can have an underscore. NOTE: If you have trouble identifying the list or the sub-attributes of a repeating item, I suggest you use the XRay script (part of the InsertArg package), to walk a character sheet and see how each element is constructed. Using these sub-attributes, you can narrow down which item from the list you want to return. For example, Bob the Slayer has a spell list on his character sheet, where every item on that list has sub-attributes of name , spell_level , and prepared . He has the spell “Disintegrating Blast” entered on that list at level 1, 2, and 3. The following call would return the spell_level of the prepared “Disintegrating Blast”: *(Bob the Slayer.spells.[name = "Disintegrating Blast" prepared].spell_level Patterns are like conditional tests of the sub-attributes of a repeating item. All of the conditions must pass validation for the pattern to detect a repeating element (in other words, they must all be true). Also, while each test can be binary (a = b) or unary (a), a unary test (like, “prepared”, just above) implicitly tests for a truthy value from the field beyond just whether it exists. This typically represents an option button or checkbox on a character sheet. Separate tests using a space. If there is space in the text provided as the right hand side of a comparison, enclose it in single quotes, double quotes, or tick marks. Valid binary tests for a sub-attribute are: TEST | DESCRIPTION
a = b | equals a != b | does not equal a > b | is greater than a >= b | is greater than or equal a < b | is less than a <= b | is less than or equal a ~ b | includes a !~ b | does not include See the Syntax Highlights at the top of this post for other examples of using patterns. Special Information About Repeating Items The default return from a repeating item is the value of the requested sub-attribute (if you request the spelllevel of a spell on the repeating list, spells, you will get the value of that attribute). There are, however, other things you can return, such as the row ID of the repeating element (the thing that makes the "Fireball" spell, and all of its sub-attributes, unique on the spells list), the row number of the element (i.e., its current position on the character sheet no matter the order it was originally added), or the name, or name variations using either of these options. To retrieve these other pieces of data, include a period or pipe (use the same character as you use throughout this Fetch structure), then one of the following keywords: KEYWORD | RETURNS | EXAMPLE RETURN
---------+---------------------------------------+--------------------------------------------------- rowid | row id of repeating element | -M1234567890abcdef row$ | sheet position of repeating element | $1 name | name of sub-attribute using rowid | repeating_spells_-M1234567890abcdef_spelllevel name$ | name of sub-attribute using row$ | repeating_spells_$1_spelllevel In use, this would look like: *(Bob the Fabulous.spells.[name="Fireball"].spelllevel.row$) Default Values If Fetch does not find the requested information (either because the source token or character could not be located or the requested item doesn't exist), it will return a zero-length string to the command line in that position. You can provide a default value for it to return, instead, by including the default as the last thing within the parentheses. Enclose the default value in brackets. Everything between the brackets will be considered the default value. @(Bob.UnderwaterMacrame) The above would use "0" as the default value if the character "Bob" could not be found, or if Bob did not have an attribute named "UnderwaterMacrame". Default values can be extremely helpful in math operations, returning either a 0 or a 1 (or some other value, as necessary) to allow processing to continue. This math can be accomplished with either MathOps (if you have that script installed), or with a deferred inline roll with ZeroFrame (again, if you have that script installed). Using Speaker For character items (properties, attributes, repeating attributes, or abilities), you can use "speaker" in the same way that you would use "selected" for a token. In this case, "speaker" will attempt to utilize the character you were speaking as when you sent the message.