Revision as of 16:33, 30 November 2021

Page Updated:   2021-11-30

What Are Meta-Scripts?

Meta-scripts are scripts that offer a level of "pre-processing" to other scripts by giving the user ways to change the message before other scripts receive it. To understand what a metascript can do and how they can help, it helps to start with understanding the different message types.

In a Roll20 game, you have simple messages... these are things that you type into the chat input and they hit the chat output pane. They can be plain text or Roll Templates, whispered or public, and they can include Inline Rolls ( [[1d10]] ), character attribute calls ( @{character|attribute} ), or Roll Queries( ?{What?|Option1|Option2} ).

You also have API messages... these are prepended with an exclamation point, and they do not (in and of themselves) hit the chat pane. They can also include inline rolls, sheet calls, or roll queries. At this point it pays to think of the message as a thing -- an object -- with certain describable properties. One property is the text that was entered into the chat input (sometimes called the command line or the message content). These message objects get handed to the scripts you have installed to see if any script needs to take an action. The scripts hand the same message object off, one script to the next. Typically, each script is looking to see if it needs to do anything with the message by the message handle (the part of the command line that immediately follows the exclamation point).

!thehandle --arg1 --arg2

The scripts are processed (usually) in install-order, handing the message over in a chain until there are no more scripts to inspect the message to see if they should take action. For standard scripts (e.g. non metascripts), the destination script designated by the handle is typically the end of the line. You want TokenMod to pick up your call to !token-mod, and you want ChatSetAttr to pick up the call to !setattrs. The message will continue on through the rest of the scripts in the queue; it's just likely that none of them will have anything to do with it.

Until recently, that was the end of the discussion.

Then The Aaron discovered a quirk of script ordering that would let a script shin-kick its way to the front of the chain of scripts waiting to handle the message in order. In other words, no matter if you installed one of these shin-kicking scripts later in your script library, it would still get the message first. That discovery gave birth to metascripts.

Metascripts use the shin-kicking technique to get to the head of the line, but they don't look for a particular handle of their own. They don't aim to be the end-destination of the message. Instead, they are looking for text triggers within the command line that tell them to take particular actions on the message before they hand it off (to the queue of regular scripts waiting to see if they should handle the message). In effect, they offer a universal level of "pre-processing" to other scripts without needing the coding infrastructure duplicated by each individual scripter.

Metascripts can alter the command line of the message, alter other properties of the message, or fire other scripts, all with the goal of getting the message into a particular shape by the time that the intended-destination script would pick it up.

APILogic^(Forum) - can conditionally include/exclude parts of a command line using comparison logic. APILogic

Muler^(Forum) - can store and retrieve variables from mule tables, offering rollable or static access. It can bypass HTML character replacement requirements for roll queries, and with ZeroFrame can operate recursively over new meta-constructions.

Plugger^(Forum) - offers a way to run script commands at meta-speed, making it easy to plug-in small, single-job code snippets or to execute full calls to other scripts. Optionally, Plugger can return some result from the plugged-in code to the command line (see this discussion^(Forum) about converting a range script to a Plugger plugin to return a range modifier).

SelectManager^(Forum) - There is a quirk of Roll20 that when a script sends a chat call to another script (we call this an 'API generated message'), the tabletop's selected tokens are not maintained with the new message. SelectManager returns those to the API generated message. It also allows you to "virtually" select tokens, replacing what is actually selected on the tabletop, or adding to that set. It can also iterate a command on a per-token basis, returning individual information to each token's command line.

Fetch^(Forum) - extends the things that can be returned from tokens, characters, etc., including a default value. It offers the ability to designate a default value in case the thing asked for isn't found, and offers a standardized framework to access a repeating attribute without having to know its position on the character sheet ahead of time. Aside from retrieving information by token or character name, Fetch can also use the selected token, the speaker, or a token from the Turn Tracker.

MathOps^(Forum) - provides an inline math parser, offering more functions than are available in a typical inline roll.

ZeroFrame^(Forum) - brings a script framework to scripts that are built to work with it... allowing the user to loop over their installed metascripts and set the order for an individual pass over the loop or for all passes. For instance, sometimes you might need to run a Fetch construction before you base APILogic off of what you return. Other times, you might need to run the APILogic comparisons before you know what you need to Fetch. ZeroFrame also allows you to defer inline rolls (only resolving them after all required meta-processing has completed), to defer other meta-constructions, and to output a simple message (hitting the chat window) and skipping the waiting queue of API scripts. That ability means you can utilize metascript constructs in what you want to be a normal message. So even though you don't have a destination script in mind, you can still use APILogic to conditionally construct your line, or you can use Muler to return a variable, or you can Fetch a token property that isn't available with the typical Roll20 syntax, or you can use Plugger to get the range between two tokens... and then output that to a roll template in the chat window.

The Meta Script Toolbox^(Forum) thread links to the articles for each of these, or visit the Meta Toolbox wiki entry for links to example posts using metascript solutions.