TL;DR: These macros increment and decrement clock tokens using TokenMod and another bit of script here. The macros are at the bottom of this post. Note: these macros are designed for clock tokens. They alter the values of Bar 2 and Bar 3. You don't want
to run it on a character token where those bars hold say, hit points or other critical information. It's just for clocks. I have been making progress clock tokens for my campaign; they are integral to Blades in the Dark and other PBTA games, and I find them useful in 5e as well — they give a sense of urgency to an encounter. These are clocks that the game master ticks up or down as an event becomes more imminent. Examples would be clocks named "The Police Arrive," or "Lady S. Deduces Your Identity."
Multi-sided tokens work very well for clocks, with a few limitations: The “Choose Side” context menu can be a little cumbersome if you have a large number of sides. Some “tick up” and “tick down” buttons would be better. The literal “side number” of a clock may not correspond to its displayed side — for instance, if your token has a “zero” side, which progress clocks typically do. If you want to operate on the token's number of sides, you could e.g. manually enter the current side number value and the total number of sides value into the token’s bars, but it’s possible for this value to become desynchronized from the actual values. It’s nice to have a visual representation that the clock is changing so the players notice, and with clock “ticks” that change can be quite subtle. I wanted to be able to output a record of the state of the clock to the chat as it was updated.
Using the invaluable TokenMod (available in the Roll20 API Script Library ) and some additional code from our resident wizard The Aaron, I was able to generate some macros that address all these issues. Here are the steps to duplicate my process:
On the Campaign Details page, under Settings > Roll20 API Script Library, install TokenMod from the pull-down list. This script does many wonderful things — we want it for its abilities to (1) programmatically change the displayed side of a multi-sided token, and (2) to write values into the bars of that token.
Also add a new script (I named it ClockSides) and paste in the code from this forum page. This code adds the ability to get two values from a token: (1) its current side and (2) its total number of sides.
Inside your game editor, create a multi-sided token as a rollable table ( here’s how ) with your own images, or grab some free clock images here , or find some clocks on the Marketplace already set up as multi-sided tokens.
These macros have some features specific to clocks (though they'll work on any multi-sided token), so my approach is to create a character sheet for each clock, attach the tokens to those sheets, and then add the macros to that sheet. The only purpose of these character sheets is to add macros directly to each clock, rather than have them appear when any old token is selected. These macros will also work if you simply add them to the game’s Collection tab under Macros , and that option is definitely less work.
For my tabletop purposes, I tweak a couple of Token Settings for these clocks. I usually give them a name and turn on Nameplate so it’s clear what the clock is counting, and I make sure that General > Player Permissions > See is turned on so all the players can view that nameplate.
I create three macros: one to increment the clock, one to decrement the clock, and one to reset the clock to its “zero” state. Note that the “zero” state for different clocks may vary, e.g. a clock that counts to 12 and then wraps around to 0 would have a “zero” side of 1 (the first image is the zero side) and a clock that counts from -3 to 3 would have a “zero” side of 4 (the fourth image is the zero side). The simpler implementation is to ignore the reset macro and just have “add one” and “subtract one” buttons. This will provide the majority of the functionality.
Macro: Increment the clock [Raw text of 3 macros at the end of this post. Here, lines are numbered for explanation.] 1 /fx nova-frost @{selected|token_id} @{selected|token_id} 2 !token-mod --set currentside|?+1 3 !set-side-number-in-bar 2 3 4 !token-mod {{ 5 --set bar3_value|-1 6 --report all|"⏱ The clock **@{selected|token_name}** was incremented to {bar2_value} of {bar3_value}" 7 }} Line 1: Call /fx in order to highlight the selected token as it is being updated. Change this to whatever effect you think is nice , or remove this line for no effect at all. Line 2: Currentside (from the new script we added) gets the value of the currently-displayed side and passes it to TokenMod. TokenMod then sets the displayed side to +1, thereby changing the token’s displayed image to the next one in the sequence of images. The "?" tells TokenMod to check that the new value is a valid side for the selected token, preventing it from counting down below 1 or up beyond the number of sides for that token. Line 3: TokenMod then puts currentside and numberofsides (total number of sides for that token) into Bar 2 and Bar 3 for that token. The reason for this is so that we can easily perform operations on those values later. The reason they are in different bars (and not in, say Bar 1 and Bar 1 Max) is to make sure a graphical bar does not display on the token. The token itself is our status indicator — we don’t want a redundant bar showing the same information. Line 4: Call TokenMod, and… Line 5: Tell TokenMod to subtract 1 from the value in Bar 3. Bar 3 holds numberofsides , and because we have a “zero” side, that value will be one more than what we think of as the number of sides. For a simple countup clock, subtracting 1 solves that offset problem. Line 6: Tell TokenMod to report the result to the chat. If the clock token has been named, it will get the name and include it in the chat output. It will also report currentside and numberofsides . The format in the chat is: ⏱ The clock clockname was incremented to currentside of numberofsides . To remove the chat output, delete Line 6. To change the format, edit the portion between the double quotes. The double asterisks are there to bold the clock name in the chat. Line 7: End TokenMod call And that's it! Decrementing the clock is basically the same, with changes to lines 2 and 6 to decrease instead of increase the count.
2 !token-mod --set currentside|? -1 6 --report all|"⏱ The clock **@{selected|token_name}** was decremented to {bar2_value} of {bar3_value}" }} So, here are the macros: Decrement the count by 1 (I name this macro "-") /fx nova-frost @{selected|token_id} @{selected|token_id} !token-mod --set currentside|?-1 !set-side-number-in-bar 2 3 !token-mod {{ --set bar3_value|-1 --report all|"⏱ The clock **@{selected|token_name}** was decremented to {bar2_value} of {bar3_value}" }} Increment the count by 1 (I name this macro "+") /fx nova-frost @{selected|token_id} @{selected|token_id} !token-mod --set currentside|?+1 !set-side-number-in-bar 2 3 !token-mod {{ --set bar3_value|-1 --report all|"⏱ The clock **@{selected|token_name}** was incremented to {bar2_value} of {bar3_value}" }} Reset the count (I name this macro "Reset") /fx nova-frost @{selected|token_id} @{selected|token_id} !token-mod --set currentside|0 !set-side-number-in-bar 2 3 !token-mod {{ --set bar3_value|-1 --report all|"⏱ The clock **@{selected|token_name}** was reset to {bar2_value} of {bar3_value}" }} Name the clock Asks for user to input a name for the selected token, turns on Nameplate, and allows players to "See" the name. !token-mod --set name|"?{Clock name|Clock}" --on showname showplayers_name
