Revision as of 16:12, 7 April 2023

Page Updated:   2023-04-07

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 - Thread 1^(Forum)
• ZeroFrame - Thread 2^(Forum)
• ZeroFrame - Batching Operations^(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
{& escape ...}         =>    characters to be removed only as the message leaves the metascript loop
{& global ([term]def)} =>    term definition for text replacement (every loop pass)

Understanding MetaScripts and the ZeroFrame Loop

MetaScripts are scripts that operate on the message object prior to the message reaching the intended destination script. For instance, if you wanted to reference the top value of a token within the text of a command line intended for another script, Roll20 does not offer a built-in syntax structure to retrieve that value. That is, there is no @{selected|top} construction you could use in your command line to reference that value. Fetch, a metascript, does offer a way to get the top value of a token: @(selected.top) , and since it is a metascript, it will return that information to the command line of the intended recipient script before that script examines the command line to determine what it needs to do.

MetaScripts, for all that they register to see the message before standard scripts, would still operate in a linear fashion in the order you install them. So if you installed Fetch before Muler, you could use Fetch to help determine which muled-variable you needed, but you couldn't use a muled-variable to help you determine which property you should fetch. This is where the ZeroFrame loop helps. ZeroFrame organizes all of the metascripts into a particular order and then repeatedly loops through them until there is no more meta-work to do: so long as one of the installed metascripts makes a change to the command line (or an inline roll is detected), ZeroFrame will run another pass through the loop.

The Loop Order

The default loop order is established to account for the vast majority of use-cases (though it can be changed). You can see your current order by running !0 from the chat input. This will show all of the installed metascripts along with their priority. Lower numbers will have a greater priority (e.g., they will run first) in the loop.

Setting Default Order (Permanent)

To change the order (permanently, so that all future calls will follow a new order), use an explicit call to ZeroFrame, setting the value for the priority of any script that requires it:

!0 sm|23 set|60

You can refer to the script by any of the shorthand references listed under the script name in the above config panel. For instance, you can affect APILogic by referring to apilogic, apil, or logic. Separate scripts by spaces, and separate the script from its intended priority with a pipe. The above example would give SelectManager a priority of 23, and the get portion of Muler a priority of 60.

Setting Default Order (Temporary)

If you have a default order of the metascripts that answers most of your needs, you may still encounter a case where you have to operate under a different order for a given call. For those specific calls, ZeroFrame also gives you an inline tag to order the scripts. The tag will only affect the command line into which they are placed, and will not affect your default order:

{& 0 get sm}

The above would load the get portion of Muler before SelectManager handled restoring selected tokens. The scripts that are included in the tag get hauled to the front of the loop order. Those scripts not mentioned are then added to the loop in their default order as it stands when the call is made.

DEFAULT ORDER            :    sm get fetch math eval set apil
INLINE TAG               :    {& math get sm }
ACTUAL TEMPORARY ORDER   :    math get sm fetch eval set apil

Setting Temporary Order and the Loop

ZeroFrame will look for the ordering tag at every pass of the loop, so if necessary you can fine-tune the loop order from one pass over the loop to the next. Note, if you do not change the loop order, it will remain whatever it was last set to (default or temporary).

Escaping Text (Deferred Processing)

You can use escape characters to break up text formations (such as Roll20 structures or metascript syntax) so that they do not process before you are ready. ZeroFrame offers two ways to do this: one as each loop passes, and one as the message is exiting the loop and proceeding on to its destination. Provided you build your command line properly, the escaping characters are gone before the message is released to other scripts.

Loop Deferral

To defer text during a loop pass, use the backslash ( \ ) character to escape the text. For instance, this backslash breaks up a Fetch construction: @\(Bob.top). One level of deferral is removed at the end of each pass of the ZeroFrame loop, so to defer a syntax structure for two loops, use two backslashes: @\\(Bob.top).

For inline rolls, use a single closing bracket after the escaping slashes for each opening bracket, and a simple backslash to escape closing brackets: [\][\]@(Bob.top)d10 \]\].

The above will roll a number of d10 equal to the top property of the Bob token. Since inline rolls are resolved before the message is handed off to the installed mod scripts, and since we can't retrieve the top value of the token until the message is already with the mod scripts, we have to disguise the roll. On the first pass of the ZeroFrame loop, Fetch will retrieve the value. At the end of the first pass, one level of deferral characters is removed. This exposes the roll to be detected as the second pass of the ZeroFrame loop begins.

You only need one deferral bracket no matter how many loops you are deferring for (that is, only one closing bracket no matter the number of backslashes): [\\\][\\\]@\\(Bob.top)d10\\\]\\\].

The example can get much more complicated as you use other Meta Toolbox scripts in the same formation:

[\][\] {& math get.Bob.AttackMods.1d10.value * 2}d10 \]\]

There, the 1d10 is initially rolled, then the value is compared to a Mule called AttackMods (see the Muler wiki entry), then passed to a math operation where that is multiplied by 2 (see the MathOps wiki entry), before finally being used as the number of d10 to roll in the second pass. Since muler-get operations occur in the loop before MathOps operations, the math construction does not need to be deferred. At the end of the first pass, the math has reduced down to a number, and we are left with valid roll syntax. As that loop finishes, ZeroFrame removes one level of deferral, and the inline roll becomes exposed to the Roll20 parsers.

Remember, one level of escaping is removed at the end of each pass of the loop, so something requiring deferral until the second pass of the loop would have two escape characters. This is how you would control the default order of the metascripts for a particular pass (and subsequent passes). This example shows how to set the default order for the third pass of the loop: {\\& 0 get sm}

Note that there must be at least one indication that the loop should continue in order for a further loop pass to be initiated and a further level of escape characters to be removed. This is generally accomplished by having some modification to the command line (via one of the registered meta-scripts), or by the detection of an inline roll after the escape characters have been removed at the end of the loop pass. (The loop runs until it finds, in a single pass, no changes from any of the registered scripts and no new inline rolls detected after un-escaping the line.)

Meta-Toolbox 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

Other APIs

• ChatSetAttr
• ScriptCards
• TokenMod