Files
dragonroll/frontend/app/content/docs/03-integrations/03-foundry.md
Aran Roig 1ec29121e1
Some checks failed
Test / test (push) Failing after 2s
Build and Deploy Nuxt / build (push) Successful in 1m51s
Deploy deepseek 2
2026-10-19 19:04:28 +02:00

9.5 KiB

Foundry VTT

The Foundry integration keeps a Dragonroll campaign and a Foundry world in step: the world's characters, item directory and scenes arrive in the campaign, and what you change in Dragonroll of those characters and items goes back to the world.

There are two separate parts, and you only need the first of them:

Part What it is
The Dragonroll Foundry API module Installed in the world. Links it to a campaign and keeps its actors and items synced. Runs in the game client.
The optional snapshot bridge A small process on the Foundry host that publishes a read-only snapshot of the world for Dragonroll to browse. Only for reading world data over the API.

Character and item sync works without the bridge.

Installing the module

Foundry VTT v12 to v14. In Foundry's Setup → Add-on Modules → Install Module, paste the manifest URL https://dragonroll.aranroig.com/foundry/module.json. Foundry downloads the module from your Dragonroll server, and the same URL later tells it when an update is available.

A self-hosted Dragonroll serves its own manifest at https://<your-dragonroll-host>/foundry/module.json.

Then enable Dragonroll Foundry API in the world's module settings. To install by hand instead, copy the dragonroll-foundry folder into {Foundry user data}/Data/modules/dragonroll-foundry/ and restart Foundry.

The module's own settings hold two things you set: the Dragonroll Endpoint — the address of your Dragonroll server, https://dragonroll.aranroig.com by default — and Dragonroll Auto-sync, which is on.

Linking a world

Open the world with a GM account. The module asks Dragonroll for a sign-up link and prints it in a notification: open it, sign in, and pick the campaign this world belongs to. Dragonroll Pairing Status in the module settings always says where things stand — waiting for a link, connected to a named campaign, or why a link could not be used.

Worth knowing:

  • The link expires after ten minutes and works once. If it goes unused, reload the world to get a new one.
  • A world links to one campaign, and a campaign to one Foundry world: linking a second world replaces the first.
  • The link, the sync token it hands back and the pairing status are all client settings: the browser that completed the link is the one that syncs. Another browser on the same world reads as not paired until it links too.
  • Dragonroll Pairing Status is written by the module. It is not a field to fill in.
  • The campaign shows the linked world's title and system under Settings → Integrations, where Unlink ends the pairing.

What syncs

In Foundry In the campaign
Character, NPC and creature actors Actors with the same sheet: abilities, saving throws, skills, combat stats, proficiencies, tools, languages, traits, spells, carried gear with its icons, coins, portrait
The world's item directory (the items tab) The campaign's item list, with category, rarity, quantity, weight, properties and description
The folders grouping that item directory Item folders with the same names and nesting
A folder's colour The campaign's folder colour — and the other way round, what you colour in Dragonroll lands on the world's folder
The world's scenes The campaign's maps: the scene's background picture and the grid laid over it, in the scene's own cell size
A journal per note folder, named after its path — one page per note Your campaign's notes. They arrive from Dragonroll: what you write in a journal does not go back

The item list is the world's item directory and nothing else. The gear a character carries is that character's inventory: it travels with the character and stays on its sheet, so a sword a fighter owns does not turn up in the campaign's item list. Spells, classes, subclasses, backgrounds, feats and species are not gear and are not imported.

The world's scenes are the campaign's maps, and only their background picture and their grid cross over: a map arrives with the scene's picture and its cell size, and with the grid where the world shifts it. That is where the two stop — what one of your cells stands for, the folder a map stands in, the notes pinned onto it and the characters standing on it as tokens stay in the campaign, and nothing about a map is written back into the world. The scene list goes over when the world links and when it loads, which is also when the map of a scene the GM deleted goes with it; scenes changed afterwards arrive as they happen. A scene with no background picture makes no map, and the full list leaves a map the campaign already had alone, so a grid you lined up yourself survives a reload.

An actor or item keeps the Dragonroll id it was given in a dragonroll-foundry.actorId / dragonroll-foundry.itemId flag, and that is what makes the two sides recognise each other. A world item that carries no flag is matched by name, so a hand-written item in Dragonroll is adopted instead of doubled, and renaming it in either place does not resurrect a duplicate.

Changes flow both ways as they happen, and Dragonroll's own edits are applied back in Foundry within a few seconds. A full snapshot — the one taken when the world links, or forced from the actor directory — is the only thing that prunes: it is the only moment either side can see the whole list and notice what is gone. Live edits never delete anything.

Notes are the exception that runs one way, because notes are written in Dragonroll: each folder stands as a journal named after its path. Notes in the root of the campaign share the journal called Dragonroll, while notes in a folder called Sessions with a subfolder Arc 1 share the journal Sessions / Arc 1; every note is a page of the journal of its folder. A note's dice widgets are buttons there as well: press one in the journal and Foundry rolls it and posts the result to chat, so advantage and disadvantage roll the way the campaign's notes describe them. The note's [[links]] work in the page too: a link to a note page, a character, an item or a scene opens it in Foundry, and ![[a character or item]] is drawn as a sheet preview inside the page. Renaming a folder renames its journal, and moving a note to another folder moves its page along. The module only pulls the notes over when something has changed, checking every fifteen seconds, so a note you make, edit or move in the app appears in its journal within that time, and deleting one takes its page with it. Pages the campaign does not own — ones the GM made in those journals themselves — are left alone, and nothing written in a journal travels back to the campaign. A folder journal whose notes have all left is removed too, unless the GM keeps pages of their own in it.

Auto-sync, and sending one actor on purpose

Dragonroll Auto-sync is what keeps the two in step: actors and world items you create, change or delete are sent to the campaign, and both sides reconcile every few seconds. Turning it off stops all of it — nothing is sent, and Dragonroll stops rewriting your Foundry documents, so the campaign keeps whatever it already holds. Turn it back on and both sides reconcile again, including the edits queued while it was off.

To send one character across right now, or to cross over while autosync is off, right-click the actor (or several) in the Foundry actor directory and pick Dragonroll: Force Sync. Those actors, with the gear inside them, are pushed immediately. It only upserts: it never prunes the campaign's other actors. Actors Dragonroll does not import — anything that is not a character, NPC or creature — are refused with a notification saying so.

Foundry's icons in Dragonroll

With a world linked, Dragonroll's item icon browser can page through the icon library that world ships with, one folder at a time. If it says the world has no address, set it under Settings → Integrations → Foundry VTT URL in the campaign.

The optional snapshot bridge

The bridge is a small Node.js (18 or newer) process that runs beside Foundry. A GM client publishes the world's actor and item snapshot to it, and Dragonroll reads that snapshot back through its own API, so a server can ask what a world holds without touching the game. It is read-only, it keeps nothing across restarts, and character sync does not depend on it.

It needs its own tokens — separate ones for publishing and for reading — and an origin allow-list for the Foundry client:

Variable What it is
DRAGONROLL_FOUNDRY_PUSH_TOKEN The token the Foundry client publishes with; the backend's FOUNDRY_API_PUSH_TOKEN must match it
DRAGONROLL_FOUNDRY_READ_TOKEN The token reads with; the backend's FOUNDRY_API_TOKEN must match it
DRAGONROLL_FOUNDRY_ALLOWED_ORIGINS The browser origins allowed to publish, comma separated
DRAGONROLL_FOUNDRY_HOST / DRAGONROLL_FOUNDRY_PORT Where the bridge listens; 0.0.0.0:8787 by default
DRAGONROLL_FOUNDRY_DATA_PATH The Foundry Data directory, which lets the bridge list the core icons/ library

The backend points at it with FOUNDRY_API_URL (and FOUNDRY_API_CLIENT_URL when the Foundry clients reach it under a different address than the backend does). Once it is set up, Dragonroll answers GET /api/foundry/world, /actors, /characters, /items, one of each by id, an actor's embedded items, and /icons — all for a signed-in Dragonroll user, and all read-only.

dragonroll-foundry/README.md in the source repository documents the bridge, its routes and its heartbeat in full.