API Reference

The Tenacity module exposes a small public API for other modules and macros. It covers reading settings, inspecting an actor’s mote pool, and granting, spending, or refunding motes.

Access

The API attaches in the ready hook. Both access paths point to the same object.

const api = game.modules.get('tenacity').api;
// or
globalThis.TENACITY;

See Settings, Earning Tenacity, Spending Tenacity, and Rest and Conversion for the gameplay context behind these methods.

Methods

getSetting(key)

Reads a registered Tenacity world setting.

Parameters:

• key (string): the setting key, typically referenced via the module’s SETTINGS constants.

Returns: the stored setting value (type depends on the setting).

Example:

const cap = api.getSetting('maxTenacity');

MoteManager

The class that owns the per-actor mote pool. The top-level API methods (grant, spend, refund, count, spendableCount, clear, getMotes) are thin wrappers around its static methods. Exposed for advanced consumers who need direct access; most callers should use the helpers below.

const motes = api.MoteManager.getMotes(actor);

grant(actor, options?)

Adds motes to an actor’s pool. The result is capped by the actor’s effective maximum: the per-actor max override if one is set, otherwise the maxTenacity world setting.

Parameters:

• actor (Actor): the target actor.
• options (object, optional)
  • amount (number): number of motes to add. Default 1.
  • sourceMessageId (string|null): chat message id this mote is tied to, used by self-rescue tracking. Default null.
  • reason (string): short tag stored on the mote record. Default 'manual'.

Returns: Promise<number>. The number of motes actually added after applying the cap.

Example:

const added = await api.grant(actor, { amount: 2, reason: 'milestone' });

spend(actor, options)

Removes motes from an actor’s pool. Returns null if the actor does not have enough spendable motes.

Parameters:

• actor (Actor): the target actor.
• options (object)
  • amount (integer): number of motes to consume. Must be a positive integer.
  • excludeSourceMessageId (string, optional): exclude motes earned from this message id from the spendable set. Used to prevent self-rescue spending the mote that was just earned.

Returns: Promise<Array|null>. The array of consumed mote records (useful for a later refund), or null if the spend was rejected.

Example:

const consumed = await api.spend(actor, { amount: 1 });
if (consumed) await api.refund(actor, consumed);

refund(actor, records)

Returns previously consumed mote records to the actor’s pool. Honors the actor’s effective maximum: the per-actor max override if one is set, otherwise the maxTenacity world setting.

Parameters:

• actor (Actor): the target actor.
• records (Array): the array returned by an earlier spend call.

Returns: Promise<number>. The number of motes actually restored after applying the cap.

Example:

const restored = await api.refund(actor, consumed);

count(actor)

Total number of motes in the actor’s pool.

Parameters:

• actor (Actor): the target actor.

Returns: number.

Example:

const total = api.count(actor);

spendableCount(actor, excludeSourceMessageId?)

Number of motes the actor can currently spend. Differs from count when excludeSourceMessageId is provided: motes tagged with that source message id are filtered out, which is how self-rescue prevents a roll from spending the mote it just earned.

Parameters:

• actor (Actor): the target actor.
• excludeSourceMessageId (string, optional): exclude motes earned from this message id.

Returns: number.

Example:

const usable = api.spendableCount(actor, message.id);

clear(actor)

Empties the actor’s mote pool.

Parameters:

• actor (Actor): the target actor.

Returns: Promise<void>.

Example:

await api.clear(actor);

getMotes(actor)

Returns a deep clone of the actor’s mote records. Safe to mutate without affecting the stored pool.

Parameters:

• actor (Actor): the target actor.

Returns: Array<{ id, sourceMessageId, earnedAt, reason }>.

Example:

const records = api.getMotes(actor);

resetAllPools()

Clears every actor’s mote pool world-wide. GM only; non-GM calls are ignored. Posts a UI notification with the number of pools cleared.

Parameters: none.

Returns: Promise<void>.

Example:

await api.resetAllPools();