The Tokens Layer

The Tokens Layer is the middle layer of the tabletop Canvas and it contains all the Sprites which represent actors within the game space. Tokens are placed onto the Tokens Layer by dragging actors from the Actors Directory (in the right sidebar) onto the canvas.

The Token Layer

All tokens which are rendered on the canvas are drawn as children of the TokenLayer(). The token layer may be accessed globally as canvas.tokens and provides the following API.

class TokenLayer()

The Token Container subclass of the PlaceablesLayer


type: string

Remember the last drawn wildcard token image to avoid repetitions


Immediately conclude the animation of any/all tokens


type: Array

An Array of tokens which are currently controlled

TokenLayer.cycleTokens(direction, reset)

Cycle the controlled token by rotating through the list of Owned Tokens that are available within the Scene Tokens are currently sorted in order of their TokenID

  • direction (Boolean) – Which direction to cycle. A “truthy” value cycles forward, while a “falsey” value cycles backwards.
  • reset (Boolean) – Restart the cycle order back at the beginning?

Boolean – A flag for whether token control was cycled


type: Array

Define the source data array underlying the placeable objects contained in this layer


Override the deactivation behavior of this layer. Placeables on this layer remain visible even when the layer is inactive.

TokenLayer.dropActor(actor, tokenData)

Drop the Token representing an Actor on the canvas at a specific position

  • actor (Actor) – The ID of the Actor whose token should be dropped
  • tokenData (Object) – An objet of additional Token data with which to override the Actor prototype

Token objects on this layer utilize the TokenHUD


Customize behaviors of this PlaceablesLayer by modifying some behaviors at a class level


type: Array

An Array of tokens which belong to actors which are owned


type: PIXI.Container

Define a Container implementation used to render placeable objects contained in this layer


Select all the tokens within a provided set of rectangular coordinates. Control any tokens within the area which you are able to control based on token permissions. See the parent PlaceablesLayer.selectObject method for more details

TokenLayer.targetObjects(x, y, width, height, releaseOthers)

Target all Token instances which fall within a coordinate rectangle.

  • x (number) – The top-left x-coordinate of the selection rectangle
  • y (number) – The top-left y-coordinate of the selection rectangle
  • width (number) – The width of the selection rectangle
  • height (number) – The height of the selection rectangle
  • releaseOthers (boolean) – Whether or not to release other targeted tokens

number – The number of Token instances which were targeted.

The Token Object

As a mod developer, you may find yourselves wanting to interact with the tokens which are active within a Scene() and are drawn within the TokenLayer(). The Token() class provides a rich API for interacting with these tokens.

class foundry.Token(data, scene)

An instance of the Token class represents an Actor within a viewed Scene on the game canvas. Each Token is reference using a numeric id which indexes its position within the scene. See the initialization signature of the parent PlaceableObject class for more details.

  • data (Object) – An object of token data which is used to construct a new Token.
  • scene (Scene) – The parent Scene entity within which the Token resides.

Draw the token’s nameplate as a text object

Returns:PIXI.Text – The Text object for the Token nameplate

A generic transformation to turn a certain number of grid units into a radius in canvas pixels

  • units (Number) – The radius in grid units

number – The radius in canvas units


type: Boolean

Provide a temporary flag through which this Token can be overridden to bypass any movement animation

foundry.Token._onCreate(sceneId, tokenData)

Handle token creation requests, adding the new token to the Scene data For active Scenes, also draw a new Token onto the canvas

  • sceneId (String) – The ID of the scene where the token is being created
  • tokenData (Object) – The data object from which to create the new token

Handle token deletion requests, deleting the token by ID from the Scene data For active Scenes, also remove the Token container from the canvas

  • sceneId (String) – The ID of the scene where the token is being created
foundry.Token._onUpdate(sceneId, data)

Update the Token with new data and push that update back to the server.

New token data is either generated by the client or provided from the server through the updateToken socket. If the updated data is originated locally, it can be pushed back to the server and emitted to other clients.

  • sceneId (String) – The ID of the scene where the token is being created
  • data (Object) – The data object from which to update new token

type: Actor

An Actor entity constructed using this Token’s data If actorLink is true, then the entity is the true Actor entity Otherwise, the Actor entity is a synthetic, constructed using the Token actorData


Animate Token movement along a certain path which is defined by a Ray object

  • ray (Ray) – The path along which to animate Token movement

The radius of bright light that the Token emits


Translate the token’s bright light distance in units into a radius in pixels.


type: Boolean

Does the current user have at least LIMITED permission to the Token

type: Object

The Token’s current central position

foundry.Token.checkCollision(destination, drag)

Check for collision when attempting a move to a new position

  • destination (Object) – An Object containing data for the attempted movement
  • drag (Boolean) – Whether we are checking collision for a drag+drop movement

Boolean – A true/false indicator for whether the attempted movement caused a collision


Compute the field-of-vision for an object, determining its effective line-of-sight and field-of-vision polygons

Returns:Object – An object containing the rays, LOS polygon, and FOV polygon for the light
foundry.Token.control(multiSelect, releaseOthers, initializeSight)

Assume control over a PlaceableObject, flagging it as controlled and enabling downstream behaviors See PlaceableObject.control() for full details

  • multiSelect (Boolean) – Is this object being selected as part of a group?
  • releaseOthers (Boolean) – Release any other controlled objects first
  • initializeSight (Boolean) – Reinitialize the sight layer

Boolean – A Boolean flag denoting whether or not control was successful.

foundry.Token.delete(sceneId, options)

Delete a Token from a specific Scene. Extend the default Token deletion request to also request deletion for any combatants linked to this token This extension occurs before the request is submitted to the Database. See PlaceableObject.delete() for the parent implementation.

  • sceneId (String) – The ID of the Scene within which to update the placeable object
  • options (Object) – Additional options which customize the deletion workflow

Promise – A Promise which resolves to the returned socket response (if successful)


The radius of dim light that the Token emits


Translate the token’s sight distance in units into a radius in pixels.


Draw the token, returning a promise once the token’s texture is loaded


Draw the active effects and overlay effect icons which are present upon the Token


Draw a text tooltip for the token which can be used to display Elevation or a resource value


type: Boolean

Test whether the Token emits light (or darkness) at any radius


type: PIXI.Polygon

The Token’s most recently computed field-of-vision polygon


A helper method to retrieve the underlying data behind one of the Token’s attribute bars

  • barName


foundry.Token.getCenter(x, y)

Get the center-point coordinate for a given grid position

  • x (Number) – The grid x-coordinate that represents the top-left of the Token
  • y (Number) – The grid y-coordinate that represents the top-left of the Token

Object – The coordinate pair which represents the Token’s center at position (x, y)


Return the token’s sight origin, tailored for the direction of their movement velocity to break ties with walls


type: Number

Translate the token’s grid height into a pixel height based on the canvas size


Is the HUD display active for this token?


type: Boolean

Test whether the Token has a limited angle of vision or light emission which would require sight to update on Token rotation


type: Boolean

Test whether the Token has sight (or blindness) at any radius


type: Boolean

An indicator for whether or not this token is currently involved in the active combat encounter.


type: Boolean

Determine whether the Token is visible to the calling user’s perspective. If the user is a GM, all tokens are visible If the user is a player, owned tokens which are not hidden are visible Otherwise only tokens whose corner or center are within the vision polygon are visible.


type: PlaceablesLayer

Provide a reference to the canvas layer which contains placeable objects of this type


type: PIXI.Polygon

The Token’s most recently computed line-of-sight polygon

type: String

Convenience access to the token’s nameplate string


A Boolean flag for whether the current game User has permission to control this token


Update display of the Token, pulling latest data and re-rendering the display of Token components


Release control over a PlaceableObject, removing it from the controlled set See PlaceableObject.release() for full details

  • resetSight (Boolean) – Trigger a re-initialization of the sight layer, this may not be necessary

Boolean – A Boolean flag confirming the object was released.


Extend the PlaceableObject.rotate method to prevent rotation if the Token is in the midst of a movement animation

foundry.Token.setPosition(x, y)

Set the token’s position by comparing its center position vs the nearest grid vertex Return a Promise that resolves to the Token once the animation for the movement has been completed

  • x (Number) – The x-coordinate of the token center
  • y (Number) – The y-coordinate of the token center

Promise – The Token after animation has completed

foundry.Token.setTarget(targeted=true, user, releaseOthers)

Set this Token as an active target for the current game User

  • targeted (boolean) – Is the Token now targeted?
  • user (User|null) – Assign the token as a target for a specific User
  • releaseOthers (boolean) – Release other active targets for the same player?

type: TokenConfig

Provide a singleton reference to the TileConfig sheet for this Tile instance

foundry.Token.shiftPosition(dx, dy)

Perform an incremental token movement, shifting the token’s position by some number of grid units. The offset parameters will move the token by that number of grid spaces in one or both directions.

  • dx (Number) – The number of grid units to shift along the X-axis
  • dy (Number) – The number of grid units to shift along the Y-axis



type: Set.<User>

Track the set of User entities which are currently targeting this Token


Add or remove the currently controlled Tokens from the active combat encounter


Toggle an active effect by it’s texture path. Copy the existing Array in order to ensure the update method detects the data as changed.

  • texture (String) – The texture file-path of the effect icon to toggle on the Token.

Set or remove the overlay texture for the Token by providing a new texture path

  • texture (String) – The texture file-path of the effect to set as the Token overlay icon



Toggle the visibility state of any Tokens in the currently selected set


type: Number

Translate the token’s grid width into a pixel width based on the canvas size