115 lines
6.6 KiB
Markdown
115 lines
6.6 KiB
Markdown
# 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 |
|
|
|
|
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.
|