Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Advertisement Create a free account

[Meta Script] Fetch - retrieve attributes, repeating attributes, abilities, or token properties

1618937496

Edited 1620074520
timmaugh
Pro
API Scripter
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[0]) => default value if Strength doesn't exist @(Bob.Strength.max[0]) => 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[0]) 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.
1618937506

Edited 1619623801
timmaugh
Pro
API Scripter
Updates and Releases v1.0.0 - Initial release v.1.0.1 - Minor bug/typo fix
1618937513
timmaugh
Pro
API Scripter
Advanced Usage and Tricks
This is working perfectly so far where {& define} had stopped working =D I noticed {&simple} still works with this, too, which is very convenient.
1618971593

Edited 1618971883
timmaugh
Pro
API Scripter
Fantastic! I'm glad it's working for you! And, yes... {&simple} still works, it's just a part of the ZeroFrame script, now, so that it's detected after all looping is complete. Also, {& flat} is another syntax token that does the same thing, should that make more sense to some people. EDIT: the good thing about the Fetch script compared to the older version of definitions in APILogic is that now you're not limited to defining the term first so that it is detected. You can drop this construction anywhere in your command line and have it be detected, parsed, and processed. You can still use a define tag, of course... but you don't have to.
1619409676
timmaugh
Pro
API Scripter
Version 1.0.1 Released FIXED : Minor bug around retrieving a value from a token when specifying the token id (instead of "selected").
1620082298

Edited 1620418341
timmaugh
Pro
API Scripter
Version 1.0.2 Released May 3, 2021 ADDED : Macro retrieval FIXED : Decoding of GM Notes field retrieval ADDED : New retrieval properties for the recognizable names of items stored as IDs (ie, getting the name of the character represented by the ID stored in the represents property. Update Notes Macro Retrieval Use the formation #(macroname) to get a macro's action text into your current command line. This allows for late retrieval of the macro, preventing Roll20 from running it before you are ready. For instance, you can do a roll query to retrieve only the macro you want: !?{What macro do you want to retrieve?|Tacos,#(Tacos)|Not Tacos,#(NotTacos)|Cake,#(Cake)|Death,#(Death)} This particular usage was discussed in this post . Name Retrieval Token Properties The following properties were added as ways to return the name of the item stored as an ID with the token. NEW PROPERTY REFERENCES page page_name the name of the page referenced by the token's pageid property bar1_name name1 The name of the attribute linked to bar1 bar2_name name2 The name of the attribute linked to bar2 bar3_name name3 The name of the attribute linked to bar3 represents_name reps_name The name of the character this token represents token_controlledby_names token_cby_names A comma separated list of the names of the players who are listed on the token as controlling players. Note: tokens that represent characters have their access list controlled at the character level (see new properties for characters, below) As an example, this would retrieve the name of the character represented by a token, and use the term "Unlinked" if the token is not set to represent anyone: @(selected.reps_name[Unlinked]) Character Properties The following properties were added as ways to return the name of the item stored as an ID with the character. NEW PROPERTY REFERENCES character_controlledby_name character_cby_name char_controlledby_name char_cby_name A comma separated list of the names of the players who are listed on the character as controlling players. As an example, this would retrieve the list of players who could control the character Bob: @(Bob.char_cby_name)
1620418658
timmaugh
Pro
API Scripter
Version 1.0.3 Released May 7, 2021 ADDED : Token data retrieval using token name Update Notes Token Name Pretty straightforward, this one. You can now use the token name for the handle to reference the token: @(Bob the Hirsuite.gmnotes)