This article is a stub. You can help the Roll20 Community Wiki by expanding it.

This script lets you change just about any property of a token from a macro or the chat (Thanks GenKitty for the idea!). You can only change tokens you control (enforced by the ability to select them), unless you are the GM, in which case you can specify token_ids with the --ids command. The same operation is applied to all selected tokens, so it makes batch changes fast and easy.

Commands

!token-mod -- This is the interface command, with the following options:

Parameter	Description
--help	Displays the help script.
--on <arguments>	Toggles supplied boolean arguments to on.
--off <argument>	Toggles supplied boolean arguments to off.
--flip <arguments>	Toggles supplied boolean arguments to their alternate state. On becomes off, off becomes on.
values>	Sets an property to the supplied value. The help is extensive, but I'll hit the highlights below.
--ids <arguments>	1|token_id}, etc.

( @James the DM's Printable reference!!: https://dl.dropboxusercontent.com/u/7544708/TokenM... )

Details for --set

Mostly, properties should work like you expect. If it's a color, it takes a color, if it's a number, it takes a number. Any argument with an invalid value is ignored. Here's a few examples that should make things clearer.

Turning on name plates for all selected tokens:

!token-mod --on showname

Moving selected tokens to the gmlayer:

!token-mod --set layer|gmlayer

Turning on aura1 for players, setting it's radius to 35, setting it's color to blue:

!token-mod --on showplayers_aura1 --set aura1_radius|35 aura1_color|0000ff

Setting up 5e style darkvision, moving to the objects layer, flipping the setting on show names, set bar1 to 25, set bar2 to 'Foe':

!token-mod --set light_radius|40 light_dimradius|0 layer|objects --flip showname --off light_otherplayers --set bar1_value|25 bar2_value|Foe

I've carefully ignored status markers until now. Status markers have a more complicated syntax to allow more flexibility.

Multiple status markers can be set at the same time, this will add the blue, green, red, padlock, and broken-shield status markers.

!token-mod --set statusmarkers|blue|green|red|padlock|broken-shield

They can also take a number by appending it with a : separator to the end of each status name. (note that the number following the dead status is ignored, as it is special.)

!token-mod --set statusmarkers|blue:0|green:3|red:9|padlock:7|broken-shield:8

Note: Numbers are bound between 0 and 9.

You can also remove status markers by prefacing them with a -. This will remove the blue and broken-shield status markers:

!token-mod --set statusmarkers|-blue|-broken-shield

If you want to completely clear all status markers when you set your new one, you can preface it with a =. Note that this will affect all previously applied status markers, even if you are applying them as part of this same set command. This will set only the red, green, and blue markers:

!token-mod --set statusmarkers|=blue|green|red

If you need to just remove all status markers, you can specify the same status marker twice, first with = and second with -:

!token-mod --set statusmarkers|=blue|-blue

Example using --ids and other things:

!token-mod --set layer|objects aura1_radius|35 aura1_color|00ff00 tint_color|transparent --on showname --ids @{target|token_id}

Changelog

v0.7 (2015-02-22) Added support for unlinking bars by passing an empty Attribute Name. (Thanks Ari K.!)-

v0.6 (2015-02-20) Switched to git and pushed into the Roll20 Official repo as well. -

v0.54 (2015-02-01)

• Release

Update v0.7 -- Added support for unlinking bars by passing an empty Attribute Name. (Thanks Ari K.!) Update v0.6 -- Switched to git and pushed into the Roll20 Official repo as well. Update v0.53 -- You can now toggle status markers on and off by prefacing them with the ! symbol. This will add the Rook piece if it isn't there, but remove it if it is:

!token-mod --set statusmarkers|!white-tower

Adding with a number will set the number if the status was not present, so this would add blue with a value of 3 if it wasn't already there, but clear it if it was:

!token-mod --set statusmarkers|!blue:3

Adding relative numbers is less useful since they would always be operating on 0 (if the status wasn't there) or not being applied (because the status is being removed if it was there already), but they don't cause an error.

I also expanded the help to show --ids and how to use it for multiple token ids (Thanks John C.), as well as cleaning up a few other points.

Update v0.52 -- Setting Number and Number or Blank can now be decimal. (Thanks Black Falcon) Update v0.51 -- Setting represents now supports character names instead of just character_id. You can use the full name (quoted if it contains spaces) or just a partial name that is unique among your characters. It is not case sensitive, so Max = max = MaX = MAX.

Update v0.5 -- Added delta changes to all reasonable number fields. You can now specify +3 or -2 instead of just a number, even on status numbers:

!token-mod --set statusmarkers|blue:-1 bar1_value|+3

This can be used on any field that is one of: Number, Number or Blank, Degrees, Text, Status Status fields will be bound between 0 or 9, other fields will not be bound.

Also added the ability to set the represents for a token. You need only specify the character_id, probably with @{<character name>|character_id}:

!token-mod --set represents|@{Bob|character_id}

Note that this will clear out any links that bars have currently...

So I've also added setting links for the bars, using the fields bar1_link, bar2_link, bar3_link. You need to specify the name of an attribute on the character the token represents. If you're specifying these in the same command as represents, be sure they are after:

!token-mod --set represents|@{Bob|character_id} bar1_link|npc_HP bar2_link|npc_ac bar3_link|npc_temp_HP

One final caution: There seems to be a bug with updating a token bar via the API when it is tied to an attribute, such that other tokens that are tied to the same attribute do not get updated. Be sure to leave a comment if you experience that, particularly if you can narrow down the case.

Update v0.4 -- Added --config command for setting configurations. Currently the only config option is players-can-ids which allows players to use the --ids command to target tokens they don't control. Updated documentation to add bar1, bar2, bar3 meta properties, added notes about support for inline rolls in --set.

Turn on players ability to use --ids with:

!token-mod --config players-can-ids|on

Play slots with this:

!token-mod --set statusmarkers|red:1d9|green:1d9|blue:1d9

Set hit points with this (sets both bar2_value and bar2_max to the result of the expression):

!token-mod --set bar2|3d8+4

Update v0.32 -- Added expansion of inline rolls and the Meta-Properties bar1, bar2, bar3 which set the _value and _max values to whatever is supplied. (Thanks for the suggestion Leo!) Update v0.31 -- Minor update to fix the issue with HTML special entities. Update v0.3 -- Fixed a bug with --ids (Thanks again James!) Update v0.2 -- Fixed a bug with colors, made the help work for non-GMs. (Thanks James!)