[Script Update] TokenMod -- An interface to adjusting properties of a token from a macro or the chat area.

Update v0.8.54 - TokenMod now creates a Handout named "Help: TokenMod" and keeps it up to date with the current Help text. (Thanks Patrick!)

If the Handout doesn't exist, it will create it.  Unfortunately, the API has no way to control where the handout is in the folder hierarchy, but once it's there, you can sort it to wherever you like and it will keep using the same one (provided you don't change the name).  By default, it will be viewable by all players and have an icon to help Identify it.  If you want to change the Icon or permissions, it won't overwrite them, provided you don't rename the handout.  It will update the help document whenever a new version starts up.

You can get this version now from my repo, or it will show up in your 1-clicks next week or so.

Github: https://github.com/shdwjk/Roll20API/blob/master/TokenMod/TokenMod.js

Fantastic update!  It’s always been a bit cumbersome to have to fill the chat with a 12-page whisper to look up command syntax. :D

Agree!  I'd always intended to do something about that, this is a great way of handling it and I'm glad Patrick mentioned it in another thread. =D

Now to add this to some of my other scripts...

I can't take credit, as stated in that post, it was advice from KeithCurtis.

I was wondering if the following would be possible with tokenmod:

Having the ability to set the number of a status, would it be possible to then reference that number with tokenmod?

Specifically I'm looking to reference it within a macro, so that as the number decreases (minion count in SWRPG), the macro roll gets adjusted automatically.

Not with TokenMod, but you can when you pair it with RealizeStatusMarkers: https://app.roll20.net/forum/permalink/6614230/

I need to update that to work with Custom Token Markers, but if you're just using the run-of-the-mill Markers, it should work out of the box. 

Valdore said:

I was wondering if the following would be possible with tokenmod:

Having the ability to set the number of a status, would it be possible to then reference that number with tokenmod?

Specifically I'm looking to reference it within a macro, so that as the number decreases (minion count in SWRPG), the macro roll gets adjusted automatically.

The Aaron said:

Not with TokenMod, but you can when you pair it with RealizeStatusMarkers: https://app.roll20.net/forum/permalink/6614230/

I need to update that to work with Custom Token Markers, but if you're just using the run-of-the-mill Markers, it should work out of the box. 

That little Bard Inspiration idea is getting a lot of action!  This is good. 

Just remember Valdore, you're limited from 9 maximum to 1 minimum.  There are no double digits (yet) in token markers, and 0 is the "Off" Value.  You can use two or more markers of the same type and visually see double and triple digits, but this is little use to macros unless they could be concatenated and reassessed as a single value.  We can't really do that on the macro side of things.

Because of the 10- and 12-sided Inspiration Die, I needed my macro to recognize half values and remultiply them on output.  It looked weird, but it worked.  So a 3 on the marker was actually a 6-sided die, and a 6 was a 12-sided die.  Just something to keep in mind.

@TheAaron - what is the programming language used to make APIs called?  I want to see if there is a book out there (...For Dummies, of course) to teach me it.  I said I don't have the patience, but then again, I'd like to be able to help, more than ask for help.

Javascript.  There are MANY books.  I recommend Javascript: The Good Parts by Douglas Crockford.  It's a little older, but it's a good grounding.  There are also many MANY good tutorials online. Javascript for Cats is hilarious and fun.  The Javascript that we use for the API is most closely related to Node.js, as it is event driven and there isn't a DOM to deal with.  And of course, you can ask questions on the Forums.  The are lots of threads out there about it already.  Here's three I have bookmarked:

• https://app.roll20.net/forum/post/6605115/namespaces-novice-seeks-help-exploring-the-revealing-module-pattern
• https://app.roll20.net/forum/post/6584105/creating-an-object-that-holds-specific-character-dot-id-and-character-name/?pagenum=1
• https://app.roll20.net/forum/post/6237754/slug%7D

There are lots more. =D

The Aaron said:

Javascript.  There are MANY books.  I recommend Javascript: The Good Parts by Douglas Crockford.  It's a little older, but it's a good grounding.  There are also many MANY good tutorials online. Javascript for Cats is hilarious and fun.  The Javascript that we use for the API is most closely related to Node.js, as it is event driven and there isn't a DOM to deal with.  And of course, you can ask questions on the Forums.  The are lots of threads out there about it already.  Here's three I have bookmarked:

• https://app.roll20.net/forum/post/6605115/namespaces-novice-seeks-help-exploring-the-revealing-module-pattern
• https://app.roll20.net/forum/post/6584105/creating-an-object-that-holds-specific-character-dot-id-and-character-name/?pagenum=1
• https://app.roll20.net/forum/post/6237754/slug%7D

There are lots more. =D

If that's Javascript - it's seen some serious upgrades since 2002.  It's like a whole new language to me.  I've seen this character - ^ - and - $ (Used heavily in PHP) - used alot, and I don't remember them back then.  In addition, I have no idea about JSON and things like that....  But I'll try to figure it all out ...

UPDATE:
@TheAaron
I ordered that book for $2.92 on Amazon ... lmao
Hopefully I'll be hitting the ground running after it comes in

Wolf Thunderspirit said:

Valdore said:

I was wondering if the following would be possible with tokenmod:

Having the ability to set the number of a status, would it be possible to then reference that number with tokenmod?

Specifically I'm looking to reference it within a macro, so that as the number decreases (minion count in SWRPG), the macro roll gets adjusted automatically.

The Aaron said:

Not with TokenMod, but you can when you pair it with RealizeStatusMarkers: https://app.roll20.net/forum/permalink/6614230/

I need to update that to work with Custom Token Markers, but if you're just using the run-of-the-mill Markers, it should work out of the box. 

That little Bard Inspiration idea is getting a lot of action!  This is good. 

Just remember Valdore, you're limited from 9 maximum to 1 minimum.  There are no double digits (yet) in token markers, and 0 is the "Off" Value.  You can use two or more markers of the same type and visually see double and triple digits, but this is little use to macros unless they could be concatenated and reassessed as a single value.  We can't really do that on the macro side of things.

Because of the 10- and 12-sided Inspiration Die, I needed my macro to recognize half values and remultiply them on output.  It looked weird, but it worked.  So a 3 on the marker was actually a 6-sided die, and a 6 was a 12-sided die.  Just something to keep in mind.

For what I want it for, it's perfect! In SWRPG, the skill rolls change depending on the number of minions left in a group. Using the script that Aaron mentioned means I can just change the value of the status marker for the number of minons left in a group and have the macro auto calculate the roll it needs to make. Plus visual feedback for the players of how many minions left in the group. Not planning on running groups bigger than 3 for usual gameplay, and definitely no bigger than 9 :D

Fyi,

Some feed back for the Tokenmod api  help handout it is curiously missing references on how to use it with custom token markers.

Hmm. Try deleting other handout and restarting the API. If you added the Custom Token Markers after the handout was made, they won't be in there. I'm going to fix that in a future release. 

Deleted , restarted sandbox no change. Deleted, Disabled and re-enabled. Still the same. Set to the latest from One Click. token statues covers everything but how to use the custom markers. I mostly mentioned it to help newer users to token mod :) not a big deal for me as I can hunting in forums to find it but might be nice to have it in a good place. I haven't added any other custom markers I just assumed they would be in the help hand out on how to call them. Note i do not have libtokenmaker installed as I assumed this was already in the script for tokenmod. I recall you mentioning that some where in another forum post. As a test I had a test game that it was not installed in (tokenmod that is) and it created the handout Updating Help Handout to v0.8.54  and its exactly the same as the one in my existing game thats had it for quite while. 

Oh.  If you don't have any Custom Token Markers, none will show up.  The interface is no different for Custom vs Legacy Token (Status) Markers.  When you do have Custom Status Markers, they'll be listed with the Status Markers section:

Ah ok good to know nice!

I ran the TokenMod help command in my Storage game so I got the names of all my Custom Token Markers in a Chat Archive that I could save as a PDF for reference. It helped setting up my 13th Age Glorantha game with a Marketplace Token Markers and Custom Token Markers easy.

I've probably garbled this up after attempting four or five different ways to get my tokens to light up for various actions (torch, light spell, driftglobe, etc), but none of them seem to work with the updated UDL settings turned on. This is the code I'm using for the macro. 

!token-mod {{ --on has_bright_light_vision light_otherplayers emits_bright_light emits_low_light --set light_brightradius|20 light_dimradius|20 aura1_radius|20 aura1_color|42eff5 aura2_radius|40 aura2_color|38ccd1

}}

Anything I've done wrong here? UDL settings for the page are enabled, and the tokens that have darkvision can see just fine, but nothing I set up to toggle on/off light sources with TokenMod are working. Any help is much appreciated. Even using the Help topic's example for a torch doesn't seem to do anything to the tokens.

You've got half UDL Settings and half LDL Settings. Here are the UDL Settings:

Try this:

!token-mod {{ --on has_bright_light_vision light_otherplayers emits_bright_light emits_low_light --set bright_light_distance|20 low_light_distance|20 aura1_radius|20 aura1_color|42eff5 aura2_radius|40 aura2_color|38ccd1 }}

Negative. Still no dice on that either. Copied and pasted just as you have it, and it doesn't do anything. Only if I manually set all their vision do they get to see. I can't seem to get a successful macro to work with the UDL setup. Maybe i'm missing something else, I'm not sure. 

Might have been the "light_otherplayers" setting screwing things up, I missed that when I edited the command.  I just tried this and got the results I expected:

!token-mod {{
  --on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
  --set
    bright_light_distance|20
    low_light_distance|20
    aura1_radius|20
    aura1_color|42eff5
    aura2_radius|40
    aura2_color|38ccd1
}}

Ok, so that set the aura properly, but the token still doesn't emit light, or have the ability to see from their perspective. Other players with nightvision can see the aura, but no light source. 

EDIT --- 

Fixed it. There was a conflict in my page settings. I was using the old Dynamic Light checkmark, not the new one. Must've swapped it last night when I was dealing with this initially. Thanks Aaron !!

Great!

I have an odd issue that I didnt see anyone else have. My code looks right to me and it sorta works but it takes running the macro twice to get it to actually appear correctly. here is my code, it should be setting the token to have sight, and emit bright light at 20ft and dim at 20 and then give the token night vision up to a variable stored on the sheet. The last part works great which is what I thought would have issues, but instead, it only gives the token 20ft of bright light and no dim unless run twice. What is really odd is it looks like it is setting the numbers right, because if I open the token menu all the numbers are there and if I save it then it shows correctly. Is this an error with my code, the API or roll20 itself?

!token-mod {{--on bright_vision emits_bright_light emits_low_light night_vision --set bright_light_distance|20 low_light_distance|20 night_distance |@{selected|darkvision} }}

Hi Casey C.  This issue actually came up on the Roll20 Discord over the weekend.  I've got a fix for it which is published in my repo and will show up in the 1-click tomorrow.  Here's the details from the Discord:

Ah, that looks like a bug. I try to mimic the interface to Tokens with the options to TokenMod.

In the old Lighting User Interface, the dim radius is the distance from the token to where the light starts to dim.  20ft radius light, 10ft start of dim gives you 10ft of bright and 10ft of dim light.

In the new Lighting User Interface, it is the distance beyond the bright radius that the dim light extends. 10ft radius bright light and 10ft radius dim gives you 10ft of bright and 10ft of dim light.

However, on the actual token, the dim radius is stored as the distance from the token to the farthest extent of the dim light.  10ft radius bright light and 10ft radius dim means bright_light_distance is set to 10 and low_light_distance is set to 20.

In order to maintain parity with the User Interface, I have to do the math in the script to set those things.  The bug is that I'm using what's on the token to do the calculation, not what is being set.

I'll fix this in the code and try to have a fix out by Tuesday.  Thanks for tracking this down!

You can get the latest version here: https://github.com/shdwjk/Roll20API/blob/master/TokenMod/TokenMod.js

Or it should just show up tomorrow.

Sweet. glad to know I'm on the cutting edge but others are further ahead getting things fixed up! Thank you!!!! BTW I think I'm using about 7 of your API's they are fantastic!

Sweet. =D

The Aaron,

I'm wondering if TokenMod can change/set the token property "Bar Location" and "Bar Style" under the advance tab of the token(same as the light conditions)?

I've reviewed the ToC and the update notes, and skimmed the code for TokenMod, and i'm not seeing it. Have I just over looked it?

That functionality is not exposed to the API yet. As soon as it is, I'll roll it in. 

I am wondering if there's a way to set a time interval or delay when TokenMod updates properties?

With the new custom status markers, I have begun to use status markers to signal a wider variety of game actions visually on the TT, many of which are momentary (e.g. drinking a potion, the fighter's action surge). So it would be cool to use TokenMod to run through a process of adding some token flair, displaying that flair for an interval of time, then removing the token flair automatically (where you're signaling this cycle of effects with one command).

I suppose there are examples where it makes sense for a particular TokenMod update to remain visible until (say) the end of a player's turn, but mostly I'd like to know if there's a simple way to automate an on/off process like this.

I was literally adding that next along with a move command. =D  Unfortunately the weekend and evenings is when I have to work on scripts and that's pretty much the worst time for the API right now.

initially, it will probably just delay the whole command, but being able to segregate parts for when to run them would be neat.  I'll have to think about how to do that...

The Aaron said:

I was literally adding that next along with a move command. =D 

You are like the GM who has already designed the whole adventure, and now looks only for ways to build suspense. =O

HAHAHHAHA.  Well, many a slip 'twix cup and lip as my dad likes to say.  =D  The proof of the pudding will be in the tasting, once I get some work done on the APIs. =D

Until Aaron works his awesome magic, the delay script might work for now: https://app.roll20.net/forum/post/6533907/script-delay You should be able to use it for most of the things you mentioned in your post.

Chris said:

I am wondering if there's a way to set a time interval or delay when TokenMod updates properties?

With the new custom status markers, I have begun to use status markers to signal a wider variety of game actions visually on the TT, many of which are momentary (e.g. drinking a potion, the fighter's action surge). So it would be cool to use TokenMod to run through a process of adding some token flair, displaying that flair for an interval of time, then removing the token flair automatically (where you're signaling this cycle of effects with one command).

I suppose there are examples where it makes sense for a particular TokenMod update to remain visible until (say) the end of a player's turn, but mostly I'd like to know if there's a simple way to automate an on/off process like this.

Thanks Cindurion - this is a cool solution and would do just the sort of thing I'm after. Unfortunately, the Delay script doesn't seem to work with the current version of TokenMod.

Cindurion said:

Until Aaron works his awesome magic, the delay script might work for now: https://app.roll20.net/forum/post/6533907/script-delay You should be able to use it for most of the things you mentioned in your post.

It does work if you do the hack mentioned in the post where you add 

if (!state.TokenMod_pid)

        state.TokenMod_pid = "API";

    if (msg.playerid !== "API")

        state.TokenMod_pid = msg.playerid;

    else

        msg.playerid = state.TokenMod_pid;  

right after this section:

if('api' !== msg.type ) {

        return;

    }

Though I don't think you can use selected or targeted macros, you have to use a character or token id, like so:

!delay 4 --!token-mod  --set statusmarkers|-back-pain --ids -M7bqo5sniph4chY6eEN

The above macro worked for me using those mods. It's not perfect, but it's something until Aaron works his magic! ^^

Chris said:

Thanks Cindurion - this is a cool solution and would do just the sort of thing I'm after. Unfortunately, the Delay script doesn't seem to work with the current version of TokenMod.

Cindurion said:

Until Aaron works his awesome magic, the delay script might work for now: https://app.roll20.net/forum/post/6533907/script-delay You should be able to use it for most of the things you mentioned in your post.

Is it possible to use pass-through variables from Powercards with Tokenmod? I'm trying to set up an AOE heal for one of my players so he can select the related tokens and it will automatically update everyone's hit points. This is what I'm trying:

!power {{

 --name|Burst Heal

 --!Howmuch|//The priest heals everyone around him for [[ [$Pwr] 1d10+8 ]] points.//

 --api_token-mod| _set bar1|+[^Pwr]

}}

Thanks!

hmmm.  I don't actually know...  I think so?  Probably a better question for the Powercards thread, honestly.  Maybe someone in the community can answer this?

Thanks, I'll do that. :)

I know that if I select a token and just use:

!token-mod --set bar1|+5

it works great on however many tokens I've selected, but I'm stymied using it in the macro. 

Oh, you're going to need to pass the token id in.  I don't know what the syntax is for getting that from Powercards, but something like:

 --api_token-mod| _set bar1|+[^Pwr] _ids [^token_id]

is what you're looking for.

Yes, that did work! I'm doing an AOE heal so I just tossed in a bunch of targets for him to select and if he has less than 6 targets the cleric can just click a target more than once. 

--api_token-mod| _set bar1_value|+[^Pwr] _ids @{target|1|token_id} _ids @{target|2|token_id} _ids @{target|3|token_id} _ids @{target|4|token_id} _ids @{target|5|token_id} _ids @{target|6|token_id}

Thanks, Aaron!

Ah, nice!

First of all: thank you so much for maintaining this API. It has been a life saver for me all the time!

One question/wish: maybe I missed how to do, but there seems to be no possibility to set the bar location and style?! I tried also to work around via setting up a token manually and then by !token-mod --set defaulttoken. But especially this attribute has been ignored. Things like aura are taken (=> --set defaulttoken works), but the bar location (in my case bottom overlapping) and bar style (compact) isn't taken. In the example I changed bar location&style and aura:

Is it planned to extend the token-mod this way?

Thanks in advance!
Bernd

That part of the token interface has not yet been exposed to the API. Aaron (and I, FWIW) constantly lobby for this. I am sure the instant it becomes available. it will find it's way into token mod. The current solution is to do whatever setup you need to do with token mod, but do the actual default token setting, manually.

keithcurtis said:

That part of the token interface has not yet been exposed to the API. Aaron (and I, FWIW) constantly lobby for this. I am sure the instant it becomes available. it will find it's way into token mod. The current solution is to do whatever setup you need to do with token mod, but do the actual default token setting, manually.

Great, thank you! Of course it would also help to extend the functionality of the default game settings section in roll20. The background to my problem is: I wanted to use Out of the Abyss, then set my own game settings. But then applying them in the game only affects the existing tokens, not the default tokens. So everytime I draw a token from the journal it is in a wrong state. My workaround is then to quickly correct this with token-mod.

Bernd S. said:

keithcurtis said:

That part of the token interface has not yet been exposed to the API. Aaron (and I, FWIW) constantly lobby for this. I am sure the instant it becomes available. it will find it's way into token mod. The current solution is to do whatever setup you need to do with token mod, but do the actual default token setting, manually.

Great, thank you! Of course it would also help to extend the functionality of the default game settings section in roll20. The background to my problem is: I wanted to use Out of the Abyss, then set my own game settings. But then applying them in the game only affects the existing tokens, not the default tokens. So everytime I draw a token from the journal it is in a wrong state. My workaround is then to quickly correct this with token-mod.

Is there not a way, in the Game Settings page, to make all tokens appear as you wish though?  I mean, for a workaround until an API can control that?

The Aaron I have a macro set up for when my players cast Faerie Fire (they use it a lot, and to great advantage), and it works great.  It pops a drop down to pick the color (they are picky), set a dim light radius, set an aura of the appropriate color, and add a status marker.  However, I am starting to play with the Updated Dynamic Lighting, and I cannot reproduce the macro.  It seems to have something to do with the query/dropdown, as it does not display the dropdown correctly when I run it and I can make it work correctly without the query and just setting one color.  Any help would be greatly appreciated.  Below is my original macro, and what I have for UDL. 

Original (working) Macro:

!token-mod {{
?{Color|Blue, 
--set
aura1_radius#7.5
aura1_color#0000ff
light_otherplayers#on 
light_radius#7.5
light_dimradius#0
statusmarkers#!aura
|Green,
--set
aura1_radius#7.5
aura1_color#008000
light_otherplayers#on 
light_radius#7.5
light_dimradius#0
statusmarkers#!aura
|Red,
--set 
aura1_radius#7.5
aura1_color#ff0000
light_otherplayers#on 
light_radius#7.5
light_dimradius#0
statusmarkers#!aura
|Violet,
--set 
aura1_radius#7.5
aura1_color#ee82ee
light_otherplayers#on 
light_radius#7.5
light_dimradius#0
statusmarkers#!aura
|End Spell,
--set aura1_radius# 
light_otherplayers#off 
light_radius# 
dimlight_radius# 
statusmarkers#!aura}
}}

UDL (non-working) Macro

!token-mod {{
?{Color|Blue, 
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#0000ff
    statusmarkers#!aura}
|Green,
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#008000
    statusmarkers#!aura}
|Red,
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#ff0000
    statusmarkers#!aura}
|Violet,
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#ee82ee
    statusmarkers#!aura}
|End Spell,
--off
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#
    low_light_distance#
    aura1_radius#
    statusmarkers#!aura}
}}

One color UDL that works.

!token-mod {{
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#7.5
    aura1_radius#7.5
    aura1_color#0000ff
    statusmarkers#!aura
}}

You have a trailing } on all your entries.  Try this:

!token-mod {{
?{Color|Blue, 
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#0000ff
    statusmarkers#!aura
|Green,
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#008000
    statusmarkers#!aura
|Red,
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#ff0000
    statusmarkers#!aura
|Violet,
--on
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#0
    low_light_distance#10
    aura1_radius#10
    aura1_color#ee82ee
    statusmarkers#!aura
|End Spell,
--off
    has_bright_light_vision
    emits_bright_light
    emits_low_light
--set
    bright_light_distance#
    low_light_distance#
    aura1_radius#
    statusmarkers#!aura}
}}