token.addAction()

Give a token another action, from inside an action.

Part of the Action API · Function reference

Available on token only. It is not exposed on target or targets.

Signature

token.addAction(name: string, code: string): void

Synchronous, returns nothing.

Parameters

Parameter	Type	Description
`name`	`string`	The button label for the new action. Required — an empty name is refused.
`code`	`string`	The new action's JavaScript, as a string. Required — an empty body is refused.

Returns

Nothing. A missing name or body is refused silently (with a warning in the browser console), so nothing tells your script it did not work.

What it does

The new action is appended to the token's action list with a generated id. It behaves like any other action from then on: it appears among the token's buttons, has the whole Action API in scope when clicked, and can be edited or deleted in the action editor.

The addition is not saved by itself. It lands on the client's copy of the token immediately, and reaches the server only when something else writes the whole token — the save an action performs on its own way out covers properties, not the action list. Treat addAction() as best-effort: verify the button is still there after a refresh before relying on it, and prefer a property flag your existing actions check when the effect has to be durable.

Writing the code string

The body is ordinary action code, but it lives inside a string, which makes quoting the hard part.

Prefer a double-quoted or single-quoted string with the other quote style inside:

token.addAction('Roar', "sendMessage(`${token.name} roars!`);");

For anything longer, a template literal with escaped inner backticks gets unreadable fast. Build it from an array instead:

const body = [
  "const healed = roll('2d4+2', { label: 'Cure Wounds' });",
  "token.applyDamage(-healed);",
].join('\n');
token.addAction('Cure Wounds', body);

The code is not checked when you add it. A syntax error surfaces as a red error in chat the first time somebody clicks the new button.

Examples

Grant a one-off reaction

sendMessage(`${token.name} readies a counterattack.`);
token.addAction('Counterattack', "sendMessage(`${token.name} strikes back!`);");
token.setProperty('readied', true);

Give the token a way to end an effect it just started

token.setProperty('raging', true);
token.addAction('End Rage', "token.setProperty('raging', false);");

Notes and gotchas

Duplicates are not prevented. Clicking the granting action twice adds the button twice. Guard with a flag:
```
if (!token.getProperty('readied')) token.addAction('Counterattack', '...');
```
There is no removeAction(). Actions added this way are removed by hand in the action editor. Design around that — a flag your action checks is usually better than a button that appears and cannot leave.
The acting token only. You cannot grant an action to a target.
The Test panel does not persist it. The action is added to the in-memory token and vanishes.