Spell Book API Reference

Macros and external modules can call the same operations the Spell Book UI does.

Accessing the API

The API is registered at Foundry init and is available on both the module entry and a global convenience alias. Both access points are ready before the ready hook fires.

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

Method summary

Method	Audience	Purpose
`spellBookQuickAccess()`	All	Open Spell Book for the selected token.
`openSpellBookForActor(actor)`	All	Render Spell Book directly for a given actor without a selected token.
`openClassRulesForActor(actor, options)`	All	Open the Class Rules dialog for a given actor with optional save/cancel callbacks.
`spellSlotTracker()`	All	Post a slot usage summary to chat.
`hasConfiguredCompendiums()`	All	Check whether a spell-bearing compendium is visible to the player.
`scrollScanner()`	All	List spell scrolls found in item compendiums.
`spellsNotInLists()`	GM	Find spells not referenced by any spell list.
`debugSpell(name)`	All	Dump index entries for spells matching a name.
`flagPurge()`	GM	Remove Spell Book flags from actors.
`openPartyCoordinator(actors, options)`	All	Open the Party Coordinator for an actors array or a group actor.
`learnFromScroll(actor, classId, scrollItem, options)`	All	Learn the spell a scroll is linked to.
`getSpellLearningCost(actor, classId, spell)`	All	Resolve the gold cost and free-pool state for a spell.

Actor operations

`spellBookQuickAccess()`

Opens Spell Book for the currently selected token’s actor. Warns if no token is selected or the token has no actor, and notifies if the actor has no spell items. Use this to launch Spell Book from a hotbar macro or an external trigger outside the character sheet.

Parameters: none

Returns: Promise<void>

Example:

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

`spellSlotTracker()`

Posts a public chat card summarizing the selected token actor’s spell slot usage: Level, Used, and Remaining for each spell level with at least one slot. The actor is set as the speaker.

Parameters: none

Returns: Promise<void>

Example:

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

`openSpellBookForActor(actor)`

Renders the Player Spell Book for the supplied actor. Calls SpellManager.handleSpellbookOpen before rendering so actor-level setup runs first. Use this for integrations that already hold an actor reference and do not want to depend on a selected token.

Parameters:

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

Returns: Promise<?SpellBook>, the rendered Spell Book instance, or null if the actor cannot open one.

Example:

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 supplied actor. Optional callbacks fire on save and on cancel.

Parameters:

Name	Type	Description
`actor`	`Actor`	The actor whose Class Rules dialog should be opened.
`options`	`object`	Optional.
`options.onSave`	`Function`	Invoked after a successful save.
`options.onCancel`	`Function`	Invoked when the dialog closes without saving.

Returns: ?ClassRules, the dialog instance, or null if it cannot be opened.

Example:

const actor = game.actors.getName('Mira');
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 for an explicit roster. Pass an array of actors, or a single group actor whose members are resolved internally. The roster is filtered down to spellcasters.

Parameters:

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

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

Example:

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

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

Resolves the spell a scroll is linked to, applies the copying cost, adds the spell to the actor’s wizard spellbook, and consumes the scroll.

Parameters:

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`	`object`	Optional.
`options.consume`	`boolean`	Overrides the scroll-consumption setting.

Returns: Promise<boolean>, whether the spell was learned.

Example:

const actor = game.actors.getName('Mira');
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 a spell costs the actor to copy, accounting for the remaining free-spell pool.

Parameters:

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 on invalid input.

Example:

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

Compendium scanning

`hasConfiguredCompendiums()`

Synchronous check for whether a spell-bearing item compendium is visible to the current user. Reads the system’s packSourceConfiguration and filters Item packs that are visible and either untyped or include spell in flags.dnd5e.types. Use it to short-circuit a caller when nothing is available to render.

Parameters: none

Returns: boolean

Example:

if (!game.modules.get('spell-book').api.hasConfiguredCompendiums()) {
  ui.notifications.warn('No spell compendiums configured.');
  return;
}

`scrollScanner()`

Scans every Item compendium for consumables of subtype scroll and presents the results in a resizable dialog. Each row shows the scroll’s name and UUID. A Copy to Console button dumps the full list, including source pack, to the developer console.

Parameters: none

Returns: Promise<void>

Example:

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

`spellsNotInLists()`

GM-only. Cross-references every spell across all Item compendiums against the spells referenced by every discoverable spell list, then opens a dialog listing spells that appear in no list.

A Copy to Console button logs the full list of name (uuid) entries. The 3DS:ATLAS troubleshooter report includes a separate debug section listing every discoverable spell list and its spells.

Parameters: none

Returns: Promise<void>

Example:

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

`debugSpell(name)`

Returns and logs every spell-index entry whose name contains the given substring, case-insensitive. Use it to diagnose pack provenance and data-shape issues.

Each result entry contains:

name
uuid
compendiumSource (from _stats.compendiumSource)
sourceBook (system.source.book)
sourceCustom (system.source.custom)
level
school
properties (array)
materials
filterData, the object returned by the internal extractSpellFilterData helper, matching the shape used by Spell Book filters

Parameters:

Name	Type	Description
`name`	`string`	Substring to match against spell names, case-insensitive.

Returns: Promise<object[]>, the same array of summary objects that is logged.

Example:

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

GM maintenance

`flagPurge()`

GM-only. Prompts for a single eligible actor, or All Eligible Actors, and purges every Spell Book module flag from the chosen actor(s), along with every embedded item that carries a Spell Book flag.

Eligible actors have a player owner and at least one spellcasting class. The dialog is destructive and irreversible; a warning appears before confirmation.

Parameters: none

Returns: Promise<void>

Example:

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

Hooks

Spell Book emits the following hooks. Register handlers with Hooks.on / Hooks.once.

Hook	Payload	When
`spell-book.spellBookOpened`	`{ actor, app }`	First render of the Player Spell Book for a given actor.
`spell-book.spellBookClosed`	`{ actor }`	Close of the Player Spell Book.
`spell-book.preLearnSpell`	`{ actor, classId, spellUuid, source, costs }`	Before a spell is copied into 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 paid or scroll copy is recorded.
`spell-book.preparationSaved`	`{ actor, classIdentifier, changes }`	After a preparation change is saved.
`spell-book.loadoutApplied`	`{ actor, classIdentifier, spellUuids, loadoutId, loadoutName }`	After a loadout is applied.

preLearnSpell is dispatched with Hooks.call. Returning false cancels the learn. A listener can mutate the costs object to change the gold cost and copying time that get applied.

Example:

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

Spell Book also listens to the system’s dnd5e.restCompleted hook to drive rest-based behavior such as cantrip and spell swaps. It does not emit that hook.

Built-in macros

The module ships a spell-book.spell-book-macros compendium that is updated automatically on world load. It contains five ready-to-use script macros: Quick Access, Slot Tracker, Scroll Scanner, Spells Not In Lists, and Flag Purge. Each is a thin wrapper around the corresponding public API method above. To add them to your hotbar, import them from the compendium.