Latest revision as of 10:48, 17 March 2022

Page Updated:   2022-03-17

API:Meta-toolbox

(Script 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. 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. Created by Timmaugh

(Meta Script) ZeroFrame API menu, tracking & managing other installed APIs.

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

[edit] Overview

Short description of each:

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

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.

[edit] Scripts

[edit] LibInline

• libInline^(Forum) – provides an easy interface for inline rolls (including roll-tips!)
• Readme
  

Abstract: libInline is a library that simplifies interaction with the 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

[edit] 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(/).

• ZeroFrame - old thread^(Forum)

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

[edit] 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.

• SelectManager^(Forum) older thread

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

Calling tokens by name with TokenMod(normally you can't reference tokens by name):

!token-mod --ids {& select Charlie, Dino} --current-page --move =90|1g

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)

[edit] Fetch

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

• (Meta Script) Fetch (Thread 2)^(Forum)
• Fetch 2.0 Documentation (most up to date)^(Forum)

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

@(selected.imgsrc_short)                                          => The token's source image, leaving off everything after the '?', returning just the workable image URL.
@(selected.tooltip)                                               => Returns the token's tooltip text.
@(selected.show_tooltip)                                          => Returns the toggle status for whether the tooltip should be shown. NOTE: currently the status of this property is not accurately reported to the API when a change is made in the UI. This is a bug that Roll20 will have to address.

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

See Fetch^(Forum) for full documentation.

Example

Calling token_id by name of token in a TokenMod command. (normally you can't reference token_id by name, it only works for character_id):

!token-mod --ids @(Charlie.token_id) --current-page --move =90|1g

General Calls

@(Glitterbomb Gleek.InitiativeMod)         fetches normal attribute
*(Bob the Slayer.spells.[name = "Disintegrating Blast" prepared].spell_level)    fetches the spell_level of a prepared “Disintegrating Blast”-spell from a repeating section
@(Bob.UnderwaterMacrame[0])              fetches attribute, returns zero as default value if teh attribute doesn't exist

[edit] Muler

Muler^(Forum) provides a way to store values on a character sheet in an ability (not attribute), which we call 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 variables are stored on a character sheet, they persists between rolls, game sessions, or even campaigns.

A clever bit about this is that usually people use character attributes to store custom stats, but as Mule store the as Abilities, they can be more easily read, and can't de accidentally deleted by commands that updates character attributes.

• Muler (thread 2)^(Forum)

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

Generic Examples

!somescript --stuff|get.thestuff {& mule ModMule} --tacos
!somescript --mod|get.initMod {& mule Viper.ModMule}

TokenMod + Muler

Sets the value of bar3 on the selected token to the value of the "Stunned"-variable, which is stored in an character ability named "ConditionTable", for a character named "Blue".

!token-mod {{!token-mod {{
--set bar3|get.Stunned {& mule Blue.ConditionTable}
}}

To make the above command work, Create character named Blue, with an character ability named ConditionTable, and save it's content as Stunned=5.

Set Mule variable (no other API)

Stores the value 65 to the Poisoned variable. If the variable doesn't exist in the ConditionTable, it will be created.

!{& mule Blue.ConditionTable} set.Blue.ConditionTable.Poisoned = 65/set

As Muler is a metascript, it's meant to use inside other API calls, but if you just place a ! at the start of a Muler -command, it will perform the action standalone(if it makes sense).

If it's easier to remember, just pretend !mule is a command(doesn't matter what's beteween ! and the Muler syntax), which means !muler {& mule Blue.ConditionTable} set.Blue.ConditionTable.Poisoned = 65/set does exactly the same thing.

[edit] 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) }

• Using MathOps standalone, more details^(Forum)

[edit] 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}

Example:

{& eval risk(--australasia --papuanewguinea|all --build|up) }
!some-other-script --targets|{& eval}withinrange(3 @{selected|token_id} ,){& /eval} --damage|tons

[edit] 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.

• APILogic^(Forum)-thread

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

[edit] Examples

Examples using one or more Meta-Toolbox APIs

• Managing PathFinder Sizes with TokenMod and Metascripts (Muler + TokenMod, extra stuff w/ ZeroFrame, SelectManager, Fetch)
• Using TokenMod to update multiple token tooltips (TokenMod + SelectManager + Fetch + ZeroFrame)
• Macro to read current face of Rollable Token
• Repeating Sections & ChatSetAttr^(Forum)
  • First example: Plugger and SelectManager; Second example: Plugger, Muler, SelectManager, and ZeroFrame.
• Using MathOps standalone, more details^(Forum)
• API Logic and Libinline^(Forum)
• selectmanager example^(Forum)
• ZeroFrame example with ColorEmote^(Forum)
• Table example with Muler & ZeroFrame^(Forum)
• Muler + more example^(Forum)
• Dealer -- Is there a way to deal to a player, even if that player's token is not selected?^(Forum) - Selectmanager example
• Audio Master API^(Forum) - fixes with MathOps & Muler
• Fix "It's a Trap" with selectmanager^(Forum)
• Search Attributes^(Forum) - InsertArg example
• Is there an API that can roll saves for groups then apply a condition to the tokens that failed?^(Forum) - selectmanager example
• TokenMod API - how to select token without clicking it^(Forum) selectmanager fix TokenMod limitation
• default token size fix^(Forum) Muler & Fetch examples
• Multi-step table resolution (Pacesetter system)^(Forum) - Muler with ZeroFrame example
• Creating a HUD^(Forum) - ZeroFrame, Fetch example working with TokenMod
• Retrieving next item in list^(Forum) - Muler, ZeroFrame, and APILogic example
• Retrieving or assigning individual data to/from many tokens with deferred inline rolls^(Forum) - examples of SelectManager's forselected handle using various metascripts with TokenMod

[edit] Other APIs

Popular APIs which can be extended & improved by using parts of the Meta-Toolbox with them:

• ChatSetAttr
• ScriptCards
• TokenMod