Installation and Settings

Requirements

• Foundry VTT: 14 or newer
• The system: 5.3.0 or newer
• Required: 3DS:ATLAS
• Optional: tidy5e-sheet, chris-premades, peddler, calendaria. See Module Integrations.

Installation

Foundry module browser

1. Launch Foundry VTT and open the Setup screen.
2. Open Add-on Modules and click Install Module.
3. Search for Spell Book by Tyler.
4. Click Install.
5. Enable the module in your world’s Manage Modules menu.

Manifest URL

1. Open Add-on Modules and click Install Module.

2. Paste the following Manifest URL:

   https://github.com/Sayshal/spell-book/releases/latest/download/module.json

3. Click Install and wait for the download to finish.

4. Enable the module in your world’s Manage Modules menu.

First-time setup

After enabling the module:

1. Open Game Settings -> Configure Settings -> Spell Book.
2. Choose your Default Spellcasting Rules (Legacy 2014 or Modern 2024).
3. Toggle Notify GM on Spell Changes to control whether the GM is whispered a card when a player changes prepared spells.
4. Open Spell Details Customization to choose which UI elements and metadata appear in spell rows.
5. Let the first GM connection finish its one-time maintenance. Class rule spell lists are normalized to arrays, module-owned spell lists are stamped with their kind, and spell list journals are re-filed into their folders. A pass that does not finish retries on the next world load.
6. As GM, open an actor’s Spell Book and use the gear icon in the sidebar to open the Spell Book Settings dialog and override world defaults per actor and per class. The gear is hidden for non-GM users. See Class Rules.

Settings reference

All settings live under Game Settings -> Configure Settings -> Spell Book. Scope: World = GM-only, shared by everyone; Client = per user, stored locally; User = per user, synced with the server.

Core rule settings

Setting	Key	Scope	Default	Description
Default Spellcasting Rules	spellcastingRuleSet	World	legacy	Default rule set for spellcasting behavior. Choose Legacy Rules (2014) or Modern Rules (2024). Per-actor override available in Class Rules.
Notify GM on Spell Changes	notifyGmOnSpellChanges	World	true	When a player saves any change to their prepared cantrips or spells, the GM receives a whispered card listing the removed and added spells. A class that is over its cantrip or spell limit adds a warning to that card. Per-actor override available in Class Rules.

Spell preparation and learning

Setting	Key	Scope	Default	Description
Consume Scrolls When Learning	consumeScrollsWhenLearning	World	true	Whether spell scrolls are consumed when a wizard learns a spell from them.
Charge Cost for Scroll Copying	chargeScrollLearningCost	World	false	Charge the normal spell learning cost when copying a spell from a scroll. Takes effect only while Deduct Spell Learning Costs is enabled.
Deduct Spell Learning Costs	deductSpellLearningCost	World	false	Automatically deduct gold from the character when learning spells. Cost per spell level is configurable per class.
Cantrip Scale Value Keys	cantripScaleValues	World	cantrips-known, cantrips	Comma-separated scale value keys the module checks to find a class’s cantrip limit. First resolving key wins; add keys here for homebrew classes.
Auto-Delete Unprepared Spells	autoDeleteUnpreparedSpells	User	false	Automatically removes unprepared prepared-casting spells from the character sheet after saving. Cleans up spells unprepared through the system UI.
Disable Long Rest Swap Prompt	disableLongRestSwapPrompt	Client	false	Disables the dialog that appears after a long rest for swapping spells or cantrips. The Spell Book remains available for swaps.
GM Approval for Spell Copying	gmApproveSpellCopy	World	false	Player spell copies wait for GM approval. Approving advances world time by the copy duration unless Skip Time is checked. A request made while no GM is connected is shown to the next GM who logs in.
Log Spell Copying to Downtime Note	spellCopyDowntimeNote	World	false	Append each copied spell and the time it took to a daily downtime note in the calendar. Requires Calendaria.

UI and display

Setting	Key	Scope	Default	Description
Maximum Note Length	spellNotesMaxLength	World	240	Maximum characters allowed in a personal spell note (range 10-1000, step 10).
Inject Notes into Spell Descriptions	injectNotesIntoDescriptions	Client	off	Inserts your personal spell notes into the spell description on the character sheet. Options: Off, Before Description, After Description.
Party Mode Token Limit	partyModeTokenLimit	Client	4	Maximum number of party member tokens displayed per spell in Party Mode (range 2-8).

Compatibility (conditional)

Setting	Key	Scope	Default	Description
Cauldron of Plentiful Resources Compatibility	cprCompatibility	World	false	Only appears when the chris-premades module is active. Runs Cauldron of Plentiful Resources automation setup after spells are added to a character sheet.

Display toggles (via Details Customization)

These toggles have no individual entries in the main settings panel. They are configured through the Spell Details Customization menu and stored as client-scope booleans, one per toggle:

• Player Spell Book UI: Favorites, Compare, Notes
• Player metadata: Spell Level, Components, School, Casting Time, Range, Damage Types, Conditions, Save, Concentration, Material Components
• Spell List Manager UI (GM): Compare
• Spell List Manager metadata (GM): same list as player metadata, stored under gmUI* keys

Full reference: Details Customization.

Hidden internal settings

These are registered with config: false and are not visible in the settings panel. They persist module state or internal bookkeeping:

Key	Scope	Purpose
customSpellListMappings	World	Compendium-to-custom-list mappings maintained by the SLM.
registryEnabledLists	World	IDs of dnd5e registry lists enabled for display.
hiddenSpellLists	World	UUIDs excluded from the Class Rules spell-list pickers and other consumers.
spellBookPositionn	Client	Last window position of the Player Spell Book.
spellListManagerPosition	Client	Last window position of the Spell List Manager.
classRuleListsMigrationComplete	World	Records that the one-time class rule list migration has finished.
spellListKindsMigrationComplete	World	Records that the one-time spell list kind migration has finished.

Theming, update notices, the troubleshooter, and logging level are provided by 3DS:ATLAS rather than by Spell Book settings.

Setting menus

Spell Details Customization

Opens a dialog where each user toggles UI elements and metadata fields on spell rows in the Player Spell Book and Spell List Manager.

• Menu label: Configure Display
• Icon: paint palette
• Restricted: No (players and GMs)

Full reference: Details Customization.

Per-actor overrides

The Spell Book Settings dialog (gear icon in the Player Spell Book sidebar) provides per-actor and per-class overrides. The gear is rendered for GMs only; non-GM users do not see it.

• Rule Set Override. Use Global / Legacy / Modern (per actor)
• Notify on Spell Changes. Boolean (per actor)
• Cantrip / Spell Swapping. None / level-up / long-rest (per class)
• Ritual Casting. None / prepared / always (per class)
• Class Spell List / Subclass Spell List. Multi-select (per class, required for spells to show)
• Show Cantrips, Force Wizard Mode, preparation bonuses, wizard learning cost/time, starting spells, spells per level

These overrides take precedence over the world-level defaults. See Class Rules.

Troubleshooting

Module not working

1. Confirm the module and 3DS:ATLAS are both enabled in Manage Modules.
2. Confirm Foundry is on 14 or newer and the system is on 5.3.0 or newer.
3. Generate a diagnostic report with the 3DS:ATLAS troubleshooter and share it on Discord or the issue tracker.

Performance

• Lower the logging level in 3DS:ATLAS.
• Disable optional integrations you do not use.

Next steps

• Players: see Player Quick Start
• GMs: see DM Quick Start
• Customizing spell lists: see Creating New Spell Lists and Modifying Existing Spell Lists