Tokens | Foundry Virtual Tabletop

Overview

The Token is a placeable object which visually represents Actors on the game Canvas. The Token displays the Actor's position, appearance, rotation, vision configuration, status effects, and more. Each Token is specific to Scenes in which it exists.

This document will familiarize you with the various options available to the tokens, and how to manipulate them. It will also detail the difference between a prototype and placed token, and how the token wildcard system works.

Token Configuration Options

The Token Configuration sheet features a large number of options spread out across five different tabs, each tab allowing you to modify certain aspects of the token. The options of each tab and their effects are explained in the following sections of this article.

Note that modifying these traits on a placed token will change them for only that token in the scene. To make changes to all future tokens placed from an actor, the prototype token must be configured first. The difference between placed and prototype tokens is explained here in this article.

Character Tab

Token Name

This determines the name which is shown for the token. When a new actor is created this defaults to whatever name that actor was given, but it can be changed to be different from the name.

Display Name

Configure the level of visibility for the token's nameplate. The following options are supported:

Never Displayed - The nameplate is not displayed at all.
When Controlled - The nameplate is displayed when the Token is currently controlled
Hovered by Owner - The nameplate is displayed when the token is hovered over by a User who owns the token's Actor
Hovered by Anyone - The nameplate is displayed when the token is hovered over by any User
Always for Owner - The nameplate is displayed at all times to any User who owns the token's Actor
Always for Everyone - The nameplate is displayed at all times to every User

Represented Actor

Specify which Actor in the world defines the Actor data which used by the Token.

Link Actor Data

When enabled, changes to the resource pools either on the base Actor or on the Token itself will reflect in the other location. These changes apply to tokens in all scenes, and as such it is best to only link tokens if their Actor is a unique character with only one instance of that Actor within any particular Scene. Alternatively, Tokens should not be linked when the Actor entry represents a generic creature or type of character. When data is not linked, each Token will have independent resources pools and turn order tracking.

Token Disposition

For non-player characters, setting a Token disposition allows for the colored border shown around a Token to be drawn in a different color which can differentiate enemies from allies during combat encounters. Neutral tokens have yellow borders, friendly tokens have teal borders, and hostile tokens have red borders.

Image Tab

Token Image Path

The file path to the artwork that is used for the Token. This file must be in the $UserData/Data/ directory or a publicly accessible web location.

Randomize Wildcard Images

If checked, the provided Token Image Path is treated as a wildcard pattern that is matched against multiple existing files. When a wildcard Token is configured, each time that Token is placed an image is randomly chosen from the matching set. Note that this can only be configured on prototype tokens. Once a token is placed in a scene the image used is set, it must then be changed manually by editing the in-scene token.

For a more detailed explanation of this feature, see the dedicated section later in this article.

Alternate Actor Tokens

If Randomize Wildcard Images is checked on a prototype token, this dropdown list appears when the token is placed into a scene. It provides a list of all available images which matched the wildcard you entered, and allows you to quickly select a specific image you want to use for that actor.

Width

The number of grid units in the horizontal dimension that this token occupies. A token which uses a single grid square would have a width of 1.

Height

The number of grid units in the vertical dimension that this token occupies. A token which uses a single grid square would have a height of 1.

Scale

A scaling ratio for the size of the Token's artwork. The token base size in grid units is unaffected by this value, but the visual size of the artwork is relative to that size and will change with scale. Numbers greater than 1 result in larger token artwork while numbers less than 1 result in smaller token artwork.

Mirror Horizontally

If this option is checked, the token artwork is flipped horizontally to "mirror" the Token's appearance.

Mirror Vertically

If this option is checked, the Token artwork is flipped vertically to "mirror" the Token's appearance.

Tint

This applies a hex color tint to the token's artwork as an overlay, and can either be entered directly or chosen using a color picker.

Position Tab

X-Coordinate: The current x-coordinate of the Token in a Scene. Directly editing this field on a token placed in a scene will change the token's position, but has no effect on prototype tokens, as these fields are automatically set when the token is placed into a scene
Y-Coordinate: The current y-coordinate of the Token in a Scene. Directly editing this field on a token placed in a scene will change the token's position, but has no effect on prototype tokens, as these fields are automatically set when the token is placed into a scene.
Elevation: The Token's current elevation in grid units which is displayed visually above the Token. This is used to indicate whether certain Tokens are flying or burrowing at an altitude that differs from what is standard for the Scene. Editing this on a prototype token has no effect, as the token starts at 0 elevation when placed into a scene.
Rotation: The Token's current direction of facing in degrees. Rotation of zero (the default) corresponds to a southward facing as this is the most commonly used convention for Token artwork. Editing this field on a prototype token determines the default rotation in degrees when it's placed into a scene. Tokens in a scene can also be rotated by holding down Shift and usind the W-A-S-D keys, the arrow keys, or the mousewheel. You can also hold down Control when using the mousewheel to get smaller icrements of rotation to more finely control a token's orientation.
Lock Rotation: If this setting is enabled the token cannot be rotated. This setting is typically ideal for portrait style tokens where the artwork orientation is more ideally fixed.

Vision Tab

Has Vision: This checkbox denotes whether the Token should be treated as a source of vision. If this is enabled, when the Token is controlled dynamic vision will be computed from the perspective of the Token. If this is disabled, the Token will not be a source of vision and no vision computations will occur as a result of controlling it. This setting, and other settings in the vision section, will only be used within a Scene which has Token Vision enabled.
Dim Vision: The visible radius with which the Token can see as if in dim light conditions.
Bright Vision: The visible radius with which the Token can see as if in bright light conditions. Please note that both this setting and the Dim Vision setting are radii with respect to the token location as the origin, so typically the Bright Vision radius is a smaller number than the Dim Vision setting.
Sight Angle: An angle of vision between zero and 360 degrees (the default) which represents the allowed field of view for this token. The computed angle of vision aligns to the direction of facing controlled by the rotation attribute.
Emit Dim Light: A radius of dim light emitted by this token that is visible by all other tokens.
Emit Bright Light: A distance of bright light emitted by this token that is visible by all other tokens. As with the above settings, these distances are radii with respect to the token center, so typically Emit Bright Light is a smaller number than the Emit Dim Light setting.
Emission Angle: An angle of light emission between zero and 360 degrees (the default) which represents the field of light that is emitted by this Token. The computed angle of emission aligns to the direction of facing controlled by the rotation attribute.
Light Color: Set the color of light that the Token emits in Hex (#000000).
Color Intensity: Adjusts how vivid the color of the light is from 0(faded) to 1(vibrant).
Animation Type: Select the style of animation shader to be applied to the light.
Animation Speed: The speed of the animation effect, from 0(slow) to 1(fast).
Animation Intensity: The intensity of the animation effect, from 0(subtle) to 1(intense).

Tokens with Shared Vision

If a User has permission to more than one token with vision, when no Token is controlled, the vision displayed will be the union of vision across all Tokens. If a User has a single Token controlled, their vision will be only what is visible to that one Token. If you select a single Token and want to go back to shared vision across all tokens just de-select it by one of the following methods:

Select an empty rectangle on the map.
Shift+click the token to remove it from the controlled set.
Press ESCAPE.
Left-click anywhere on the canvas. (if you have enabled "Left-click to Release Objects" from the Settings Menu)

Resources Tab

Display Bars

Configure the level of visibility for the token's resource bars. The following options are supported:

Never Displayed - Resource bars will not be shown
When Controlled - Resource bars are displayed when the Token is currently controlled.
Hovered by Owner - Resource bars are displayed to any User that owns the token's Actor when they hover their cursor over the token.
Hovered by Anyone - Resource bars are displayed to any User that overs their cursor over the token.
Always for Owner - Resource bars are displayed at all times, and visible to the Actor's owner.
Always for Everyone - Resource bars are displayed at all times, and visible to all Users.

Bar 1 Attribute

Select the attribute from the Actor's available data fields which should be displayed using the Token's primary resource bar.

Bar 1 Data

These fields are displayed for reference purposes only - you cannot configure the value of resource bars within the Token configuration as those are controlled by the Actor which the Token represents.

Bar 2 Attribute

Select the attribute from the Actor's available data fields which should be displayed using the Token's secondary resource bar.

Bar 2 Data

The Token Hud

Player Token HUD — The token hud allows you to make quick adjustments to a token's status.

Once a character has been placed onto the canvas as a token, a number of quick actions become available through the Token Heads Up Display that can bew viewed by right clicking on a token at any time. The specific functions are detailed below.

Resource Bars: If configured via the resource table, these bars provide a visual representation of resource attibutes. The system will govern what resources can be tracked and modified.
Resource Bar Inputs: Are used to change the value of the displayed resource bars. Clicking on the input and then adding a positive or negative number allows you to quickly increase or decrease the number presented.
Status Effects: This allows you to assign status effects to the token, which appear as small icons overlaid on the token art in the upper left corner. The specific art of the status effects are defined by whichever Game System is currently in use. Right clicking an icon creates a large overlay that covers the majority of the token. Tokens can only have one large overlay at a time.
Elevation: This provides a simple height indicator label that will appear above a token to indicate their current elevation in the measurement that the map is configured to use. This does not affect token vision at this time. Using positive and negative numbers in this field allows a user to quickly adjust the number instead of directly editing the elevation number.
Target: This allows a user to toggle a targeting indicator on the token.
Toggle Combat: If there is an active combat, clicking this button will place the token in the combat tracker. Clicking it a second time will remove the token from combat. When this is done, the token's initiative score (if it had one) is not retained.

Wildcard Token Images

Wildcard tokens provide a way for GMs to manage use of a single actor representing a diverse group of characters that all have the same attributes, or which do not necessarily require a fully linked actor sheet.

To configure Wildcard Tokens, access the token configuration menu and on the image tab, set the following options:

Token Image Path: The path to the folder containing the images you wish to have the token draw from. This should be set to something such as: /your/path/here/* for all images in the folder or /your/path/here/*.png for all files of the .png format in the folder. It can also include case sensitive options such as /your/path/here/Goblin* for all images that start with the word "Goblin."; It can also include a selection list, for specified options using /your/path/here/{Goblin_1,Goblin_2}.png to choose only between the Goblin_1.png or Goblin_2.png when the actor is placed into a scene. This can be combined with the asterisk as detailed above to further randomize how Foundry VTT selects tokens.

Randomize Wildcard Images: This checkbox enables Foundry to apply the wildcard filter to the path provided, when it is unchecked, Foundry will not apply any token if the path contains a *.

After placing a token that has the Randomize Wildcard Image option set, you can change the token from a convenient list of other tokens in that folder. To do so, right click the token you wish to change and on the image tab simply select a different image from the Alternate Actor Tokens selection menu.

Prototype vs. Placed Tokens

An important concept to understand when working with Tokens is the difference between a Prototype Token and a placed Token.

Prototype Tokens

A Prototype Token is the configuration of a Token for a particular Actor before that Token has been placed onto the game canvas. The prototype defines the default setup that a newly created Token starts with. To configure the Prototype Token for an Actor, open the Actor Sheet and click the Prototype Token button in the top bar.

Placed Tokens

Once a Token is placed, it becomes its own independent copy of the prototype. For example - a Prototype Token for a player character could be configured to have a certain vision distance - but when that Token is placed into a Scene that has different lighting conditions, the placed copy of the Token could be changed to increase or decrease visibility for that scene. To configure a placed Token, right click on the Token to display the Token HUD and click the gear icon to open that Token's configuration sheet, or double right-click the token.

Tokens - Prototype Token Example — The highlighted areas indicate the differences between a prototype token and a token placed into a scene, while the arrow indicates the title difference between both windows.

API References

To interact with Tokens programmatically, consider using the following API concepts:

The Token Object
The TokenLayer Canvas Layer
The TokenConfig Application
The TokenHUD Interface

Additionally, the wildcard system for token images utilizes the minimatch library.

Official minimatch documentation