Fix issue #79: Implement documentation
All checks were successful
Test / test (push) Successful in 2s
All checks were successful
Test / test (push) Successful in 2s
This commit is contained in:
114
frontend/app/content/docs/03-integrations/03-foundry.md
Normal file
114
frontend/app/content/docs/03-integrations/03-foundry.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user