The token action gives you some options to display stats of tokens in Foundry, and can be set up to do some things when you press the button, for example center the view on that token, or open the token's character sheet.
See the image below for an example on how to set up a token control screen.
Only the top row is set up using the token action, the other are set up using the Macro and Move actions.
Button functions in the top row, from left to right:
- Back - Exits this folder to go back to the home page of the profile
- 2x empty
- Display name and icon
- Display HP
- Display AC
- Display movement speed
- Display initiative
Game Systems
The Stream Deck application automatically detects what game system you're using, as long as Foundry is running and connected. If not, it will default to DnD 5e. In the module settings it is possible to configure a system override, which will force MD to use a specific system.System-specific options, such as the some 'stats' or 'on-click' options, can result in blank fields in the property inspector, when switching from a system that supports them to one that doesn't.
Overview
Token Selection
The first 2 options ('Page-Wide Token' and 'Token') determine which token (or actor) will be used for the action. Using the 'Token' dropdown menu, you can select between the following options:- Selected Token: The currently selected token
- Token Name: Specify the token name in the 'Name' box
- Actor Name: Specify the actor name in the 'Name' box
- Token Id: Specify the token id in the 'Id' box
- Actor Id: Specify the actor id in the 'Id' box
Token/Actor Name
Fill in the complete token or actor name. The first token or actor with that name that the module finds will be selected.Token/Actor Id
Each token and actor has a unique id, using this you can be sure that the correct token/actor is selected.To find the token/actor id, open the console (press F12, make sure you're in the 'Console' tab). At the bottom there should a a field where you can write commands. First select the token you want the token or actor id from and enter the following in the field:
console.log("Token id:", game.canvas.tokens.controlled[0].id, " Actor id:", game.canvas.tokens.controlled[0].actor.id)
It should return something like:
Token id: dQI2JudPTjw9j738 Actor id: HmrqCnyhEMvb0aDR
, where the first 'code' is the token id and the second is the actor id. Fill this in in the 'Id' field in the Stream Deck app.
Page-Wide Token
All 'Token' actions with 'Page-Wide Token' enabled, will use the same token, so if you change, for example, the token name, this will change for all those actions. This allows for you to quickly reconfigure a page, or use the 'Set Page-Wide Token' 'On Click' option to change the token selection using a button press.You could, for example, populate the top row of your Stream Deck with all PC tokens (by selecting those tokens by name), and configure them all to set the page-wide token to their token. If you then populate the rest of the Stream Deck with other 'Token' actions, you can quickly change what token the buttons are applied to.
Mode
The Token Action has multiple modes to select from:- Token: Display token stats, and perform on click actions such as moving the token or rolling for skill checks
- Inventory: Display an inventory item and perform rolls using that item
- Features: Display a token feature and perform rolls using that feature
- Spellbook: Display a spell and roll for that spell
- Offsets: Allows you to configure an offset so you can scroll through more items, features and spells
Token Mode
The Token mode can be used to display stats of a token or actor, such as its hit points, armor class or ability scores. You can configure the stats to display, and what to do when you click the button.Prepend Title
Material Deck gives you the option to display text on the Stream Deck buttons, for example the statistics like HP. If 'Display Name' has been selected, the name of the token will always be displayed first followed by the selected statistic, for example:Akra 4/9
Where 'Akra' is the token name and '4/9' is the current and max HP.
Using the 'Prepend Title' field, you can add some text before the statistic. So if you were to fill in
HP: , the resulting text would be:
Akra HP: 4/9
Stats
With the 'Stats' dropdown menu, you can select what to display on the button.The stats that are available will depend on the game system, and will usually include the most important stats of that system. Other stats that are not available can be added using the 'Custom' option.
Custom Stats
By selecting 'Custom', you can enter a formula to get any stat from a token by filling in the path the the desired stat (from the token or actor object).For example, to get the strength modifier in dnd5e, you'd use the path:
actor.system.abilities.str.mod
Any stat you want to display needs to be prefixed by '@', and surrounded by square brackets '[' and ']'.
So for the strength modifier, you'd fill in:
[@actor.system.abilities.str.mod].
You can add text around it:
STR: [@actor.system.abilities.str.mod]
And use multiple stats:
STR: [@actor.system.abilities.str.mod] DEX: [@actor.system.abilities.dex.mod]
Besides actor data you can also get token data, for example the token name:
[@token.name]
Or the token's sight:
[@token.document.sight.range] Ft.
You can also perform a simple 'if' comparison. For example, if you want the Stream Deck to display 'Token is strong' when a token has a strength modifier of 3 or higher and 'Token is weak' for lower than 3, you could use the following formula:
`Token is [if(@actor.system.abilities.str.mod >= 3) then(strong) else(weak)]`
Or to display the highest value of either the wisdom or intelligence:
`[if(@actor.system.abilities.wis.mod > @actor.system.abilities.int.mod) then(@actor.system.abilities.wis.mod) else(@actor.system.abilities.int.mod)]`
You can use the following comparison operators: `==`, `<`, `>`, `<=`, `>=`
'if then' statements and nested if statements are not supported.
On Click
Using 'On Click', you can perform something by pressing the button.Most should be self-explanatory, but some are described below.
Custom On Click
Please note that this function is quite powerful, but can seriously mess up tokens and actors if you're not careful with the targets. Please make sure you fill in the correct path and create a test character to test it out on first!By selecting 'Custom', you can modify a value in the token or actor object. When you select 'Custom' you will get a new 'Formula' input box.
In 'Formula' you can fill in the desired formula. You can use the following:
- Numbers - Any number you want
- Token and actor data - see below
- Macros - see below
[@this]- gets the value of 'target', see below;- separates multiple formulas/macros=- sets the target on the left of '=' to the value on the right++- add 1--- subtract 1+- addition-- subtraction*- multiplication/- division**- exponentiation%- modulus<,<=,>,>=- limit the value- Strings - see below
Forget about the proper order of operations, any operation is performed from left to right. Each operation must be separated by an empty space. A properly formatted formula has a 'target' in the form of token or actor data, followed by a '=', followed by either a value or a function.
Token and actor data is the path the the desired data (from the token object).
For example, to get the hit points in dnd5e, you'd use the path actor.system.attributes.hp.value.
Any path you want needs to be prefixed by '@', and surrounded by square brackets '[' and ']'.
So in for the hp you'd fill in [@actor.system.attributes.hp.value]
[@this] is a shorthand for whatever data path you have to the left of the '=' sign.
Here are some examples:
Set the walking speed to 25 feet: [@actor.system.attributes.movement.walk] = 25
Increment the HP by 1: [@actor.system.attributes.hp.value] = [@this] ++
Increment the HP by 1 but limit to the max hp: [@actor.system.attributes.hp.value] = [@this] ++ <= [@actor.system.attributes.hp.max]
Set the AC to 10 plus the DEX modifier: [@actor.system.attributes.ac.value] = 10 + [@actor.system.abilities.dex.mod]
Currently you cannot use shorthand notation such as [@actor.system.attributes.hp.value] ++ or [@actor.system.attributes.hp.value] += 1. Instead you will need to use one of the following methods:
[@actor.system.attributes.hp.value] = [@actor.system.attributes.hp.value] ++
[@actor.system.attributes.hp.value] = [@actor.system.attributes.hp.value] + 1
[@actor.system.attributes.hp.value] = [@this] ++
If you want to modify string data, such as a token name, any part to the right of '=' should not contain any maths, or you might get unexpected results.
If the string contains any empty spaces, you must surround the string with square brackets '[' and ']'.
So, for example, to set the token name: [@actor.name] = John or [@actor.name] = [John Doe]. Setting it to [@actor.name] = John Doe will not work.
You can trigger macros using @macro macroName.
If you have The Furnace enabled, you can use The Furnace's advanced macros and call arguments. You can do this by simply adding the arguments after the macro name. For example, let's say you have the following macro to move the selected token x and y gridspaces, named 'moveToken':
const newPosition = {
x: token.x + args[0]*canvas.grid.size,
y: token.y + args[1]*canvas.grid.size
};
await token.update(newPosition);
You would use, for example: @macro moveToken 1 0 to move the token 1 gridspace in the x direction.
If the name of you macro or any of the arguments has spaces in it, you have to surround the name with square brackets '[' and ']'. For example, if you macro is named Test Macro, you use @macro [Test Macro].
You can set multiple formulas or multiple macros to the same button by separating them with ';'. So you can increment the HP by 1 and set the walking speed to 25 feet with:
[@actor.system.attributes.movement.walk] = 25 ; [@actor.system.attributes.hp.value] = [@this] ++
Or increment the HP by 1 and call the macro 'moveToken':
[@actor.system.attributes.hp.value] = [@this] ++ ; @macro moveToken 1 0
Move Token
Select a direction for the token to move to. The token will move 1 grid space in that direction when the button is pressed.Rotate Token
You can rotate the token in one of two ways: Rotate to Value: Set a value in degrees in the 'Value' field and the token will rotate to that value. For example, 0 is the normal orientation, 90 is rotated 90 degrees. Rotate by Value: Set a value in degrees in the 'Value' field and the token will rotate that value relative to it's current rotation. For example, if it is currently rotated 90 degrees, setting the value to -10 will rotate it to 80 degrees.Set Vision & Light
If 'Set Vision' was selected at 'On Click', a lot of vision settings appear. They behave identical to the settings in the Vision tab the Token Configuration screen in Foundry. Refer to the Token Configuration to find out what each setting does.Selection Boxes
The selection boxes all have a 'No Change' option. Selecting this will prevent that setting from being updated when pressing the button. Setting it to anything else will perform a change.Number Fields
If no value is filled in, that value is not updated, so it is possible to set, for example, the 'Dim Light Radius' without affecting the 'Dim Vision' setting by keeping the 'Dim Vision' field empty.Sliders & Color Selectors
Sliders and color selectors have a checkbox to their right. The values/color is only updated if that checkbox is selected.Set Token Wildcard Image
You can change the token image if you use the wildcard image option that foundry provides click [here](https://foundryvtt.com/article/tokens/) for more info on how to set up wildcard images.When you set 'On Click' to 'Set Token Wildcard Image' you get the two new boxes in the PI: 'Wildcard Image' and 'Value'.
With 'Wildcard Image' you select what you want the button to do.
If it is set to 'Iterate Image' it will change the token image to a next one in the wildcard image list. How many images it iterates is set with the 'Value' input box.
If you set 'Wildcard Image' to 'Set Image', it will set the image to the n'th image of the list, where 'n' is set using the 'Value' input box.
By setting 'Wildcard Image' to 'Offset', you can offset the selected image by 'Value'. So if on one button you have 'Wildcard Image' set to 'Set Image' and 'Value' set to n, after pressing the button set to 'Offset', n will be n plus the offset value.
Toggle Condition
Select a condition and toggle it on or off with the button. The 'Remove All' option removes all conditions from the token.Some systems also give you the option to increase or decrease the condition.
Toggle CUB Condition
The Combat Utility Belt module gives you greater flexibility when it comes to conditions, such as adding custom conditions. To toggle one of these conditions, fill in the name of the condition in the 'Condition Name' field.Dice Roll
Select a roll and roll it by pressing the button. The type of rolls and roll modes depend on the system.Usually you can select abilities, saves and skills.
Roll Mode
The types of roll modes available depend on the system.For example, for dnd5e, you have the following options:
- Default: Rolls as is default in Foundry, opening a dialog box for further selection
- Normal Roll: Roll normally (no advantage or disadvantage), skip the dialog box
- Advantage: Roll with advantage, skip the dialog box
- Disadvantage: Roll with disadvantage, skip the dialog box
Inventory, Features & Spellbook Modes
The 'Inventory', 'Features' and 'Spellbook' modes all function similarly, where they allow you to display (and roll) an item, feature or spell from the token.Type/Spell Level
'Type' allows you to filter the selection down to, for example, weapons, active abilities, or level 2 spells. The available options depend on the 'Mode' and gaming system.Selection
Here you can specify how the item, feature or spell is selected.- Order: Select a nr in the 'Nr' field, the item in that position of the iteam/feature/spell list will be selected (ordered as they appear in the character sheet)
- Name: Fill in the item/feature/spell name in the 'Name' field, and the first item with that name will be selected
- Id: Fill in the item/feature/spell id in the 'Id' field, and the item with that id will be selected
Display Uses/Quantity
Enabling this will display a box at the bottom of the button, displaying either the uses of a feature or spell, or the quantity of the item.Display Name
Enabling this will display the name of the item/feature/spell on the Stream DeckDisplay Icon
Enabling this will display the icon of the item/feature/spell on the Stream DeckOffsets
Offsets can be used to scroll through the items, features or spells, for items/features/spells that have 'Selection' set to 'Order'.Item Absolute Offset
Set the offset using the 'Offset' field. This will add the 'Offset' value to the 'Nr' field of the selection.Item Relative Offset
Set the offset using the 'Offset' field. Everytime you press the button, the offset increases or decreases by that value.Display Item Offset
Display the current offset on the Stream Deck.Prepend Title
Add text in front of the item offset value.On Color
Sets the color of the ring that's shown on the button when the offset is set to the value set in the offset box.Off Color
Sets the color of the ring that's shown on the button when the offset is set to the value set in the offset box.Icon, Name & Background
Icon
Selects which icon should be displayed on the button:- None: Display no icon
- Token Icon: Display the token icon
- Actor Icon: Display the actor icon
- Default: Display a 'default' icon, depending on the 'stat' option. For example, the 'HP' stat will display a heart, while the 'Speed' stat will display boots