token.getProperty()

Read a property from a token by name, alias, or id — without caring how it is spelled or where the system stored it.

Part of the Action API · Function reference

Available on token, target, and every entry of targets.

Signature

token.getProperty(propertyName: string): any

Synchronous.

Parameters

Parameter	Type	Description
`propertyName`	`string`	The property's name, one of its aliases, or its id. Case-insensitive.

Returns

The stored value — number, string, boolean, object, whatever the property holds — or undefined when nothing matches.

undefined means "no such property on this token", which is not the same as zero. Supply your own fallback when zero is the sensible default:

const ac = token.getProperty('ac') ?? 10;

How the name is resolved

Four things are tried, in order, and the first hit wins:

The property's name as the system or campaign defines it — Strength.
Its id — str, or a system-prefixed dnd5e-2014_str. A prefixed id also matches on its suffix alone.
Its aliases, the comma-separated list on the property definition — str.
A direct case-insensitive match on the token's raw stored keys, for properties with no definition behind them at all.

So on a D&D 5e token, all of these return the same number:

token.getProperty('Strength');
token.getProperty('strength');
token.getProperty('STR');
token.getProperty('dnd5e-2014_str');

This is why getProperty() is worth using over token.someName. Reading the field directly only works when you happen to spell the stored key exactly right, and system-prefixed keys are almost never what an author would guess.

Examples

Read a stat with a fallback

const hp = token.getProperty('hp') ?? 0;
const max = token.getProperty('hp_max') ?? hp;
sendMessage(`${token.name}: ${hp}/${max} HP`);

Compare against a target

const attack = roll('1d20+attackBonus', { label: 'Attack' });
if (attack >= (target.getProperty('ac') ?? 10)) {
  target.applyDamage(roll('1d8+3'), 'piercing');
}

Branch on a flag

if (token.getProperty('concentrating')) {
  sendMessage(`${token.name} loses concentration.`);
  token.setProperty('concentrating', false);
}

Read from every target

const weakest = targets
  .slice()
  .sort((a, b) => (a.getProperty('hp') ?? 0) - (b.getProperty('hp') ?? 0))[0];

Notes and gotchas

Values are raw. No modifier maths happens here — a Strength of 18 comes back as 18. The same is true inside roll() expressions.
Reads are of the client's current copy. Another player's change made a moment ago may not have arrived yet.
Works on targets. Reading a target is always allowed; writing to one is a different matter — see setProperty().
character.getProperty() is a different function with different resolution rules. See character.getProperty().