Token
A creature placed on a Map.
A token is a creature’s physical presence on the playing surface: where it stands, how big it
is, what it looks like, and — through vision — what it can see. Like a Combatant it
carries no statistics of its own, pointing at an Entity through reference instead.
Token and combatant are two views of the same creature at different tables: the token is on
the map, the combatant is in the initiative order, and when both exist they are linked through
combatant and kept in sync on name, label, role and visibility.
- SeeAlso:
Map,Combatant,Vision,Aura,Entity
| Property | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | The unique identifier for this token. A UUID string automatically generated when the token is created. This serves as the primary key in the Realm database. |
name |
string |
No | The token’s display name. Copied from the referenced entity when the token is placed, and editable afterwards. Examples: "Goblin" |
label |
string |
No | A short label distinguishing this token from identical ones. Drawn on the token itself and kept in sync with Combatant/label. Examples: "G1", "G2" |
role |
string |
No | Which side the creature is on, as the raw value of a Role. Determines the ring color drawn around the token. Use roleValue for the typed form. Examples: "friendly", "neutral", "hostile" |
x |
integer |
Yes | The token’s horizontal position in map coordinates. SeeAlso: position |
y |
integer |
Yes | The token’s vertical position in map coordinates. |
scale |
number |
Yes | A fine adjustment to the token’s rendered size. Applied on top of the whole-cell footprint given by width and height, so artwork can be nudged to fit without changing the space the creature occupies. |
width |
integer |
Yes | The token’s width in grid cells. Examples: 1 — a medium creature; 2 — a large creature |
height |
integer |
Yes | The token’s height in grid cells. |
style |
string |
No | How the artwork is presented, as the raw value of a TokenStyle. Use styleValue for the typed form. Examples: "circle", "topdown" |
rotation |
integer |
Yes | The token’s facing, in degrees. Meaningful mainly for TokenStyle/topdown artwork, and used as the origin for directional vision. |
elevation |
integer |
Yes | The token’s height above the ground, in grid units. Shown as a badge so flying and burrowing creatures can be tracked on a flat map. |
hidden |
boolean |
Yes | Whether the token is concealed from the players. Kept in sync with Combatant/hidden. |
asset |
Asset | No | The artwork drawn for this token. SeeAlso: Asset |
vision |
Vision | No | What this token can see, when line of sight is enabled. A token with no vision object neither sees nor illuminates. SeeAlso: Vision, Map/lineOfSight |
reference |
string |
No | A soft link to the Entity this token represents. Stored as an app URL rather than a Realm relationship, matching Combatant/reference. Examples: "/monster/goblin" SeeAlso: referenceURL, entity |
auras |
Array<Aura> | Yes | Radial areas drawn around the token. Used for aura effects, threat range, or any radius that should follow the creature. SeeAlso: Aura |
entityId |
any |
Yes | |
trackingId |
integer |
No | |
image |
any |
Yes | |
path |
Array<any> |
No | |
combatant |
Combatant | No | The combatant this token is bound to, when the creature is in combat. The link that keeps the map and the initiative tracker consistent — name, label, role and visibility propagate across it. SeeAlso: Combatant |
player |
any |
Yes |
TokenStyle
Section titled “TokenStyle”How a Token’s artwork is presented on the map.
Type: string — one of:
circletopdown