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.

If this token modifies an actor entry, retrieve it


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

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.

Token.createToken(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

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


Delete a token from the board and push that update to other connected clients

Token.deleteToken(sceneId, tokenId)

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
  • tokenId (Number) – The token ID to delete from the Scene

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


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


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


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


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.

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


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 TODO: If the token is in the middle of a moment animation, do not push the rotation change to the server

  • delta (Number) – An offset of rotation in degrees
  • snap (Boolean) – Snap rotation to the closest 45 degree increment
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.
Token.update(data, push=false, options)

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.

  • data (Object) – The data object from which to update the token
  • push (Boolean) – Push the token update to the server
  • options (Object) – Additional options which customize the way the token is updated

Array – An array of the keys of Token data which were updated. This is potentially useful for downstream mods which extend Token behavior to know what was changed during the update.

Token.updateToken(sceneId, tokenData)

Handle Token update requests, updating the Scene data For active Scenes also draw the Token update on 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