Spell Book API Reference

Accessing the API

The API is registered during init on the module entry and on the SPELLBOOK global.

const api = game.modules.get('spell-book').api;
// or
SPELLBOOK.api.spellBookQuickAccess();

Most methods do not check the user’s role; syncGrantedSpellList is GM only. Methods that write to actors only succeed for actors the user can update.

Method summary

Method	Purpose
`spellBookQuickAccess()`	Open Spell Book for the selected token.
`spellSlotTracker()`	Post a slot usage summary to chat.
`openSpellBookForActor(actor)`	Open Spell Book for a given actor.
`openClassRulesForActor(actor, options)`	Open the Class Rules dialog with optional save/cancel callbacks.
`openPartyCoordinator(actors, options)`	Open the Party Coordinator for an actors array or a group actor.
`syncGrantedSpellList(actor)`	Create or update the actor’s granted spell list.
`setClassSpellLists(actor, classIdentifier, uuids)`	Set the spell lists a class draws from.
`learnFromScroll(actor, classId, scrollItem, options)`	Learn the spell a scroll is linked to.
`getSpellLearningCost(actor, classId, spell)`	Resolve the copying cost and free-pool state for a spell.
`hasConfiguredCompendiums()`	Check whether an enabled spell-bearing compendium is visible.
`scrollScanner()`	List spell scrolls found in Item compendiums.
`spellsNotInLists()`	Find spells not referenced by any spell list.
`debugSpell(name)`	Return index summaries for spells matching a name.
`flagPurge()`	Remove Spell Book flags and flagged items from actors.

Actor operations

`spellBookQuickAccess()`

Opens Spell Book for the first controlled token’s actor. Shows a notification and returns when no token is selected, the token has no actor, or the actor owns no spell items.

Returns: Promise<void>

game.modules.get('spell-book').api.spellBookQuickAccess();

`spellSlotTracker()`

Creates a chat message for the first controlled token’s actor, spoken as that actor. The table lists Level, Used (as used/max), and Remaining for every spell level with slots, plus Pact Magic. Shows a notification instead when there is no token, actor, spellcasting data, or slots.

Returns: Promise<void>

game.modules.get('spell-book').api.spellSlotTracker();

`openSpellBookForActor(actor)`

Runs the same actor setup as the sheet button, then renders Spell Book for the actor.

Name	Type	Description
`actor`	`Actor`	The actor whose Spell Book should be opened.

Returns: Promise<?SpellBook>, the rendered app, or null when no actor is passed.

const actor = game.actors.getName('Mira');
await game.modules.get('spell-book').api.openSpellBookForActor(actor);

`openClassRulesForActor(actor, options)`

Opens the Class Rules (Spell Book Settings) dialog for the actor.

Name	Type	Description
`actor`	`Actor`	The actor to configure.
`options.onSave`	`Function`	Optional. Invoked after the save completes.
`options.onCancel`	`Function`	Optional. Invoked when the dialog closes without saving.

Returns: ?ClassRules, the rendered dialog, or null when no actor is passed.

game.modules.get('spell-book').api.openClassRulesForActor(actor, {
  onSave: () => console.log('Class rules saved'),
  onCancel: () => console.log('Edit cancelled')
});

`openPartyCoordinator(actors, options)`

Opens the Party Coordinator. A group actor resolves to its spellcasting members. An array is filtered to spellcasters. An actor counts as a spellcaster when it has a spellcasting class or owns spells granted by a non-class source.

Name	Type	Description
`actors`	`Actor[]\|Actor`	Actors, or a group actor.
`options.groupActor`	`Actor`	Optional. Group actor supplying the window’s title context.

Returns: ?PartyCoordinator, the rendered app, or null when no spellcaster resolves.

const group = game.actors.getName('The Company');
game.modules.get('spell-book').api.openPartyCoordinator(group);

`syncGrantedSpellList(actor)`

Creates or updates the actor’s granted spell list from its current species and feat granted spells. GM only.

Name	Type	Description
`actor`	`Actor`	The actor whose granted spell list should be synced.

Returns: Promise<?object>, the granted list page, or null when the actor has no granted spells or the caller is not a GM.

const actor = game.actors.getName('Mira');
await game.modules.get('spell-book').api.syncGrantedSpellList(actor);

`setClassSpellLists(actor, classIdentifier, uuids)`

Sets the spell list pages a class draws spells from, the same field as Class Spell List in Spell Book Settings. If the change would unprepare spells the actor no longer has access to, this prompts a confirmation dialog before applying it.

Name	Type	Description
`actor`	`Actor`	The actor to update.
`classIdentifier`	`string`	The class identifier.
`uuids`	`string[]`	Spell list page UUIDs.

Returns: Promise<boolean>. false when an argument is missing or the confirmation dialog is cancelled.

await game.modules.get('spell-book').api.setClassSpellLists(actor, 'wizard', [listUuid]);

`learnFromScroll(actor, classId, scrollItem, options)`

Adds the scroll’s linked spell to the actor’s wizard spellbook through the normal copy flow, including the preLearnSpell and spellLearned hooks. A cost applies only when Charge Cost for Scroll Copying is enabled. The scroll is consumed according to Consume Scrolls When Learning, unless options.consume is passed.

Name	Type	Description
`actor`	`Actor`	The actor owning the scroll.
`classId`	`string`	The wizard-enabled class identifier.
`scrollItem`	`Item`	The scroll item on the actor.
`options.consume`	`boolean`	Optional. Overrides the consumption setting.

Returns: Promise<boolean>. false when an argument is missing, the scroll has no resolvable spell, a preLearnSpell listener cancels, or currency deduction fails.

const scroll = actor.items.getName('Spell Scroll: Fireball');
await game.modules.get('spell-book').api.learnFromScroll(actor, 'wizard', scroll);

`getSpellLearningCost(actor, classId, spell)`

Resolves what the spell costs the actor to copy. Cantrips, and any spell while the free-spell pool has room, return isFree: true.

Name	Type	Description
`actor`	`Actor`	The actor document.
`classId`	`string`	The wizard-enabled class identifier.
`spell`	`Item`	The spell document.

Returns: Promise<?{ cost: number, isFree: boolean }>, or null when an argument is missing.

const spell = await fromUuid(spellUuid);
const { cost, isFree } = await game.modules.get('spell-book').api.getSpellLearningCost(actor, 'wizard', spell);

Compendium scanning

`hasConfiguredCompendiums()`

Synchronous. Returns true when at least one Item pack is visible to the current user, is not disabled in the system’s packSourceConfiguration, and either has no flags.dnd5e.types or includes spell in them.

Returns: boolean

if (!game.modules.get('spell-book').api.hasConfiguredCompendiums()) return;

`scrollScanner()`

Scans every Item compendium for consumables of subtype scroll and lists each scroll’s name and UUID in a resizable dialog. Copy to Console logs every entry with its source pack.

Returns: Promise<void>

await game.modules.get('spell-book').api.scrollScanner();

`spellsNotInLists()`

Compares every spell in every Item compendium against the spells referenced by every discoverable spell list. A dialog lists each unreferenced spell’s name and source pack. Copy to Console logs name (uuid) entries.

Returns: Promise<void>

await game.modules.get('spell-book').api.spellsNotInLists();

`debugSpell(name)`

Finds spells whose name contains name, case-insensitive. Each summary holds name, uuid, compendiumSource, sourceBook, sourceCustom, level, school, properties, materials, and filterData, the object Spell Book filters match against. The array is also logged at the 3DS:ATLAS verbose log level.

Name	Type	Description
`name`	`string`	Substring to match against spell names.

Returns: Promise<object[]>

console.table(await game.modules.get('spell-book').api.debugSpell('Fire Bolt'));

GM maintenance

`flagPurge()`

Prompts for one eligible actor or All Eligible Actors. Eligible actors have a player owner and at least one spellcasting class. Every Spell Book flag is unset on the chosen actors, and every embedded item carrying a Spell Book flag is deleted.

Returns: Promise<void>

await game.modules.get('spell-book').api.flagPurge();

Hooks

Hook names carry the spell-book. prefix. A listener on a bare name such as spellBookOpened matches nothing.

Hook	Payload	When
`spell-book.spellBookOpened`	`{ actor, app }`	A Spell Book window first renders.
`spell-book.spellBookClosed`	`{ actor }`	A Spell Book window closes.
`spell-book.preparationSaved`	`{ actor, classIdentifier, changes }`	Preparation for one class is saved, including by a loadout. `changes` is `{ added, removed }` of `{ uuid, name, level }`.
`spell-book.loadoutApplied`	`{ actor, classIdentifier, spellUuids, loadoutId, loadoutName }`	After a loadout is applied and saved.
`spell-book.preLearnSpell`	`{ actor, classId, spellUuid, source, costs }`	Before a spell is added to a wizard spellbook.
`spell-book.spellLearned`	`{ actor, classId, spellUuid, source, name, school, level }`	After a spell is added to a wizard spellbook.
`spell-book.spellCopied`	`{ actorName, spellName, minutes }`	After a non-free learn, only while Log Spell Copying to Downtime Note is enabled. Broadcast to other clients.

source is free, copied, or scroll.

preLearnSpell is dispatched with Hooks.call. Returning false cancels the learn. A listener can change costs.cost and costs.time (minutes) before they are applied.

A copy approved through GM copy approval runs on the primary GM’s client, so the learn hooks fire there.

Hooks.on('spell-book.spellBookOpened', ({ actor, app }) => {
  console.log(`Spell Book opened for ${actor.name}`, app);
});

Built-in macros

The Spell Book Macros compendium (spell-book.spell-book-macros) holds five script macros: Quick Access, Slot Tracker, Scroll Scanner, Spells Not In Lists, and Flag Purge. Each calls the matching method above. When a GM loads the world, missing macros are created and outdated ones are updated. Import them from the compendium to use them on the hotbar.