Skip to content

character.getCurrentPortraitArtworkId()

Find which of the character's artworks is currently serving as the portrait.

Part of the Action API · Function reference

Available on character, which is null for tokens with no character sheet.

Signature

character.getCurrentPortraitArtworkId(): number | undefined

Synchronous.

Parameters

None.

Returns

number — the zero-based index into the character's artworks array of the artwork in use as the portrait. An index, not an id.

undefined when the character has no artworks, or none is marked as the portrait.

How it decides

The character's stored portrait-artwork id is looked up in its artwork list, and if none is set, the first artwork tagged as a portrait is used — the same fallback that keeps older characters working.

The portrait is the image shown in panels, sheet headers, and chat. The map image is a separate slot, answered by getCurrentTokenArtworkId().

Examples

Cycle portraits

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

Only change the portrait if it differs from the map art

const portrait = character?.getCurrentPortraitArtworkId();
const mapArt = character?.getCurrentTokenArtworkId();
if (portrait !== undefined && portrait === mapArt) {
  sendMessage('<i>Portrait and token art are the same image.</i>');
}

Restore after a transformation

const before = character?.getCurrentPortraitArtworkId() ?? 0;
token.setProperty('portraitBeforeShift', before);
token.changePortraitArtwork(2);

Notes and gotchas

  • An index, not an id — pass it straight to token.changePortraitArtwork().
  • undefined when unset. Distinguish it from 0 if that matters.
  • character may be null — use ?..
  • It reads the character's list, while changePortraitArtwork() writes against the token's. They agree for a freshly spawned token; check token.currentPortraitArtId when they might have diverged.

See also