Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

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

Any chance of adding a Ping option to Tokenmod?  

Something like:

!token-mod --ping --nomove --ids <token-id>

Unless you know of a wrapper function somebody has already written for the ping function.

May 04 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Reporter can do it. It's not in one-click yet, but it can gm- and player-ping and run token-mod commands internally.

Hi everyone. I have a simple request, how do I create a macro using the API that will roll some dice and reduce that amount from the selected token?

I don't want a roll to hit, just this:


1] Select token to recieve the damage by clicking on it

2] Click on the macro and have it take away 2d8 damage from bar 1. 

May 04 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Yup:

!token-mod --set bar1_value|-[[2d8]]!

The - makes the value relative (subtraction instead of setting), and the ! keeps it from going negative.

Thankyou so much! This is what I was looking for. Is there any way to have this damage number show up in the chat log?

May 05 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Yup.  You can use the --report argument:

!token-mod --set bar1_value|-[[2d8]]! --report all|"{name} took {bar1_value:abschange} points of damage."

The help handout has more information:

Report

Experimental
 --report provides feedback about the changes that were made to each token that a command affects. Arguments to the --report command are | separated pairs of Who to tell, and what to tell them, with the following format:

!token-mod --report Who[:Who ...]|Message

You can specify multiple different Who arguments by separating them with a :. Be sure you have no spaces.

Available options for Who
  • player will whisper the report to the player who issued the command.
  • gm will whisper the report to the gm.
  • all will send the report publicly to chat for everyone to see.
  • token will whisper to whomever controls the token.
  • character will whisper to whomever controls the character the token represents.
  • control will whisper to whomever can control the token from either the token or character controlledby list. This is equivalent to specifying token:character.

The Message must be enclosed in quotes if it has spaces in it. The Message can contain any of the properties of the of the token, enclosed in { }, and they will be replaced with the final value of that property. Additionally, each property may have a modifier to select slightly different information:

Available options for Property Modifiers
  • before -- Show the value of the property before a change was applied.
  • change -- Show the change that was applied to the property. (Only works on numeric fields, will result in 0 on things like name or imagsrc.)
  • abschange -- Show the absolute value of the change that was applied to the property. (Only works on numeric fields, will result in 0 on things like name or imagsrc.)

Showing the amount of damage done to a token.

!token-mod {{
  --set
    bar1_value|-[[2d6+8]]
  --report
    all|"{name} takes {bar1_value:abschange} points of damage."
}}

Showing everyone the results of the hit, but only the gm and the controlling players the actual damage and original hit point value.

!token-mod {{
  --set
    bar1_value|-[[2d6+8]]
  --report
    all|"{name} takes a vicious wound leaving them at {bar1_value}hp out of {bar1_max}hp."
    gm:control|"{name} damage: {bar1_value:change}hp, was at {bar1_value:before}hp"
}}

Thanks again! I'm using damage as an abstraction for casualties taken by a large unit of troops. Is there any way I could swap out 'abschange' for 'change' and multiply that number by 10, so that the bar takes let's say 4 damage, but what is displayed on the chat log says 'Unit took 40 casualties'?

May 05 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Hmm.  abschange just drops the sign, so using change you'd get -4 instead of 4.  So, there isn't a way to do math in the output, but since it's a multiple of ten, you can just do:

!token-mod --set bar1_value|-[[2d8]]! --report all|"{name} unit took {bar1_value:abschange}0 casualties."

@The Aaron, I did some more testing last night and can confirm that appending a bar value change with a ! works in v0.8.64 but messes up the command in v0.8.65

Thanks. I aspire to be as helpful as you one day.

May 05 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

@Alastair -- LOL, glad that's working for you. =D

@Persephone -- Thanks for tracking that down!  I'll take a look at it tonight and try to get a patch out.  I'm sure I just missed something in one of the regexs I use to parse the argument for relative changes.

May 05 (3 years ago)

An acquaintance wrote an API that pings and centers you view based on a tokens name. I do not think he is ready to share it publicly yet. I will ask him again. He calls it Find. So in game I made a menu that has all the characters names, I can select one and it will focus my screen on that character. 


I will ask again about sharing this code. 



Bob 

Will M. said:

Any chance of adding a Ping option to Tokenmod?  

Something like:

!token-mod --ping --nomove --ids <token-id>

Unless you know of a wrapper function somebody has already written for the ping function.




This scriptlet called Find Token has worked really well for me! Even lets you choose whether you want just your own view pinged or all players.

Just wondering: what's the best way via Tokenmod to set darkvision on a token with UDL? Has the "Nocturnal" option been made available to the API?

May 08 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Nocturnal has not yet been exposed to the API.

Hi all,

Is token mod able to access the color of the token bars ?


What I'd love is to be able to have a script that changes the color of HP Bar depending on the Hp %.


Is this achievable through a script or an API that my DM could implement ?


Thanks.

May 09 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

That property does not appear to be available to the API.

May 09 (3 years ago)

Edited May 09 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Hmmm... A script could be written to change the player color (the box next to their name) based on health status. This might be useful for healers to track the health of the party, but it would have some limitations:

1) it would remove a bit of player agency by taking away their ability to chose their color.

2) you would have to set up a single specific character for each player.

Ok, I've installed TokenMod, but I have no clue where to start! Sooo many options. Could someone point me in the direction of some useful macros to use it with? I'm not completely computer-illiterate but programming is not really my thing, so I could use some help getting started. Thanks a lot!

May 11 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Kind of a pared down summary of the syntax is:

!token-mod {{
  --set
   <THING>|<VALUE>
   <THING>|<VALUE>
}}

Where <THING> is what you want to set, like the bar1_value, and <VALUE> is what you want to set it to or how you want to change it, like -[[2d8]]

By default, it affects the selected tokens, but you can specify them by id with:

--ids @{target|token_id}

or hard coded, or with the character_id.

My go to example is letting players mark something like Hunter's Query:

!token-mod --set statusmarkers|!archery-target --ids @{target|token_id}

That will toggle (because of the !) the archery-target status marker on and off on the target token.  Note that for players to do that, you need to turn on Players can IDS at the bottom of the help:

!token-mod --help

May 11 (3 years ago)
CryptoCartographer
Pro
Marketplace Creator
I'm using TokenMod to change the background image (a large, multisided token on the Map layer) from a chat menu. The chat menu macro and the token-side-selector macros it calls (one for each side) are all located on a dummy character sheet. (I'm actually adjusting two tokens: one is the large full-map background art, and one is an information overlay on the GM layer that corresponds to the background art, but only shows to the GM). The token will not be selected; the idea is to change it without going to the other layer.

Everything works, but each time I make an adjustment to the token (e.g. adding a new "side" image) the id of the token changes and I have to revise a dozen little macros with the new id.

Does anyone have a suggestion for:

  • a way to persistently reference the multi-sided token through deletion and replacement,
  • a programmatic means of targeting the token, or
  • some more clever thing I'm not thinking of.

Thanks!


Chat menu:

/w gm &{template:default} {{name=District Art}} {{=Select District
[Barrowcleft](~Art-Select|District-Barrowcleft)
[Brightstone](~Art-Select|District-Brightstone)
[Charhollow](~Art-Select|District-Charhollow)
[Charterhall](~Art-Select|District-Charterhall)
[Coalridge](~Art-Select|District-Coalridge)
[Crow's Foot](~Art-Select|District-CrowsFoot)
[The Docks](~Art-Select|District-Docks)
[Dunslough](~Art-Select|District-Dunslough)
[Nightmarket](~Art-Select|District-Nightmarket)
[Silkshore](~Art-Select|District-Silkshore)
[Six Towers](~Art-Select|District-SixTowers)
[Whitecrown](~Art-Select|District-Whitecrown)
}}

Typical macro to change token sides:

!token-mod {{
--set currentside|1
--ids --M_PPdCWeM2Zp13y_gzd -M_P5bsJbFV7ZqqCk1j6
}}

May 11 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

If you set the token to represent a character, you can use the character_id to refer to all the tokens that represent that character, and further specify --current-page or --active-pages to only target the tokens on the current page or pages with people on them.

Token IDs are unique to a single created token.  Each time you create a new one, either by dragging in, or copy/pasting, it will have a new id.

May 11 (3 years ago)
CryptoCartographer
Pro
Marketplace Creator

Works great. I thought I had tried that, but I must not have had the token linked correctly. Much easier to maintain! Thanks!

May 12 (3 years ago)

Edited May 12 (3 years ago)


Alryon said:

Ok, I've installed TokenMod, but I have no clue where to start! Sooo many options. Could someone point me in the direction of some useful macros to use it with? I'm not completely computer-illiterate but programming is not really my thing, so I could use some help getting started. Thanks a lot!

For which I use it are the following topics:

  • Set/reset bars (HP values, visibility)
  • Set status markers (I have a drop-down list with status where I set them accordingly)
  • Set height in the name for flying monsters/PCs to indicate how high they are
  • And very important: set sight/lighting of a token. But that works only perfect for me with Legacy Lighting. UDL has too many missing features and bugs currently to use.





Bernd S. said:


Alryon said:

Ok, I've installed TokenMod, but I have no clue where to start! Sooo many options. Could someone point me in the direction of some useful macros to use it with? I'm not completely computer-illiterate but programming is not really my thing, so I could use some help getting started. Thanks a lot!

For which I use it are the following topics:

  • Set/reset bars (HP values, visibility)
  • Set status markers (I have a drop-down list with status where I set them accordingly)
  • Set height in the name for flying monsters/PCs to indicate how high they are
  • And very important: set sight/lighting of a token. But that works only perfect for me with Legacy Lighting. UDL has too many missing features and bugs currently to use.





Adding to your list:


Monster setup. I use the following macro in conjunction with the TokenNameNumber script: 

!token-mod --set represents|"?{Monster}"
!token-mod {{
  --on showname
  --off isdrawing 
  --set
    name|"Creature %%NUMBERED%%"
	 light_hassight#no
    showplayers_name#yes
bar2_link|npc_ac
bar3_link|hp_temp
aura2_color|#980000
defaulttoken
}}
Scenes in Theater of the Mind (keithcurtis's trick)

Damage and healing

Hit dice


May 12 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Lighting and Vision are essential uses.

May 13 (3 years ago)
Richard @ Damery
Pro
API Scripter

I use Token-mod extensively for implementing effects of spells, powers and magic items.  My round management API, RoundMaster, supports effect markers and automatically runs macros for effects optionally when they start, each turn they are in effect, and when they end.  These effects often change the attributes of tokens, including lighting, auras, and most often bar values.  Token-mod is a great piece of code - thanks again to The Aaron for it.

However, I've hit a problem with it in the last 5 days. Here's an example.  The following effect macro is run each turn for any token with the "Regeneration" effect placed upon it - it should add the value of @{conregen} attribute of the character related to the token to bar3_current but not allow it to go above the maximum (set to 144), and report this as (:From ): Ctenmiir regenerates 40 -> 60 HP

!token-mod --ignore-selected --ids ^^tid^^ --set bar3_current|+[[@{^^cname^^|conregen}]]! --report control|"{name} regenerates {bar3_current:change} HP"

My RoundMaster API parses this and replaces ^^tid^^ with the token_id and ^^cname^^ with the character name - this is happening successfully, and results in e.g. 

!token-mod --ignore-selected --ids -MRJljwNEwLzJlZnxBsQ --set bar3_current|+[[@{ctenmiir|conregen}]]! --report control|"{name} regenerates {bar3_current:change} HP"

This worked excellently, and certainly was working fine on all days including last Friday 7 May.  However, yesterday, on Wednesday 12 May, the result was to report

(From ): Ctenmiir regenerates 40 -> +20! HP

And the token bar3_current was set to '+20!' which is meaningless as a HP value. 

If I remove the '!' it works, but does not limit the value to the max:

!token-mod --ignore-selected --ids -MRJljwNEwLzJlZnxBsQ --set bar3_current|+[[@{ctenmiir|conregen}]] --report control|"{name} regenerates {bar3_current:change} HP"
(From ): Ctenmiir regenerates 130 -> 150 HP

What has changed?  Nothing in my game, as far as I am aware, but I might have done something stupid. How can I fix this?


May 13 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Ah!  Sorry, this is a bug I accidentally introduced last week, Persephone mentioned it above. I'll set a reminder to get that fixed tonight, sorry about that.

May 13 (3 years ago)


keithcurtis said:

Hmmm... A script could be written to change the player color (the box next to their name) based on health status. This might be useful for healers to track the health of the party, but it would have some limitations:

1) it would remove a bit of player agency by taking away their ability to chose their color.

2) you would have to set up a single specific character for each player.


Check out the API Aura/Tint HealthColors, I think it will do what you want. 

May 13 (3 years ago)


Alryon said:

Ok, I've installed TokenMod, but I have no clue where to start! Sooo many options. Could someone point me in the direction of some useful macros to use it with? I'm not completely computer-illiterate but programming is not really my thing, so I could use some help getting started. Thanks a lot!


I use it to change light settings on the token. Light up a torch, snuff the torch out. Light a Bullseye lantern, Open Close a Lantern. 



May 15 (3 years ago)

Edited May 15 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Update v0.8.66 -- Fixed issue with ! on the end of bar sets causing bad behavior. (Thanks Persephone)

May 15 (3 years ago)

Edited May 15 (3 years ago)


The Aaron said:

Update v0.8.66 -- Fixed issue with ! on the end of bar sets causing bad behavior. (Thanks Persephone)


Looking forward to this. I encountered the same + bug in my game tonight and was sad I couldn't use any of my TokenMod-based damage or healing macros. :)

May 15 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Sorry about that!  Should be in the 1-click Tuesday.


keithcurtis said:

That property does not appear to be available to the API.


Ah, thanks for letting me know about Nocturnal, keith. So, how are folks handling darkvision in UDL, then, if Nocturnal isn't exposed to the API? I had the following macro early in UDL's development:

!token-mod --set bright_vision#yes night_vision#yes night_distance#60 emits_bright#no emits_low#no

&{template:npcaction} {{rname=Set Light Source}} {{description=@{selected|token_name} uses their **Darkvision** to see.}}

Would this work?

May 17 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

Manually, at the moment. Same way I handle setting default tokens... :(


keithcurtis said:

Manually, at the moment. Same way I handle setting default tokens... :(


Ugh. They had better make Nocturnal available to the API...



May 17 (3 years ago)
keithcurtis
Forum Champion
Marketplace Creator
API Scripter

They say that is the intent, but we've been waiting over two years for them to finish adding the existing token settings.

I've noticed another new weird behavior since the latest update. I use a macro that plugs in a value that it subtracts from a token bar, and sometimes that value is negative so it instead adds to the bar. Since they v0.8.66, if, for example, -1 gets plugged into the macro, it's now setting the bar to --1 instead of subtracting -1.

I think doing a value change like bar1_value|--1 already caused issues in the script because my macro has the query in square brackets to get around that, making the final change bar1_value|-[[-1]]. This workaround is what's no longer working.


keithcurtis said:

Manually, at the moment. Same way I handle setting default tokens... :(

Concerning my everlasting problems with default tokens: this also doesn't work, probably also because they didn't expose all the API?! If I set up a token, let's say size, bars, bar type (=overlapping below compact). Then I use token-mod --set defaulttoken. The bar values are correct, but overlapping below and compact got lost. It's always above and detail - which I hate for some reasons.

I would have thought that the option does the same as edit->remove default token->use selected in the editor. But obviously not.

How do you guys handle that? Since there is still no way in roll20 to set up default tokens (of monsters that are already in game), I always have to adjust them ALL manually.


May 19 (3 years ago)

Here is my macro for applying damage.  I use the [[DAM]] idea like you did, but only had to put the negative sign in once

!token-mod --ids @{target|token_id} --set bar1_value|-[[floor(?{Damage}*?{Damage Adj|None,1|Resistant,.5|Immune,0})]]


Persephone said:

I've noticed another new weird behavior since the latest update. I use a macro that plugs in a value that it subtracts from a token bar, and sometimes that value is negative so it instead adds to the bar. Since they v0.8.66, if, for example, -1 gets plugged into the macro, it's now setting the bar to --1 instead of subtracting -1.

I think doing a value change like bar1_value|--1 already caused issues in the script because my macro has the query in square brackets to get around that, making the final change bar1_value|-[[-1]]. This workaround is what's no longer working.





Bernd S. said:


keithcurtis said:

Manually, at the moment. Same way I handle setting default tokens... :(

Concerning my everlasting problems with default tokens: this also doesn't work, probably also because they didn't expose all the API?! If I set up a token, let's say size, bars, bar type (=overlapping below compact). Then I use token-mod --set defaulttoken. The bar values are correct, but overlapping below and compact got lost. It's always above and detail - which I hate for some reasons.

I would have thought that the option does the same as edit->remove default token->use selected in the editor. But obviously not.

How do you guys handle that? Since there is still no way in roll20 to set up default tokens (of monsters that are already in game), I always have to adjust them ALL manually.



Yeah, the location and size of the bar isn't exposed to the API. Frustrating. I feel the same way you do. I loathe the above bar, and always set it to bottom overlapping.

For default tokens for in-game monsters, not much you can do. Going forward, though, after you run --set defaulttoken, select the token, change its bar settings to what you prefer, shift double-click to get to the character sheet editor (for the monster), and use that token as the default token. Every subsequent instance of the monster you drag onto the VTT map will come in with your preferred bar location/size.


May 19 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter


Persephone said:

I've noticed another new weird behavior since the latest update. I use a macro that plugs in a value that it subtracts from a token bar, and sometimes that value is negative so it instead adds to the bar. Since they v0.8.66, if, for example, -1 gets plugged into the macro, it's now setting the bar to --1 instead of subtracting -1.

I think doing a value change like bar1_value|--1 already caused issues in the script because my macro has the query in square brackets to get around that, making the final change bar1_value|-[[-1]]. This workaround is what's no longer working.

Oof!  I'm surprised they worked, and annoyed it doesn't now. I'll see if I can adjust my regular expression and get it working again. 

@The Aaron oops! I must have accidentally deleted the last paragraph of my last post before submitting.

I meant to ask: Is there a more efficient way I might set up that macro? To avoid you having to do a whole new update!

@Darryn thanks! The macro I'm using in this case tho is intended for a different use. I use it for undoing the most recent health bar change in case of a mistake, so to undo an increase it subtracts a positive value but to undo damage it subtracts a negative value — that's where the double negative comes in.

May 19 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

No, I think that's an actual oversight on my part.  I look for + - = and a few other symbols that I take as operations.  I've been including them as part of the number, but it really makes sense to have the operation + and - distinctly separate from the number's + and -.  Besides, it should be an easy change.  =D

May 19 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Update v0.8.67 -- Fixed issue with double - or double + when adjusting numeric values. (Thanks Persephone)

May 19 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Should be in the one click next week, or you can grab an advance copy from:

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

Glad it was an easy fix! I didn't mean for my initial request to have such a domino effect. I appreciate you taking the time to implement it and the ensuing bug fixes =D

May 19 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Lol.  Not a problem. =D

May 19 (3 years ago)
The Aaron
Roll20 Production Team
API Scripter

Update v0.8.68 -- Fixed the = operations for numeric types. (Thanks Consecrated)