Skip to content

character.getCurrentTokenArtworkId()

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

Part of the Action API · Function reference

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

Signature

character.getCurrentTokenArtworkId(): number | undefined

Synchronous.

Parameters

None.

Returns

number — the zero-based index into the character's artworks array of the artwork in use as token art. Despite the name, this is a position, not an id.

undefined when the character has no artworks, or when none of them is marked as the token image.

How it decides

The character's stored token-artwork id is looked up in its artwork list. If no id is set, the first artwork tagged as token art is used instead, which is how characters created before artwork ids still resolve.

Why it exists

It pairs with token.changeTokenArtwork(), which takes an index. Together they let an action cycle or swap artwork without hard-coding positions:

const current = character?.getCurrentTokenArtworkId() ?? 0;
token.changeTokenArtwork(current + 1);

Note the two sides read from different lists — this method indexes the character's artworks, while changeTokenArtwork() indexes the token's. For a token spawned from its character they are the same list in the same order, but after art is added to one and not the other they can drift. When you need certainty, read token.currentTokenArtId instead, which is the token's own view of the same question.

Examples

Cycle to the next artwork, safely

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

Remember the original, then restore it

const original = character?.getCurrentTokenArtworkId();
token.changeTokenArtwork(3);
token.setProperty('originalArtIndex', original ?? 0);

Only act when there is something to act on

const index = character?.getCurrentTokenArtworkId();
if (index === undefined) return 'No token artwork is set.';

Notes and gotchas

  • An index, not an id. Feed it to changeTokenArtwork() unchanged.
  • undefined, not -1, when nothing matches. ?? 0 is a convenient default, but check explicitly when the difference matters.
  • character may be null — use ?..
  • Read-only. Changing the artwork is token.changeTokenArtwork()'s job.

See also