New {&tracker} Tag to Add/Update Token Entry in Turn Tracker (ZeroFrame) Roll20 provides a &{tracker} syntax structure that you can use in an inline roll to use the result of the roll as the initiative value for the currently selected token in the Turn Order. In other words, you can select a token and enter: [[ 1d20 &{tracker} ]] ...into the chat and you will either add that token to the Turn Order or you will update the entry for the token in the Turn Order (if it is already there). In either case, that token's entry in the Turn Order would now bear the result of this roll. This functionality does not require a mod script. That simple functionality does not help in situations where you don't immediately have a selected token. That could be when one script calls another script (for instance, if you use a script like ScriptCards and have it dispatch a call to some other script, or if you use the metascript loop of ZeroFrame), or it could be where you don't immediately know which token should be selected, or it could be where you have too many tokens to select and don't want to go through the process manually. For all of these cases, ZeroFrame now offers a metascript variation: {&tracker} While the tag can take further syntax to customize its behavior, it's easiest to see the difference between the Roll20 and metascript versions if I present it in this simplest form. There are a few requirements for using this tag and obtaining the result you'd expect. Requirement 1: Must Use Deferred Roll This is critical to using this new tag without crashing your sandbox. In any message that gets sent to Roll20 chat, inline rolls are detected by Roll20 before the message comes to the script stack. That means the roll is parsed before ZeroFrame can detect and take action on the {&tracker} tag. Because of this, in a normal roll the {&tracker} tag will, at best,, do nothing... but when using the more complex syntax (discussed, below), it might crash your sandbox with a roll syntax violation. For a fuller discussion of deferred rolls, see the ZeroFrame wiki entry . For now, just understand that deferred rolls are rolls that are hidden from Roll20 parsers until a certain number of metascript loops pass. In order to use the new {&tracker} tag, we'll require at least 1 loop cycle. Here is a simple example of what this might look like: [\][\] 1d20 {&tracker} \]\] How this works is that ZeroFrame, at the end of any metascript loop where meta-work has been done, un-defers rolls by one slash (one deferral), and then checks the command line for the presence of the {&tracker} tag within an inline roll . If it finds that combination, it consumes the {&tracker} tag, rendering the inline roll safe to pass through the Roll20 parsers. You'll notice that I said, "at the end of any metascript loop where meta-work has been done." That is, in fact, our second requirement... Requirement 2: Something Must Trigger the Loop ZeroFrame will only un-defer rolls (and detect the {&tracker} tag) if some meta-work was done in the previous loop. This can be a metascript operation necessary to the message (for instance, using {&select} to select tokens, or using Fetch to return some data from a token or character), or it can be something designed simply to trigger the loop without impacting the message (for instance a {&global} declaration that will not change the text of the message, or a Fetch retrieval of data in a place that won't affect the function of the message -- like between template parts in a template message). Basic Example !Adding @(selected.token_name) to Turn Order with value of [\][\] 1d20 {&tracker} \]\]. {&simple} {&select ?{Enter start of a token name}*} In that example, we wait for the user to enter the start of a token name before we know which token we should enter. Since the result of the query feeds a {&select} statement (a part of SelectManager), and SelectManager runs before Fetch, we could then utilize Fetch constructions to construct the roll, as necessary: !Adding @(selected.token_name) to Turn Order with value of [\][\] 1d20 + @(selected.initiative) {&tracker} \]\]. {&simple} {&select ?{Enter start of a token name}*} Extended Basic Example Using this syntax in conjunction with a forselected construction (SelectManager), you can iterate over tokens and give them individual Turn Order entries, each rolled separately. This example selects all tokens that begin "BobHorde" then iterates over them, rolling a 1d20 as a tracker value: !forselected(^) Adding @^(selected.token_name) at [^\\][^\\] 1d20 {^&tracker} ^\\]^\\] {^&simple} {&select BobHorde*} You can do the same thing without announcing each result in chat, but I added that just as a demonstration that the roll will still process and function. Why does the roll in this case require 2 backslashes (being deferred twice)? Because the initial message goes through the metascript loop before it is caught (at normal script speed) by the forselected handle of SelectManager. During this initial loop, SelectManager selects all tokens beginning "BobHorde". This prompts ZeroFrame to send the initial message through another cycle -- which means one deferral is stripped off. That is the end of the metascript processing for the main message, so then the iterated messages are dispatched, one for each token. For each of these messages, the act of restoring the iterated token to the message as a selected token constitutes the "triggering work" that causes a loop, so the second deferral is removed, and the tracker tag is discovered in a roll. Advanced Syntax The {&tracker} syntax structure can also take a comma separated list of token references. If you supply such a list, the tag will operate on the tokens you reference (if they are found) rather than the selected tokens. {&tracker Bob, Joe, Calamity Mike} Since the {&tracker} syntax is found at the end of the metascript loop, you not only can use Roll20 constructions (such as @{selected|token_id} or @{target|Select Target|token_id} ), you could also use metascript constructions (provided they were present in the command line for the utilized script to have detected and taken action on them). For instance, you could use a Fetch reference to the next token up in the tracker: {&tracker Bob, Joe, @(tracker+1.token_id)} But there is a better way to reference a given entry in the Turn Order. For each of the tokens referenced in the {&tracker} list, you can follow them with information to instruct ZeroFrame which entry to update or how to behave. Counting the option to have no trailing text, there are four options: Bob => default, adds an entry for Bob (if not found in the Turn Order) or updates first existing entry (if found) Bob+ => adds a new turn in the Turn Order for Bob, regardless of how many are there already Bob@13 => will update the first* Turn Order entry for Bob that currently has a value of 13, or create a new one (if one isn't found) Bob#2 => will update the second* Turn Order entry for Bob, or create a new one if Bob doesn't already have 2 * - the order for these constructions is the Turn Order as it stands when the {&tracker} tag is utilized {&tracker Bob+, Joe@16, Cornelius Whitaker#1} That would use the value of the roll where this construction was found to set a new entry for Bob, to update the entry for Joe that is currently at 16 (or create a new entry if that one isn't found), and do the same for the first Cornelius Whitaker entry.
