Action API — Function Reference

One page per function in the Action API. Each page gives the full signature, every parameter, what comes back, the edge cases, and worked examples.

If you are new to actions, read Actions first, then the Action API overview. This section is the detail you come back for.

Global functions

Available by name inside any action, with nothing to import.

Function	Returns	What it does
`roll()`	`number`	Roll dice and show the roll in chat
`rollSilent()`	`number`	Roll dice without touching chat
`rollDetailed()`	`object`	Roll dice without touching chat, with the individual dice
`sendMessage()`	`void`	Write a message to the chat log
`prompt()`	`Promise`	Ask the clicking user a question
`draw()`	`Promise<string>`	Put a shape, zone, or wall on the map

The `api` namespace

Where new surface lands since Action API 0.2. api.version is the version string this platform provides ('0.3.0').

Function	Returns	What it does
`api.pickSquares()`	`Promise<{x,y}[] \| null>`	Ask the user for N grid squares
`api.importCharacter()`	`Promise<Token \| null>`	Put a character on the map where the user clicks
`api.importParty()`	`Promise<Token[] \| null>`	Put every member of a party on the map
`api.importRelatedCharacters()`	`Promise<Token[] \| null>`	Summon a character's minions, partners, allies
`api.history.commits()`	`Promise<HistoryCommit[]>`	The map's (or an entity's) commits, newest first — read-only
`api.history.diff()`	`Promise<{summary, changes}>`	The change list between two commits
`api.campaign.configuration()`	`Promise<Record<string, unknown> \| unknown>`	The campaign's settings, resolved — the whole record or one key (0.4)
`api.treasury.buckets()`	`Promise<TreasuryBucket[]>`	The Treasury's buckets the user may see (0.5)
`api.treasury.holdings()`	`Promise<TreasuryItem[]>`	The items — a character's, or all the view carries (0.5)
`api.treasury.distribution()`	`Promise<Record<string, unknown> \| null>`	The running distribution session, or null (0.5)
`api.timeline.list()`	`Promise<TimedEffect[]>`	The map's running timed effects (0.6)
`api.timeline.createEffect()`	`Promise<TimedEffect>`	Start an effect — rounds, indefinite, or a function that decides (0.6)
`api.timeline.editEffect()`	`Promise<TimedEffect>`	Change a running effect (0.6)
`api.timeline.endEffect()`	`Promise<TimedEffect>`	End one now — Dispel Magic (0.6)
`api.timeline.startBuff()`	`Promise<TimedEffect>`	A buff on the Timeline — its duration, and (0.8) its effects on the bearer's numbers (0.6)
`api.timeline.endEffects()`	`Promise<{ ended, refused }>`	Cleansing — end a token's running effects of a category (0.8)
`api.chat.stream()`	`void`	Write a named slot in the action's chat document — see the overview
`api.chat.brief()`	`void`	Set the summary the action's message shows in the feed, its steps folded beneath it as a thread; rewrite it as the action runs (0.7)

Token methods

Called on token (the acting token), and — except where noted — on target and each entry of targets.

Method	Returns	What it does
`getProperty()`	`any`	Read a property by name, alias, or id
`setProperty()`	`void`	Write a property, logging the change
`applyDamage()`	`void`	Propose damage or healing for approval
`requestRoll()`	`Promise<number \| null>`	Ask that token's owner to roll
`getDistanceTo()`	`number`	Distance to another token, in grid units
`getLineOfSightTo()`	`boolean`	Whether walls block the view
`addAction()`	`void`	Give the token another action
`changeTokenArtwork()`	`void`	Swap the map artwork — `token` only
`changePortraitArtwork()`	`void`	Swap the portrait — `token` only
`autoTokenizeArtwork()`	`Promise<void>`	Re-crop the current art as a token — `token` only

Character methods

Called on character, the read-only source character behind the token. null when the token is not linked to one.

Method	Returns	What it does
`character.getProperty()`	`unknown`	Read an attribute or exposed field
`character.getCurrentTokenArtworkId()`	`number \| undefined`	Index of the artwork in use as map art
`character.getCurrentPortraitArtworkId()`	`number \| undefined`	Index of the artwork in use as the portrait

Values, not functions

These are in scope too, and are covered on the overview page: token, target, targets, character, damageTypes, and area.

Your campaign's own campaign functions are in scope as well — global ones by name, token ones as token.yourFunction().