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 Token(data)

An instance of the Token class represents a character token rendered on the game canvas. Each Token is reference using a numeric id which indexes its position within the scene.

  • data (Object) – An object of token data which is used to construct a new Token.
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
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

If this token modifies an actor entry, retrieve it


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


Test whether the current User is able to view the Token resource bars


Test whether the current User is able to view the Token nameplate

Token position is defined by the top-left coordinate of the token’s image However, for some calculations it is useful to have coordinates for the token’s center. This attribute returns a object of coordinates x and y representing the center of the token’s icon.


Check for collision when attempting a move to a new position

  • moveData (Object) – An Object containing data for the attempted movement

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


Copy the Token, returning a new PIXI.Container with identical attributes The returned Token is non-interactive, and has no Id If you plan to use it permanently you should emit a tokenCreate event

Returns:Token – A new non-interactive Token sprite

Assume control over the Token, allowing for drag, movement, or rotation events to occur.

  • options (Object) – Optional parameters which customize how control of the Token is acquired.
  • options.releaseOthers (Boolean) – Release any other controlled tokens first
  • options.initializeSight (Boolean) – Reinitialize the sight layer

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


The icon rotation of a token is typically expressed in radians. For some use cases it is convenient to express that rotation in degrees.


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


Draw the Token completely from scratch


Draw the token resource bar, if enabled

Returns:PIXI.Container – The resource bars for the Token

Draw rectangular token border

  • color (Number) – A hex color code

PIXI.Graphics – The rectangular Token border


Draw the quick controls menu to the right side of the token. Quick controls allow for the following actions:

  1. Toggle token visibility
  2. Add or remove token status effects
  3. Add or remove the token from the current combat encounter
Returns:PIXI.Container – A container which includes the Token quick control icons as children

Draw a container for token status effects on the left side of the Token


Draw the token icon

Returns:PIXI.Sprite – The sprite icon for the token

Draw the token’s nameplate as a text object

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

Draw the token overlay icon which may optionally display a single overlay effect


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


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


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 which are within the vision polygon are visible.


type: PlaceablesLayer

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

Token.limitMovement(start, end)

Given a requested movement position, return an equivalent object with x and y coordinates limited by the token’s visible radius.

  • start (Object) – The initial location
  • end (Object) – The attempted destination

Object – The allowed movement coordinates

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


Release player control of the token, unsubscribing to drag, movement, or rotation events. Return a Boolean for whether the token release was successful.

  • resetSight (Boolean) – Trigger a re-initialization of the sight layer, this may not be necessary
Token.rotate(delta, snap=false)

Incrementally shift the token’s rotation by some delta degrees

  • delta (Number) – An offset of rotation in degrees
  • snap (Boolean) – Snap rotation to the closest 45 degree increment

Start from facing south [0, 1] with angle 0 Work clockwise, moving first to south-west [-1, 1]

  • offsets (Array) – The keyboard offset directions in which movement is requested
Token.setPosition(x, y)

Set the token’s position by comparing its center position vs the nearest grid vertex

  • x (Number) – The x-coordinate of the token center
  • y (Number) – The y-coordinate of the token center
Token.setRotation(angle, snap, push)

Set the token’s rotation by providing an angle in degrees, internally converting to the radians that PIXI uses

  • angle
  • snap
  • push

Modify the token’s current visibility. Tokens which are hidden are only visible to GM users.

  • hidden (Boolean) – The new visibility status which should be applied to the token.
Token.shiftMany(dx, dy)

Move many Tokens simultaneously, avoiding unnecessary re-draws of the Sight layer This moves all tokens individually using the Token.shiftPosition method and passes the noSight argument to update

  • 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
Token.shiftPosition(dx, dy, ...args)

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
  • args (*) – Additional arguments forwarded on to Token.update

Add current Token to, or remove from the current set of combat participants

Token.toggleControl(control, isActive)

Toggle the control buttons active state - rendering the icon and border differently for active vs. inactive

  • control (PIXI.Container) –
    The control icon to toggle the appearance for
  • isActive (Boolean) –
    The new active state for the control

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

type: Number

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