api.pickSquares()

Ask the clicking user for one or more grid squares, and get their coordinates.

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

Signature

api.pickSquares(count: number, label?: string): Promise<{ x: number; y: number }[] | null>

Asynchronous — await it. Nothing happens until the user has clicked.

Parameters

Parameter	Type	Description
`count`	`number`	How many squares to collect. A positive integer; anything else throws.
`label`	`string`	What the squares are for, shown in the banner: Choose square 1 of 2 for the fire pits. Optional.

Returns

The squares in the order they were clicked, each as grid coordinates ({ x, y }, the same units as token.x / token.y) — or null if the user cancelled. Cancelling is Escape, a right-click, or the banner's Cancel button. It is an outcome, not an error: check for null and return.

What the user sees

The same targeting mode that token-targeting actions use, but the cursor highlights the square under it rather than snapping to tokens, and the banner counts: Choose square 2 of 3 for Bill, Bob and Ann. Squares already taken stay highlighted. Clicking the same square twice does not count it twice.

Needs a map

This only works from an action run on an open map — the impersonated-token bar or the map's menu. Anywhere else (the Test panel on a character page, say) it rejects with api.pickSquares needs an open map before entering a mode nothing could complete.

Examples

Ask where, then say so:

const squares = await api.pickSquares(1, 'the fireball');
if (!squares) return;
const [{ x, y }] = squares;
return `${token.name} hurls a fireball at ${x}, ${y}.`;

Three squares, and how far each is from the caster:

const spots = await api.pickSquares(3, 'the wards');
if (!spots) return 'No wards placed.';
return spots
  .map((s) => `a ward ${Math.max(Math.abs(s.x - token.x), Math.abs(s.y - token.y))} squares away`)
  .join(', ');

(To put a character in the square, use the import functions below — they do the pick for you. draw() cannot yet be pointed at a square by coordinates; see its known issue.)