Latest revision as of 13:17, 25 August 2024

Page Updated:   2024-08-25

Main Page: Token/API

This page is related to Roll20 Mods, which require Pro info from the game's creator. (formerly known as API "Scripts") Main Page: Mod:Use Guide

TokenMod provides an interface to setting almost all changeable properties of a token. Players can also use it to edit tokens they control, with option to edit/target other's tokens.

TokemMod is among the most popular Mods, and is quickly updated every time Roll20 makes new Mod/API keys accessible.

!token-mod <--help|--ignore-selected|--config|--on|--off|--flip|--set> <parameter> [<parameter> ...] ... [ --ids <token id> [<token id> ...]]

Full user documentation can be found in the Help: TokenMod-Handout in-game, or by running the command !token-mod --help.

• TokenMod sourcecode - lastest version
• TokenMod Forum thread^(Forum)

[edit] Config

Enable players to target/edit tokens they don't control(is also a button in the config menu):

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

[edit] Commands

!token-mod <--help|--ignore-selected|--config|--on|--off|--flip|--set> <parameter> [<parameter> ...] ... [ --ids <token id> [<token id> ...]]

This command takes a list of modifications and applies them to the selected tokens (or tokens specified with --ids by a GM or Player depending on configuration).

• --help -- Displays the help documentation
• --api-as <playerid> -- Sets the player id to use as the player when the API is calling the script.
• --config -- Sets Config options.
• on/off/flip (See "Boolean Arguments"-section in handout for more details)
  • --on -- Turns on any of the specified parameters.
  • --off -- Turns off any of the specified parameters.
  • --flip -- Flips the value of any of the specified parameters.
• --set -- Each parameter is treated as a key and value, divided by a | character. Sets the key to the value. If the value has spaces, you must enclose it ' or ". See below for specific value handling logic.
• --move -- Moves each token in a direction and distance based on its facing.
• --order -- Changes the ordering of tokens. Specify one of:
  • tofront, front, f, top to bring something to the front
  • toback, back, b, bottom to push it to the back.
• --report -- Displays a report of what changed for each token.
  Experimental

Full user documentation can be found in the Help: TokenMod-Handout in-game, or by running the command !token-mod --help.

[edit] Token Selection

By default, any command is activated for selected tokens.

Options

• --ignore-selected -- Prevents modifications to the selected tokens (only modifies tokens passed with --ids).
• --current-page -- Only modifies tokens on the calling player's current page. This is particularly useful when passing character_ids to --ids.
• --active-pages -- Only modifies tokens on pages where there is a player or the GM. This is particularly useful when passing character_ids to --ids.
• --ids -- Each parameter is a Token ID or Character ID
  • Easiest way to provide the ID with @{target|Target 1|token_id} or @{Charlie|character_id}.
    • The name used in example @{Charlie|character_id} is the name of the character, not the token. @{Charlie|token_id} doesn't work
  • works with providing an Token/Char ID directly (ex. !token-mod --ids -Mxxzfp9Bxbn4JqzGOkB --move =90|1g
  • By default, only a GM can use this argument.

You can enable players to use --ids as well with --config players-can-ids|on.

Note: If you are using multiple @{target|token_id} calls in a macro, and need to adjust fewer than the supplied number of token ids, simply select the same token several times. The duplicates will be removed.

[edit] Use with other APIs

If you use other APIs to call TokenMod, it's possible to target tokens by their name. (Useful when token isn't linked to a character, or has a name that doesn't match the character it represents.

• SelectManager Metascript to improve selection handling for other APIs
  • ex. !token-mod --ids {& select Charlie, Dino} --current-page --move =90|1g (Target's token by name, not possible normally)
• Script:Fetch Metascript to fetch info from tokens & characters
  • ex. !token-mod --ids @(Charlie.token_id) --current-page --move =90|1g (Target's token by name, not possible normally)
• It's A Trap can be used to trigger TokenMod commands when tokens are moved into a defined trigger area, among things.

[edit] Considerations

Note: Each --option can be specified multiple times and in any order.

Note: Anywhere you use |, you can use # instead. Sometimes this makes macros easier.

Note: You can use the {{ and }} to span multiple lines with your command for easier clarity and editing:

!token-mod {{
  --on
    flipv
    fliph
  --set
    rotation|180
    bar1|[[8d8+8]]
    light_radius|60
    light_dimradius|30
    name|"My bright token"
}}

[edit] Examples

Some examples of !token-mod commands, with possible explanations. Examples are taken from forums thread, in-game documentation, and other places.

• https://app.roll20.net/forum/post/9177966/cool-things-to-do-with-tokenmod

!token-mod --on showname            // show nameplate
!token-mod --off showname --ids -MqL6-o4cFq5-9Z5_W8K  // turn off nameplate for token with that token_id
!token-mod --set layer|gmlayer      // move token to GM layer
!token-mod --set bar1_value|-3      // decrease value of bar 3 by 3
!token-mod --set name|"Sir Thomas" bar1_value|23      //Setting a token's name to "Sir Thomas" and bar1 value to 23
!token-mod --set represents|@{Bob|character_id} defaulttoken      // sets the default token for that character, a quick way to update the default token
!token-mod --set statusmarkers|blue|broken-shield       //adds the 2 status markers to the token
!token-mod --move 3g                // move token 3 grids in the current facing(up being default)
!token-mod --move =90|2u           // moves 2 grids to the right(ignoring current facing)
!token-mod --flip lockMovement     // locks the token's movement

//Various examples
!token-mod --on showplayers_aura1 --set aura1_radius|35 aura1_color|0000ff //Turning on aura1 for players, setting it's radius to 35, setting it's color to blue
!token-mod --set bar[[1d3]]_value|X statusmarkers|blue:[[1d9]]|green:[[1d9]] name:"[[1t[randomName]]]"     // use inline rolls to set values
!token-mod --set width|25s height|35s     // 's' represent the unit of measurement for the page
!token-mod --set scale|*2
!token-mod --set imgsrc|https://s3.amazonaws.com/files.d20.io/images/4095816/086YSl3v0Kz3SlDAu245Vg/max.png?1400535580        // change token image 
!token-mod --set tooltip|"Hey, you can see this on hover!" --on show_tooltip

//Sidenumber Multi-sided tokens
!token-mod --set currentside|2      //set selected token to show side 2
!token-mod --set currentside|+      //set selected token to show "next" side, by "shifting" the token side number by +1
!token-mod --set currentside|*      //set selected token to show random side

//Controlled by
!token-mod --set controlledby|bob
!token-mod --set controlledby|+susan|+tommy        //add susan & tommy to list
!token-mod --set controlledby|=@{target|token_id}   //copy controlled by from other token
!token-mod --set controlledby|                      //nobody
!token-mod --set controlledby|all                   //all players

//Updated DL Examples
!token-mod --on emits_bright emits_low --set bright_distance|40 low_distance|20
!token-mod --flip emits_bright emits_low                          //Toggles on/off emitted light for the token
!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|20 low_light_distance|20 light_angle|360             //selected token emits light as a standard 5E Torch

//Legacy DL Example
!token-mod --set light_radius|40 light_dimradius|20 adv_fow_view_distance|30

//Chaining multiple TokenMod commands
!token-mod {{
  --set
    represents|@{bob|character_id}
    bar1_link|hp
    bar2_link|speed
    bar3_link|ac
    controlledby|tom|sally|nancy
    statusmarkers|blue:3|red:[[1d6]]
    defaulttoken
}}

[edit] Update Token

[edit] Default Token

If you have a token selected, which is set to represent a character, you can do the following command and the Character's default token will be updated. This is much quicker than the Link Token-method.

!token-mod --set defaulttoken

[edit] Token Image

Setting the token image to a library image using an URL (in this case, the orange ring Aaron uses for TurnMarker1):

!token-mod --set imgsrc|https://s3.amazonaws.com/files.d20.io/images/4095816/086YSl3v0Kz3SlDAu245Vg/max.png?1400535580

Setting the token image from another token by specifying it's token_id:

!token-mod --set imgsrc|@{target|token_id} --ids @{selected|token_id}

Handy for players to update their token image themselves, while still keeping the token's other settings. You can then run !token-mod --set defaulttoken to update the character's default token.

WARNING: Because of a Roll20 bug with @{target|} and the API, you must specify the tokens you want to change using --ids when using @{target|}.

Multi-Sided Token:

You can append additional images to the list of sides by prefacing the source of an image with +:

!token-mod --set imgsrc|+https://s3.amazonaws.com/files.d20.io/images/4095816/086YSl3v0Kz3SlDAu245Vg/max.png?1400535580

More examples for Multi-Sided can be found in the "Help:Token Mod"-handout in-game.

[edit] Character-Specific Command

Toggles on/off Darkvision for tokens representing the character named "Wizard", and only on the current map page. Doesn't apply the changes to any selected characters.

Great example of fairly fool-proof command that can be given to a players as a macro, which they can active for their own character for the quickbar or a macro, without the risk of accidentally affecting other tokens than the one currently played by the player.

!token-mod {{
  --flip
    night_vision
  --set
    night_vision_distance|60
    light_angle|360
    night_vision_effect|nocturnal
  --ids @{Wizard|character_id}
  --current-page
  --ignore-selected
}}

[edit] Color Light dropdown

"a macro to change the light colour emitted by a token. Included are the basic colours and a collection of some others that I thought would be interesting." - source^(Forum)

!token-mod ?{Colour|Black, --set lightColor#000000|Silver, --set lightColor#c0c0c0|Gray, --set lightColor#808080|White, --set lightColor#ffffff|Maroon, --set lightColor#800000|Red, --set lightColor#ff0000|Purple, --set lightColor#800080|Fuchsia, --set lightColor#9900ff|Pink, --set lightColor#ffc0cb|Green, --set lightColor#008000|Lime, --set lightColor#00ff00|Olive, --set lightColor#808000|Yellow, --set lightColor#ffff00|Navy, --set lightColor#000080|Blue, --set lightColor#0000ff|Teal, --set lightColor#008080|Aqua, --set lightColor#00ffff|Orange, --set lightColor#ffa500|-,
|Aquamarine, --set lightColor#7fffd4|Coral, --set lightColor#ff7f50|Cornflowerblue, --set lightColor#6495ed|Crimson, --set lightColor#dc143c|Darkcyan, --set lightColor#008b8b|Darkgreen, --set lightColor#006400|Darkseagreen, --set lightColor#8fbc8f|Deeppink, --set lightColor#ff1493|Firebrick, --set lightColor#b22222|Gold, --set lightColor#ffd700|Goldenrod, --set lightColor#daa520|Lavender, --set lightColor#e6e6fa|Orangered, --set lightColor#ff4500|Saddlebrown, --set lightColor#8b4513|Salmon, --set lightColor#fa8072|Seagreen, --set lightColor#2e8b57|Skyblue, --set lightColor#87ceeb|Violet, --set lightColor#ee82ee|Wheat, --set lightColor#f5deb3|-,
|Clear, --set lightColor#transparent|}

[edit] Move dead to map layer

by Jarren^(Forum)

use to move dead NPCs between the object layer and map layer (so that I don't keep clicking on them accidentally, but they stay visible for the players).

!?{Dead or Alive?|Dead,--order tofront --set layer#map --report gm#"{name} is dead"|Alive,--order tofront --set layer#objects --report gm#"{name} is alive"}
!token-mod ?{Dead or Alive?|Dead|Alive}

[edit] WildShape

API command:

/w gm Quill wills himself to transform!
!token-mod {{
  --set
    ?{Choose Form|Giant Toad,currentside#1 represents#@{Giant Toad|character_id} width#[[2*70]] height#[[2*70]]
      |Giant Hyena,currentside#2 represents#@{Giant Hyena|character_id} width#[[2*70]] height#[[2*70]]
      |Dire Wolf,currentside#3 represents#@{Dire Wolf|character_id} width#[[2*70]] height#[[2*70]]
      |Reef Shark,currentside#4 represents#@{Reef Shark|character_id} width#[[2*70]] height#[[2*70]]
      |Quill,currentside#5 represents#@{Quill|character_id} width#[[70]] height#[[70]]
    }
    bar1_link|speed bar2_link|hp
    bar3_link|ac
    name|"Quill"
    showname|yes
}}

[edit] Dynamic Lighting

[edit] Token Menu

macro by keith

for UDL

/w gm &{template:npcaction} {{rname=Vision and Light}}{{description=**Vision**
[On](!token-mod --set has_bright_light_vision|on has_night_vision|on light_angle|360) | [Off](!token-mod --set has_bright_light_vision|off has_night_vision|off light_angle|360) | [GM](!token-mod --set has_bright_light_vision|on has_night_vision|on night_vision_distance|10 light_angle|360)
[Touch](!token-mod --set  has_bright_light_vision|on has_night_vision|on night_vision_distance|5 light_angle|360) | [Blindfighting](!token-mod --set has_bright_light_vision|on has_night_vision|on night_vision_distance|10 light_angle|360)
[Darkvision](!token-mod --set has_bright_light_vision|on has_night_vision|on night_vision_distance|60 light_angle|360 night_vision_effect|nocturnal) | [DV90](!token-mod --set has_bright_light_vision|on has_night_vision|on night_vision_distance|90 light_angle|360 night_vision_effect|nocturnal) | [DV120](!token-mod --set has_bright_light_vision|on has_night_vision|on night_vision_distance|120 light_angle|360 night_vision_effect|nocturnal) | [DV off](!token-mod --set has_bright_light_vision|on has_night_vision|off night_vision_distance|0 light_angle|360)
**Light**
[Off](!token-mod --set emits_bright_light|off emits_low_light|off light_angle|360) | [On](!token-mod --set emits_bright_light|on emits_low_light|on light_angle|360) | [Spot](!token-mod --set emits_bright_light|on bright_light_distance|5 low_light_distance|0 light_angle|360) | 
 [Candle](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|2 low_light_distance|5 light_angle|360) | [Lamp](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|15 low_light_distance|15 light_angle|360) | [Torch](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|20 low_light_distance|20 light_angle|360)
[Hooded Lantern](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|30 low_light_distance|30 light_angle|360) | [Bullseye Lantern](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|60 low_light_distance|60 light_angle|90)
[*Light*](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|20 low_light_distance|20 light_angle|360) | [*Daylight*](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|60 low_light_distance|60 light_angle|360) | [*Dancing*](!token-mod --set emits_bright_light|off emits_low_light|on bright_light_distance|0 low_light_distance|10 light_angle|360) | [*Faerie Fire*](!token-mod --set emits_bright_light|off emits_low_light|on bright_light_distance|0 low_light_distance|10 statusmarkers|purple light_angle|360)
[*Gem of Brightness*](!token-mod --set emits_bright_light|on emits_low_light|on bright_light_distance|30 low_light_distance|30 light_angle|360)}}

[edit] Set Vision

by Klaus^(Forum)

for UDL

Players can set Vision for themselves easily:

• On, Off, Blindfighting, Darkvision 60/90/120/300/Off, Devils Sight 120

!token-mod --set ?{Vision|On, has_bright_light_vision#on has_night_vision#on light_angle#360|Off, has_bright_light_vision#off has_night_vision#off light_angle#360|Blindfighting, has_bright_light_vision#on has_night_vision#on night_vision_distance#10 light_angle#360|Darkvision 60, has_bright_light_vision#on has_night_vision#on night_vision_distance#60 light_angle#360 night_vision_effect#nocturnal|Darkvision 90, has_bright_light_vision#on has_night_vision#on night_vision_distance#90 light_angle#360 night_vision_effect#nocturnal|Darkvision 120, has_bright_light_vision#on has_night_vision#on night_vision_distance#120 light_angle#360 night_vision_effect#nocturnal|Darkvision 300, has_bright_light_vision#on has_night_vision#on night_vision_distance#300 light_angle#360 night_vision_effect#nocturnal|Darkvision Off, has_bright_light_vision#on has_night_vision#off night_vision_distance#0 light_angle#360|Devils Sight 120, has_bright_light_vision#on has_night_vision#on night_vision_distance#120 light_angle#360 night_vision_effect#nocturnal}

[edit] Set Light Source

by Klaus^(Forum)

Player can set light source

On, Off,Spot, Candle, Lamp, Torch, Hooded Lantern, Bullseye Lantern, Light Cantrip, Dancing Lights, Daylight Spell, Faerie Fire, Gem of Brightness, Crown of 4+/1-3 Stars, Sunblade 10/10,15/15, 20/20, 25/25, 30/30

!token-mod --set ?{Light|On, emits_bright_light#on emits_low_light#on light_angle#360|Off, emits_bright_light#off emits_low_light#off light_angle#360|Spot 5ft, emits_bright_light#on bright_light_distance#5 low_light_distance#0 light_angle#360|Candle, emits_bright_light#on emits_low_light#on bright_light_distance#2 low_light_distance#5 light_angle#360|Lamp, emits_bright_light#on emits_low_light#on bright_light_distance#15 low_light_distance#15 light_angle#360|Torch, emits_bright_light#on emits_low_light#on bright_light_distance#20 low_light_distance#20 light_angle#360|Hooded Lantern, emits_bright_light#on emits_low_light#on bright_light_distance#30 low_light_distance#30 light_angle#360|Bullseye Lantern, emits_bright_light#on emits_low_light#on bright_light_distance#60 low_light_distance#60 light_angle#90|Light Cantrip, emits_bright_light#on emits_low_light#on bright_light_distance#20 low_light_distance#20 light_angle#360|Dancing Lights, emits_bright_light#off emits_low_light#on bright_light_distance#0 low_light_distance#10 light_angle#360|Daylight Spell, emits_bright_light#on emits_low_light#on bright_light_distance#60 low_light_distance#60 light_angle#360|Faerie Fire, emits_bright_light#off emits_low_light#on bright_light_distance#0 low_light_distance#10 light_angle#360|Gem of Brightness, emits_bright_light#on emits_low_light#on bright_light_distance#30 low_light_distance#30 light_angle#360|Crown of 4+ Stars, emits_bright_light#on emits_low_light#on bright_light_distance#30 low_light_distance#30 light_angle#360|Crown of 1-3 Stars, emits_bright_light#off emits_low_light#on bright_light_distance#0 low_light_distance#30 light_angle#360|Sunblade 10/10, emits_bright_light#on emits_low_light#on bright_light_distance#10 low_light_distance#10 light_angle#360|Sunblade (1st)15/15, emits_bright_light#on emits_low_light#on bright_light_distance#15 low_light_distance#15 light_angle#360|Sunblade 20/20, emits_bright_light#on emits_low_light#on bright_light_distance#20 low_light_distance#20 light_angle#360|Sunblade 25/25, emits_bright_light#on emits_low_light#on bright_light_distance#25 low_light_distance#25 light_angle#360|Sunblade 30/30, emits_bright_light#on emits_low_light#on bright_light_distance#30 low_light_distance#30 light_angle#360}

[edit] Tooltip Update Menu

more info

Dropdown menu to choose between tooltip descriptions, for selected character. Includes option to clear&hide the tooltip when the condition is over. !token-mod --set tooltip|?{Condition|Prone,"disadvantage on melee attacks" --on show_tooltip|Grappled,"A grappled creatures speed becomes 0" --on show_tooltip|Incapacitated,"An incapacitated creature can’t take Actions or Reactions." --on show_tooltip|clear tooltip, --off show_tooltip}

[edit] Combine with other APIs

• Meta-Toolbox
  • Script:Fetch
  • Script:SelectManager
• Script:It's a Trap
• Script:Customizable Roll Listener - CRL can activate a TokenMod command when it sees a specific thing in the text chat
• ScriptCards

[edit] Changelog

Some recent changes:

• v0.8.74 - Add option for new Lock Token feature March 2022
  • ex. !token-mod --flip lockMovement
• v0.8.73 - Dec. 2021
  • Fixed a bug that crashed TokenMod when any message used an inline roll of a Rollable Table with no rows. (Thanks Shane M. )
  • TokenMod will do a better job of ignoring messages that aren't meant for it
• v0.8.72 - Oct. 2021 - Support for Token Tooltip
• v0.8.71^(Forum) - includes support for lightColor
• v0.8.69^(Forum) - June 2021 - Support for Token Bar Location, Compact Token Bars, Light Sensitivity Multiplier (UDL), and Night Vision Effect (UDL)

[edit] See Also

• API:Script Index Curated list of Roll20 APIs
  • Token/API
  • Character_Sheet/API
  • Script:ChatSetAttr
• Tokens
  • Link Token to Sheet
• Complete Guide to Rolls & Macros
  • Inline Rolls
  • Chat Menu