api.importRelatedCharacters()

Summon the characters related to one — its minions, its partners, its allies — one square each.

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

Signature

api.importRelatedCharacters(characterId: string, types?: string[]): Promise<Token[] | null>

Asynchronous — await it.

Parameters

Parameter	Type	Description
`characterId`	`string`	The character whose relationships to follow. Usually `token.characterId`.
`types`	`string[]`	Which relationship types count — `['minion']`, `['minion', 'familiar']`. Case does not matter. Omit or pass `[]` for every related character.

Returns

The tokens that were created, in the order the squares were clicked — or null if the user cancelled. Throws with a plain sentence if the token has no character (characterId is null), no character matches the types, or there is no open map.

Relationships

A character's relationships are set on its sheet — the Relationships block under Campaign & Party, in Build mode. Each is a link from this character to another with a type you choose: Shelly → Bill, minion. They are directional: Shelly's sheet says Bill is her minion; Bill's sheet says nothing unless you add it there.

This function follows the links from characterId. The types you pass are matched against the types on those links.

Example

Shelly the necromancer has two skeletons, Bill and Bob, each with their own character sheet and each related to her as minion. Her Summon Skeletons action:

const skeletons = await api.importRelatedCharacters(token.characterId, ['minion']);
if (!skeletons) return;
return `${token.name} raises ${skeletons.length} skeletons.`;

She clicks two squares; Bill and Bob appear in them.