API Reference
Access
Section titled “Access”The API attaches during the ready hook. Both paths point to the same object.
const api = game.modules.get('tenacity').api;// orglobalThis.TENACITY;Methods
Section titled “Methods”getSetting(key)
Section titled “getSetting(key)”Returns the value of a Tenacity world setting. Pass the setting key as a string.
const cap = api.getSetting('maxTenacity');MoteManager
Section titled “MoteManager”The class that owns the per-actor mote pool. Most methods below wrap its static methods.
A map of the hook names listed under Hooks.
Hooks.on(api.HOOKS.MOTE_SPENT, ({ actorUuid, amount }) => {});grant(actor, options?)
Section titled “grant(actor, options?)”Adds motes to an actor’s pool, capped at the actor’s effective maximum. The effective maximum is the per-actor override when one is set, otherwise the maxTenacity setting.
amount(number): motes to add. Default1.sourceMessageId(string|null): chat message id the mote is tied to. Self-rescue tracking uses it. Defaultnull.reason(string): tag stored on the mote record. Default'manual'.
Returns: Promise<number>, the number of motes added after the cap.
const added = await api.grant(actor, { amount: 2, reason: 'milestone' });spend(actor, options)
Section titled “spend(actor, options)”Removes motes from an actor’s pool.
amount(integer): motes to consume. Must be a positive integer.excludeSourceMessageId(string, optional): motes earned from this message id are not spendable.reason(string, optional): tag passed totenacity.moteSpent. Default'spend'.
Returns: Promise<Array|null>, the consumed mote records, or null if the spend was rejected.
const consumed = await api.spend(actor, { amount: 1 });if (consumed) await api.refund(actor, consumed);refund(actor, records)
Section titled “refund(actor, records)”Returns records from an earlier spend to the actor’s pool, capped at the effective maximum.
Returns: Promise<number>, the number of motes restored after the cap.
clear(actor, options?)
Section titled “clear(actor, options?)”Empties the actor’s pool. options.reason is passed to tenacity.poolReset. Default 'manual'.
Returns: Promise<void>.
Read methods
Section titled “Read methods”| Method | Returns |
|---|---|
count(actor) | Total motes in the pool. |
spendableCount(actor, excludeSourceMessageId?) | Motes the actor can spend, excluding motes earned from the given message, if any. |
getMotes(actor) | A deep clone of the mote records: Array<{ id, sourceMessageId, earnedAt, reason }>. |
resetAllPools()
Section titled “resetAllPools()”Clears the pool of every world actor and posts a notification with the number of pools cleared. GM-only; a non-GM call does nothing.
Returns: Promise<void>.
| Hook | Payload | Fires |
|---|---|---|
tenacity.moteGranted | { actorUuid, amount, reason } | When a grant or refund adds motes. Refunds use reason refund. |
tenacity.moteSpent | { actorUuid, amount, reason, consumed } | On a spend. consumed is the array of removed records. |
tenacity.poolReset | { actorUuid, cleared, reason } | On a clear. cleared is the pool size before the reset. |
tenacity.rollBumped | { actorUuid, messageId, amount, reason } | After a bumped roll’s chat message updates. Monk’s TokenBar row bumps add tokenId; Flash Rolls row bumps add uniqueId. |
tenacity.rollRerolled | { actorUuid, messageId, originalTotal, consumed } | After a rerolled roll’s chat message updates. |
| Flag | Type | Effect |
|---|---|---|
flags.tenacity.maxOverride | integer | Per-actor maximum that replaces the maxTenacity setting for that actor. |
flags.hero-mancer.grantsMotes | boolean | When true on a new character, Tenacity skips its starting grant. Hero Mancer sets it. |