Skip to content

token.changeTokenArtwork()

Switch which of the token's artworks is shown on the map.

Part of the Action API · Function reference

token only. Not available on target or targets — an action cannot restyle someone else's token.

Signature

token.changeTokenArtwork(id: number): void

Synchronous, returns nothing. The save it triggers happens in the background.

Parameters

Parameter Type Description
id number Zero-based index into token.artworks — not an artwork id string, despite the parameter name.

Returns

Nothing. Out-of-range indexes and tokens with no artworks are ignored, with a warning in the browser console.

What it does

Points the token's map image at token.artworks[id] and saves the change, so everyone at the table sees it. Any tokenize settings already saved on that artwork — crop, background, border — are reused, so a piece of art that was set up as a token still looks like one.

The portrait is untouched. Use changePortraitArtwork() for that.

Finding the index

token.artworks is the array, and token.currentTokenArtId is the index currently in use (or undefined when none matches). For a token built from a character, character.getCurrentTokenArtworkId() answers the same question from the character's own list.

Examples

Cycle to the next artwork

const count = (token.artworks || []).length;
if (count > 1) {
  const current = token.currentTokenArtId ?? 0;
  token.changeTokenArtwork((current + 1) % count);
}

Wild shape: swap art and stats together

token.changeTokenArtwork(2);
token.setProperty('form', 'bear');
sendMessage(`${token.name} takes the shape of a bear.`);

Revert

token.changeTokenArtwork(0);
token.setProperty('form', 'humanoid');

Pick by name rather than position

const index = (token.artworks || []).findIndex((a) => a.name === 'Bear Form');
if (index >= 0) token.changeTokenArtwork(index);

Notes and gotchas

  • Index, not id. Passing an artwork's id string does nothing.
  • Silent on failure. A bad index leaves the token as it was and reports nothing to your script or to chat. Range-check first if the number is computed.
  • Nothing is announced. Add a sendMessage() if the change should be visible in the log as well as on the map.
  • Only the token's own artworks. There is no way to attach new art from an action; upload it to the token or character first.

See also