api.importCharacter()

Put a character on the map, in a square the user clicks.

Part of the Action API · Function reference · Since Action API 0.2 (v0.86.0)

Signature

api.importCharacter(idOrSlug: string): Promise<Token | null>

Asynchronous — await it.

Parameters

Parameter	Type	Description
`idOrSlug`	`string`	The character's id, or its slug (the short name on its sheet). Must be a character you can see.

Returns

The token that was created, as the server returned it — or null if the user cancelled the square pick. Throws with a plain sentence if the character does not exist, you cannot read it, or there is no open map.

What it does

Exactly what the map's Import Character does, minus the modal:

Fetches the character.
Enters targeting mode asking for one square — Choose a square for Bill — via api.pickSquares().
Creates a token of the character there: the system's projection of its sheet (properties, actions), its token art, its chat colour, linked back to the character. A summoned token is indistinguishable from an imported one because it is built the same way.

Examples

A familiar that comes when called:

const owl = await api.importCharacter('archimedes');
if (!owl) return;
return `${token.name} calls, and ${owl.name} lands nearby.`;

Only if it is not already on the map:

const already = targets.length ? null : await api.importCharacter('archimedes');