Hey, Damon, you're examples are very close. Let me see if I can shed some light. The bulk of this reply will be explaining/educating how/why the metascripts do what they do. If you want to jump to a working version, see the TL;DR header at the end. Ok, here we go...
The metascripts are still scripts in that they can only operate if the message is pre-pended with an exclamation point (to send it to the API). After that, it's a matter of:
1) managing the order of operations
2) including the syntax tokens that would trigger the metascript you want to use, and then
3) leaving the message in the state that you need in order for the next operation (a regular script or a simple chat message)
If you can break things down into these segments, it does get easier.
Exclamation Point
Having to start with an exclamation point means we can't use the /r notation to trigger a roll. Messages that begin with /r are never sent to the API, so the metascripts never know to do anything with them. In order to use metascripts, we have to start with an exclamation point and use inline roll notation (double brackets) for our rolls. As a by-product, we need to be aware that messages that begin with an exclamation point are never sent to the chat, so we need to have a way to do that part, manually.
Order of Operations
Beyond Roll20's order of ops, you should think about the larger order...
Roll20 Parsing => metascripts => normal scripts
If you have ZeroFrame installed, the first two items in that list become a loop, so that after Roll20 parses the message and metascripts make changes, the message is exposed to the Roll20 parsers again.
|| ||
||: Roll20 Parsing => metascripts :|| => normal scripts
|| ||
The loop operates until no further metascript changes are detected.
The other change with ZeroFrame installed is that the metascripts can be ordered within that portion of the loop. The metascripts would normally operate in the order they were installed, but with ZeroFrame installed, they have a defaulted order. You can alter that order, of course, but the point is that you have to pay attention to the order to know which metascripts will process before others.
Syntax Tokens
Each metascript looks for its own tokens to take actions on the message. For MathOps, that is the {& math} token. ZeroFrame offers an ordering tag ( {&0}), a roll extraction tag (.value), and a tag to output a non-API message ({&simple} or {&flat}). Those last two become important in the next part.
What Comes Next
When the metascripts are finished, the message moves on. If the message is still an API message, it will not hit the chat by default (we can change that -- read on). It will continue to move through the installed scripts, giving each the opportunity to take action. As an example:
!The result of 2+2 is {&math 2+2}When that MathOps token condenses, the resulting command line will be:
!The result of 2+2 is 4
But now that command line moves on to the other scripts you have installed. Standard scripts typically pick up the message based on the opening characters, like !token-mod, !setattr, etc. In our case, no script is going think it should take action based on our new command line. On the other hand, if we were using a MathOps construction in a TokenMod command, this would be exactly what we wanted:
!token-mod --on emits_bright_light --set bright_light_distance#{& math @{selected|level}*2}This time, after Roll20 parsing, MathOps sees the {& math } construction as:
{& math 4*2}(assuming the level of the character is 4)
The final command line, after metascript processing, is:
!token-mod --on emits_bright_light --set bright_light_distance#8
This time when the message moves on, TokenMod will pick up the message and see the 8 that was rendered by MathOps.
In order to output a rendered message to chat, we need to use the {&simple} tag from ZeroFrame. That will release the message to the chat interface rather than letting it continue through the rest of the installed scripts. This is what we have to do if we want to utilize the metascripts, but see the result in the chat (say, in a roll template). Returning to the first example:
!The result of 2+2 is {& math 2+2}{&simple}The {&simple} tag says that after metascripts have finished, send the resulting message content to the chat.
Here's the same thing in a roll template:
!&{template:default}{{name=I Can Do This?}}{{The result of 2+2 is={&math 2+2}}}{&simple}
Advanced Steps
If you want to use MathOps in an inline roll, we have to think through the order of operations again. In the listed example:
[[ {&math (2+3)/4} ]]What happens is that Roll20 parses the message first, but can't process the inline roll with the MathOps construction. We need the MathOps metascript to run BEFORE the inline roll. In this case, we can't let the inline roll be recognized by Roll20 until we are ready. I call this deferring the inline roll, and it involves adding backslashes to the brackets (as well as a closing bracket to each opening bracket -- don't ask, there's a quirk of Roll20 parsing that requires this added character):
[\][\] {&math (2+3)/4} \]\]In a message prepended with an exclamation point (to send it to the API), this formation will go undetected by the Roll20 parsers on the first pass, allowing the MathOps construction to parse out to 1.25. On the second pass of the loop, ZeroFrame will escape the inline roll by one set of backslashes before initiating the Roll20 parsers again. At that time, the inline roll is detected and processed. Remember that if you want to see this roll in your chat (instead of sending on through the rest of the API scripts) you still need to include ZeroFrame's {&simple} tag:
![\][\] {&math (2+3)/4} \]\]{&simple}Taking this to another level, imagine a mechanic where you have a roll composed of a number of d10 and d4. You get your level divided by 5 (rounded down) in d10. You get the remainder (the modulus) in d4. So a level of 6 should be 1d10 + 1d4. A level of 12 should be 2d10 + 2d4. We can get the d10 using Roll20 inline roll syntax:
[[floor(@{selected|level}/5)]]d10... or MathOps syntax:
{& math floor(@{selected|level}/5)}d10And we can get the d4 with MathOps:
{& math @{selected|level}%5}d4Since we have to use MathOps for one of them, we have to defer the inline rolls that depend on the MathOps construction one time to let MathOps parse out. The final version will look like one of these two options:
![\][\] [[floor(@{selected|level}/5)]]d10+{&math @{selected|level}%5}d4 \]\]{&simple}
![\][\] {&math floor(@{selected|level}/5)}d10+{&math @{selected|level}%5}d4 \]\]{&simple}TL;DR
Make sure you start with an exclamation point to trigger the metascripts. Make sure you include {&simple} somewhere in the message if you want it to hit chat (instead of continuing on to another script). Make sure that if you need an inline roll (which you sometimes don't need/want if you can do it in MathOps) you use inline roll notation, and defer your roll if it would rely on MathOps, giving MathOps time to parse itself out of the way.
REQUIRED SCRIPTS: ZeroFrame and MathOps
