236 lines
15 KiB
Markdown
236 lines
15 KiB
Markdown
# 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
|
|
|
|
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 omits `/api` and the backend accepts
|
|
the local pairing route at its root. 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): every
|
|
note stands as a page of one JournalEntry named **Dragonroll**. The module creates that journal — or
|
|
adopts one the GM already made under that name, marking it as the notes' journal — and renders each
|
|
note's markdown into page HTML with Foundry's own renderer. Notes are written in Dragonroll, so this
|
|
copy runs one way: a note made or edited in the campaign rewrites its page on the next reconcile, and
|
|
a note deleted there takes its page with it. Pages the campaign does not own — the GM's own pages in
|
|
that journal — are left alone, and nothing written in the journal travels back. Autosync off stops it
|
|
too, like the rest of the sync.
|
|
|
|
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, and the journal page each stands as |
|
|
| `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 <read-token>`. 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.
|