The Meta-Toolbox (there is a lot to post, and other threads to populate with information so I can generate links... please be patient over the next few minutes!) ABSTRACT : Meta-scripts intercept a chat message meant for other scripts, allowing you a way to modify the message before the intended-recipient script even gets involved. Since meta-scripts apply to any script call, they effectively provide ways to extend the Roll20 commands and interface. ZeroFrame loops over the toolbox of other scripts, allowing them to operate on the message in turn, altering it to your needs, before releasing it to the intended-recipient script or (if desired) outputting it as a simple chat message. FILE LOCATIONS: ZeroFrame - thread libInline (script dependency for ZeroFrame) SelectManager - thread Muler - thread Fetch - thread MathOps - thread Plugger - thread APILogic - thread For example, these scripts provide a way to retrieve token properties (including properties not usually available to you, like a token's currentside, last move, etc.), sheet items, and even repeating items. You can retrieve things based on the speaker, token id, character id, or proximate names, and all while providing a default value if the thing isn't found. The scripts also provide the ability to perform inline math operations, store and retrieve variables, select tokens, remember selected tokens for downstream API calls (which would otherwise forget that there are tokens selected). The scripts give you IF/ELSE logic branching, inline unpacking of inline rolls, and the ability to plug in your own scriptlets to take advantage of the meta interaction. In other words, there is a LOT of stuff these things can do. Oh, and they work together. You do not need all of these scripts for any individual one to work, but they each offer something different. The scripts in this set can run on their own or as a part of the ZeroFrame loop. With ZeroFrame installed, you can control the order that the operations are executed, and the series of scripts is looped over until they all report that they are finished with the message. This gives incredible flexibility to the way you can retrieve and process information on the fly. ZeroFrame ZeroFrame is the framework that loops over the other meta-scripts. It handles parsing inline rolls and prioritizes the other scripts to run in the order you need them to run. The other scripts (below) register with a particular priority, establishing a default order. You can set a new default order, and/or override your default order for a particular macro. The image above is the the ZeroFrame configuration report, showing the way the scripts have been ordered. Here is a log output showing the steps that were taken as a part of looping over the meta-scripts before the message was eventually released: SelectManager When one script launches another, the second script has no idea about what tokens are selected, creating a real problem if it relies on selected tokens to do its work. In other cases, a script might only be set up to work on one token at a time, creating a tedious manual process of selecting a single token, then running your command. SelectManager helps with all of this by tracking the selected tokens and handing them off to scripts that might have forgotten them. You can prepend an existing script call with "forselected" to iterate that script command over the selected tokens one at a time: !forselected spawn {{ --name|Giant Ape --size|0.5,0.5 --offset|1,0
}} In this release, SelectManager also gains the ability to virtually "select" tokens without having to actually select them on the map, either replacing what is already selected on the map or adding to that set of tokens. {& select Heretic, India, Number of Other Small Countries } This can make it easier to run macros, since you won't always have to locate or select the appropriate tokens if you know them ahead of time, or if you could store them in a Muled variable and select them from a drop down (see Muler, below). Muler (Get/Set) Muler provides variable storage and retrieval, tracking the variables in an ability on a character sheet. Any such ability, called a "mule", can be loaded up for a given message, lending access to the variables within. The application for this goes beyond just storing a piece of data. They can be a way to perform a late-inclusion of command syntax that would otherwise require HTML substitution, track the tokens to be selected for a given macro or situation, or serve as tables where instead of a randomized return (like a typical "rollable table") you need a static return (ie, a crit of this value produces this effect; a character whose Hit Points is this number suffers this specific effect). Numeric ranges are also supported for variable names, so that a variable could be retrieved by anything less than X, or between X and Y, or greater than X, etc. Fetch Fetch offers a unified syntax to expand the amount of things that can be retrieved with simple token or sheet calls. You can retrieve any token property, sheet attribute, or repeating attribute. Token property : @(selected.currentside) Sheet Attribute: @(selected.Strength) Sheet Attribute: @(Bob the Hirsute.Strength.max) Repeating Attr : *(Englebert Slaptiback.spells.[spell_name~Fireball prepared].spell_roll) It also expands the source of the returned sheet item to include "speaker". @(speaker.Strength.max) ... and can return the rowID of a repeating attribute, the row number ($0), or the name of either brand of reference. Not only do these offer the advantage of not breaking the chat message if they don't exist (the way a standard token or sheet item call would), they also give you the ability to substitute in a default value should the one you are looking for not exist: @(The President of Burundi.Coffee[default value here]) MathOps MathOps gives you the ability to perform inline math operations before the recipient script gets the result. Most of the math functions in the javascript Math library are available, including sin, cos, random, etc. Nest parentheses and functions to properly order the equation's processing. It will naturally unpack inline rolls. Combined with Muled variables or Fetched data, this can make for powerful, real-time calculations that don't require development from the individual owners of your various scripts. {& math sin(2 * [[1d20]])/360 } Plugger Plugger is a way to give zero-order, shin-kick-my-way-to-the-head-of-the-line priority to other scripts that would offer some alteration to the message. In other words, plugins. Plugger will run these plugins prior to handing the message off to the recipient script, or in the ZeroFrame loop at the specified priority level. {& eval risk(--australasia --papuanewguinea|all --build|up) } APILogic APILogic gives other scripts IF/ELSE structure and logical evaluation. Depending on how a condition evaluates, the final command line might be altered in one way or another. IF blocks can be nested. APILogic also offers definitions, to save having to retype given information, and lets you name condition sets so that they can be referenced later (even in a later ZeroFrame loop). NOTE: APILogic is the grand-daddy of the meta-scripts, and originally incorporated the loop, mathops, muling, plug-ins, and certain fetch operations. Breaking those components off not only makes for more organized code (and thus quicker development or troubleshooting, as necessary), it allows for more components to be included and for greater control over the way the loop is handled (now in ZeroFrame). All of this to say that if you had APILogic before, almost all of what you could do is still possible -- it's just spread between the appropriate scripts in the Meta-Toolbox. The one thing to note is that the syntax for sheet item retrieval (in a condition or a definition) changed slightly as it rolled into the Fetch script. Consult that script for the new syntax to use to retrieve the item you're looking for. Credit and Thanks Credit for discovering the original trick that makes meta-scripts work must be given to -- who else? -- The Aaron, who has been an invaluable help as I worked through the various problems associated with making something like the Meta-Toolbox work. I need to also thank the other members of the House of Mod (especially Keith, Andreas, and Scott) for their input around design, look, layout, syntax, scope, troubleshooting... suffice it to say, this project would not be what it is without all of their help. Thank you all!
