6.6 KiB
Foundry VTT
The Foundry integration keeps a Dragonroll campaign and a Foundry world in step: the world's characters and item directory arrive in the campaign, and what you change in Dragonroll 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. Copy the dragonroll-foundry folder into
{Foundry user data}/Data/modules/dragonroll-foundry/, restart Foundry, and enable Dragonroll
Foundry API in the world's module settings.
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, combat stats, proficiencies, traits, spells, carried gear, 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 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.
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.
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.