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

Difference between revisions of "Script:ZeroFrame"

From Roll20 Wiki

Jump to: navigation, search
(Understanding MetaScripts and the ZeroFrame Loop)
Line 23: Line 23:
 
==Understanding MetaScripts and the ZeroFrame Loop==
 
==Understanding MetaScripts and the ZeroFrame Loop==
 
'''[[API:Meta_Scripts|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. '''[[Script:Fetch|Fetch]]''', a metascript, does offer a way to get the top value of a token: <code>@(selected.top)</code> , 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.
 
'''[[API:Meta_Scripts|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. '''[[Script:Fetch|Fetch]]''', a metascript, does offer a way to get the top value of a token: <code>@(selected.top)</code> , 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 <code>!0</code> 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.
 
<noinclude>
 
<noinclude>
  

Revision as of 13:59, 7 April 2023

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.


Meta-Toolbox Examples

Examples using one or more Meta-Toolbox APIs

Other APIs