Spell Book Troubleshooter

GM-only diagnostic tool for generating and sharing support reports, and for transferring Spell Book settings between worlds.

---

Opening the Troubleshooter

The Troubleshooter is registered as a world-scoped settings menu (troubleshooterMenu, bug icon) restricted to GMs.

1. Open Configure Settings from the Game Settings sidebar.
2. Select the Spell Book tab.
3. Click Open Troubleshooter (bug icon) next to the Troubleshooter entry.

---

Window Layout

• Intro hint describing the purpose of the report.
• Include Actor Data checkbox, shown only when you own one or more spellcasting character actors. Actors of any other type, and characters with no spellcasting class, do not count. The checkbox persists to the per-user client setting troubleshooterIncludeActors. The hint beneath it lists the spellcasting actors that will be exported, by count and name.
• Output log: a read-only monospace panel containing the full generated report, themed to match the rest of Spell Book (no default browser styling).
• Footer buttons, in order:
  • Import Settings
  • Download
  • Copy to Clipboard
  • Join Discord
  • Report Issue

---

Report Contents

The report is plain text with sections delimited by /////////////// Section /////////////// headers.

Section	Contents
Game Information	Foundry version, system id and version, world id and title, user name and role, active scene name, ISO timestamp
Module Information	Spell Book version and active/inactive state, followed by every active module sorted by title with its version
Compendium Browser Sources	A dump of the Compendium Browser pack configuration: the total Item and Actor pack count with enabled and disabled tallies, the list of disabled packs, and the list of enabled packs with their title and collection id. Disabled packs that explain missing-spell reports can be spotted here
Spell Book Settings	Registered setting count vs defined count, each registered setting with a value summary, then a === FULL SETTINGS DATA (for import) === marker followed by a pretty-printed JSON dump of every registered Spell Book setting

Only module-scoped settings are exported. Settings owned by other modules are never included.

The Compendium Browser Sources section reads the systems’ packSourceConfiguration setting and lists every enabled and disabled Item and Actor pack. Disabled packs explain why expected spells are absent from a report.

Disabling a source in the Compendium Browser also hides any stock spell list whose spells all come from that source. Such lists disappear from the Class Rules picker and the Spell List Manager, and a class assigned one shows a “No spells available” notice. Re-enable the source to bring the lists back.

---

Include Actor Data

When the Include Actor Data checkbox is enabled, the Download action writes one JSON file per relevant actor alongside the report. Each file is the actor’s full document export via Actor#toCompendium(), not just Spell Book data. Only owned character actors that have at least one spellcasting class are exported. Non-caster owned actors are skipped.

Each actor file is augmented with an _stats.exportSource block containing:

• worldId
• uuid
• coreVersion
• systemId
• systemVersion
• exportedBy (user id)
• exportedAt (ISO timestamp)
• troubleshooterExport: true

Failed actor exports are reported via a warning notification listing the affected names.

Warning

Enabling this option can dramatically increase report size and may include personal character data. Keep it off unless a support request specifically calls for actor dumps.

---

Actions

Import Settings

Reads a previously downloaded Troubleshooter .txt report and applies the embedded settings block.

1. Click Import Settings and select a report file.
2. The embedded JSON block after === FULL SETTINGS DATA (for import) === is extracted and parsed. Files without that marker are rejected with a notification.
3. A confirmation dialog shows the number of settings contained in the file.
4. On confirm, each setting is applied with the following rules:
   • Unknown keys (not defined in SETTINGS) are dropped.
   • Values that match the current value are skipped.
   • Deferred keys (currently only loggingLevel) are applied after all other settings.
   • Values that fail deferred validation are skipped.
   • Write failures are collected and surfaced as a warning notification.
5. If more than 5 settings were imported, a Reload Recommended dialog offers to reload Foundry immediately.

Download

Saves the report as spellbook-troubleshooter-{timestamp}.txt. When Include Actor Data is enabled, each relevant actor is also written as actor-{slug}-{timestamp}.json.

Copy to Clipboard

Copies the current report text to the system clipboard.

Join Discord

Opens https://discord.gg/PzzUwU9gdz in a new tab.

Report Issue

Opens https://github.com/Sayshal/spell-book/issues in a new tab.

---

Settings Transfer Workflow

The settings block at the end of every report is a self-contained snapshot that can replicate a configuration in another world.

1. Open the Troubleshooter in the source world and click Download.
2. In the target world, open the Troubleshooter and click Import Settings.
3. Select the downloaded .txt file.
4. Confirm the count in the dialog.
5. If prompted, reload Foundry to let all settings take effect.

Note

Import only touches keys registered by Spell Book. Any foreign keys (from other modules or from older Spell Book versions that no longer exist) are silently dropped.

---

When to Use

• Bug reports: attach the downloaded .txt (and actor JSON files, if relevant) to a GitHub issue.
• Discord support: use Copy to Clipboard and paste the report into a support thread.
• Configuration transfer: share a report between GMs or worlds to reproduce an exact Spell Book configuration.
• Missing-spell diagnosis: check the Compendium Browser Sources (dnd5e) section for disabled packs that explain why expected spells are absent.