Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:Token Mod"

From Roll20 Wiki

Jump to: navigation, search
m
(5 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
|name=TokenMod
 
|name=TokenMod
 
|author={{user profile|104025|Aaron C. M.}}
 
|author={{user profile|104025|Aaron C. M.}}
|version=0.7
+
|version=0.8.57
|dependencies={{api repository link|IsGM}}
+
|lastmodified=2020-06-10}}
|lastmodified=2015-02-22}}
+
{{stub}}
+
  
 +
The Aaron's TokenMod API Script. '''TokenMod''' provides an interface to setting almost all changeable properties of a token.
  
 +
'''Commands:''' <code><nowiki>!token-mod <--help|--ignore-selected|--config|--on|--off|--flip|--set> <parameter> [<parameter> ...] ... [ --ids <token id> [<token id> ...]]</nowiki></code>
  
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.
+
Full user documentation can be found in the ''Help: TokenMod''-Handout in-game, or by running the command <code>!token-mod --help</code>.
  
===Commands===
+
* {{repo|shdwjk/Roll20API/tree/master/TokenMod TokenMod sourcecode}} - lastest version
:'''!token-mod''' -- This is the interface command, with the following options:
+
* {{forum|post/4225825/script-update-tokenmod-an-interface-to-adjusting-properties-of-a-token-from-a-macro-or-the-chat-area TokenMod Forum thread}}  
::{| class="wikitable"
+
|-
+
! 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&#124;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&#124;1&#124;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:
+
==Examples==
:'''Example:'''
+
Some examples of <code>!token-mod</code> commands, with possible explanations. Texamples taken from the forum thread or in-game documentation.  
<br />
+
'''!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)]"''
+
<pre style="overflow:auto;" data-language="javascript">
  
This will get updated as I make further changes (coming soon to all my scripts!)
+
!token-mod --on showname            // show nameplate
 +
!token-mod --set layer|gmlayer      // move to gmlayer
 +
!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 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)
  
===Details for --set===
+
//Various examples
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.
+
!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
  
:Turning on name plates for all selected tokens:
+
//Sidenumber Multi-sided tokens
::'''''!token-mod''' --on showname''
+
!token-mod --set currentside|2
 +
!token-mod --set currentside|+      //shift side by 1
 +
!token-mod --set currentside|*      //set random side
  
:Moving selected tokens to the gmlayer:
+
//Controlled by
::'''''!token-mod''' --set layer|gmlayer''
+
!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
  
:Turning on aura1 for players, setting it's radius to 35, setting it's color to blue:
+
//Legacy DL examples
::'''''!token-mod''' --on showplayers_aura1 --set aura1_radius|35 aura1_color|0000ff''
+
!token-mod --set light_radius|40 light_dimradius|20 adv_fow_view_distance|30
  
:Setting up 5e style darkvision, moving to the objects layer, flipping the setting on show names, set bar1 to 25, set bar2 to 'Foe':
+
//Chaining multiple TokenMod commands
::!'''''token-mod''' --set light_radius|40 light_dimradius|0 layer|objects --flip showname --off light_otherplayers --set bar1_value|25 bar2_value|Foe''
+
!token-mod {{
 
+
  --set
I've carefully ignored status markers until now. Status markers have a more complicated syntax to allow more flexibility.
+
    represents|@{bob|character_id}
 
+
    bar1_link|hp
:Multiple status markers can be set at the same time, this will add the blue, green, red, padlock, and broken-shield status markers.
+
    bar2_link|speed
::'''''!token-mod''' --set statusmarkers|blue|green|red|padlock|broken-shield''
+
    bar3_link|ac
 
+
    controlledby|tom|sally|nancy
: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.)
+
    statusmarkers|blue:3|red:[[1d6]]
::'''''!token-mod''' --set statusmarkers|blue:0|green:3|red:9|padlock:7|broken-shield:8''
+
    defaulttoken
::'''''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:&#91;&#91;1d9]]|green:&#91;&#91;1d9]]|blue:&#91;&#91;1d9]]''
+
 
+
:Set hit points with this (sets both bar2_value and bar2_max to the result of the expression):
+
::'''''!token-mod''' --set bar2|&#91;&#91;3d8+4]]''
+
  
<br clear="all">
+
</pre>
  
=== Changelog ===
+
<br>
{{changelog version|0.8.1|2015-03-29|Added support for Multi-line commands via {{ }}, light_multiplier, startup version logging, and config API Button.
+
<br>
{{changelog version|0.7|2015-02-22|Added support for unlinking bars by passing an empty Attribute Name. (Thanks Ari K.!)-}}
+
[[Category:User API Scripts]]
{{changelog version|0.6|2015-02-20|Switched to git and pushed into the Roll20 Official repo as well. -}}
+
[[Category:Tokens]]
{{changelog version|0.54|2015-02-01|* Release}}
+

Revision as of 21:08, 31 January 2021

API ScriptAuthor: Aaron C. M.
Version: 0.8.57
Last Modified: 2020-06-10
Code: TokenMod
Dependencies: None
Conflicts: None

The Aaron's TokenMod API Script. TokenMod provides an interface to setting almost all changeable properties of a token.

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.

Examples

Some examples of !token-mod commands, with possible explanations. Texamples taken from the forum thread or in-game documentation.


!token-mod --on showname            // show nameplate
!token-mod --set layer|gmlayer      // move to gmlayer
!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 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)

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

//Sidenumber Multi-sided tokens
!token-mod --set currentside|2
!token-mod --set currentside|+      //shift side by 1
!token-mod --set currentside|*      //set 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

//Legacy DL examples
!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
}}