Foundry and discord bot
All checks were successful
Build and Deploy Nuxt / build (push) Successful in 1m51s
All checks were successful
Build and Deploy Nuxt / build (push) Successful in 1m51s
This commit is contained in:
111
dragonroll-foundry/README.md
Normal file
111
dragonroll-foundry/README.md
Normal 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.
|
||||
Reference in New Issue
Block a user