169 lines
9.9 KiB
Markdown
169 lines
9.9 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 and world Items 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.
|
|
|
|
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. It is an upsert 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 is synchronized with the world's gear, both ways:
|
|
|
|
- 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. Items embedded in a character travel with
|
|
that character's snapshot instead.
|
|
- Gear is deduplicated by name: the same sword in the world directory and in three characters'
|
|
inventories becomes one Dragonroll item. Names Dragonroll renames away from are remembered on the
|
|
item (`foundryNames`), so Foundry's copies keep folding into it rather than coming back as a
|
|
duplicate. 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.
|
|
- 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. Deleting a synced item in
|
|
Dragonroll removes its Foundry world copy on the next reconcile. Items that live only in an actor's
|
|
inventory are owned by that actor's snapshot: editing such an item in Dragonroll does not rewrite the
|
|
actor's copy.
|
|
|
|
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 |
|
|
| `GET /api/foundry/sync/characters` | Characters to apply back in Foundry |
|
|
| `GET /api/foundry/sync/items` | Items to apply back in Foundry |
|
|
| `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 world items are marked with `dragonroll-foundry.syncMutation` while Dragonroll writes them so
|
|
the write is not echoed back.
|
|
|
|
## 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'
|
|
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 |
|
|
|
|
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.
|
|
|
|
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.
|