Files
dragonroll/dragonroll-foundry
Gitea OpenCode Agent 22c6403736
All checks were successful
Test / test (push) Successful in 2s
Fix issue #35: Dragonroll frontend: item modifications
2026-10-14 18:08:19 +00:00
..
2026-10-11 22:26:29 +02:00

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.

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.

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.

Dragonroll Pairing Status in the module settings always says whether this browser holds a pairing and, once Dragonroll has answered GET /api/foundry/sync/status, which campaign the world is connected to. It is written by the module, not by the GM: it appears as not connected until the world is paired, names the campaign after a pairing or a check on world start and every minute afterwards, gives the reason when a pairing code can never be redeemed, and says the world is no longer linked once the campaign unlinks it. Because both the pairing code and the sync token are client settings, another browser of the same world reads as not paired.

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
GET /api/foundry/sync/status The campaign this world's token belongs to, for the module's pairing status
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:

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:

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.