Map tokens
A token is a character or creature on a map: the innkeeper behind the
bar, the council at their table, a monster in its lair. A character's
token on a place's map says where that character is. They start a game
there when the game starts at that place, join the scene when the party
arrives, and are found there when the story looks for them. In a game,
players see the scene's people rather than your tokens. Tokens are
points on a map whose kind is token.
To add or change one, use the Token tool (T).
Click the map, then link a character file, or skip the link and give the token a label ("Goblin 3").
Token fields
id
The marker's own id, unique on this map.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
id |
string |
yes |
kind
pin marks a place; token marks a character or creature.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
kind |
"pin" | "token" |
"pin" |
Always token for a token.
label
The name shown on the map. Left out, the linked file's name is shown.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
label |
string |
Left out, the token shows the character's name. Give several tokens of one creature their own labels to tell them apart.
fileReferenceId
The file it marks, by reference id: a location for a pin, a character for a token. Null for a plain marker.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
fileReferenceId |
string | null |
Link the character's file. Only linked tokens put a character in a place for the GM. Several tokens of one creature file become numbered copies in the scene.
position
Where it sits on the map.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
position |
{ x, y } |
yes | ||
position.x |
number |
yes | Across the map: 0 at the left edge, 1 at the right. | |
position.y |
number |
yes | Down the map: 0 at the top edge, 1 at the bottom. |
On a gridded map with snapping on, a moved token lands on whole cells.
style
The marker's color and icon.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
style |
{ color, icon? } |
yes | ||
style.color |
string |
yes | The marker's color. | |
style.icon |
string | null |
An icon name, or null for none. |
{ "style": { "color": "#3b82f6", "icon": null } }
token
Tokens only: how big it is on the map, its footprint.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
token |
object |
To set it, use Size on the token's bar on a gridded map, or Footprint in the token's panel: Visual, Grid or World. With no grid footprint, the GM sizes a token from the character (a Large creature takes 2 × 2 squares), else one square.
The sizes the map's Size menu offers are ¼ × ¼, ½ × ½, 1 × 1, 2 × 2, 3 × 3, 4 × 4 squares. A token of ½ or ¼ of a square (a cat, a rat) is drawn smaller but still stands in one square: the GM names its square and keeps others out of it as for a token of one square.
locked
Locked in place, so it can't be dragged or removed by mistake.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
locked |
boolean |
To set it, use the lock on the element's selection bar, or Lock element in its right-click menu.
Footprints
visual
A plain marker, the same size on screen at any zoom.
{"mode":"visual"}
grid
Covers whole grid cells: a Large creature is 2 by 2.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
width |
number |
1 |
Cells across. | |
height |
number |
1 |
Cells down. |
{"mode":"grid"}
The GM counts a token's squares from this footprint on a square grid.
world
A circle of a real size, in the map's units.
| Field | Type | Required | Default | What it is |
|---|---|---|---|---|
shape |
"circle" |
"circle" |
Its shape. Only circle for now. | |
diameter |
{ value, unit } |
yes | Its real width: 10 ft. |
{"mode":"world","diameter":{"value":10,"unit":"ft"}}
Use it when a creature's real size matters on a map with no grid.