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.

Arguments:
  • data (Object) – An object of token data which is used to construct a new Token.
Token.actor

If this token modifies an actor entry, retrieve it

Token.brightRadius

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

Token.center

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.

Token.checkCollision(moveData)

Check for collision when attempting a move to a new position

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

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

Token.checkSight(position)

Check the token sight to determine its visibility polygon

Arguments:
  • position (Object) – Optionally, check sight for a given target position, instead of the token’s center
Token.clone()

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
Token.combatPosition

Return this token’s index position in Array of current combat participants, if any.

Token.control(releaseOthers=true)

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

Arguments:
  • releaseOthers (Boolean) – Optionally, you may force any other controlled tokens to be released.
Returns:

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

Arguments:
  • 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
Token.degrees

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

Token.delete()

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

Arguments:
  • sceneId (String) – The ID of the scene where the token is being created
  • tokenId (Number) – The token ID to delete from the Scene
Token.drawBar()

Draw the token resource bar, if enabled

Token.drawBorder(color)

Draw rectangular token border

Arguments:
  • color (Number) – A hex color code
Returns:

PIXI.Graphics – The rectangular token border

Token.drawControls()

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
Token.drawEffects()

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

Token.drawIcon()

Draw the token icon

Returns:PIXI.Sprite – The sprite icon for the token
Token.drawNameplate()

Draw the token’s nameplate as a text object

Token.inCombat

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

Token.isVisible

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.

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

Object – The allowed movement coordinates

Token.owner

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

Token.release()

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

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

Arguments:
  • delta (Number) – An offset of rotation in degrees
  • snap (Boolean) – Snap rotation to the closest 45 degree increment
Token.setPosition(x, y, snap=true)

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

Arguments:
  • x (Number) – The x-coordinate of the token center
  • y (Number) – The y-coordinate of the token center
  • snap (Boolean) – Snap the token to the nearest grid square
Token.setRotation(angle, snap, push)

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

Arguments:
  • angle
  • snap
  • push
Token.setVisibility(hidden)

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

Arguments:
  • hidden (Boolean) – The new visibility status which should be applied to the token.
Token.shiftPosition(offsetX, offsetY, push=true)

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.

Arguments:
  • offsetX (Number) – The number of grid units to shift along the X-axis
  • offsetY (Number) – The number of grid units to shift along the Y-axis
  • push (Boolean) – Whether or not to push the updated token position to other connected clients
Token.sightRadius

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

Token.toggleCombat()

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

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

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.

Arguments:
  • texture (String) – The texture file-path of the effect icon to toggle on the Token.
Token.update(data, push=false)

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.

Arguments:
  • data (Object) – The data object from which to update the token
  • push (Boolean) – Push the token update to the server
Returns:

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

Arguments:
  • 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