Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Script:ZeroFrame

From Roll20 Wiki

Revision as of 15:24, 7 April 2023 by Tim R. (Talk | contribs)

Jump to: navigation, search
Main Page: Meta-Toolbox

Contents

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

ZeroFrameConfig.png

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


Meta-Toolbox Examples

Examples using one or more Meta-Toolbox APIs

Other APIs