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.
--set <arguments|values>	Sets an property to the supplied value. The help is extensive, but I'll hit the highlights below.
--ids <arguments>	The GM can supply a list of token_ids, probably with @{target|1|token_id}, etc.

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

You can now use the multiline syntax for your TokenMod commands:

Example:

!token-mod {{

--set

light_radius|40

light_dimradius|0

light_multiplier|1.5

layer|objects

--flip showname

--off light_otherplayers

--set

bar1_value|25

bar2_value|Foe

--ids

@{target|target 1|token_id}

@{target|target 2|token_id}

@{target|target 3|token_id}

}} on API startup, it will now log out the version number and last update date as follows:

 "-=> TokenMod v0.8.1 <=-  [Sun Mar 29 2015 00:40:56 GMT-0500 (CDT)]"

This will get updated as I make further changes (coming soon to all my scripts!)

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}

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.

Setting Number and Number or Blank can now be decimal. (Thanks Black Falcon)

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.

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: This will clear out any links that bars have currently allocated to them. use with caution.

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

Note: 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.

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]]

Changelog

{{changelog version|0.8.1|2015-03-29|Added support for Multi-line commands via {{ }}, light_multiplier, startup version logging, and config API Button. 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