Skip to content

token.autoTokenizeArtwork()

Re-crop the token's current map artwork into a round token, finding the face automatically.

Part of the Action API · Function reference

token only. Not available on target or targets.

Signature

token.autoTokenizeArtwork(): Promise<void>

Asynchronous. await it if anything after it depends on the new framing.

Parameters

None.

Returns

Promise<void> — it resolves whether or not the tokenization worked. There is no success value and no rejection; every failure path logs a console warning and resolves quietly.

What it does

Takes whichever artwork is currently the token's map image, runs face detection over it, applies a circular crop centred on what it found, marks the artwork as tokenized, and saves the result. The map re-renders with the new framing for everyone.

Any existing border width and colour on that artwork are preserved, so a token you have already styled keeps its ring.

It works on the current map artwork. To tokenize a different one, switch to it with changeTokenArtwork() first.

When nothing happens

The call resolves without doing anything if:

  • the token has no artworks, or none is set as the map image
  • that artwork has no usable source image
  • the source is a temporary blob or data URL — an image that has not finished uploading yet
  • face detection or the crop itself fails

Each of these logs a warning to the browser console and nothing else. Your script cannot tell them apart.

Examples

Tokenize whatever art the token is wearing

await token.autoTokenizeArtwork();
sendMessage(`${token.name}'s portrait has been re-framed.`);

Switch art, then frame it

token.changeTokenArtwork(3);
await token.autoTokenizeArtwork();

Frame every artwork in turn

const count = (token.artworks || []).length;
for (let i = 0; i < count; i++) {
  token.changeTokenArtwork(i);
  await token.autoTokenizeArtwork();
}
token.changeTokenArtwork(0);

Notes and gotchas

  • It is slow. Detection and the upload that follows take a moment; an action that does this on every use will feel sluggish.
  • It overwrites the crop. Manual framing on that artwork is replaced. There is no undo from script.
  • Not awaiting it means your action can finish before the crop lands, which is fine when nothing depends on it.
  • The Test panel does the work for real — the artwork is modified and saved.

See also