# Dragonroll Foundry integration Foundry modules run in the game client, so the module cannot bind an HTTP port on the Foundry host. This integration uses a small companion bridge process on that host: 1. A linked GM client syncs character Actors, world Items and Scenes directly with the Dragonroll campaign. 2. The module publishes the active world's actor and item snapshot to the optional bridge. 3. The bridge serves authenticated HTTP read endpoints that Dragonroll proxies under `/api/foundry/*`. The Foundry module uses the client-side package API and hooks documented by Foundry: [module development](https://foundryvtt.com/article/module-development/). ## 1. Install the Foundry module In Foundry's **Setup → Add-on Modules → Install Module**, paste the manifest URL `https://dragonroll.aranroig.com/foundry/module.json`. The frontend serves that manifest and the zip it points to (`/foundry/dragonroll-foundry.zip`), both built from this directory, and the same manifest URL is what Foundry checks for updates. A self-hosted Dragonroll serves it at `https:///foundry/module.json`. Alternatively, copy the contents of this directory into `{Foundry user data}/Data/modules/dragonroll-foundry/`. Restart Foundry, then enable **Dragonroll Foundry API** in the world's module settings. After linking a campaign, the module stores a client-only token for character synchronization that persists across Foundry restarts. If the optional bridge is configured, Dragonroll also sends its connection settings to the module. Existing clients continue using their saved bridge URL and publish token automatically. The module publishes at world startup and after actor or item changes, and sends a lightweight heartbeat once a minute. Its local JavaScript API remains available at `game.modules.get("dragonroll-foundry").api`. ## Link a Foundry world to a Dragonroll campaign Open the campaign's **Settings → Integrations** tab in Dragonroll and create a pairing code. In the Foundry module settings, set **Dragonroll Endpoint** if you use a different Dragonroll server; it defaults to `https://dragonroll.aranroig.com` and the module adds `/api` automatically. Paste the code into **Dragonroll Campaign Pairing Code** and save. Codes expire after ten minutes and can only be used once. Both sides of the pairing survive restarts: Dragonroll keeps a pending code on the campaign so the settings screen re-displays it after a page reload, the window being closed, or a server restart (until it expires or is used), and the Foundry module keeps a code it could not redeem yet — for example one pasted while Dragonroll was restarting — retrying it at world startup and once a minute until the world finishes linking. For a local backend, use `http://localhost:5000`; the module adds `/api` like it does for any other server. Character synchronization works without the optional snapshot bridge. Configure that bridge only if you also need the read-only world snapshot API described below. **Dragonroll Pairing Status** in the module settings always says whether this browser holds a pairing and, once Dragonroll has answered `GET /api/foundry/sync/status`, which campaign the world is connected to. It is written by the module, not by the GM: it appears as not connected until the world is paired, names the campaign after a pairing or a check on world start and every minute afterwards, gives the reason when a pairing code can never be redeemed, and says the world is no longer linked once the campaign unlinks it. Because both the pairing code and the sync token are client settings, another browser of the same world reads as not paired. The campaign settings show the linked world's title and system. A Foundry world can be linked to only one campaign at a time. The pairing endpoint accepts cross-origin requests from the Foundry client and uses the one-time code instead of a Dragonroll login token. ## Character and item synchronization After linking, the GM client imports Foundry character, NPC, and creature Actors into the campaign. Creates, updates, and deletes sync in either direction; Dragonroll changes are applied in Foundry within about five seconds. The module currently creates Dragonroll characters in D&D 5e Foundry worlds. After updating an already-linked world to a version with character sync, create a fresh pairing code and enter it in Foundry once to issue the sync token. ### Auto-sync, and sending one actor on purpose **Dragonroll Auto-sync** in the module settings (on by default) is what keeps the campaign and this world in step: actors and world items the GM creates, updates or deletes are sent to Dragonroll, and both sides reconcile every few seconds. Turn it off to stop synchronizing altogether — nothing is sent to the campaign, and Dragonroll stops rewriting those documents in Foundry, so the campaign keeps whatever it already holds. Turn it back on to reconcile both sides again; the Foundry edits queued while it was off are sent as the world catches up. With autosync off — or any time a single character needs to cross over right now — right-click an actor (or several selected ones) in the Foundry actor directory and pick **Dragonroll: Force Sync**. Those actors, together with the gear carried inside them, are pushed to the campaign immediately even when autosync is off, **replacing everything that campaign holds for them** (Syndria98/dragonroll#96): what the campaign had edited on those actors is written over by what the world says. It replaces those actors only — it never prunes the campaign's other actors, which a full snapshot does and a forced sync never claims to. Actors Dragonroll does not import (anything that is not a character, NPC or creature) are refused with a notification. The optional read-only snapshot bridge is not affected: it keeps publishing the world snapshot behind `/api/foundry/*`, which is never written into the campaign. ### Items The campaign's Item list mirrors the world's item directory (Foundry's **items tab**) and nothing else (Syndria98/dragonroll#67): - The GM sends the world item directory (`game.items`) with every snapshot, and world items created, changed or deleted in Foundry are pushed as they happen. The items embedded in a character are that character's own inventory: they travel with its snapshot and stay on its sheet, so gear a character merely carries does not stand in the campaign's item list. - A world item folds into a Dragonroll row that already carries its name — one a campaign made by hand, or one it renamed away from and remembers (`foundryNames`) — instead of doubling it. Spells, classes, subclasses, backgrounds, feats and species are not gear and are not imported. - Foundry owns the fields it sends (category from the item type, rarity, quantity, weight, weapon properties, description). An item made by hand in Dragonroll is created in the world's item directory on the next reconcile, mapped afterwards, and editing it in Dragonroll updates the Foundry document. - The folders grouping the world's item directory arrive in the campaign as its own item folders, tree and nesting included, and the items are filed in them. A folder's **colour** goes the other way too: what the GM colours in Foundry shows on the campaign's folder, and what the campaign colours lands on the world's folder on the next reconcile (the world's document keeps its name and nesting either way). - A full snapshot keeps Dragonroll edits on reconnect; live Foundry edits overwrite. Item removal is pruned only by a full snapshot, so a live item push never deletes anything: only a full snapshot sees the whole world directory and can tell which synced rows it has let go of. Deleting a synced item in Dragonroll removes its Foundry world copy on the next reconcile. ### Maps A scene of the world is one of the campaign's maps (Syndria98/dragonroll#99), and only two things about it cross over: the scene's **background picture** and the **grid** laid over it. - The picture is sent as an absolute URL of this world, the way an actor's portrait is, so the campaign draws the same battle map the table is looking at. Its cell size is the scene's own (`grid`, and `grid.size` since Foundry V13), and the grid starts where the world shifts it (`flags.core.shiftX` / `.shiftY`). A scene with no background picture makes no map. - Everything else a scene holds stays in the world, and everything else a map holds stays in the campaign: what one of its cells stands for, the folder it stands in, the notes pinned onto it and the actors standing on it as tokens are the campaign's own. Nothing of a map is written back into the world — scene sync runs one way, so a map deleted in the campaign comes back with its scene on the next full list, and taking the scene off is what ends the map. - A scene is matched to a map by its Foundry id, kept on the map as `foundrySceneId` (unique within the campaign). A campaign that drew the same place by hand before its scene arrived is adopted instead of doubled: the scene takes over the unmapped map holding its name. - Live scene edits overwrite the map, including a picture and grid the campaign had set itself; a full snapshot (the world linking or loading) leaves a map it already has alone. The maps of scenes the world let go of are pruned by a full snapshot only, and a scene deleted in the world is reported on `foundry/sync/scene-delete`. - Autosync covers maps like everything else: turned off, no scene crosses over at all, and the ones queued while it was off go over when it is turned back on. ### Notes The campaign's notes read like the campaign's journal in the world (Syndria98/dragonroll#98): each folder stands as a JournalEntry named after its path. Notes in the root of the campaign share the journal called **Dragonroll**, and notes in a folder called *Sessions* with a subfolder *Arc 1* share the journal **Sessions / Arc 1**; a note is always a page of the journal of its folder. The module creates those journals — or adopts ones the GM already made under the same name, marking them as the notes' journals — and renders each note's markdown into the page's HTML (headings, lists, quotes, code and the inline marks), so the page reads in the journal the way the note reads in Dragonroll. A note's dice widgets become buttons in the page too: pressing one rolls the expression with Foundry's own dice and posts the result to chat (`adv`/`dis` are sent as `kh1`/`kl1`), so the note rolls at the table without going back to the app. Its `[[Name]]` links become Foundry content links that open the note page, character, item or scene they name, and `![[Name]]` embeds a character or an item as a sheet preview right in the page (Foundry's `@UUID` and `@Embed` enrichers). A name the world has no document for is shown dimmed, the way Dragonroll dims a link to an entry it cannot find. If a folder is renamed, its journal is renamed with it, and moving a note to another folder moves its page to that folder's journal. Notes are written in Dragonroll, so this copy runs one way: a note made or edited in the campaign rewrites its page, and a note deleted there takes its page with it. Pages the campaign does not own — the GM's own pages in those journals — are left alone, and nothing written in a journal travels back. A folder journal whose notes have all moved or gone is removed too, unless the GM keeps pages of their own in it. Autosync off stops it too, like the rest of the sync. Unlike the actor and item reconciles, the notes are only pulled over when something moved. Every fifteen seconds the module asks for `GET /api/foundry/sync/notes/revision` — a hash of the campaign's notes and their folder paths — and compares it with the pages it last wrote into the journals. While both are unchanged the check stops there, so an idle campaign costs one hash comparison instead of a pull of every note and a journal rewrite. A note made, edited, moved or deleted in Dragonroll, a folder renamed, or a page of a notes' journal the GM changed or removed, moves one of the two and the next check writes the pages in step again. The module calls these Dragonroll routes with the campaign sync token (no Dragonroll login): | Route | Use | |---|---| | `POST /api/foundry/sync/snapshot` | Actors and world items upsert; `fullSync` also prunes | | `POST /api/foundry/sync/item-snapshot` | Live world item edits, upsert only | | `POST /api/foundry/sync/item-delete` | A world item was deleted | | `POST /api/foundry/sync/scenes` | The world's scenes upsert as the campaign's maps; `fullSync` also prunes | | `POST /api/foundry/sync/scene-delete` | A scene was deleted | | `GET /api/foundry/sync/characters` | Characters to apply back in Foundry | | `GET /api/foundry/sync/items` | Items, and the item folders with their Dragonroll colours, to apply back in Foundry | | `GET /api/foundry/sync/notes` | The campaign's notes, markdown and all, their folder path, and the journal page each stands as | | `GET /api/foundry/sync/notes/revision` | A hash of the campaign's notes and folder paths, for the module's change check | | `POST /api/foundry/sync/map-note` | Store a note's journal page id after creating that page | | `GET /api/foundry/sync/status` | The campaign this world's token belongs to, for the module's pairing status | | `POST /api/foundry/sync/map` / `map-item` | Store an id mapping after creating a document | | `POST /api/foundry/sync/delete` | An actor was deleted | Foundry documents keep the Dragonroll id in the `dragonroll-foundry.actorId` / `dragonroll-foundry.itemId` flag, and a journal page the module made for a note keeps its note's id in the `dragonroll-foundry.noteId` flag, so the notes reconcile recognises its own pages. World items are marked with `dragonroll-foundry.syncMutation` while Dragonroll writes them so the write is not echoed back. A folder colour is written with that folder held in the client's set of folders being synced, for the same reason. ## 2. Run the bridge on the Foundry host The bridge uses only Node.js built-in modules and requires Node 18 or newer. Set separate random tokens for backend reads and Foundry snapshot publishing, then start it: ```sh export DRAGONROLL_FOUNDRY_READ_TOKEN='replace-with-a-long-random-read-token' export DRAGONROLL_FOUNDRY_PUSH_TOKEN='replace-with-a-different-long-random-publish-token' export DRAGONROLL_FOUNDRY_ALLOWED_ORIGINS='https://vtt.example.com' export DRAGONROLL_FOUNDRY_HOST='0.0.0.0' export DRAGONROLL_FOUNDRY_PORT='8787' # Optional: the Foundry Data directory. With it the bridge can list the core # `icons/` library Dragonroll's item icon browser shows. export DRAGONROLL_FOUNDRY_DATA_PATH='/home/foundry/Foundry Data' npm start --prefix foundry/bridge ``` Put the bridge behind HTTPS when it is reachable outside a trusted private network. The Foundry browser origin must be listed in `DRAGONROLL_FOUNDRY_ALLOWED_ORIGINS`; separate multiple origins with commas. The bridge binds to `0.0.0.0` by default so Dragonroll can reach it on another host. Restrict network access to the bridge port to Dragonroll and Foundry clients. If the reverse proxy serves the bridge under a path prefix, configure it to strip that prefix before forwarding requests to port 8787. ## 3. Configure Dragonroll's backend Set these variables in the backend environment. `FOUNDRY_API_URL` is the bridge base URL reachable by the backend, without an API path. `FOUNDRY_API_CLIENT_URL` is optional and overrides the bridge URL sent to Foundry clients when they cannot reach the backend's bridge URL (for example, when the backend uses a private network address). `FOUNDRY_API_PUSH_TOKEN` must match the bridge's `DRAGONROLL_FOUNDRY_PUSH_TOKEN`: ```sh FOUNDRY_API_URL='https://vtt.example.com/dragonroll-bridge/' FOUNDRY_API_CLIENT_URL='https://vtt.example.com/dragonroll-bridge/' FOUNDRY_API_TOKEN='replace-with-the-bridge-read-token' FOUNDRY_API_PUSH_TOKEN='replace-with-the-bridge-publish-token' ``` The backend exposes these JWT-protected routes when the optional snapshot bridge is configured: | Dragonroll route | Data | |---|---| | `GET /api/foundry/world` | Active Foundry world metadata | | `GET /api/foundry/actors` | All world actors | | `GET /api/foundry/characters` | Actors with type `character` | | `GET /api/foundry/actors/:id` | One actor | | `GET /api/foundry/actors/:id/items` | Items embedded in an actor | | `GET /api/foundry/items` | World-level items | | `GET /api/foundry/items/:id` | One world-level item | | `GET /api/foundry/icons?campaign=&dir=&offset=` | One folder of Foundry's core icon library | The bridge exposes the matching routes under `/api/*`, plus `GET /health`. Data routes require `Authorization: Bearer `. Responses contain `{ status: "ok", data, world, syncedAt, ageSeconds, stale }`. The snapshot stays in memory; `stale` becomes true when the bridge has not received a GM heartbeat for more than two minutes. The bridge returns `503 foundry.not-ready` until a configured GM client has published its first snapshot. The icon library is the one route that reads the disk instead of the snapshot: with `DRAGONROLL_FOUNDRY_DATA_PATH` set, `GET /api/icons?dir=icons/svg&offset=120&limit=120` answers one folder at a time — `{ status: "ok", dir, directories, files, offset, next }` of paths relative to the data directory — and never reads outside `icons/`. `next` is the offset of the next page of icons, or null once the folder is listed, which is how the campaign's icon browser keeps a library of thousands lazy to load. Without that variable the route answers `503 foundry.errors.icons-unavailable`. World-level items come from Foundry's `game.items`; actor inventories come from each actor's embedded items collection. The API returns plain document data snapshots. This is a read-only integration: it does not create or update Foundry documents, and it does not persist the bridge cache across restarts.