More things
Some checks failed
Test / test (push) Failing after 5s
Build and Deploy Nuxt / build (push) Successful in 2m3s

This commit is contained in:
2026-11-20 18:59:01 +01:00
parent b83f64ff9e
commit d61659cfdd
51 changed files with 1777 additions and 3817 deletions

View File

@@ -3,7 +3,7 @@
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, world Items and Scenes directly with the Dragonroll campaign.
1. A linked GM client syncs character Actors and world Items into 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/*`.
@@ -68,19 +68,18 @@ 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.
Sync runs one way only — from Foundry to Dragonroll: creates, updates and deletes in the world reach
the campaign, and nothing changed in Dragonroll is written back into Foundry. Character sync requires
the D&D 5e Foundry system. 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.
world in step: actors and world items the GM creates, updates or deletes are sent to Dragonroll.
Turn it off to stop synchronizing altogether — nothing is sent to the campaign, so it keeps whatever
it already holds. Turn it back on to send the world's current state 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**.
@@ -107,72 +106,13 @@ else (Syndria98/dragonroll#67):
or one it renamed away from and remembers (`foundryNames`) — instead of doubling it. 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.
properties, description). Nothing is written from Dragonroll into the world's item directory.
- The folders grouping the world's item directory arrive in the campaign as its own item folders, tree
and nesting included, and the items are filed in them. A folder's **colour** goes the other way too:
what the GM colours in Foundry shows on the campaign's folder, and what the campaign colours lands on
the world's folder on the next reconcile (the world's document keeps its name and nesting either way).
and nesting included, and the items are filed in them. What the GM colours in Foundry shows on the
campaign's folder.
- 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: only a full snapshot sees
the whole world directory and can tell which synced rows it has let go of. Deleting a synced item in
Dragonroll removes its Foundry world copy on the next reconcile.
### Maps
A scene of the world is one of the campaign's maps (Syndria98/dragonroll#99), and only two things
about it cross over: the scene's **background picture** and the **grid** laid over it.
- The picture is sent as an absolute URL of this world, the way an actor's portrait is, so the
campaign draws the same battle map the table is looking at. Its cell size is the scene's own
(`grid`, and `grid.size` since Foundry V13), and the grid starts where the world shifts it
(`flags.core.shiftX` / `.shiftY`). A scene with no background picture makes no map.
- Everything else a scene holds stays in the world, and everything else a map holds stays in the
campaign: what one of its cells stands for, the folder it stands in, the notes pinned onto it and
the actors standing on it as tokens are the campaign's own. Nothing of a map is written back into
the world — scene sync runs one way, so a map deleted in the campaign comes back with its scene on
the next full list, and taking the scene off is what ends the map.
- A scene is matched to a map by its Foundry id, kept on the map as `foundrySceneId` (unique within
the campaign). A campaign that drew the same place by hand before its scene arrived is adopted
instead of doubled: the scene takes over the unmapped map holding its name.
- Live scene edits overwrite the map, including a picture and grid the campaign had set itself; a
full snapshot (the world linking or loading) leaves a map it already has alone. The maps of scenes
the world let go of are pruned by a full snapshot only, and a scene deleted in the world is
reported on `foundry/sync/scene-delete`.
- Autosync covers maps like everything else: turned off, no scene crosses over at all, and the ones
queued while it was off go over when it is turned back on.
### Notes
The campaign's notes read like the campaign's journal in the world (Syndria98/dragonroll#98): each
folder stands as a JournalEntry named after its path. Notes in the root of the campaign share the
journal called **Dragonroll**, and notes in a folder called *Sessions* with a subfolder *Arc 1* share
the journal **Sessions / Arc 1**; a note is always a page of the journal of its folder. The module
creates those journals — or adopts ones the GM already made under the same name, marking them as the
notes' journals — and renders each note's markdown into the page's HTML (headings, lists, quotes,
code and the inline marks), so the page reads in the journal the way the note reads in Dragonroll. A
note's dice widgets become buttons in the page too: pressing one rolls the expression with Foundry's
own dice and posts the result to chat (`adv`/`dis` are sent as `kh1`/`kl1`), so the note rolls at the
table without going back to the app. Its `[[Name]]` links become Foundry content links that open the
note page, character, item or scene they name, and `![[Name]]` embeds a character or an item as a
sheet preview right in the page (Foundry's `@UUID` and `@Embed` enrichers). A name the world has no
document for is shown dimmed, the way Dragonroll dims a link to an entry it cannot find. If a folder
is renamed, its journal is renamed with it, and
moving a note to another folder moves its page to that folder's journal. Notes are written in
Dragonroll, so this copy runs one way: a note made or edited in the campaign rewrites its page, and a
note deleted there takes its page with it. Pages the campaign does not own — the GM's own pages in
those journals — are left alone, and nothing written in a journal travels back. A folder journal whose
notes have all moved or gone is removed too, unless the GM keeps pages of their own in it. Autosync
off stops it too, like the rest of the sync.
Unlike the actor and item reconciles, the notes are only pulled over when something moved. Every
fifteen seconds the module asks for `GET /api/foundry/sync/notes/revision` — a hash of the campaign's
notes and their folder paths — and compares it with the pages it last wrote into the journals. While
both are unchanged the check stops there, so an idle campaign costs one hash comparison instead of a
pull of every note and a journal rewrite. A note made, edited, moved or deleted in Dragonroll, a
folder renamed, or a page of a notes' journal the GM changed or removed, moves one of the two and the
next check writes the pages in step again.
the whole world directory and can tell which synced rows it has let go of.
The module calls these Dragonroll routes with the campaign sync token (no Dragonroll login):
@@ -181,24 +121,12 @@ The module calls these Dragonroll routes with the campaign sync token (no Dragon
| `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 |
| `POST /api/foundry/sync/scenes` | The world's scenes upsert as the campaign's maps; `fullSync` also prunes |
| `POST /api/foundry/sync/scene-delete` | A scene was deleted |
| `GET /api/foundry/sync/characters` | Characters to apply back in Foundry |
| `GET /api/foundry/sync/items` | Items, and the item folders with their Dragonroll colours, to apply back in Foundry |
| `GET /api/foundry/sync/notes` | The campaign's notes, markdown and all, their folder path, and the journal page each stands as |
| `GET /api/foundry/sync/notes/revision` | A hash of the campaign's notes and folder paths, for the module's change check |
| `POST /api/foundry/sync/map-note` | Store a note's journal page id after creating that page |
| `GET /api/foundry/sync/status` | The campaign this world's token belongs to, for the module's pairing status |
| `POST /api/foundry/sync/unlink` | The module unlinks the world; the campaign forgets it and the token is revoked |
| `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 a journal page the module made for a note keeps its note's id in the `dragonroll-foundry.noteId`
flag, so the notes reconcile recognises its own pages. World items are marked with
`dragonroll-foundry.syncMutation` while Dragonroll writes them so
the write is not echoed back. A folder colour is written with that folder held in the client's set of
folders being synced, for the same reason.
flag, so the two sides recognise each other on the next push.
## 2. Run the bridge on the Foundry host