Skip to content

token.changePortraitArtwork()

Switch which of the token's artworks is used as its portrait.

Part of the Action API · Function reference

token only. Not available on target or targets.

Signature

token.changePortraitArtwork(id: number): void

Synchronous, returns nothing.

Parameters

Parameter Type Description
id number Zero-based index into token.artworks — an index, not an artwork id.

Returns

Nothing. An out-of-range index, or a token with no artworks, is ignored with a console warning.

What it does

Points the token's portrait at token.artworks[id] and saves it. The portrait is the image used in panels, the character sheet header, and chat — everywhere except the map itself. The map artwork is untouched.

token.currentPortraitArtId holds the index currently in use, or undefined when nothing matches.

Examples

Show a wounded portrait below half health

const hp = token.getProperty('hp') ?? 0;
const max = token.getProperty('hp_max') ?? 1;
token.changePortraitArtwork(hp < max / 2 ? 1 : 0);

Swap both images at once

token.changeTokenArtwork(2);
token.changePortraitArtwork(2);

Cycle through portraits

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

Notes and gotchas

  • Index, not id.
  • Silent on failure, exactly as with the map artwork.
  • Chat avatars follow the portrait, so this changes how the token appears in the log for messages sent afterwards.
  • The acting token only.

See also