Difference between revisions of "Script:Token Mod"
From Roll20 Wiki
Andreas J. (Talk | contribs) m |
Andreas J. (Talk | contribs) m |
||
Line 7: | Line 7: | ||
'''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. | '''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. | |
'''Commands:''' <pre>!token-mod <--help|--ignore-selected|--config|--on|--off|--flip|--set> <parameter> [<parameter> ...] ... [ --ids <token id> [<token id> ...]]</pre> | '''Commands:''' <pre>!token-mod <--help|--ignore-selected|--config|--on|--off|--flip|--set> <parameter> [<parameter> ...] ... [ --ids <token id> [<token id> ...]]</pre> |
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.
Commands:!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)
Roll20 Mod
Mod Suggestions
- D&D 5E
- Combat
- Character Sheet
- Dynamic Lighting
- Jukebox
- Maps
- Text Chat/Macros
- Tokens
- System Specific
- Mod Guides by Script
Debug
Other
Contents |
[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
- The name used in example
- 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.
- Easiest way to provide the ID with
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)
- ex.
- 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)
- ex.
- 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.
!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|}
.
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
Used with D&D 5E by Roll20/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
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: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
- ex.
- 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
- Tokens
- Complete Guide to Rolls & Macros