Tokens | Foundry Virtual Tabletop

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.

Token Configuration Modes

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

Prototype Token Configuration

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 Token Configuration

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.

Token Configuration Options

The Token Configuration sheet features the following options which are shown in the above image and explained in the table below.

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.

Token Image Path

The file path to the artwork that is used for the Token. This file must either be served locally from within the public directory or from some 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.

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.

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).

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

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/*: or
/your/path/here/*.png: . It can also include case sensitive options such as
/your/path/here/Goblin*: .
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.

Frequently Asked Questions

How can I allow players to have shared vision across multiple Tokens?

This can be accomplished by ensuring the player or players have Observer or Owner permission to each of the Actors. 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)

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