Fix issue #99: Make maps sync
All checks were successful
Test / test (push) Successful in 2s

This commit is contained in:
Gitea OpenCode Agent
2026-10-15 23:59:54 +00:00
parent c9ee16f2f2
commit 437a11d23e
12 changed files with 936 additions and 5 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 and world Items directly with the Dragonroll campaign.
1. A linked GM client syncs character Actors, world Items and Scenes 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/*`.
@@ -105,6 +105,30 @@ else (Syndria98/dragonroll#67):
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.
The module calls these Dragonroll routes with the campaign sync token (no Dragonroll login):
| Route | Use |
@@ -112,6 +136,8 @@ 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/status` | The campaign this world's token belongs to, for the module's pairing status |

View File

@@ -33,9 +33,13 @@ let itemSyncRunning = false;
let itemSyncErrorLogged = false;
let folderSyncTimeout;
let folderSyncRunning = false;
let sceneSyncTimeout;
let sceneSyncRetryTimeout;
let sceneSyncErrorLogged = false;
const syncingItemIds = new Set();
const syncingFolderIds = new Set();
const queuedItemChanges = new Map();
const queuedSceneChanges = new Map();
function getCollectionContents(collection, collectionName) {
if (!collection) {
@@ -300,6 +304,7 @@ async function applyDragonrollLink(result) {
scheduleSnapshotSync(0);
setTimeout(initializeCharacterSync, 0);
setTimeout(reconcileDragonrollItems, 2000);
setTimeout(initializeSceneSync, 1000);
} else {
// Without a token this client cannot sync, and only a fresh link gives one.
linkProblem = "this client could not save the token it was given";
@@ -441,6 +446,8 @@ function handleAutoSyncChange(value) {
clearTimeout(actorSyncTimeout);
clearTimeout(itemSyncTimeout);
clearTimeout(folderSyncTimeout);
clearTimeout(sceneSyncTimeout);
clearTimeout(sceneSyncRetryTimeout);
return;
}
if (!game.user?.isGM || !getSyncToken()) return;
@@ -450,6 +457,7 @@ function handleAutoSyncChange(value) {
initializeCharacterSync();
reconcileDragonrollItems();
queueFoundryItemFolders(400);
initializeSceneSync();
if (queuedActorChanges.size) {
clearTimeout(actorSyncTimeout);
actorSyncTimeout = setTimeout(flushActorChanges, 400);
@@ -458,6 +466,10 @@ function handleAutoSyncChange(value) {
clearTimeout(itemSyncTimeout);
itemSyncTimeout = setTimeout(flushItemChanges, 400);
}
if (queuedSceneChanges.size) {
clearTimeout(sceneSyncTimeout);
sceneSyncTimeout = setTimeout(flushSceneChanges, 400);
}
}
function dragonrollActorId(actor) {
@@ -1356,6 +1368,102 @@ function queueFoundryActorChange(kind, actor) {
queueActorChange(kind, actor);
}
// --- Scene sync ---------------------------------------------------------------
// A scene of this world is one of the campaign's maps (Syndria98/dragonroll#99): its
// background picture and the grid laid over it travel to Dragonroll, which keeps a map per
// scene. That is all of a scene that crosses over — pinning notes on a map, standing tokens
// on it and saying how far one of its cells goes are the campaign's own business, so none
// of it comes back to the world.
// A scene travels as plain document data with its picture read from this world: Dragonroll
// draws it outside Foundry, so the path becomes an absolute URL the way a portrait does.
// Since V13 the picture sits under `background.src`, and under plain `img` before that.
function serializeFoundryScene(scene) {
const data = toPlainData(scene);
if (!data) return null;
const absolute = (path) => new URL(path, window.location.origin).toString();
if (data.background?.src && !/^(https?:|data:|\/\/)/i.test(data.background.src)) {
data.background = { ...data.background, src: absolute(data.background.src) };
} else if (data.img && !/^(https?:|data:|\/\/)/i.test(data.img)) {
data.img = absolute(data.img);
}
return data;
}
// The scenes the campaign mirrors as its maps. Every scene goes, including one with no
// picture: Dragonroll decides what of a scene is a map and, since such a scene's id is
// still listed, no map of the campaign is pruned because of it.
async function pushFoundryScenes(scenes, fullSync = false) {
const token = getSyncToken();
// A full push travels even with no scenes left: it is the one that tells the campaign
// which of the maps it mirrors from this world the world has let go of.
if (!token || !game.user?.isGM || !game.world || (!scenes.length && !fullSync)) return;
await postDragonroll("foundry/sync/scenes", {
worldId: game.world.id,
scenes: scenes.map(serializeFoundryScene).filter(Boolean),
fullSync,
}, token);
sceneSyncErrorLogged = false;
}
async function deleteDragonrollScene(foundrySceneId) {
const token = getSyncToken();
if (!token || !game.world || !foundrySceneId) return;
await postDragonroll("foundry/sync/scene-delete", {
worldId: game.world.id,
foundrySceneId,
}, token);
}
function reportSceneSyncError(error) {
if (sceneSyncErrorLogged) return;
sceneSyncErrorLogged = true;
console.warn(`${MODULE_ID} | Map sync failed and will retry.`, error);
}
function queueFoundrySceneChange(kind, scene) {
if (!scene || !game.user?.isGM || !getSyncToken()) return;
queuedSceneChanges.set(scene.id, { kind, scene });
clearTimeout(sceneSyncTimeout);
sceneSyncTimeout = setTimeout(flushSceneChanges, 400);
}
async function flushSceneChanges() {
// Autosync off: the scene edits wait here, like the actor and item changes do.
if (!isAutoSyncEnabled()) return;
const changes = [...queuedSceneChanges.values()];
queuedSceneChanges.clear();
const deleted = changes.filter((change) => change.kind === "delete");
const changed = changes.filter((change) => change.kind !== "delete");
try {
for (const change of deleted) await deleteDragonrollScene(change.scene.id);
if (changed.length) await pushFoundryScenes(changed.map((change) => change.scene));
} catch (error) {
reportSceneSyncError(error);
for (const change of changes) queuedSceneChanges.set(change.scene.id, change);
clearTimeout(sceneSyncTimeout);
sceneSyncTimeout = setTimeout(flushSceneChanges, 5000);
}
}
// The whole scene list travels when the world links and when it loads: the campaign's map
// list mirrors this world's scenes, and only a push holding every scene can say which of
// those maps the world has let go of.
async function initializeSceneSync() {
if (!getSyncToken() || !game.user?.isGM || !game.world || !isAutoSyncEnabled()) return;
try {
await pushFoundryScenes(game.scenes?.contents || [], true);
} catch (error) {
reportSceneSyncError(error);
clearTimeout(sceneSyncRetryTimeout);
sceneSyncRetryTimeout = setTimeout(initializeSceneSync, 15000);
}
}
async function publishSnapshot() {
if (!game.user?.isGM || !game.world) return;
if (syncInProgress) {
@@ -1448,6 +1556,10 @@ Hooks.once("ready", () => {
// already seen the world directory when it starts sending its own items back.
setTimeout(reconcileDragonrollItems, 2000);
setInterval(reconcileDragonrollItems, 5000);
// The campaign's maps mirror this world's scenes: the whole list goes once the world is
// loaded, and that push alone tells the campaign which of its synced maps this world has
// let go of.
setTimeout(initializeSceneSync, 3000);
for (const event of [
"createActor", "updateActor", "deleteActor",
@@ -1481,6 +1593,13 @@ Hooks.once("ready", () => {
queueFoundryItemChange(isDelete ? "delete" : "upsert", document);
});
}
// A scene the GM makes, renames or throws away is one of the campaign's maps being drawn
// or let go of (Syndria98/dragonroll#99). Only its picture and grid cross over, so this
// goes one way and needs no snapshot of the world behind it.
for (const event of ["createScene", "updateScene", "deleteScene"]) {
Hooks.on(event, (document) => queueFoundrySceneChange(event.startsWith("delete") ? "delete" : "upsert", document));
}
});
// A GM sends selected actors to Dragonroll from the actor directory's context