# 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, 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 | | A journal called **Dragonroll** — one page per note | Your campaign's notes. They arrive **from** Dragonroll: what you write in the 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. 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: every note stands as a page of a single journal called **Dragonroll**. A note you make or edit in the app appears on that journal within a few seconds, and deleting one takes its page with it. Pages the campaign does not own — one the GM made in that journal themselves — are left alone, and nothing written in the journal travels back to the campaign. ## 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.