Roll20 Wiki

{{revdate}}'''{{user profile|5962076|timmaugh}}''' is creator of a number of [[API]] library scripts, most which are used for extending or helping other APIs.


See [[#Examples|Examples]]-section for further examples on using the various scripts made by him. Several examples use more than one at a time.

==API==
APIs created by timmaugh

* '''{{fpl|10307453/ Activity Tracker}}''' --  Track Events Even When You're Not In Your Game
* [[Script:APILogic]]
* '''{{forum|permalink/9430875/ DiscreteWhisper}}''' -- multi-recipient whispers with asides and buttons
* '''{{forum|permalink/9097236/ InsertArg}}''' -- script preamp, siege engine, menu maker, command line constructor
** {{yt.be|cU3BBw9qYOo InsertArg tutorial}} 60min
* [[Script:HeroRoller]] -- API for the Hero System 6E game


__TOC__
==Meta-Toolbox==
'''{{fpl|10005695/(Script Set) The Meta-Toolbox}}'''

'''ABSTRACT:''' Meta-scripts intercept a chat message meant for other scripts, allowing you a way to modify the message before the intended-recipient script even gets involved. '''Since meta-scripts apply to any script call, they effectively provide ways to extend the Roll20 commands and interface.''' {{fpl|10005704/ (Meta Script) ZeroFrame}} loops over the toolbox of other scripts, allowing them to operate on the message in turn, altering it to your needs, before releasing it to the intended-recipient script or (if desired) outputting it as a simple chat message.

[[File:ZeroFrameConfig.png|thumbnail|500px| {{fpl|10005704/ (Meta Script) ZeroFrame}} API menu, tracking managing other APIs installed]]
The Meta-Toolbox is broken down into multiple individual APIs, to make their management & learning easier.
* {{forum|permalink/9770117/ libInline}} - provides an easy interface for [[inline rolls]], (dependency for Meta-Toolbox) 
* '''{{fpl|10495194/ ZeroFrame}}''' - one script to control them all
* '''{{fpl|9817678/ SelectManager}}''' -- preserves Token selection between different APIs
* '''{{fpl|10005710/ Muler}}''' - get/set variables, static tables
* '''{{fpl|10005732/ Fetch}}''' - retrieve attributes, repeating attributes, abilities, or token properties
* '''{{fpl|10005717/ MathOps}}''' - inline math operations and nested formulas
* '''{{fpl|10005724/ Plugger}}''' - give scripts and plugins zero-order priority
* '''[[APILogic]]''' -- Gives <code>if</code>/<code>elseif</code>/<code>else</code> processing to other scripts ({{forum|permalink/9771314/ APILogic thread}})


For example, these scripts provide a way to retrieve token properties (including properties not usually available to you, like a token's currentside, last move, etc.), sheet items, and even repeating items. You can retrieve things based on the speaker, token id, character id, or proximate names, and all while providing a default value if the thing isn't found. The scripts also provide the ability to perform inline math operations, store and retrieve variables, select tokens, remember selected tokens for downstream API calls (which would otherwise forget that there are tokens selected). The scripts give you IF/ELSE logic branching, inline unpacking of inline rolls, and the ability to plug in your own scriptlets to take advantage of the meta interaction.

In other words, there is a LOT of stuff these things can do. Oh, and they work together.

You '''do not''' need all of these scripts for any individual one to work, but they each offer something different. The scripts in this set can run on their own or as a part of the ZeroFrame loop. With ZeroFrame installed, you can control the order that the operations are executed, and the series of scripts is looped over until they all report that they are finished with the message. This gives incredible flexibility to the way you can retrieve and process information on the fly.

===LibInline===
* {{forum|permalink/9770117/ libInline}} – '''provides an easy interface for [[Inline Rolls|inline rolls]] (including roll-tips!)'''
* '''{{api-gh|tree/master/libInline#readme Readme}}'''

'''Abstract:''' libInline is a library that simplifies interaction with the [[Inline Rolls|inline rolls]] object of a message. Using this library, a scripter can easily obtain various datapoints from any inline roll, such as the resulting total, the resulting value (different for a table versus a die roll), various combinations of the resulting dice (all the dice, only the included dice, only the dropped dice, only the critical successes, only the critical failures, etc.), and, most importantly, the resulting rolltip (the tip that pops up when you hover over an inline roll in the chat window). Using this library should free you from having to manually reduce the inline rolls from a message, and should provide the well-formatted roll-tip that was lacking in the common form that reduction would take.

APIs using LibInline:
* [[SmartAoE]]

===ZeroFrame===
{{fpl|10495194/ ZeroFrame}} provides a way to organize, order, and loop over the other meta-scripts in the Meta Toolbox. It can unpack [[Inline|inline rolls]] right in the command line, and lets you defer things like inline roll detection or the syntax token (the structures that would trigger the other meta-scripts) by escaping the text with a backslash(<code>/</code>).

* {{fpl|10005704/ ZeroFrame - old thread}}

'''Syntax:'''

<pre style="overflow:auto;white-space:pre-wrap;">!0 config            =>    displays the ZeroFrame configuration (showing script priorities and handles)
!0 sm|20             =>    sets the priority of SelectManager to 20
!0 logic|75 set|80   =>    multiple meta-scripts can be set in one statement (APILogic to 75, Muler Setting to 80)
{& 0 get sm }        =>    an inline tag for calls to another script changing the default loop order
                           for this call (only), the order will be Muler Get, SelectManager, then the other scripts in default order
.value               =>    inline token to reduce an inline roll to its value (i.e., [[1d10]].value or $[[0]].value )
{& log}              =>    inline tag to output the ZeroFrame log
{& flat}             =>    send the resulting message to the chat (no further API interaction), only detected after the loop finishes
{& stop}             =>    stops further processing (no chat, no API); only detected after the loop finishes</pre>

===SelectManager===
'''{{forum|permalink/9817678/ SelectManager}}''' helps API-generated messages remember what tokens are selected (they would otherwise not know), and lets you send commands to other scripts using the forselected handle. It also lets you "virtually" select tokens to ease interaction with the map.

'''Syntax:'''
<pre style="overflow:auto;white-space:pre-wrap;">No direct call interaction                                     => SM can hand off tokens automatically
!forselected spawn...                                          => iterates a spawn script over the selected tokens
!forselected !spawn...                                         => same, including the exclamation point for downstream script
!forselected(^) spawn @^(selected.token_id)                    => custom escape character for downstream script
{& select Jax, Heretic}                                        => replace selected tokens with comma-separated list
                                                                  (token ID, name,  or near name)
{& inject Jax}                                                 => Add Jax to the selected tokens, if not already included
{& select get.TheParty}                                        => Use a Muled variable "TheParty" to retrieve comma-separated list
                                                                  (requires Muler script)
{& select get.?{Select...|Party,TheParty|Townies,TownNPCs|...  => Utilize Roll20 query to choose the selected token set at run time
                                                                  (example requires Muler script)
BONUS SYNTAX:
!script --@forselected+|token-mod ...                          => forselected as downstream call, initiating downstream call
                                                                  (scriptcards calling forselected calling token-mod)</pre>

{{ex}}

With a command line like:
<pre style="overflow:auto;white-space:pre-wrap;">!forselected(^) somescript --tgt|@^(selected.token_id)</pre>

...what is sent to chat by <code>forselected</code> will be:
<pre style="overflow:auto;white-space:pre-wrap;">!somescript --tgt|@(selected.token_id)</pre>

===Muler===
'''{{fpl|10005710/ Muler}}''' provides a way to store values on a character sheet in an ability (called a Mule). Syntax tokens can be used in any API command line to load a mule, retrieve a variable, and/or set a variable. Since the variable is stored on a character sheet, it persists between rolls, game sessions, or even campaigns.

'''Syntax'''

Drop these syntax tokens into any API command to trigger the associated behavior. They will be filtered out (or replaced with the appropriate data) by the script.
<pre style="overflow:auto;white-space:pre-wrap;">{& mule ModTable}                                => loads the first ModTable mule it finds (from characters you control)
{& mule TableMule.ModTable}                      => loads the ModTable mule from the TableMule character
{& mule Cake Izzard.OrDeath}                     => loads the Cake mule (first found) as well as Izzard's OrDeath mule
get.4                                            => if mules are loaded, attempts to retrieve the variable "4"
get.ModTable.4                                   => gets the variable "4" from the ModTable mule (ModTable must be loaded)
get.TableMule.ModTable.4                         => same, but specifically from the TableMule character
set.Izzard.Cake.Rush = We're all outta cake/set  => sets the "Rush" variable in Izzard's Cake mule to "We're all outta cake"
                                                    note the ending /set to close the variable's value</pre>

{{ex}}
<pre style="overflow:auto;white-space:pre-wrap;">!somescript --stuff|get.thestuff {& mule ModMule} --tacos
!somescript --mod|get.initMod {& mule Viper.ModMule}

===Fetch===
'''{{fpl|10005732/ Fetch}}''' offers a unified syntax to expand the amount of things that can be retrieved with simple token or sheet calls. You can retrieve any token property, sheet attribute, or repeating attribute.
<pre style="overflow:auto;white-space:pre-wrap;">Token property : @(selected.currentside)
Sheet Attribute: @(selected.Strength)
Sheet Attribute: @(Bob the Hirsute.Strength.max)
Repeating Attr : *(Englebert Slaptiback.spells.[spell_name~Fireball prepared].spell_roll)</pre>

It also expands the source of the returned sheet item to include "speaker".

<pre style="overflow:auto;white-space:pre-wrap;">@(speaker.Strength.max)</pre>

... and can return the rowID of a repeating attribute, the row number ($0), or the name of either brand of reference.

Not only do these offer the advantage of not breaking the chat message if they don't exist (the way a standard token or sheet item call would), they also give you the ability to substitute in a default value should the one you are looking for not exist:

<pre style="overflow:auto;white-space:pre-wrap;">@(The President of Burundi.Coffee[default value here])</pre>

'''Syntax:'''
<pre style="overflow:auto;white-space:pre-wrap;">
@(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</pre>

===MathOps===
'''{{fpl|10005717/ MathOps}}''' gives you the ability to perform inline math operations before the recipient script gets the result. Most of the math functions in the JavaScript Math library are available, including <code>sin</code>, <code>cos</code>, <code>random</code>, etc (full list in forum post). Nest parentheses and functions to properly order the equation's processing. It will naturally unpack inline rolls. Combined with Muled variables or Fetched data, this can make for powerful, real-time calculations that don't require development from the individual owners of your various scripts.

{{ex}}
<pre style="overflow:auto;white-space:pre-wrap;">{& math sin(2 * [[1d20]])/360 }
{& math (2+3)/4}
{& math round(sin(90) * pi, 2) / randb(0,4) }</pre>

* {{fpl|10384428/ Using MathOps standalone, more details}} 

===Plugger===
'''{{fpl|10005724/ Plugger}}''' is a way to give zero-order, shin-kick-my-way-to-the-head-of-the-line priority to other scripts that would offer some alteration to the message.

In other words, plugins. Plugger will run these plugins prior to handing the message off to the recipient script, or in the ZeroFrame loop at the specified priority level.

'''Syntax:'''
<pre style="overflow:auto;white-space:pre-wrap;">{& eval}scriptlet(--arg1|val --arg2|val){& /eval}
{{ex}}
<pre style="overflow:auto;white-space:pre-wrap;">{& eval risk(--australasia --papuanewguinea|all --build|up) }
!some-other-script --targets|{& eval}withinrange(3 @{selected|token_id} ,){& /eval} --damage|tons</pre>

===APILogic===
{{main|APILogic}}

'''[[APILogic]]''' introduces logical structures (things like IF, ELSEIF, and ELSE) as well as real-time inline math operations, and variable muling to Roll20 command lines. It can test sets of conditions and, depending on the result, include or exclude parts of the command line that actually reaches the chat processor.

For example, given the statement:
<pre>!somescript {&amp; if a = a} true stuff {&amp; else} default stuff {&amp; end}
</pre>
…results in the following reaching the chat:
<pre>!somescript true stuff
</pre>

==Examples==
Examples using one or more Meta-Toolbox APIs

* {{fpl|10382038/ Repeating Sections & ChatSetAttr}}
** First example: Plugger and SelectManager; Second example: Plugger, Muler, SelectManager, and ZeroFrame.
* {{fpl|10384428/ Using MathOps standalone, more details}}
* {{fpl|10375753/ API Logic and Libinline}}
* {{fpl|10380867/ selectmanager example}}
* {{fpl|10367335/ ZeroFrame example with ColorEmote}}
* {{fpl|10223910/ Table example with Muler & ZeroFrame}}
* {{fpl|10248506/ Muler + more example}}
* {{fpl|10361976/ Dealer -- Is there a way to deal to a player, even if that player's token is not selected?}} - Selectmanager example
* {{fpl|10368622/ Audio Master API}} - fixes with MathOps & Muler
* {{fpl|10343617/ Fix "It's a Trap" with selectmanager}}
* {{fpl|10334672/ Search Attributes}} - InsertArg example
* {{fpl|10337644/ Is there an API that can roll saves for groups then apply a condition to the tokens that failed?}} - selectmanager example
* {{fpl|10325610/ TokenMod API - how to select token without clicking it}} selectmanager fix [[TokenMod]] limitation
* {{fpl|/10316973/ default token size fix}} Muler & Fetch examples
<br>