Foundry and discord bot
All checks were successful
Build and Deploy Nuxt / build (push) Successful in 1m51s

This commit is contained in:
2026-10-11 22:26:29 +02:00
parent a2b512699a
commit 1402045001
65 changed files with 5962 additions and 144 deletions

View File

@@ -0,0 +1,111 @@
# 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 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 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.
## 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.