Page Updated:   2023-04-10

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 and Deferring Text (Delayed 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.

Deferring Text (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). Deferrals "hide" the syntax construction from being detected by the parsers (either Roll20 or metascripts), so as they are removed and the message is re-processed during the next loop, those constructions might become detectable again. This gives you a measure of control over when certain constructions are processed.

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

Escaping Text (After the Loop)

At the end of any loop where ZeroFrame did not detect that a metascript took action on the command line nor is there an inline roll waiting to be rolled, ZeroFrame will release the message, allowing it to pass on to the stack of standard mod scripts you have installed (see Using MetaScripts in Non-Script Commands (the SIMPLE Tag), below). At this point, ZeroFrame checks for an {&escape ... } tag. Use this tag with a string of characters to designate that string for removal from the message prior to ZeroFrame releasing the message:

{& escape =}
{& escape =+= }
{& escape ~}

Because this happens after the loop, this can ensure certain constructions will remain in the command line. This can be helpful if you want to wait for further user interaction (like clicking a button) before retrieving certain data or having Roll 20 roll dice, or to establish a point where Roll20 will properly respond to queries and targeting statements (which require a user-generated message).

... @~{target|Target1|token_id} ... {&escape ~} ...

The above uses the tilde (a user-chosen character) to break up the targeting statement to keep it from being detected by Roll20. Then it uses the {&escape...} syntax token to remove that tilde as the message is being released. If the above is part of creating a chat button which should ask for a target, this ensures that the targeting statement survives until the user can click the button.

Advanced Usage

If you are spawning a command line which, itself, will be an mod script command line that requires further escaping (for another command line), you can escape the embedded escape token by using the string chosen in the first escape token:

... {==&escape ~} ... @~{target|token_id} ... {& escape ==} ...

In the above, nothing happens to the targeting statement in the top level macro. However, the escape token removes all == from the surviving message before it is released. This exposes a new escape token to the resulting (subsequent) command line. If that is a part of a mod script command, the message will be processed by the metascripts, and the new escape sequence (a tilde) will be removed from the line before the message is released from that ZeroFrame loop. This finally exposes the targeting statement, letting it survive until the proper (third) command sequence has reached the chat.

Using MetaScripts in Non-Script Commands (the SIMPLE Tag)

Use the {&simple} or {&flat} tag to output the command line, in whatever form results after metascript processing, to the chat window. The two versions, {&simple} and {&flat} are equivalent. If ZeroFrame sees one of these tags at the end of the final pass through the loop, it will stop the message from continuing on to your installed mod scripts and will instead redirect it to chat. That means that you could use one of these tags as a way to test various metascript formations to make sure you are getting back the information you need (or that your command line is in the form you are aiming to create). For example, checking that you are getting a Fetch construction returned to you:

!The value for the top of the token is @(selected.top){&simple}

The Two Kinds of Messages

Remember, metascripts are still mod scripts; they simply operate during the window of time between Roll20 parsing (getting attributes, abilities, macros, inline rolls, and queries) and standard mod scripts. The ability to produce a "simple" (e.g., chat-output) message might make it seem like metascript syntax can be used in normal, chat-bound messages -- and they can: those messages just have to start out as intended for the script moderator (starting with a bang: !). It helps to understand that there are two kinds of general messages: those intended for the chat window, directly, and those intended to be passed to the script stack (or what we call the script moderator).

• Messages that start with a bang do not automatically hit the chat output. Anything that gets output to the chat panel as a result of running one of these lines is the product of a mod script generating the content.

• Messages that do not start with a bang are sent to the chat output after Roll20 parsers examine the line.

While mod scripts can listen for either/both kind of message, most mod scripts require the message to be specifically intended for that script. This is because nothing can stop a standard/simple chat message from hitting the chat output even if a mod script wants to take an action based on something it detected in the command line. ChatSetAttr is a good example of a script that works around this limitation, in that it lets you embed command lines between roll template parts in a standard message. The template still hits the chat window, and since templated messages do not display any of the text that is between the template parts, the ChatSetAttr command is never shown in the message output. Meanwhile, ChatSetAttr works in the background to take additional actions as included in the command line.

In the case of metascripts, the whole idea is that they will alter the message in some way as it passes through them. This ability is fairly well obviated if the original message hits the chat window prior to (and regardless of) anything the metascripts would try to do to it. This is why we say the ZeroFrame {&simple} tag lets you use metascript constructions in a standard, chat-bound message, but in actuality what that requires is that the message start out as a bangsy message, and then include the {&simple} tag. To put a fine point on it, these constructions will NOT work:

The top of the token is at @(selected.top).
The top of the token is at @(selected.top).{&simple}

To make it work, start with a bang and include a {&simple} somewhere in the command line that survives to the end of the last ZeroFrame loop:

!The top of the token is at @(selected.top).{&simple}

Using SIMPLE with a Roll Template

Following the above guidelines for starting messages with a bang to get the metascripts involved, you can use the {&simple} tag to output a roll template message to chat. This way you could utilize all of the Meta Toolbox functionality as needed to arrive at the template syntax you need, then output the message when the meta-work has finished:

!/w gm &{template:default}{{name=Token Info}}{{Top=@(selected.top)}}{{Left=@(selected.left)}}{{Height=@(selected.height)}}{{Width=@(selected.width)}}{&simple}

Stopping or Skipping Processing

Once a metascript (like Fetch, APILogic, etc.) is installed, that script will examine every message to see if there is something for it to do. If, for any reason, you need to bypass metascript processing for a particular message, include a ZeroFrame {&skip} tag in the command line. This will tell ZeroFrame not to let any metascript examine the command line, and to simply release the message as-is.

On a related note, if a message is passed through metascript examination during the ZeroFrame loop, but the result of that processing should result in no message (no message to the chat and no message continuing on to your standard scripts), you can use a ZeroFrame {&stop} tag. This is particular useful with APILogic conditional constructions:

!{&if @(selected.top) > 700}token-mod --set top|-1u{&else} {&stop} {&end}

That command will move a selected token up one grid unit only if the starting value of the token's top property is more than 700. Otherwise, the message is stopped.

The TEMPLATE Tag

If you include a Roll20 &{template:...} tag, the Roll20 parsers immediately consume that syntax and attach a template property to the message. However, using metascripts, we might want to decide on a template message later in the process (sometime during the loop), or we might be deciding between 2 or 3 potential templates depending on information the metascripts retrieve from the game. In this case, ZeroFrame offers a slight alteration on the Roll20 syntax structure: {&template:...}.

Use this anywhere in the command line to have ZeroFrame detect the template you wish to use for the message. The detection of this tag comes at the end of the last pass through the loop, just before the message is released, and the last TEMPLATE tag detected will apply. Again, this is quite helpful with APILogic conditionals:

!{&if @(selected|npc_ac[none]) = none){&template:simple}{{rname=PC Action}}...{&else}{&template:npcaction}{{name=@{selected|token_name}}}...{&end}{&simple}

That command detects whether you have an NPC token selected (by testing the npc_ac Fetch construction with a default value of none), and outputs a different roll template depending on the result.

Managing and Re-Using Rolls

===Getting an Inline Roll's Value You can append .value to any roll or roll marker to have ZeroFrame extract the roll's value right in the line. This is the equivalent of substituting the value of the roll into that position in the command line.

!somescript --attackval|[[1d20+2]].value --altattack|$[[0]].value
    ...becomes...
!somescript --attackval|14 --altattack|14

====Automatic Unpacking Typically, you only need to do this in a situation where the roll will not be unpacked automatically. Automatic unpacking happens for nested inline rolls (see below), for rolls that are output to a simple/flat chat message (see below), as well as in certain meta-script constructions (in an APILogic IF condition, or a MathOps tag, for example). Also, it's good to remember that if you are sending a macro or command line to the API that is intended for another script, there is a good chance that other script knows what it wants to do with inline rolls, already, so if you don't need to actually use the value of the roll, you could just leave it in the command line.

====Roll Availability The Roll20 parsers detect inline rolls, process them, and leave behind roll markers in the command line (things like $0). This happens before each pass of the ZeroFrame loop. Also with each pass of the loop, ZeroFrame evaluates the .value token to look for places where you want to unpack a roll. If a roll is not available at the time that the .value token is detected, the token will be left in the command line (to allow for the referenced inline roll becoming available in a later loop pass) unless ZeroFrame detects that it is finished working with the roll. If ZeroFrame detects there is no more work to do, the unpacking of the .value token returns a 0.

As an example:

!somescript --roll0|[[1d10]] --roll1|[\][\]1d20\]\] --arg|$[[1]].value --arg

In the above command line, the rolls will be indexed as:

$[[0]]  => [[1d10]]
$[[1]]  => [[1d20]]

However, roll $1 isn't available in the initial pass (it is deferred). In that case, knowing that there is another loop coming, ZeroFrame doesn't try to extract the value immediately. After the next loop, the roll is available, so ZeroFrame can extract the value, then.

Here is another example in a templated output with various usages. Note the way this can both re-use rolls (with hover tips) in a simple message, and how it can extract the values from rolls that aren't available until later passes of the loop. Finally, note that the $3 roll does not exist in this command line, so when ZeroFrame goes to release the message, the $3.value construction is replaced with a 0:

!&{template:default}{{name=Roll Proof}}{{Roll0=[[1d20]]}}{{Roll 1=[\][\]2d20\]\]}}{{Roll 2=[\\][\\]3d20\\]\\]}}{{Re-Use 0=$[[0]]}}{{Re-Use 1=$[[1]]}}{{Re-Use 2=$[[2]]}}{{Value 1=$[[1]].value}}{{Value 2=$[[2]].value}}{{Non-Existent 3=$[[3]].value}}{&simple}

===Nesting Inline Rolls As just demonstrated, ZeroFrame takes advantage of its loop to give you the ability to nest your reused inline rolls. We can take this a step further and re-use our rolls in other rolls. For instance, we know that the first inline roll detected by the Roll20 parser can be reused in the command line by using the $0 marker. However, using that marker nested inside another inline roll would break the Roll20 parser and throw an error:

[[ $[[0]]d10 ]]

(this breaks in a normal chat call!)

We can make this sort of usage work with ZeroFrame with one minor change of escaping the outer roll as mentioned above:

[\][\] $[[0]]d10 \]\]

When ZeroFrame sees a nested roll such as this (one roll marker used in another roll), it will automatically extract the roll's value and insert it into the command line in place of the roll marker. You do not need to use a .value structure.

Since the outer roll is dependent on the inner roll's value, we must slow it down by one loop (one deferral). Specifically, we must slow it down so that it only becomes detectable as an inline roll one loop cycle after the nested roll is available. In the above case, we are assuming that the $0 roll is available in the first loop pass, so we only need to slow down the outer roll by one pass to allow ZeroFrame the opportunity to extract the roll value.

Nest multiple levels of inner rolls by using 1-more escape character for each outer wrapping of inline roll structure, as mentioned above in the section Escaping Text (Deferred Processing).

Batching Sub-Commands (Sharing Rolls Across Messages)

The GLOBAL Tag (Declaring Variables)

Logging and Troubleshooting

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