Skip to main content

DDB Importer

Frequently asked questions

I have some questions about 2024 D&D or version 4.x D&D 5e System​

See the 2024 FAQ.

How long till I can import backgrounds, features, species, and classes into compendiums?​

DDB Importer works best (and always has) importing characters pre-built from DDB. If you really want to build your characters in Foundry, please see below. There is also the official foundry modules.

There is a new option in the Advanced character import settings to import to compendiums. This imports classes (level 20 characters only), features, feats, backgrounds, species and traits into the relevant DDB Importer compendiums. Please note, these will use a different structure to compendiums created in earlier versions of the software and D&D Systems. Classes, subclasses and features now go into the DDB Classes compendium. Species and Traits now go into the DDB Species compendium.

You may need to tweak some of these, and it will generally only select chosen options on a character.

Bulk Imports will return later in 2025. I'm unwilling to give a firm answer right now.

Why does DDB Importer work best importing characters directly?​

DDB Importer works by looking at the rich data exposed in the character sheets on DDB. This allows for very careful creation of content and items on your character (for example, automatically applying stat changes for the Artificers Battle Ready feature).

With the continued improvement of the 5e system it makes creating character features and classes for general use a lot harder, as there is a lot of linking and referencing features that are not chosen on a sheet.

You can still import classes/species/backgrounds/features (see 2024 FAQ).

DDB Importer is installed but doesn't show up as an available module​

  • DDB Importer only works for for the Foundry 5e system, no other systems (e.g. Advanced 5e).
  • Make sure your version of DDB Importer is supported by your D&D5e and Foundry versions. For example 6.x.x of DDB Importer requires Foundry 12 and D&D version 4.x.x, see also the below question for advice on using an older version of the module.

How do I install an older version of DDB Importer​

Visit the modules page on the Foundry website.

In the list of releases find the release you want. The 6.x.x+ series of DDB Importer only supports Foundry v12 and D&D 4.x+. The 5.2.x series supports Foundry 11 and 12, and D&D 3.2.

Right click on the Manifest URL link, and select Copy Link.

Go to your Foundry Setup screen, and to the Add-on Modules section. Uninstall DDB Importer if it's already installed. Click Install Module. Paste the link into the Manifest URL box at the bottom and click Install.

The import buttons are greyed out!​

They require the cobalt token setting to be set.

There are no map backgrounds after importing an adventure​

Make sure you are using the most up to date version of Adventure Muncher.

How do I get the Cobalt key manually?​

Open up a page of DnDbeyond and be sure you're logged in. Hit F12 or CTRL + Shift + I > Application > Cookies > dndbeyond.com > Search for Cobalt > Copy the key from the Value Field

My Core settings screen won't open​

Open the Browser Developer Console (F12) and run the following:

game.modules.get("ddb-importer").api.resetSecrets();

My Muncher window never appears​

I get a UI message Checking your DDB details - this might take a few seconds!.

Open the Browser Developer Console (F12) and run the following:

game.modules.get("ddb-importer").api.resetSecrets();

Whenever I use the "Fetch My Campaigns" button it hangs and nothing happens​

If you know what the campaign ID (it's a number, you can find it in the URL of your campaign on DDB) you can manually set it by opening the Browser Developer Console (F12) and run the following:

game.settings.set("ddb-importer", "campaign-id", "ID_HERE")

I purchased content on DDB and it's not available!​

Sometimes you just need to wait a little bit. Sometimes you need to Sync your entitlements.

For characters/spells/items check that you can create a character on DDB with those features. For adventures, make sure you can download the adventure in the DDB mobile app. For monsters make sure you can access the monster's stats in the DDB Encounter Builders. (By this I mean search for the monster, it will appear then click to expand the stat block, if it expands you have access, if it doesn't or wants your to purchase it, you do not).

Monsters that I have on DDB don't import​

  1. Make sure you can access the monster's stats in the DDB Encounter Builders. (By this I mean search for the monster, it will appear then click to expand the stat block, if it expands you have access, if it doesn't or wants your to purchase it, you do not).
  2. Own it or recently purchased? Make sure your entitlements are in sync.
  3. Make sure you are not excluding the content source category. If importing third party content, the source category is normally the publishers name or campaign world.

Spells/Items that I have on DDB don't import​

  1. Are they shared with you? Make sure your campaign id is set.
  2. Own it or recently purchased? Make sure your entitlements are in sync.
  3. Make sure you are not excluding the content source category. If importing third party content, the source category is normally the publishers name or campaign world.
  4. Done the above (and the content is not shared)? Create a new character in DDB that is not in a campaign and make sure you can add the item/spell to the character.

I tried the custom proxy and want to reset to use yours​

In the DDB Importer settings > Custom proxy settings, untick "Use a custom proxy?".

If that doesn't work try:

Open the Browser Developer Console (F12) and run the following:

game.modules.get("ddb-importer").api.resetProxy();

I want to use your macros/effects/etc but don't use DDB​

danger

If you are using a version of DDB Importer that works on the D&D Sytem 3.2 or earlier see the macro below. If you are on 4.x or highter, you cannt apply these effects at present to pre-existing content

You can apply the effects to existing actors/items using the following commands. This works best on spells, but some effect generation require spell descriptions, and for certain data (like damage) to already be on the spell:

Actor:

actor = game.actors.getName("Zinroe");
await game.modules.get("ddb-importer")?.api.effects.addDDBIEffectsToActorDocuments(actor);

Item:

item = game.items.getName("Cloak of Displacement");
await game.modules.get("ddb-importer")?.api.effects.addDDBIEffectToDocument(item);

Integration into the GUI will be forthcoming.

My Characters Hit Points aren't right​

Sometimes DDB can get confused, normally if the character is created using the random or guided mode.

Try adding and removing a level on DDB and then reimporting.

The Importer is overwriting custom or modified items/actions​

There are two options available:

  1. Click on the item, then the DDB icon on the title bar and check the ignore this item option.
  2. On the import screen check the "Ignore items on character sheet that have not been imported from DDB"

I want to prevent DDB Importer overwriting a thing on my character sheet!​

There are two main options available:

  1. Click on the feature/item/spell/etc and click the DDB Icon in the title bar, select the "Ignore this item when importing the character".
  2. Add a copy of the feature/item/spell/etc to the DDB Overrides compendium, and on the Advanced tab of the character importer screen select "Replace Items using those in your Override compendium".

I see the message "Unable to open the Compendium"​

Open "Configure Settings" -> "Module Settings" -> "D&D Beyond Importer" -> "Compendiums".

Ensure the Compendiums listed exist and are all different.

Default compendiums are called things like "DDB Spells".

If they are all the same, or are the first compendium in the list, chances are that Foundry has been unable to create default or select the chosen compendium.

Create compendiums if required, select them in the drop downs then click "Save".

My monsters have a vision of can't see anything/can see everything!​

The monster muncher uses the Token Defaults to apply to your tokens. it will set the sight radius to the appropriate darkvision range, but the "Has Vision" option will grant the token a vision attribute or not. (i.e. can it see normally or full access).

Clerics and Druids don't get their un-prepared spells​

You need to have the cobalt token set to get these spells.

Can I import books/adventures?​

Yes! But you should see the DDB Adventure Muncher.

My Characters AC is wrong​

This is almost certainly because you have the "Dynamic Active Effects" module installed. In the DAE module settings make sure you untick the set base AC and autocalculate ac options or DAE will try to do that for you.

It might also be because your AC settings in the "Active Effects" tab is incorrect.

My characters hit points are wrong​

First try adding a level and removing it, sometimes the underlying JSON can get stuck on another level.

Why do not all monsters have descriptions​

It uses the data that comes off the Encounter Builder as it's provide it's in JSON/structured way which makes parsing quick and "easy". However, not all the monsters there have the description that is on the full monster page.

TLDR: only the description available via the encounter builder on DDB gets pulled in for monsters.

How can I share content between my worlds in Foundry?​

Setup a shared compendium module.

I've upgraded to a new major Foundry version how do I migrate my shared compendium content to the new model?​

Open the Browser Developer Console (F12) and run the following:

game.modules.get("ddb-importer").api.compendiums.migrateCompendiums();

Okay so I have migrated to D&D 5e sytem version 1.4.0/1 and now none of my shared compendium monster AC's are right!

Answer: run the above migration command.

Do I need Compendium Content or the Character builder content?​

  • For integrating characters/spells/items you need to the character builder content.

  • For adventure muncher you need the compendium content.

Can I import all my characters without opening each one?​

Yes, use the following macro:

globalThis.DDBImporter.updateAllPCs.foundry();

My Pact Spells are not marked as prepared​

Pact spells can be marked as prepared during import by opening the browser console(F12) and enter game.settings.set("ddb-importer", "pact-spells-prepared", true).

My Homebrew doesn't import!​

Common issues are:

  • you have a campaign set in the core settings, so it will pull that campaigns homebrew, not yours.
  • you have not added the homebrew to your collection on DDB (unlikely if you can add this homebrew to a new character in DDB that is not in a campaign).

My Homebrew parsing fails

You need to try and match the style and html formatting of official monsters.

A short primer:

  • each action MUST be in a <p> tag.
  • action title MUST be in a <strong> tag. It MUST end with a full stop/period ..

Wording Examples:

You can use the regex links to check your syntax

Can I use the Icon Mapping API?​

Yes!

let item = game.items.find(i => i.name === "Shield")

await game.modules.get("ddb-importer").api.getIconPath(item);
'systems/dnd5e/icons/skills/weapon_18.jpg'

await game.modules.get("ddb-importer").api.getIconPath({ name: "Claws", type: "weapon" }, true, "Wolf");
'icons/commodities/claws/talon-red.webp'

I want to use the SRD Monster Art​

Use the following workflow:

  • Ensure that on the Settings tab "[Caution] Use SRD compendium things" is ticked.
  • On the Monsters tab ensure "Update Monster images on existing items?" is not checked.
  • Import your monsters, this will copy the SRD monsters across instead of using the DDB ones.
  • If you want to use the DDB generated data but the SRD images, untick the "[Caution] Use SRD compendium things" and reimport you monsters. The image will not be updated, but the features/attacks etc will.

If you like the SRD art them the "Forgotten Adventures" tokens and also the Token Variant Art module which allows you to easily apply the art from such packs to tokens.

I want to use tokens like Forgotten Adventures etc​

If you want other art like "Forgotten Adventures" the Token Variant Art module which allows you to easily apply the art from such packs to monster compendiums.

How can I purge a compendium of all content munched by DDBI?​

danger

All data removed by this can't be recovered unless you have a backup.

Replace world.testcomp with whatever id you named your compendium and run this in the browser console (F12) or as a script macro.

let pack = game.packs.get("world.testcomp");
let index = await pack.getIndex({
  fields: ["name", "flags.ddbimporter"]
});
let count = 0, total = index.size;
for (let i = total-1; i >= 0; i--) {
  const entry = index.contents[i];
  if (entry.flags?.ddbimporter) {
    if (pack.metadata.type === "Item") await Item.deleteDocuments([entry._id], { pack: pack.metadata.id });
    if (pack.metadata.type === "Actor") await Actor.deleteDocuments([entry._id], { pack: pack.metadata.id });
  }
  count++;
  console.log(`[${Math.floor(count / total * 100)}%] done (${count} of ${total} entries) - ${entry.name}`);
}
await Folder.deleteDocuments(pack.folders.map(f =>f.id), { pack: pack.metadata.id });

console.log("Finished!");

How do I purge all the content in journals?​

Warning, Using the code below will delete the data beyond recovery unless a backup is used:

JournalEntry.deleteDocuments([],{ deleteAll: true });
Folder.deleteDocuments(game.folders.filter(f => f.type == "JournalEntry").map(f => f.id));

Are some, but not all, map files are missing after import?​

This might also appear as an error such as Scene [xxxxxxx] validation errors: background: src: does not have a valid file extension.

If you are running FoundryVTT behind an Ingress(e.g. Kubernetes) or a web proxy, it may have an individual file size limit on uploads. If this limit is smaller than some of the high-res maps images it may cause them to fail to be imported.

Here are some links to common resolutions to this issue:

Can I set the doors to make a sound on opening?​

The following macro will update a scene:

/// Update All Door Sounds on scene
/// All Door Sounds from CONFIG.Wall.doorSounds
/// "futuristicFast", "futuristicHydraulic","futuristicForcefield"
/// "industrial","industrialCreaky"
/// "jail","metal"
/// "slidingMetal","slidingModern","slidingWood"
/// "stoneBasic","stoneRocky","stoneSandy"
/// "woodBasic","woodCreaky","woodHeavy"

const updates = canvas.walls.doors.map(d => ({_id: d.id, doorSound: "stoneSandy"}));
await canvas.scene.updateEmbeddedDocuments("Wall", updates);

I want to send you a useful log info​

Open the browser dev console (F12) and type:

await game.modules.get("ddb-importer").api.debug.start();

Perform the action which errors. (e.g. importing a character, trying to update a character)

In the browser dev console (F12) enter:

await game.modules.get("ddb-importer").api.debug.stop();

This will download a file to send to me.