DDB Sync

DDB Sync is an unofficial Foundry VTT module that syncs selected D&D Beyond character data into Foundry and can forward Beyond20 rolls through a local proxy.

Current package: 0.2.0
Foundry module version: 0.2.0
Proxy package version: 0.2.0

This project is not affiliated with D&D Beyond, Wizards of the Coast, Foundry Virtual Tabletop, or Beyond20.

Components

The package contains three parts:

• Foundry module: ddb-sync
• Node proxy: local service for D&D Beyond requests and bridge events
• Browser extension: helper for forwarding Beyond20 data to the proxy

Requirements

• Foundry VTT v14
• DnD5e system for Foundry
• Node.js for the local proxy
• A D&D Beyond account
• D&D Beyond characters that are public or otherwise readable by the character endpoint
• Optional: DDB Importer
• Optional: Dice So Nice
• Optional for the bridge: Beyond20 and the included browser extension

Character Sync can only read D&D Beyond characters that the DDB character endpoint can access. Private or inaccessible characters may fail even with a valid CobaltSession.

Installation

1. Stop Foundry.
2. Extract the ZIP file.
3. Copy the ddb-sync folder into Foundry's Data/modules/ folder.
4. Start Foundry.
5. Enable DDB Sync in the world.

The module folder must be named ddb-sync.

Starting the proxy

The proxy runs locally at:

http://127.0.0.1:32123

From inside the ddb-sync folder:

npm install
npm run proxy

On Windows, you can also run:

start-proxy.bat

Keep the proxy running while using Character Sync or the Beyond20 Bridge.

Basic setup

Open Configure Settings -> Module Settings -> DDB Sync.

Recommended order:

1. Actor Mapping
2. Connection Settings
3. Character Sync Settings
4. Chat Settings
5. Beyond20 Bridge Settings

The main settings include the master switches:

• Enable Character Sync
• Parse DDB Rolls to Chat
• Enable Bridge
• Enable Debug Logging

Connection settings

Set the following values:

• Local Proxy URL: usually http://127.0.0.1:32123
• CobaltSession: the value of your D&D Beyond CobaltSession cookie
• DDB User ID: normally auto-detected

The User ID is used by some DDB gamelog requests. Authorization still depends on the CobaltSession. In most cases, enter the CobaltSession, create at least one Actor Mapping, and use auto-detection.

Actor mapping

Character Sync only applies to explicitly mapped actors.

Mapped actors can receive:

• HP, max HP, temp HP, and temp max HP
• Inspiration
• Conditions and exhaustion
• Death saves
• Initiative updates
• Other active DDB character sync behavior

DDB Importer flags may be used for mapping suggestions and rebuild actions. They do not trigger active sync by themselves.

The same DDB Character ID may be mapped to multiple Foundry actors.

Extra mapping

D&D Beyond Extras can be mapped to Foundry actors through the Extra Mapping form.

Notes:

• Loading Extras merges with existing mappings.
• Duplicate entries for the same parent character and Extra ID are skipped.
• Extras from different characters are preserved.
• Unowned NPC actors and other actor types can be shown for mapping when needed.
• DDB Extras do not expose conditions. The module currently syncs their HP and temp HP behavior.

Character sync

Character Sync can update:

• HP and max HP
• Temp HP and temp max HP
• Inspiration
• Death saves
• Conditions and exhaustion
• Extras
• Initiative, when enabled and when a Foundry combat exists

HP and ability scores

D&D Beyond does not expose one final HP field for all cases. The module calculates the displayed value from DDB character data, including:

• class/base HP
• effective CON modifier per level
• HP bonuses
• DDB Bonus HP and Temp Max HP
• DDB Override Max HP
• removed HP
• temporary HP

Effective ability scores are calculated from DDB data, including:

• base stats
• bonus stats
• manual overrides
• selected ASI and feat choices
• granted race, background, feat, and item modifiers
• active set-score items such as Amulet of Health
• attunement requirements

2024 backgrounds

Current behavior:

• Legacy/2014 backgrounds: racial ability-score increases are applied.
• Official 2024 backgrounds: racial ability-score increases are suppressed, matching DDB behavior.
• Homebrew/custom backgrounds: the module follows DDB's current behavior and keeps racial ASIs active when DDB does so.

Known limitation: DDB does not currently provide a reliable way to mark homebrew backgrounds as official 2024 backgrounds. The module follows the effective values DDB shows instead of trying to correct homebrew rules.

Initiative sync

Initiative Sync reads DDB gamelog initiative rolls and applies them to the current Foundry combat tracker.

Behavior:

• Initiative rolls are only used for the tracker when a combat exists.
• The combat may be open but not started.
• If auto-add is enabled, the module can add a mapped actor's placed token to combat.
• Actors without a placed token on the current scene are not auto-added.
• If the dnd5e Dexterity tie-breaker setting is enabled, the module uses effective DDB DEX for the decimal tie-breaker.

DDB roll chat sync

The module can read recent DDB gamelog rolls and post them into Foundry chat.

Supported categories include:

• Ability checks
• Saving throws
• Skill checks
• Initiative
• Death saves

Death saves are posted privately to the GM.

Beyond20 Bridge

The bridge forwards Beyond20 payloads from D&D Beyond to Foundry through the local proxy.

Supported behavior includes:

• Character and monster rolls
• Attack and damage cards
• Fixed damage
• Critical damage
• Advantage, disadvantage, and triple advantage display
• Whisper handling
• Dice So Nice integration
• Display in VTT text
• Explicit image popouts from Beyond20/bridge payloads
• Duplicate and reload protection

Browser extension setup

1. Open the browser extension options.
2. Set the proxy URL, usually http://127.0.0.1:32123.
3. Copy the Custom VTT target URL from the extension.
4. Add that URL to Beyond20 as a custom VTT target.
5. Keep the local proxy running.

The bridge receiver opens only for D&D Beyond pages where the extension content script can respond.

Debug logging

Use Enable Debug Logging in the main module settings.

When enabled, debug output may include:

• mapped actor discovery
• DDB character fetches
• HP and ability-score calculations
• condition and death-save updates
• initiative handling
• Beyond20 payload inspection
• duplicate/reload protection decisions
• image and Display in VTT handling

Debug logging is off by default.

Troubleshooting

Character data does not sync

Check:

• You are logged in as GM.
• The proxy is running.
• The proxy URL is correct.
• CobaltSession is current.
• The D&D Beyond character is public/readable.
• The Foundry actor is explicitly mapped.
• Character Sync is enabled.

Rolls do not appear in chat

Check:

• Parse DDB Rolls to Chat is enabled.
• The specific roll type is enabled in Chat Settings.
• DDB User ID is present or auto-detected.
• The proxy is running.
• The relevant character is mapped where required.

Beyond20 Bridge does not receive rolls

Check:

• Enable Bridge is active.
• The local proxy is running.
• The browser extension proxy URL matches the module/proxy URL.
• Beyond20 is configured to send to the custom VTT target.
• Reload protection may ignore old queued events after startup.

Temporary DDB 409 conflicts

D&D Beyond can sometimes return:

409 Conflict
No adequate concurrency handler

The module treats the first such error in a short polling window as temporary, logs it to the console, and retries on the next poll. Repeated errors within the window still show the normal throttled Foundry warning.

Known limitations

• The module reads from D&D Beyond only. It does not write data back to DDB.
• DDB characters must be accessible to the DDB character endpoint.
• DDB Extras do not expose conditions.
• Homebrew/custom 2024-style backgrounds may not match official 2024 background behavior in DDB.
• The proxy must be running for Character Sync and the Beyond20 Bridge.

Credits

DDB Sync is an unofficial integration for personal Foundry VTT use.

Browser Extension

Before configuring Beyond20, install the included browser extension.

For local testing:

1. Open chrome://extensions.
2. Enable Developer mode.
3. Click Load unpacked.
4. Select the browser-extension folder.