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

TokenLayer.concludeAnimation()

Immediately conclude the animation of any/all tokens

TokenLayer.controlledTokens

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

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

Boolean – A flag for whether token control was cycled

TokenLayer.dataArray

type: Array

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

TokenLayer.deactivate()

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

TokenLayer.draw()

Draw the TokenLayer. Draw each contained Token within the scene as a child of the objects container

Returns:TokenLayer
TokenLayer.drawSelect(event)

Draw the select rectangle given an event originated within the base canvas layer

Arguments:
  • event
TokenLayer.gridPrecision

Tokens should only snap to the grid at whole unit intervals

TokenLayer.ownedTokens

type: Array

An Array of tokens which belong to actors which are owned

TokenLayer.placeableClass

type: PIXI.Container

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

TokenLayer.releaseAllTokens(resetSight)

Release control of all tokens on the board

TokenLayer.select

type: PIXI.Graphics

Token Selection Rectangle

TokenLayer.selectTokens(coords)

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.


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)

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

Draw the token’s nameplate as a text object

Returns:PIXI.Text – The Text object for the Token nameplate
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

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
foundry.Token._onDelete(sceneId)

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

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

If this token modifies an actor entry, retrieve it

foundry.Token.animateMovement(ray)

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

Arguments:
  • ray (Ray) – The path along which to animate Token movement
foundry.Token.brightLightRadius

The radius of bright light that the Token emits

foundry.Token.brightRadius

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

foundry.Token.canViewSheet

type: Boolean

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

foundry.Token.center

type: Object

The Token’s current central position

foundry.Token.checkCollision(destination, drag)

Check for collision when attempting a move to a new position

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

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

foundry.Token.control(options)

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

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

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

foundry.Token.dimLightRadius

The radius of dim light that the Token emits

foundry.Token.dimRadius

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

foundry.Token.draw()

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

Returns:Promise
foundry.Token.drawEffects()

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

foundry.Token.drawTooltip()

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

foundry.Token.getCenter(x, y)

Get the center-point coordinate for a given grid position

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

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

foundry.Token.getLightRadius(units)

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

Arguments:
  • units (Number) – The radius in grid units
Returns:

number – The radius in canvas units

foundry.Token.getSightOrigin()

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

Returns:Object
foundry.Token.h

type: Number

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

foundry.Token.inCombat

type: Boolean

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

foundry.Token.isVisible

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.

foundry.Token.layer

type: PlaceablesLayer

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

foundry.Token.moveMany(offsets, rotate)

Move or rotate many Token objects simultaneously

Arguments:
  • offsets (Array) – The keyboard offset directions in which movement is requested
  • rotate (Boolean) – Rotate tokens to the selected offset position instead of shifting them
Returns:

Promise – A resolved promise once all tokens have been moved or rotated

foundry.Token.name

type: String

Convenience access to the token’s nameplate string

foundry.Token.owner

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

foundry.Token.refresh()

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

foundry.Token.release(resetSight)

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

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

Incrementally shift the token’s rotation by some delta degrees

Arguments:
  • delta (Number) – An offset of rotation in degrees
  • snap (Boolean) – Snap rotation to the closest 45 degree increment
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

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

Promise – The Token after animation has completed

foundry.Token.sheet

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.

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

Promise

foundry.Token.showStatusEffects()

Add Token status effects as an active display on the ControlsLayer

foundry.Token.toggleCombat()

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

Returns:Promise
foundry.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
foundry.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.
foundry.Token.toggleOverlay(texture)

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

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

Promise

foundry.Token.toggleVisibility()

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

Returns:Promise
foundry.Token.w

type: Number

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


Token Status Effects

Mod developers may want to customize the set of status effects which can be applied to tokens. The game system provides the flexibility to accomplish this by interacting with the TokenEffects() class.

class TokenEffects()

A singleton canvas element which allows the player to assign status effect icons to tokens they control. Whenever a player wants to assign status effect icons to a token we just reposition the same container.

Mod developers can customize the set of icons which are valid token status effects by altering the CONFIG.statusEffects Array.

TokenEffects.activate(token)

Activate the TokenEffects ui and display it next to the specified token. Set the token that the interface is actively modifying to direct click events on the effect icons.

Arguments:
  • token (Token) – The Token next to which the status effects icons should be displayed
TokenEffects.deactivate(token)

Hide the TokenEffects container from view and unset the active token that it modifies.