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 Configuration - Identity Tab
This tab controls what actor data is associate with the token.

Appearance Tab

Token Configuration - Appearance Tab
This tab controls the art used for the token and how it appears.

Vision Tab

Token Configuration - Vision Tab
This tab allows you to control a token's vision.

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

Token Configuration - Light Tab
This tab allows you to manipulate a token's light emission.

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

Token Configuration - Resources Tab
This tab determines what attributes from the actor sheet are tracked on the token.

The Token HUD

Player Token HUD
The token HUD (Head-Up Display) allows you to make quick adjustments to a token's status on the fly.

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.

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.

Tokens - Prototype vs. Placed
Prototype token configuration (orange outline) versus placed token configuration (purple outline) differs slightly in terms of available options.

API References

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

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