Revision as of 14:41, 9 June 2021

timmaugh is creator of a number of API library scripts, most which are used for extending or helping other APIs.

API

APIs created by timmaugh

• DiscreteWhisper^(Forum) -- multi-recipient whispers with asides and buttons
• InsertArg^(Forum) -- script preamp, siege engine, menu maker, command line constructor
• Script:HeroRoller -- API for the Hero System 6E game

Meta-Toolbox

Set) The Meta-Toolbox^(Forum)

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. (Meta Script) ZeroFrame^(Forum) 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.

(Meta Script) ZeroFrame^(Forum) API menu, tracking managing other APIs installed

The Meta-Toolbox is broken down into multiple individual APIs, to make their management & learning easier.

• ZeroFrame^(Forum) - one script to control them all
• SelectManager^(Forum) -- preserves Token selection between different APIs
• Muler^(Forum) - get/set variables, static tables
• Fetch^(Forum) - retrieve attributes, repeating attributes, abilities, or token properties
• MathOps^(Forum) - inline math operations and nested formulas
• Plugger^(Forum) - give scripts and plugins zero-order priority
• APILogic -- Gives if/elseif/else processing to other scripts (APILogic thread^(Forum))
• libInline^(Forum) - provides an easy interface for inline rolls, (dependency for Meta-Toolbox)

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.

ZeroFrame

ZeroFrame^(Forum) provides a way to organize, order, and loop over the other meta-scripts in the Meta Toolbox. It can unpack 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(/).

Syntax:

!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

SelectManager

SelectManager^(Forum) 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:

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)

Example:

With a command line like:

!forselected(^) somescript --tgt|@^(selected.token_id)

...what is sent to chat by forselected will be:

!somescript --tgt|@(selected.token_id)

Muler

Muler^(Forum) 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.

{& 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

Example:

!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)

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

@(speaker.Strength.max)

... 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:

@(The President of Burundi.Coffee[default value here])

Syntax:

@(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

MathOps

MathOps^(Forum) 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 sin, cos, random, 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.

Example:

{& math sin(2 * [[1d20]])/360 }
{& math (2+3)/4}
{& math round(sin(90) * pi, 2) / randb(0,4) }

Plugger

Plugger^(Forum) 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:

{& 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

APILogic

Main Page: 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:

!somescript {& if a = a} true stuff {& else} default stuff {& end}

…results in the following reaching the chat:

!somescript true stuff