Tokens

Overview

The Token is a placed 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.

Identity 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.
• 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. The dropdown list of options is drawn from the available actors in the game world.
• 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 all linked tokens in all scenes, and is best used for unique or named characters. It's not recommended to link actor data for generic creatures or types of character (such as bandits). When data is not linked, each Token will have independent resources pools and turn order tracking.
• Coordinates (Pixels): (Placed Tokens Only) The current horizontal X position and vertical Y position of the Token in a Scene. Directly editing these fields on a token placed in a scene will change the token's position, these fields are automatically set when the token is placed into a scene or moved during play.
• Elevation (Distance): The Token's current elevation in grid units distance 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 (Degrees): 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 using the W-A-S-D keys, the arrow keys, or the mouse wheel. You can also hold down Control when using the mouse wheel to get smaller increments 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.
• Token Disposition: Sets the color of the border shown around a Token when it's selected or hovered over with a mouse cursor. Disposition is used to differentiate enemies from allies during combat encounters. Neutral tokens have yellow borders, friendly tokens have teal borders, and hostile tokens have red borders.

Appearance 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: (Prototype Tokens Only) 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. Please see below for more information on using image wildcards.
• Alternate Actor Tokens: (Placed Tokens Only) If Randomize Wildcard Images is checked on a prototype token, this dropdown list appears in the token config window for the placed actor. This list provides 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.
• Dimensions (Grid Units): The number of grid units this token occupies. A token which uses a single grid square would have a width and height of 1.
• Scale (Ratio): 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 Image:: This option provides two check boxes which determine if the token artwork is flipped horizontally or vertically, based on which boxes are checked.
• 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.

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 vision enabled.
• Vision Radius (Grid Units): Sets the radius with which the Token can see. The Dim field acts as though their vision range is a dim light only they can see, while the Bright field provides a vision radius with which the Token can see as if in bright light conditions. Please note that both settings are radii with respect to the token location as the origin, so typically the Bright Vision radius should be a smaller number than the Dim Vision setting.
• Vision Angle (Degrees): 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.

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, and any other tokens will have their vision hidden.

Lighting Tab

This tab is broken down into three sub-tabs which determine the appearance and reach of the token's light emission. The settings here are identical to those found in the ambient lighting tools, please refer to Lighting for an in-depth explanation of the various options available.

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

The Token HUD

Once a character has been placed onto the canvas as a token, a number of quick actions become available through the Token Head-Up Display that can be 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 attributes. 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 appearance tab, tick the Randomize Wildcard Images toggle. Then configure the image path to use wildcards.

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.

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

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.

API References

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

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

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

• Official minimatch documentation