Files
dragonroll/dragonroll-foundry/scripts/api.js
Aran Roig b83f64ff9e
Some checks failed
Build and Deploy Nuxt / build (push) Successful in 1m10s
Test / test (push) Failing after 2s
jdkjskdj
2026-10-19 19:42:10 +02:00

2388 lines
92 KiB
JavaScript

const MODULE_ID = "dragonroll-foundry";
const SETTING_BRIDGE_URL = "bridgeUrl";
const SETTING_PUSH_TOKEN = "pushToken";
const SETTING_BRIDGE_CONFIG = "bridgeConfig";
const SETTING_DRAGONROLL_API_URL = "dragonrollApiUrl";
const SETTING_LINK_CODE = "linkCode";
const SETTING_LINK_URL = "linkUrl";
const SETTING_PAIRING_STATUS = "pairingStatus";
const SETTING_SYNC_TOKEN = "syncToken";
const SETTING_AUTO_SYNC = "autoSync";
// How often a world asks Dragonroll whether its sign-up link has been answered.
const LINK_POLL_MS = 5000;
let syncTimeout;
let syncInProgress = false;
let syncRequested = false;
let askingForLink = false;
let checkingLink = false;
let updatingLinkSetting = false;
// Marks a pairing Dragonroll honoured once and no longer accepts: the campaign
// unlinked this world, so the token this client holds is dead.
const PAIRING_REVOKED = "revoked";
let updatingPairingStatus = false;
let linkedCampaignName = "";
let linkProblem = "";
let actorSyncTimeout;
let characterSyncRetryTimeout;
let characterSyncRunning = false;
let actorSyncErrorLogged = false;
const syncingActorIds = new Set();
const queuedActorChanges = new Map();
let itemSyncTimeout;
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) {
throw new Error(`Foundry ${collectionName} collection is not available yet.`);
}
return collection.contents;
}
function toPlainData(document) {
return document?.toObject() ?? null;
}
const api = Object.freeze({
/** Return metadata for the currently loaded world. */
getWorld() {
if (!game.world) return null;
return {
id: game.world.id,
title: game.world.title,
system: game.system.id,
url: window.location.origin,
};
},
/** Return plain data snapshots for all Actor documents in the active world. */
getActors() {
return getCollectionContents(game.actors, "actor").map(toPlainData);
},
/** Return plain data snapshots for Actors whose system type is `character`. */
getCharacters() {
return getCollectionContents(game.actors, "actor")
.filter((actor) => actor.type === "character")
.map(toPlainData);
},
/** Return one Actor snapshot, or null when its id is not in the active world. */
getActor(actorId) {
return toPlainData(game.actors?.get(actorId));
},
/** Return plain data snapshots for world-level Item documents. */
getItems() {
return getCollectionContents(game.items, "item").map(toPlainData);
},
/** Return one world-level Item snapshot, or null when its id is not in the active world. */
getItem(itemId) {
return toPlainData(game.items?.get(itemId));
},
/** Return embedded Item snapshots belonging to an Actor, or null if the Actor is missing. */
getActorItems(actorId) {
const actor = game.actors?.get(actorId);
if (!actor) return null;
return getCollectionContents(actor.items, "actor item").map(toPlainData);
},
});
Hooks.once("init", () => {
game.settings.register(MODULE_ID, SETTING_BRIDGE_URL, {
name: "Legacy bridge URL",
scope: "client",
config: false,
type: String,
default: "",
});
game.settings.register(MODULE_ID, SETTING_PUSH_TOKEN, {
name: "Legacy bridge publish token",
scope: "client",
config: false,
type: String,
default: "",
});
game.settings.register(MODULE_ID, SETTING_BRIDGE_CONFIG, {
name: "Bridge configuration",
scope: "client",
config: false,
type: Object,
default: {},
});
game.settings.register(MODULE_ID, SETTING_SYNC_TOKEN, {
name: "Character sync token",
scope: "client",
config: false,
type: String,
default: "",
});
game.settings.register(MODULE_ID, SETTING_DRAGONROLL_API_URL, {
name: "Dragonroll Endpoint",
hint: "The Dragonroll server URL. The API path is added automatically.",
scope: "client",
config: true,
type: String,
default: "https://dragonroll.aranroig.com",
});
game.settings.register(MODULE_ID, SETTING_LINK_CODE, {
name: "Dragonroll Connection Link Code",
scope: "client",
config: false,
type: String,
default: "",
});
game.settings.register(MODULE_ID, SETTING_LINK_URL, {
name: "Dragonroll Connection Link",
scope: "client",
config: false,
type: String,
default: "",
});
game.settings.register(MODULE_ID, SETTING_PAIRING_STATUS, {
name: "Dragonroll Pairing Status",
hint: "Whether this world is connected to a Dragonroll campaign. The module keeps this text up to date: it asks Dragonroll for a sign-up link, and whoever opens that link picks the campaign. There is nothing to set here.",
scope: "client",
config: true,
type: String,
default: "",
onChange: handlePairingStatusChange,
});
game.settings.register(MODULE_ID, SETTING_AUTO_SYNC, {
name: "Dragonroll Auto-sync",
hint: "Keep the linked Dragonroll campaign in step with this world as its actors and items change. Turn this off to stop synchronizing; the actor directory's Dragonroll: Force Sync entry then sends an actor over only when you ask for it.",
scope: "client",
config: true,
type: Boolean,
default: true,
onChange: handleAutoSyncChange,
});
registerPairingMenu();
const module = game.modules.get(MODULE_ID);
if (!module) {
console.warn(`${MODULE_ID} | Could not register the public API: module was not found.`);
return;
}
module.api = api;
console.info(`${MODULE_ID} | Public API registered.`);
});
function dragonrollEndpoint(path) {
const endpoint = game.settings.get(MODULE_ID, SETTING_DRAGONROLL_API_URL)?.trim();
if (!endpoint) throw new Error("Set the Dragonroll endpoint in the Dragonroll Foundry module settings first.");
const apiBase = new URL(endpoint);
const basePath = apiBase.pathname.replace(/\/+$/, "");
const hasApiPath = basePath.endsWith("/api");
apiBase.pathname = `${hasApiPath ? basePath : `${basePath}/api`}/`;
apiBase.search = "";
apiBase.hash = "";
return new URL(path.replace(/^\/+/, ""), apiBase);
}
// A Dragonroll that is not there, or a URL that points at the web app instead of
// the API, answers with HTML. Say that plainly instead of a JSON parse error.
async function readDragonrollJson(response, url) {
try {
return await response.json();
} catch {
throw new Error(`Dragonroll answered HTTP ${response.status} at ${url} but not with JSON. Check the Dragonroll Endpoint setting.`);
}
}
async function postDragonroll(path, body, token = "") {
const headers = { "Content-Type": "application/json" };
if (token) headers.Authorization = `Bearer ${token}`;
const url = dragonrollEndpoint(path);
const response = await fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
});
const result = await readDragonrollJson(response, url);
if (!response.ok || result.status !== "ok") {
throw new Error(result.msg || `Dragonroll returned HTTP ${response.status}.`);
}
return result;
}
async function getDragonroll(path, token) {
const url = dragonrollEndpoint(path);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${token}` },
});
const result = await readDragonrollJson(response, url);
if (!response.ok || result.status !== "ok") {
throw new Error(result.msg || `Dragonroll returned HTTP ${response.status}.`);
}
return result;
}
// --- Connecting a world ----------------------------------------------------
// A world does not paste a code into its settings any more: it asks Dragonroll
// for the same sign-up link every service gets, the GM opens it and picks the
// campaign this world may work on. That link then hands the world its token.
function worldLinkRequest() {
const world = api.getWorld();
return {
service: "foundry",
target: {
id: world.id,
name: world.title,
user: game.user?.name || "",
meta: { system: world.system, url: world.url },
},
};
}
async function setLink(code, url) {
updatingLinkSetting = true;
try {
await game.settings.set(MODULE_ID, SETTING_LINK_CODE, code);
await game.settings.set(MODULE_ID, SETTING_LINK_URL, url);
} finally {
updatingLinkSetting = false;
}
}
async function requestDragonrollLink() {
if (askingForLink || !game.user?.isGM || !game.world) return;
askingForLink = true;
try {
const result = await postDragonroll("link/start", worldLinkRequest());
linkProblem = "";
await setLink(String(result.code || ""), String(result.linkUrl || ""));
ui.notifications?.info(`Open this link to pick the Dragonroll campaign for this world: ${result.linkUrl}`);
} catch (error) {
console.error(`${MODULE_ID} | Could not get a Dragonroll connection link.`, error);
linkProblem = error.message;
} finally {
askingForLink = false;
await setPairingStatus(pairingStatusText());
}
}
// What a link leaves this client with once a campaign has been picked: the token
// its sync runs on, and the bridge settings that came with it.
async function applyDragonrollLink(result) {
let syncTokenStored = false;
if (result.syncToken) {
try {
await game.settings.set(MODULE_ID, SETTING_SYNC_TOKEN, result.syncToken);
syncTokenStored = true;
} catch (error) {
console.error(`${MODULE_ID} | Could not save the character sync token.`, error);
}
}
if (result.bridgeConfig?.url && result.bridgeConfig?.pushToken) {
try {
await game.settings.set(MODULE_ID, SETTING_BRIDGE_CONFIG, result.bridgeConfig);
} catch (error) {
console.error(`${MODULE_ID} | Could not save the bridge configuration.`, error);
ui.notifications?.warn("This world was linked, but its bridge settings could not be saved on this client.");
}
}
linkedCampaignName = String(result.campaign?.name || "").trim();
await setLink("", "");
if (syncTokenStored) {
ui.notifications?.info("This Foundry world is now linked to the Dragonroll campaign.");
scheduleSnapshotSync(0);
setTimeout(initializeCharacterSync, 0);
setTimeout(reconcileDragonrollItems, 2000);
setTimeout(initializeSceneSync, 1000);
// The notes are pulled over on their own change check; get the first one in
// as soon as the world has a token instead of waiting for the next poll.
setTimeout(reconcileDragonrollNotes, 3000);
} 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";
ui.notifications?.warn("This world is linked to a Dragonroll campaign, but character sync is unavailable. Update Dragonroll and link the world again.");
}
}
// Where the sign-up link stands: still waiting for the GM to pick a campaign,
// finished and handing its token over, or gone, in which case there is a new
// link to show instead of a world that quietly stops trying.
async function advanceDragonrollLink() {
if (askingForLink || checkingLink || !game.user?.isGM || !game.world || getSyncToken()) return;
const code = game.settings.get(MODULE_ID, SETTING_LINK_CODE)?.trim();
if (!code) return requestDragonrollLink();
checkingLink = true;
try {
const result = await postDragonroll("link/pickup", { code });
if (result.state === "pending") return;
if (result.state === "linked") await applyDragonrollLink(result);
else if (result.state === "revoked") {
linkProblem = PAIRING_REVOKED;
await setLink("", "");
} else {
await setLink("", "");
await requestDragonrollLink();
}
} catch (error) {
// Dragonroll may be restarting: the next check asks again.
console.warn(`${MODULE_ID} | Could not check the Dragonroll connection link.`, error);
} finally {
checkingLink = false;
await setPairingStatus(pairingStatusText());
}
}
// --- Pairing status --------------------------------------------------------
// The pairing status is the sentence the module settings show. Everything in it
// comes from this client plus what Dragonroll last said about its token, so it
// reads correctly from the first frame and is corrected by refreshPairingStatus.
function pairingStatusText() {
const link = game.settings.get(MODULE_ID, SETTING_LINK_URL)?.trim();
if (linkProblem === PAIRING_REVOKED) {
return link
? `Not connected: this world is no longer linked to the Dragonroll campaign it was paired with. Open ${link} to pick a campaign again.`
: "Not connected: this world is no longer linked to the Dragonroll campaign it was paired with. Its settings will show a link to pick one again.";
}
if (getSyncToken()) {
return linkedCampaignName
? `Connected to the Dragonroll campaign "${linkedCampaignName}".`
: "Connected to a Dragonroll campaign.";
}
if (linkProblem) return `Not connected: Dragonroll did not answer this world's link (${linkProblem})`;
if (link) {
return `Not connected yet: open ${link} in a browser, sign in and pick the campaign for this world.`;
}
return "Not connected to a Dragonroll campaign. Set the Dragonroll Endpoint in these settings, then reload this world to get a sign-up link.";
}
async function setPairingStatus(text) {
if (game.settings.get(MODULE_ID, SETTING_PAIRING_STATUS) === text) return;
updatingPairingStatus = true;
try {
await game.settings.set(MODULE_ID, SETTING_PAIRING_STATUS, text);
} catch (error) {
console.warn(`${MODULE_ID} | Could not store the Dragonroll pairing status.`, error);
} finally {
updatingPairingStatus = false;
}
}
// Nothing is configured here: anything typed into the status is replaced by the
// status the module actually has.
function handlePairingStatusChange() {
if (updatingPairingStatus) return;
setPairingStatus(pairingStatusText());
}
// A token in this client only proves the world was paired once. Ask Dragonroll
// which campaign that token belongs to, and hear back when the campaign has
// unlinked this world again in the meantime.
async function refreshPairingStatus() {
const token = getSyncToken();
if (!token) {
linkedCampaignName = "";
await setPairingStatus(pairingStatusText());
return;
}
try {
const result = await getDragonroll("foundry/sync/status", token);
linkedCampaignName = String(result.campaign?.name || "").trim();
if (linkProblem === PAIRING_REVOKED) linkProblem = "";
} catch (error) {
// An unauthorized token is a campaign that unlinked this world. Any other
// failure (an unreachable Dragonroll, or one old enough to have no status
// route) says nothing about the pairing, so keep showing what we know.
if (error.message === "unauthorized") {
linkProblem = PAIRING_REVOKED;
linkedCampaignName = "";
// The dead token is dropped so the world stops pushing to a campaign that
// no longer wants it, and its link check asks for a sign-up link again.
await game.settings.set(MODULE_ID, SETTING_SYNC_TOKEN, "");
ui.notifications?.warn("This world is no longer linked to its Dragonroll campaign. Its settings show the link to pick one again.");
}
}
await setPairingStatus(pairingStatusText());
}
// --- Connection actions ----------------------------------------------------
// The module settings open a small window for the two things a GM does about a
// pairing: hand its sign-up link to somebody, and let the campaign go again.
// The sign-up link lives in a client setting, so copying it is how it reaches
// the browser the user will open it in.
async function copyPairingLink() {
if (getSyncToken()) {
ui.notifications?.info("This world is already linked to a Dragonroll campaign; there is no sign-up link to copy.");
return;
}
if (!game.settings.get(MODULE_ID, SETTING_LINK_URL)?.trim()) await requestDragonrollLink();
const link = game.settings.get(MODULE_ID, SETTING_LINK_URL)?.trim();
if (!link) {
ui.notifications?.warn("Dragonroll does not have a sign-up link for this world right now. Check the Dragonroll Endpoint setting.");
return;
}
try {
await navigator.clipboard.writeText(link);
ui.notifications?.info("Dragonroll sign-up link copied to the clipboard.");
} catch (error) {
// A browser can refuse the clipboard; the link is still the GM's to copy.
console.warn(`${MODULE_ID} | Could not copy the Dragonroll sign-up link.`, error);
ui.notifications?.warn(`Copy the Dragonroll sign-up link yourself: ${link}`);
}
}
// Letting the campaign go from this side: Dragonroll forgets the world and drops
// the token, so this world can pair with a campaign again. An unreachable
// Dragonroll keeps the token — dropping it here would leave the campaign still
// listing a world that can no longer reach it.
async function unlinkDragonrollCampaign() {
if (!game.user?.isGM || !game.world) return;
const token = getSyncToken();
try {
if (token) await postDragonroll("foundry/sync/unlink", { worldId: game.world.id }, token);
} catch (error) {
if (error.message !== "unauthorized") {
console.error(`${MODULE_ID} | Could not unlink this world from Dragonroll.`, error);
ui.notifications?.warn(`Dragonroll could not unlink this world: ${error.message}`);
return;
}
}
await game.settings.set(MODULE_ID, SETTING_SYNC_TOKEN, "");
linkedCampaignName = "";
linkProblem = "";
await setLink("", "");
await setPairingStatus(pairingStatusText());
ui.notifications?.info("This Foundry world is no longer linked to its Dragonroll campaign.");
await requestDragonrollLink();
}
function registerPairingMenu() {
const ApplicationV2 = globalThis.foundry?.applications?.api?.ApplicationV2;
// The module is loaded without Foundry's settings UI in its tests, and no
// Foundry this module runs on lacks ApplicationV2.
if (typeof game.settings.registerMenu !== "function" || !ApplicationV2) return;
class DragonrollPairingMenu extends ApplicationV2 {
static DEFAULT_OPTIONS = {
id: "dragonroll-pairing-menu",
classes: [MODULE_ID],
window: { title: "Dragonroll Connection", icon: "fa-solid fa-link" },
position: { width: 560 },
actions: {
copyLink() {
return copyPairingLink().then(() => this.render());
},
unlink() {
return unlinkDragonrollCampaign().then(() => this.render());
},
},
};
async _renderHTML() {
const link = game.settings.get(MODULE_ID, SETTING_LINK_URL)?.trim();
const root = document.createElement("div");
root.className = "dragonroll-pairing-menu";
const status = document.createElement("p");
status.textContent = pairingStatusText();
root.append(status);
if (link) {
const field = document.createElement("input");
field.type = "text";
field.readOnly = true;
field.value = link;
field.addEventListener("focus", () => field.select());
root.append(field);
}
const actions = document.createElement("div");
actions.className = "dragonroll-pairing-actions";
const copy = document.createElement("button");
copy.type = "button";
copy.dataset.action = "copyLink";
copy.innerHTML = '<i class="fa-solid fa-copy"></i> Copy link';
copy.disabled = Boolean(getSyncToken());
const unlink = document.createElement("button");
unlink.type = "button";
unlink.dataset.action = "unlink";
unlink.innerHTML = '<i class="fa-solid fa-link-slash"></i> Unlink campaign';
unlink.disabled = !getSyncToken();
actions.append(copy, unlink);
root.append(actions);
return root;
}
_replaceHTML(result, content) {
content.replaceChildren(result);
}
}
game.settings.registerMenu(MODULE_ID, "pairingMenu", {
name: "Dragonroll Connection",
label: "Copy link / Unlink",
hint: "Copy this world's sign-up link, or unlink the Dragonroll campaign it was paired with.",
icon: "fa-solid fa-link",
type: DragonrollPairingMenu,
restricted: true,
});
}
function scheduleSnapshotSync(delay = 500) {
clearTimeout(syncTimeout);
syncTimeout = setTimeout(publishSnapshot, delay);
}
function getBridgeConfig() {
const configured = game.settings.get(MODULE_ID, SETTING_BRIDGE_CONFIG);
if (configured?.url?.trim() && configured?.pushToken?.trim()) return configured;
const legacy = {
url: game.settings.get(MODULE_ID, SETTING_BRIDGE_URL)?.trim(),
pushToken: game.settings.get(MODULE_ID, SETTING_PUSH_TOKEN)?.trim(),
};
return legacy.url && legacy.pushToken ? legacy : null;
}
function getSyncToken() {
return game.settings.get(MODULE_ID, SETTING_SYNC_TOKEN)?.trim() || "";
}
// Autosync is what the module has always done: every Foundry create, update and
// delete pushes to Dragonroll, and both sides reconcile on a timer. When it is
// off, nothing syncs on its own and only a forced actor sync reaches Dragonroll.
function isAutoSyncEnabled() {
return game.settings.get(MODULE_ID, SETTING_AUTO_SYNC) !== false;
}
function handleAutoSyncChange(value) {
if (value === false) {
clearTimeout(actorSyncTimeout);
clearTimeout(itemSyncTimeout);
clearTimeout(folderSyncTimeout);
clearTimeout(sceneSyncTimeout);
clearTimeout(sceneSyncRetryTimeout);
return;
}
if (!game.user?.isGM || !getSyncToken()) return;
// Switching it back on converges both sides again, then the changes queued
// while autosync was off are pushed so this world's state wins over them.
initializeCharacterSync();
reconcileDragonrollItems();
queueFoundryItemFolders(400);
reconcileDragonrollNotes();
initializeSceneSync();
if (queuedActorChanges.size) {
clearTimeout(actorSyncTimeout);
actorSyncTimeout = setTimeout(flushActorChanges, 400);
}
if (queuedItemChanges.size) {
clearTimeout(itemSyncTimeout);
itemSyncTimeout = setTimeout(flushItemChanges, 400);
}
if (queuedSceneChanges.size) {
clearTimeout(sceneSyncTimeout);
sceneSyncTimeout = setTimeout(flushSceneChanges, 400);
}
}
function dragonrollActorId(actor) {
return actor.getFlag?.(MODULE_ID, "actorId") || actor.flags?.[MODULE_ID]?.actorId || "";
}
function serializeFoundryActor(actor) {
const data = {
...toPlainData(actor),
// Embedded items go through serializeFoundryItem so their icons become
// absolute URLs too: Dragonroll renders them outside of Foundry.
items: (actor.items?.contents?.map(serializeFoundryItem) || []).filter(Boolean),
};
if (data.img && !/^(https?:|data:|\/\/)/i.test(data.img)) {
data.img = new URL(data.img, window.location.origin).toString();
}
// Tools and languages travel by their names: what the actor holds are proficiency
// keys (and, since the third release of the system, language documents), which mean
// nothing to a sheet outside Foundry.
const names = { tools: foundryTraitNames(actor, "tools"), languages: foundryTraitNames(actor, "languages") };
if (names.tools || names.languages) data.dragonroll = { ...names };
return data;
}
// A proficiency list of `system.traits`: its keys resolved to the labels CONFIG gives
// them, plus whatever the GM typed as a proficiency of their own. `null` for an actor
// that has no such list, an empty array for one that has none of that kind. Dragonroll
// names its lists in full, while the world keeps its tools under `system.traits.tool`
// and its languages under `system.traits.languages`.
const TRAIT_FIELDS = { tools: "tool", languages: "languages" };
function foundryTraitNames(actor, kind) {
if (game.system?.id !== "dnd5e") return null;
const trait = actor.system?.traits?.[TRAIT_FIELDS[kind] ?? kind];
if (!trait || typeof trait !== "object") return null;
const names = (Array.isArray(trait.value) ? trait.value : [])
.map((key) => foundryProficiencyLabel(kind, key))
.filter(Boolean);
for (const custom of String(trait.custom ?? "").split(",")) {
const name = custom.trim();
if (name) names.push(name);
}
return [...new Set(names)];
}
function foundryProficiencyLabel(kind, key) {
if (typeof key !== "string" || !key) return "";
const entry = CONFIG.DND5E?.[kind === "languages" ? "languages" : "tools"]?.[key];
const label = entry?.label ?? entry?.name;
if (label) return String(label);
// A language the world added itself stands as a document of its own rather than in
// the system's config.
const document = kind === "languages" ? game.items?.get?.(key) : null;
if (document?.name) return String(document.name);
// The key beats dropping a proficiency the character really has.
return key;
}
function isSupportedCharacterActor(actor) {
const savedType = actor.getFlag?.(MODULE_ID, "actorType") || actor.flags?.[MODULE_ID]?.actorType;
return ["character", "npc", "creature"].includes(savedType || actor.type);
}
// Embedded documents the world owns outright (Syndria98/dragonroll#89): a feat is a trait
// and a race is a species — they reach the campaign through its traits and species fields,
// never through its inventory. Dragonroll must neither mark them as its own nor delete one
// when it writes the character, and an older campaign still holding such a row in its
// inventory must be let to write it out of the campaign without the document going with it.
const WORLD_OWNED_EMBEDDED_TYPES = new Set(["feat", "race", "species", "status", "spellbook", "language"]);
async function markActorItemsAsSynced(actor) {
const updates = actor.items.contents
.filter((item) => !item.getFlag?.(MODULE_ID, "syncedItem") && !WORLD_OWNED_EMBEDDED_TYPES.has(item.type))
.map((item) => ({
_id: item.id,
[`flags.${MODULE_ID}.syncedItem`]: true,
}));
if (updates.length) {
await withActorSyncSuppressed(actor, () => actor.updateEmbeddedDocuments("Item", updates));
}
}
async function withActorSyncSuppressed(actor, callback) {
if (!actor?.id) return callback();
syncingActorIds.add(actor.id);
try {
return await callback();
} finally {
syncingActorIds.delete(actor.id);
}
}
async function setDragonrollActorId(actor, actorId) {
if (!actor || !actorId) return;
await withActorSyncSuppressed(actor, () => actor.update({
[`flags.${MODULE_ID}.actorId`]: String(actorId),
[`flags.${MODULE_ID}.syncMutation`]: false,
}));
}
function reportActorSyncError(error) {
if (actorSyncErrorLogged) return;
actorSyncErrorLogged = true;
console.warn(`${MODULE_ID} | Character sync failed and will retry.`, error);
}
async function pushFoundryActors(actors, fullSync = false, replace = false) {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || (!actors.length && !fullSync)) return;
if (game.system.id !== "dnd5e") {
throw new Error("Character sync currently requires the D&D 5e Foundry system.");
}
const supportedActors = actors.filter(isSupportedCharacterActor);
for (const actor of supportedActors) await markActorItemsAsSynced(actor);
const result = await postDragonroll("foundry/sync/snapshot", {
worldId: game.world.id,
actors: supportedActors.map(serializeFoundryActor),
// The world item directory is what the campaign lists as its items
// (Syndria98/dragonroll#67); the gear a character carries travels inside that
// actor's snapshot as its inventory, not as campaign items.
items: getWorldItemSnapshots(),
// The folder tree those world items stand in (see worldItemFolderSnapshots).
folders: worldItemFolderSnapshots(),
fullSync,
// A forced sync replaces the campaign's row for these actors outright; a live
// change or a full snapshot never sets this, so the campaign keeps its edits.
replace,
}, token);
for (const mapping of result.actors || []) {
const actor = game.actors.get(mapping.foundryActorId);
if (actor && dragonrollActorId(actor) !== mapping.actorId) {
await setDragonrollActorId(actor, mapping.actorId);
}
}
await rememberItemMappings(result.items);
actorSyncErrorLogged = false;
}
async function deleteDragonrollActor(foundryActorId) {
const token = getSyncToken();
if (!token || !game.world || !foundryActorId) return;
await postDragonroll("foundry/sync/delete", {
worldId: game.world.id,
foundryActorId,
}, token);
}
// Sending actors on purpose, whether or not autosync is on: this is the push the
// GM asks for. It replaces everything the campaign holds for those actors (Syndria98/
// dragonroll#96), but it upserts them only, so unlike a full snapshot it never prunes
// anything else the campaign holds.
async function forceSyncActorsToDragonroll(actors) {
if (!game.user?.isGM || !game.world || !actors.length) return;
if (!getSyncToken()) {
ui.notifications?.warn("Link this world to a Dragonroll campaign before syncing actors to it.");
return;
}
const supported = actors.filter(isSupportedCharacterActor);
const refused = actors.filter((actor) => !supported.includes(actor));
if (refused.length) {
ui.notifications?.warn(`${refused.map((actor) => actor.name).join(", ")} ${refused.length === 1 ? "is" : "are"} not a character, NPC or creature: Dragonroll does not import ${refused.length === 1 ? "it" : "them"}.`);
}
if (!supported.length) return;
try {
await pushFoundryActors(supported, false, true);
ui.notifications?.info(supported.length === 1
? `${supported[0].name} was sent to the Dragonroll campaign.`
: `${supported.length} actors were sent to the Dragonroll campaign.`);
} catch (error) {
console.error(`${MODULE_ID} | Could not force sync the selected actors.`, error);
ui.notifications?.error(`Dragonroll sync failed: ${error.message}`);
}
}
function queueActorChange(kind, actor) {
if (!actor || !game.user?.isGM || !getSyncToken()) return;
if (syncingActorIds.has(actor.id) || actor.flags?.[MODULE_ID]?.syncMutation) return;
queuedActorChanges.set(actor.id, { kind, actor });
clearTimeout(actorSyncTimeout);
actorSyncTimeout = setTimeout(flushActorChanges, 400);
}
async function flushActorChanges() {
// Autosync may have been switched off while changes were queued: keep them
// waiting so turning it back on still sends them.
if (!isAutoSyncEnabled()) return;
const changes = [...queuedActorChanges.values()];
queuedActorChanges.clear();
const deleted = changes.filter((change) => change.kind === "delete");
const changed = changes.filter((change) => change.kind !== "delete");
try {
for (const change of deleted) await deleteDragonrollActor(change.actor.id);
await pushFoundryActors(changed.map((change) => change.actor));
} catch (error) {
reportActorSyncError(error);
for (const change of changes) queuedActorChanges.set(change.actor.id, change);
clearTimeout(actorSyncTimeout);
actorSyncTimeout = setTimeout(flushActorChanges, 5000);
}
}
// --- World item sync -------------------------------------------------------
// Items embedded in an actor travel with that actor's snapshot; the items below
// handle the world-level item directory (game.items) in both directions.
function itemPropertyLabels(item) {
const values = item.system?.properties?.value;
if (!Array.isArray(values) || !values.length || game.system?.id !== "dnd5e") return [];
const propertyConfigs = [
CONFIG.DND5E?.weaponProperties,
CONFIG.DND5E?.armorProperties,
CONFIG.DND5E?.toolProperties,
CONFIG.DND5E?.consumableProperties,
];
return values
.map((key) => {
for (const config of propertyConfigs) {
const label = config?.[key]?.label;
if (label) return String(label).toLowerCase();
}
return typeof key === "string" ? key : "";
})
.filter(Boolean);
}
function serializeFoundryItem(item) {
const data = toPlainData(item);
if (!data) return null;
if (data.img && !/^(https?:|data:|\/\/)/i.test(data.img)) {
data.img = new URL(data.img, window.location.origin).toString();
}
// Dragonroll shows plain property text; send Foundry's own labels when present
// so keys such as "ver" do not end up in its Item list.
const properties = itemPropertyLabels(item);
if (properties.length) data.dragonroll = { properties };
return data;
}
// --- Item folders ------------------------------------------------------------
// Dragonroll mirrors the folders the world's item directory is grouped into, so its
// item list reads like Foundry's. `game.folders` also holds the folders an actor
// keeps for its own inventory: those hang off the actor instead of the world, and
// the campaign has no use for them, so only folders rooted in the world go over.
// The folder a folder is nested in, or null when it is not nested in a folder.
function itemFolderParent(folder) {
const parent = typeof folder.parent === "string" ? game.folders?.get(folder.parent) : folder.parent;
return parent?.documentName === "Folder" ? parent : null;
}
// Whether a folder belongs to the world's item directory: its whole ancestry has
// to be folders, ending in one that nothing is above.
function isWorldItemFolder(folder, seen = new Set()) {
if (folder.type !== "Item" || seen.has(folder.id)) return false;
seen.add(folder.id);
const rawParent = folder.parent;
const rawParentId = typeof rawParent === "string" ? rawParent : rawParent?.id;
if (!rawParentId) return true;
const parent = typeof rawParent === "string" ? game.folders?.get(rawParentId) : rawParent;
if (parent?.documentName !== "Folder") return false;
return isWorldItemFolder(parent, seen);
}
// A Foundry folder's colour, or null for one the GM left uncoloured. Null travels as null:
// it tells Dragonroll to take a colour off the folder it was given before, whereas a module
// that says nothing about colours at all leaves the campaign's own choice alone.
function itemFolderColor(folder) {
const color = typeof folder?.color === "string" ? folder.color.trim() : "";
return color || null;
}
function worldItemFolderSnapshots() {
return (game.folders?.contents || [])
.filter((folder) => isWorldItemFolder(folder))
.map((folder) => ({
id: folder.id,
name: folder.name,
parent: itemFolderParent(folder)?.id || null,
color: itemFolderColor(folder),
}));
}
// A world item travels with the folder it stands in, so Dragonroll can file it the
// same way; `""` says the world keeps it at the root of the item directory. Items
// embedded in an actor use serializeFoundryItem instead: their folders are the
// actor's own, and the campaign's item list is deduplicated by name anyway.
function serializeFoundryWorldItem(item) {
const data = serializeFoundryItem(item);
if (!data) return null;
data.dragonroll = { ...data.dragonroll, folder: worldItemFolderId(item) };
return data;
}
// The folder id an item data carries is either the id or the Folder document
// itself, depending on the Foundry version.
function worldItemFolderId(item) {
const folder = item?.folder;
if (!folder) return "";
if (typeof folder === "string") return game.folders?.get(folder)?.documentName === "Folder" ? folder : "";
return folder.documentName === "Folder" ? String(folder.id || "") : "";
}
function getWorldItemSnapshots() {
return (game.items?.contents || []).map(serializeFoundryWorldItem).filter(Boolean);
}
// --- Folder colours ----------------------------------------------------------
// Colouring a folder is the one thing about the tree the campaign gets to do on its
// own: the world owns what the folders are called and how they nest, and Dragonroll
// owns the colour its user picks for one. So the colour travels back with the folder
// list the item reconcile reads, and lands on the world's folder — marked, like every
// Dragonroll write, so the world does not echo it straight back to the campaign.
async function withFolderSyncSuppressed(folder, callback) {
if (!folder?.id) return callback();
syncingFolderIds.add(folder.id);
try {
return await callback();
} finally {
syncingFolderIds.delete(folder.id);
}
}
async function applyDragonrollFolderColors(entries) {
for (const entry of entries || []) {
const folder = entry?.foundryFolderId ? game.folders?.get(entry.foundryFolderId) : null;
// Only the world's item directories: a Dragonroll folder the world has no document
// for is the campaign's business alone, and making one there is not ours to do.
if (!folder || folder.documentName !== "Folder" || !isWorldItemFolder(folder)) continue;
const color = entry.color || null;
if (itemFolderColor(folder) === color) continue;
await withFolderSyncSuppressed(folder, () => folder.update({ color }));
}
}
function dragonrollItemIdOf(item) {
return item.getFlag?.(MODULE_ID, "itemId") || item.flags?.[MODULE_ID]?.itemId || "";
}
async function withItemSyncSuppressed(item, callback) {
if (!item?.id) return callback();
syncingItemIds.add(item.id);
try {
return await callback();
} finally {
syncingItemIds.delete(item.id);
}
}
async function setDragonrollItemId(item, itemId) {
if (!item || !itemId) return;
await withItemSyncSuppressed(item, () => item.update({
[`flags.${MODULE_ID}.itemId`]: String(itemId),
[`flags.${MODULE_ID}.syncMutation`]: false,
}));
}
async function rememberItemMappings(mappings) {
for (const mapping of mappings || []) {
const item = game.items?.get(mapping.foundryItemId);
if (item && String(dragonrollItemIdOf(item)) !== String(mapping.itemId)) {
await setDragonrollItemId(item, mapping.itemId);
}
}
}
function reportItemSyncError(error) {
if (itemSyncErrorLogged) return;
itemSyncErrorLogged = true;
console.warn(`${MODULE_ID} | Item sync failed and will retry.`, error);
}
// Item pushes are upserts only: the full world snapshot sent with the actors
// owns pruning, because it is the only one that sees every embedded copy.
async function pushFoundryItems(items) {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || !items.length) return;
const result = await postDragonroll("foundry/sync/item-snapshot", {
worldId: game.world.id,
items: items.map(serializeFoundryWorldItem).filter(Boolean),
// The folder tree goes along, so an item that moved into or out of a folder
// arrives with the folder it names.
folders: worldItemFolderSnapshots(),
}, token);
await rememberItemMappings(result.items);
itemSyncErrorLogged = false;
}
async function deleteDragonrollItem(foundryItemId) {
const token = getSyncToken();
if (!token || !game.world || !foundryItemId) return;
await postDragonroll("foundry/sync/item-delete", {
worldId: game.world.id,
foundryItemId,
}, token);
}
function queueFoundryItemChange(kind, item) {
if (!item || !game.user?.isGM || !getSyncToken()) return;
if (syncingItemIds.has(item.id) || item.flags?.[MODULE_ID]?.syncMutation) return;
queuedItemChanges.set(item.id, { kind, item });
clearTimeout(itemSyncTimeout);
itemSyncTimeout = setTimeout(flushItemChanges, 400);
}
// A folder the GM made, renamed or nested has to reach the campaign even though no
// item changed, so the tree goes over on its own without pushing the items in it.
function queueFoundryItemFolders(delay = 400) {
clearTimeout(folderSyncTimeout);
folderSyncTimeout = setTimeout(pushFoundryItemFolders, delay);
}
async function pushFoundryItemFolders() {
// Autosync off: folder changes wait, like the item edits do.
if (!isAutoSyncEnabled()) return;
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || folderSyncRunning) return;
folderSyncRunning = true;
try {
await postDragonroll("foundry/sync/item-snapshot", {
worldId: game.world.id,
items: [],
folders: worldItemFolderSnapshots(),
}, token);
itemSyncErrorLogged = false;
} catch (error) {
reportItemSyncError(error);
queueFoundryItemFolders(5000);
} finally {
folderSyncRunning = false;
}
}
async function flushItemChanges() {
// Autosync off: the queued edits wait here, like the actor changes do.
if (!isAutoSyncEnabled()) return;
const changes = [...queuedItemChanges.values()];
queuedItemChanges.clear();
const deleted = changes.filter((change) => change.kind === "delete");
const changed = changes.filter((change) => change.kind !== "delete");
try {
for (const change of deleted) await deleteDragonrollItem(change.item.id);
if (changed.length) await pushFoundryItems(changed.map((change) => change.item));
} catch (error) {
reportItemSyncError(error);
for (const change of changes) queuedItemChanges.set(change.item.id, change);
clearTimeout(itemSyncTimeout);
itemSyncTimeout = setTimeout(flushItemChanges, 5000);
}
}
const CATEGORY_TO_FOUNDRY_ITEM_TYPE = {
weapon: "weapon",
armor: "equipment",
shield: "equipment",
consumable: "consumable",
tool: "tool",
"adventuring-gear": "loot",
"magic-item": "loot",
treasure: "loot",
other: "loot",
};
const RARITY_TO_FOUNDRY_VALUE = {
common: "common",
uncommon: "uncommon",
rare: "rare",
"very-rare": "veryRare",
legendary: "legendary",
artifact: "artifact",
};
function makeFoundryItemData(entry) {
const type = CATEGORY_TO_FOUNDRY_ITEM_TYPE[entry.category] || "loot";
const data = {
name: String(entry.name || "").trim(),
type,
img: getDragonrollImageUrl(entry.image) || undefined,
system: {
quantity: Number(entry.quantity) || 1,
weight: Number(entry.weight) || 0,
rarity: RARITY_TO_FOUNDRY_VALUE[entry.rarity] || "common",
description: { value: entry.description || "" },
},
flags: { [MODULE_ID]: { itemId: String(entry._id), syncMutation: true } },
};
if (type === "equipment") data.system.armor = { type: entry.category === "shield" ? "shield" : "medium" };
return data;
}
function foundryItemUpdateData(entry) {
const updates = {
name: String(entry.name || "").trim(),
"system.quantity": Number(entry.quantity) || 1,
"system.weight": Number(entry.weight) || 0,
"system.rarity": RARITY_TO_FOUNDRY_VALUE[entry.rarity] || "common",
"system.description.value": entry.description || "",
};
// An icon the campaign picked in Dragonroll travels back to Foundry; no icon
// there means leave the world's own choice alone, not erase it.
const image = getDragonrollImageUrl(entry.image);
if (image) updates.img = image;
return updates;
}
async function applyDragonrollItem(item, entry) {
const updates = foundryItemUpdateData(entry);
const changed = Object.entries(updates).some(([key, value]) => documentValue(item, key) !== value);
await withItemSyncSuppressed(item, async () => {
if (changed) await item.update(updates);
if (dragonrollItemIdOf(item) !== String(entry._id)) {
await item.update({ [`flags.${MODULE_ID}.itemId`]: String(entry._id) });
}
});
}
async function mapDragonrollItem(itemId, foundryItemId) {
const token = getSyncToken();
return postDragonroll("foundry/sync/map-item", {
worldId: game.world.id,
itemId: String(itemId),
foundryItemId: String(foundryItemId),
}, token);
}
async function createFoundryWorldItem(entry) {
const data = makeFoundryItemData(entry);
if (!data.name) return;
const item = await Item.create(data);
if (!item) return;
await withItemSyncSuppressed(item, async () => {
await item.update({ [`flags.${MODULE_ID}.syncMutation`]: false });
});
await mapDragonrollItem(entry._id, item.id);
}
async function reconcileDragonrollItems() {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || itemSyncRunning || !isAutoSyncEnabled()) return;
itemSyncRunning = true;
try {
const result = await getDragonroll("foundry/sync/items", token);
// The folder colours are applied first, and whatever system this world runs: a
// colour is the same on every one of them, while writing an item is what needs D&D 5e.
await applyDragonrollFolderColors(result.folders);
if (game.system.id !== "dnd5e") {
throw new Error("Item sync currently requires the D&D 5e Foundry system.");
}
const remoteItems = result.items || [];
const remoteById = new Map(remoteItems.map((entry) => [String(entry._id), entry]));
const localByRemoteId = new Map(game.items.contents
.map((item) => [String(dragonrollItemIdOf(item)), item])
.filter(([itemId]) => itemId));
const retainedFoundryIds = new Set();
for (const entry of remoteItems) {
let item = entry.foundryItemId ? game.items.get(entry.foundryItemId) : null;
if (!item) item = localByRemoteId.get(String(entry._id));
if (item) {
retainedFoundryIds.add(item.id);
await applyDragonrollItem(item, entry);
if (!entry.foundryItemId) await mapDragonrollItem(entry._id, item.id);
} else if (entry.foundryItemId) {
// Imported gear that only exists inside an actor's inventory: its actor
// snapshot owns it, so cloning it into the world would duplicate it.
continue;
} else {
// A Dragonroll item named like an unmapped Foundry item maps to that
// document instead of adding a second copy of the same gear.
const sameName = game.items.contents.find((candidate) => candidate.name === String(entry.name).trim()
&& !dragonrollItemIdOf(candidate));
if (sameName) {
retainedFoundryIds.add(sameName.id);
await mapDragonrollItem(entry._id, sameName.id);
} else {
await createFoundryWorldItem(entry);
}
}
}
for (const item of game.items.contents) {
const itemId = dragonrollItemIdOf(item);
if (!itemId || retainedFoundryIds.has(item.id) || remoteById.has(String(itemId))) continue;
await withItemSyncSuppressed(item, () => item.delete());
}
itemSyncErrorLogged = false;
} catch (error) {
reportItemSyncError(error);
} finally {
itemSyncRunning = false;
}
}
function getDragonrollImageUrl(image) {
if (!image) return "";
if (/^(https?:|data:|\/\/)/i.test(image)) return image;
const endpoint = new URL(game.settings.get(MODULE_ID, SETTING_DRAGONROLL_API_URL));
const basePath = endpoint.pathname.replace(/\/+$/, "");
endpoint.pathname = `${basePath.endsWith("/api") ? basePath : `${basePath}/api`}/public/${encodeURIComponent(image)}`;
endpoint.search = "";
endpoint.hash = "";
return endpoint.toString();
}
function makeFoundryCharacterData(entry) {
const stats = entry.abilityScores || {};
const items = [];
if (entry.className) items.push({ name: entry.className, type: "class", system: { levels: Number(entry.level) || 1 } });
if (entry.subclass) items.push({ name: entry.subclass, type: "subclass" });
if (entry.background) items.push({ name: entry.background, type: "background" });
for (const name of String(entry.spells || "").split("\n").map((value) => value.trim()).filter(Boolean)) {
items.push({ name, type: "spell" });
}
for (const item of entry.inventory || []) {
if (!item.name?.trim()) continue;
items.push({
name: item.name.trim(),
type: "loot",
system: { quantity: Number(item.quantity) || 1, weight: { value: Number(item.weight) || 0 } },
});
}
return {
name: entry.name,
type: entry.type === "character" ? "character" : "npc",
img: getDragonrollImageUrl(entry.image) || undefined,
system: {
// `details.race` and `details.background` are left out on purpose: they reference
// embedded items and are linked once the actor stands with its items made.
details: {
level: Number(entry.level) || 1,
biography: { value: entry.description || "" },
cr: entry.challengeRating || "",
},
abilities: Object.fromEntries(["str", "dex", "con", "int", "wis", "cha"].map((key) => [
key,
{ value: Number(stats[key]) || 10 },
])),
attributes: {
ac: { value: Number(entry.armorClass) || 10 },
movement: { walk: Number(entry.speed) || 30 },
},
},
items,
flags: { [MODULE_ID]: {
actorId: String(entry._id),
actorType: entry.type,
traits: entry.traits || "",
proficiencies: entry.proficiencies || "",
syncMutation: true,
} },
};
}
function documentValue(document, path) {
return path.split(".").reduce((value, key) => value?.[key], document);
}
function characterUpdateData(entry) {
const stats = entry.abilityScores || {};
const updates = {
name: entry.name,
img: getDragonrollImageUrl(entry.image) || "icons/svg/mystery-man.svg",
"system.details.level": Number(entry.level) || 1,
"system.details.biography.value": entry.description || "",
"system.details.cr": entry.challengeRating || "",
[`flags.${MODULE_ID}.traits`]: entry.traits || "",
[`flags.${MODULE_ID}.proficiencies`]: entry.proficiencies || "",
"system.attributes.ac.value": Number(entry.armorClass) || 10,
"system.attributes.movement.walk": Number(entry.speed) || 30,
};
for (const key of ["str", "dex", "con", "int", "wis", "cha"]) {
updates[`system.abilities.${key}.value`] = Number(stats[key]) || 10;
}
return updates;
}
// `system.details.background` and `system.details.race` are LocalDocumentFields in
// D&D 5e: they hold the id of an item embedded in the actor, never its name. A name
// written into one is a reference that resolves to nothing, and adding that item in
// Foundry then fails, so each of these follows the actor's own item for it instead.
const EMBEDDED_DETAILS = [
// Dragonroll owns the background item it lists, so its reference follows it always and
// a background taken off in the campaign leaves no reference behind.
{ field: "background", path: "system.details.background", types: ["background"], clearWhenMissing: true },
// The species item belongs to the world: point at it when it carries the name, and
// leave the reference to the GM when it does not.
{ field: "species", path: "system.details.race", types: ["race", "species"] },
];
function localDocumentId(value) {
// The field resolves to the referenced document when it can and to the stored id
// when the document is gone (its `fallback` option).
if (typeof value === "string") return value;
return value?._id || "";
}
function embeddedDetailReferenceData(actor, entry) {
const updates = {};
for (const detail of EMBEDDED_DETAILS) {
const wanted = String(entry[detail.field] || "").trim();
const item = wanted
? actor.items?.contents?.find((candidate) => detail.types.includes(candidate.type) && candidate.name === wanted)
: null;
const reference = item?.id || "";
if (!reference && !detail.clearWhenMissing) continue;
if (localDocumentId(documentValue(actor, detail.path)) !== reference) updates[detail.path] = reference;
}
return updates;
}
async function reconcileEmbeddedItems(actor, entry) {
const desired = [];
if (entry.className) desired.push({ type: "class", name: entry.className, system: { levels: Number(entry.level) || 1 } });
if (entry.subclass) desired.push({ type: "subclass", name: entry.subclass });
if (entry.background) desired.push({ type: "background", name: entry.background });
for (const name of String(entry.spells || "").split("\n").map((value) => value.trim()).filter(Boolean)) {
desired.push({ type: "spell", name });
}
for (const item of entry.inventory || []) {
if (item.name?.trim()) desired.push({
type: "loot",
name: item.name.trim(),
system: { quantity: Number(item.quantity) || 1, weight: { value: Number(item.weight) || 0 } },
});
}
const retainedIds = new Set();
for (const wanted of desired) {
const existing = actor.items.contents.find((item) => item.name === wanted.name
&& item.type === wanted.type && item.getFlag?.(MODULE_ID, "syncedItem"))
|| actor.items.contents.find((item) => item.name === wanted.name
&& item.getFlag?.(MODULE_ID, "syncedItem") && !WORLD_OWNED_EMBEDDED_TYPES.has(item.type));
// A carried row holding the name of one of the world's own trait or species documents
// — a trait a campaign that synced before #89 still has in its inventory — stands in
// the world as that document: no loot is made after its name, and the document itself
// is let be. Writing it out of the campaign is the campaign's to do, keeping it is the world's.
if (!existing && wanted.type === "loot") {
const worldOwned = actor.items.contents.find((item) => item.name === wanted.name
&& WORLD_OWNED_EMBEDDED_TYPES.has(item.type));
if (worldOwned) {
retainedIds.add(worldOwned.id);
continue;
}
}
if (existing) {
retainedIds.add(existing.id);
const update = { _id: existing.id };
const expected = { name: wanted.name };
if (wanted.system?.levels !== undefined) expected["system.levels"] = wanted.system.levels;
if (wanted.system?.quantity !== undefined) expected["system.quantity"] = wanted.system.quantity;
if (wanted.system?.weight?.value !== undefined) expected["system.weight.value"] = wanted.system.weight.value;
let changed = false;
for (const [key, value] of Object.entries(expected)) {
if (documentValue(existing, key) !== value) {
update[key] = value;
changed = true;
}
}
if (changed) await actor.updateEmbeddedDocuments("Item", [update]);
} else {
const created = await actor.createEmbeddedDocuments("Item", [{
...wanted,
flags: { [MODULE_ID]: { syncedItem: true } },
}]);
for (const item of created) retainedIds.add(item.id);
}
}
const staleItemIds = actor.items.contents
.filter((item) => item.getFlag?.(MODULE_ID, "syncedItem") && !retainedIds.has(item.id)
&& !WORLD_OWNED_EMBEDDED_TYPES.has(item.type))
.map((item) => item.id);
if (staleItemIds.length) await actor.deleteEmbeddedDocuments("Item", staleItemIds);
}
async function applyDragonrollCharacter(actor, entry) {
const updates = characterUpdateData(entry);
const changed = Object.entries(updates).some(([key, value]) => documentValue(actor, key) !== value);
await withActorSyncSuppressed(actor, async () => {
if (changed) await actor.update(updates);
await reconcileEmbeddedItems(actor, entry);
// The item references are written after the reconcile that makes the items they point at.
const references = embeddedDetailReferenceData(actor, entry);
if (Object.keys(references).length) await actor.update(references);
if (dragonrollActorId(actor) !== String(entry._id)
|| actor.getFlag?.(MODULE_ID, "actorType") !== entry.type) {
await actor.update({
[`flags.${MODULE_ID}.actorId`]: String(entry._id),
[`flags.${MODULE_ID}.actorType`]: entry.type,
});
}
});
}
async function mapDragonrollActor(actorId, foundryActorId) {
const token = getSyncToken();
return postDragonroll("foundry/sync/map", {
worldId: game.world.id,
actorId: String(actorId),
foundryActorId: String(foundryActorId),
}, token);
}
async function createFoundryCharacter(entry) {
if (game.system.id !== "dnd5e") {
throw new Error("Character sync currently requires the D&D 5e Foundry system.");
}
const actor = await Actor.create(makeFoundryCharacterData(entry), { renderSheet: false });
if (!actor) return;
await withActorSyncSuppressed(actor, async () => {
await actor.update({
// The actor was made with its items, so its background and species references
// can point at them right away.
...embeddedDetailReferenceData(actor, entry),
[`flags.${MODULE_ID}.syncMutation`]: false,
});
});
await mapDragonrollActor(entry._id, actor.id);
}
async function reconcileDragonrollCharacters() {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || characterSyncRunning || !isAutoSyncEnabled()) return;
characterSyncRunning = true;
try {
if (game.system.id !== "dnd5e") {
throw new Error("Character sync currently requires the D&D 5e Foundry system.");
}
const result = await getDragonroll("foundry/sync/characters", token);
const remoteActors = result.actors || [];
const remoteById = new Map(remoteActors.map((actor) => [String(actor._id), actor]));
const localByRemoteId = new Map(game.actors.contents
.map((actor) => [String(dragonrollActorId(actor)), actor])
.filter(([actorId]) => actorId));
const retainedFoundryIds = new Set();
for (const entry of remoteActors) {
let actor = entry.foundryActorId ? game.actors.get(entry.foundryActorId) : null;
if (!actor) actor = localByRemoteId.get(String(entry._id));
if (actor) {
retainedFoundryIds.add(actor.id);
await applyDragonrollCharacter(actor, entry);
if (!entry.foundryActorId) await mapDragonrollActor(entry._id, actor.id);
} else {
await createFoundryCharacter(entry);
}
}
for (const actor of game.actors.contents) {
const actorId = dragonrollActorId(actor);
if (!actorId || retainedFoundryIds.has(actor.id) || remoteById.has(String(actorId))) continue;
await withActorSyncSuppressed(actor, () => actor.delete());
}
actorSyncErrorLogged = false;
} catch (error) {
reportActorSyncError(error);
} finally {
characterSyncRunning = false;
}
}
// Both sides converge on a timer that only runs while the world is open, so a
// round that could not reach Dragonroll is asked for again in a while instead of
// leaving the campaign with whatever it happened to receive.
function scheduleDragonrollCharacterSync(delay = 15000) {
clearTimeout(characterSyncRetryTimeout);
characterSyncRetryTimeout = setTimeout(reconcileDragonrollCharacters, delay);
}
async function initializeCharacterSync() {
if (!getSyncToken() || !game.user?.isGM || !game.world || !isAutoSyncEnabled()) return;
try {
await pushFoundryActors(game.actors.contents, true);
await reconcileDragonrollCharacters();
} catch (error) {
reportActorSyncError(error);
scheduleDragonrollCharacterSync(15000);
}
}
function queueFoundryActorChange(kind, actor) {
if (kind !== "delete" && (actor.flags?.[MODULE_ID]?.syncMutation || syncingActorIds.has(actor.id))) return;
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);
}
}
// --- Note pages ------------------------------------------------------------
// The campaign's notes read like the campaign's journal in the world: each folder
// stands as a JournalEntry named after its path, and every note inside it is one
// of that journal's pages. Notes in the root of the campaign share the journal
// named "Dragonroll", and a note in "Sessions / Arc 1" belongs to the journal
// named after that path. Notes are written in Dragonroll, so this copy runs one way — the
// reconcile writes each note into its page and drops the page of a note the
// campaign deleted. Nothing of the journal is read back, and the GM's own pages
// are left alone: only the ones this module made carry the
// `dragonroll-foundry.noteId` flag. Moving a note to another folder moves its page
// to that folder's journal; the journal of a folder whose notes all left goes with
// them when the GM has no pages of their own in it.
//
// The poll asks Dragonroll for a cheap revision first: the notes are only pulled
// over — and the journals only rewritten — when that revision or the pages this
// module wrote have changed since the last reconcile, so an untouched campaign
// costs one hash comparison instead of a page rewrite every few seconds.
const NOTES_JOURNAL_NAME = "Dragonroll";
let noteSyncRunning = false;
let noteSyncErrorLogged = false;
// What the last reconcile was based on: the campaign's notes revision, and a summary
// of the pages this module put in the world. Both unchanged means there is nothing to
// do, which is how an idle campaign skips the whole pull-and-render.
let lastNoteRevision = null;
let lastNoteJournalSignature = null;
function dragonrollNoteId(page) {
return page.getFlag?.(MODULE_ID, "noteId") || page.flags?.[MODULE_ID]?.noteId || "";
}
// --- Links and embeds in a note -------------------------------------------
// Dragonroll writes `[[Name]]` for a link and `![[Name]]` for an embed. Foundry has its own
// enrichers for both: `@UUID[…]` becomes a content link that opens the document, and `@Embed[…]`
// draws that document's sheet in the page. The note only carries names, so the target is looked up
// in the world the same way the campaign lists it: notes first, then characters, items and maps.
function normalizeNoteLabel(value) {
return String(value ?? "")
.normalize("NFD")
.replace(/[\u0300-\u036f]/g, "")
.toLowerCase()
.trim();
}
function noteDocumentUuid(document, documentName) {
return document?.uuid || `${document?.documentName || documentName}.${document?.id}`;
}
// A journal page's uuid is the pair of its journal and its own id; tests and older
// Foundry versions do not always carry the getter, so it is rebuilt when missing.
function notePageUuid(journal, page) {
return page?.uuid || `JournalEntry.${journal.id}.JournalEntryPage.${page.id}`;
}
function noteJournalPages() {
const pages = [];
for (const journal of notesJournals()) {
for (const page of journal.pages?.contents || []) pages.push({ journal, page });
}
return pages;
}
function findNoteJournalPage(needle) {
const pages = noteJournalPages();
// Prefer the page the module itself made for a note: a GM page with the same
// name is not the note the campaign is pointing at.
return pages.find(({ page }) => dragonrollNoteId(page) && normalizeNoteLabel(page.name) === needle)
|| pages.find(({ page }) => normalizeNoteLabel(page.name) === needle)
|| null;
}
// The document a written label points at. An embed only makes sense for a character or
// an item, which are the documents Foundry knows how to show inline.
function findNoteTarget(label, { embed = false } = {}) {
const needle = normalizeNoteLabel(label);
if (!needle) return null;
if (!embed) {
const note = findNoteJournalPage(needle);
if (note) return { uuid: notePageUuid(note.journal, note.page), type: "note" };
}
const actor = (game.actors?.contents || []).find((candidate) => normalizeNoteLabel(candidate.name) === needle);
if (actor) return { uuid: noteDocumentUuid(actor, "Actor"), type: "actor" };
const item = (game.items?.contents || []).find((candidate) => normalizeNoteLabel(candidate.name) === needle);
if (item) return { uuid: noteDocumentUuid(item, "Item"), type: "item" };
if (embed) return null;
const scene = (game.scenes?.contents || []).find((candidate) => normalizeNoteLabel(candidate.name) === needle);
if (scene) return { uuid: noteDocumentUuid(scene, "Scene"), type: "map" };
return null;
}
function noteWikiLinkHtml(label) {
const text = String(label ?? "").trim();
const target = findNoteTarget(text);
if (!target) {
return `<span class="dragonroll-note-link is-unresolved">${escapeNoteHtml(text)}</span>`;
}
return `@UUID[${target.uuid}]{${escapeNoteHtml(text)}}`;
}
function noteEmbedHtml(label) {
const text = String(label ?? "").trim();
const target = findNoteTarget(text, { embed: true });
if (!target) {
return `<span class="dragonroll-note-link is-unresolved">${escapeNoteHtml(text)}</span>`;
}
return `@Embed[${target.uuid}]{${escapeNoteHtml(text)}}`;
}
// A note is markdown, a journal page is HTML. Foundry keeps no markdown renderer
// the module can call — the `TextEditor._getMarkdown` this once probed for was
// never real, so every note fell through to escaped paragraphs and a `#` heading
// stayed a `#` heading — so the note's markdown is drawn here and the journal
// styles the page like any other.
function notePageHtml(content) {
const markdown = String(content ?? "").replace(/\r\n?/g, "\n");
if (!markdown.trim()) return "";
return markdownBlocks(markdown);
}
// Dragonroll's dice widget is a button in the journal too: pressing it rolls the
// expression in Foundry and posts the result to chat. `adv`/`dis` are Dragonroll's
// names for rolling twice and keeping the better/worse die, which Foundry writes as
// `kh1`/`kl1`; everything else in the expression is already Foundry's syntax.
function dragonrollRollFormula(expression) {
return String(expression ?? "")
.trim()
.replace(/(\d*)d(\d+)\s*adv\b/gi, (match, count, sides) => `2d${sides}kh1`)
.replace(/(\d*)d(\d+)\s*dis\b/gi, (match, count, sides) => `2d${sides}kl1`);
}
function noteRollButtonHtml(expression, block = false) {
const label = String(expression ?? "").trim();
const formula = dragonrollRollFormula(label);
const classes = block ? "dragonroll-note-roll dragonroll-note-roll-block" : "dragonroll-note-roll";
return `<button type="button" class="${classes}" data-dragonroll-roll="${escapeNoteHtml(formula)}"`
+ ` title="Roll ${escapeNoteHtml(label)}">`
+ '<i class="fa-solid fa-dice-d20" aria-hidden="true"></i>'
+ `<span>${escapeNoteHtml(label)}</span></button>`;
}
// Every dice button the module draws listens through one delegated handler: the
// journal re-renders its pages, so binding each button would go stale.
function onDragonrollNoteRollClick(event) {
const button = event.target?.closest?.("[data-dragonroll-roll]");
if (!button) return;
event.preventDefault();
return rollDragonrollNote(button);
}
async function rollDragonrollNote(button) {
const formula = button?.dataset?.dragonrollRoll;
if (!formula) return;
try {
const roll = new Roll(formula);
await roll.evaluate();
await roll.toMessage({
speaker: ChatMessage.getSpeaker(),
flavor: `Dragonroll: <strong>${escapeNoteHtml(formula)}</strong>`,
});
} catch (error) {
console.warn(`${MODULE_ID} | Could not roll "${formula}".`, error);
ui.notifications?.warn?.(`Dragonroll: could not roll ${formula}.`);
}
}
function bindDragonrollNoteRolls() {
if (typeof document === "undefined") return;
document.addEventListener("click", onDragonrollNoteRollClick);
}
// The block-level elements a note is written with, line by line. A blank line
// ends a block, anything no block rule claims is a paragraph, and the single
// newlines inside a paragraph become line breaks.
function markdownBlocks(markdown) {
const lines = markdown.split("\n");
const blocks = [];
let index = 0;
while (index < lines.length) {
const line = lines[index];
if (!line.trim()) {
index += 1;
continue;
}
// A dice widget on its own line: `@roll`, the expression, then `@end`. A
// block without its closing marker is left to the paragraph rules below.
if (/^@roll\s*$/.test(line)) {
let closing = index + 1;
while (closing < lines.length && !/^@end\s*$/.test(lines[closing])) closing += 1;
if (closing < lines.length) {
blocks.push(noteRollButtonHtml(lines.slice(index + 1, closing).join("\n"), true));
index = closing + 1;
continue;
}
}
// A fenced code block: everything up to the line that closes the fence is
// kept as written, escaped rather than read as markdown.
const fence = line.match(/^\s*(`{3,}|~{3,})(.*)$/);
if (fence) {
const marker = fence[1][0];
const isClosingFence = (candidate) => {
const trimmed = candidate.trim();
return trimmed.length >= 3 && [...trimmed].every((character) => character === marker);
};
index += 1;
const code = [];
while (index < lines.length && !isClosingFence(lines[index])) {
code.push(lines[index]);
index += 1;
}
index += 1;
const language = fence[2].trim().split(/\s+/)[0].replace(/[^\w+#-]/g, "");
blocks.push(`<pre><code${language ? ` class="language-${language}"` : ""}>${escapeNoteHtml(code.join("\n"))}</code></pre>`);
continue;
}
if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) {
blocks.push("<hr />");
index += 1;
continue;
}
const heading = line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
if (heading) {
blocks.push(`<h${heading[1].length}>${noteInlineHtml(heading[2])}</h${heading[1].length}>`);
index += 1;
continue;
}
// A line underlined with `=` or `-` is a heading of its own.
const underline = lines[index + 1]?.match(/^\s*(=+|-+)\s*$/);
if (underline) {
const level = underline[1][0] === "=" ? 1 : 2;
blocks.push(`<h${level}>${noteInlineHtml(line.trim())}</h${level}>`);
index += 2;
continue;
}
if (/^\s*>/.test(line)) {
const quote = [];
while (index < lines.length && /^\s*>/.test(lines[index])) {
quote.push(lines[index].replace(/^\s*>\s?/, ""));
index += 1;
}
blocks.push(`<blockquote>${markdownBlocks(quote.join("\n"))}</blockquote>`);
continue;
}
const listItem = line.match(/^\s*([-*+]|\d+[.)])\s+/);
if (listItem) {
const ordered = /^\d/.test(listItem[1]);
const items = [];
while (index < lines.length) {
const item = lines[index].match(/^\s*(?:[-*+]|\d+[.)])\s+(.*)$/);
if (!item) break;
const continuation = [item[1]];
index += 1;
while (index < lines.length && lines[index].trim()
&& !/^\s*(?:[-*+]|\d+[.)])\s+/.test(lines[index])) {
continuation.push(lines[index].trim());
index += 1;
}
items.push(`<li>${noteInlineHtml(continuation.join("\n")).replace(/\n/g, "<br />")}</li>`);
}
const tag = ordered ? "ol" : "ul";
blocks.push(`<${tag}>\n${items.join("\n")}\n</${tag}>`);
continue;
}
const paragraph = [line.trim()];
index += 1;
while (index < lines.length && lines[index].trim()
&& !/^\s*(`{3,}|~{3,})/.test(lines[index])
&& !/^#{1,6}\s+/.test(lines[index])
&& !/^\s*>/.test(lines[index])
&& !/^\s*(?:[-*+]|\d+[.)])\s+/.test(lines[index])
&& !/^\s*([-*_])(\s*\1){2,}\s*$/.test(lines[index])
&& !/^\s*[=-]+\s*$/.test(lines[index])) {
paragraph.push(lines[index].trim());
index += 1;
}
blocks.push(`<p>${noteInlineHtml(paragraph.join("\n")).replace(/\n/g, "<br />")}</p>`);
}
return blocks.join("\n");
}
// The inline marks inside a block: code spans and dice widgets are lifted out
// first so nothing in them is read as a mark, and the rest — images, links,
// strong, emphasis and strikethrough — are plain, non-nesting replacements over
// escaped text.
function noteInlineHtml(text) {
const atoms = [];
const hold = (html) => {
atoms.push(html);
return `\u0000${atoms.length - 1}\u0000`;
};
let html = String(text)
.replace(/`([^`]+)`/g, (match, code) => hold(`<code>${escapeNoteHtml(code)}</code>`))
.replace(/@roll\s*\[([^\]]*)\]/g, (match, expression) => hold(noteRollButtonHtml(expression)))
// The bang has to be read first: `![[Name]]` would otherwise be caught by the
// link rule and drawn as a plain link.
.replace(/!\[\[([^\n]*?)\]\]/g, (match, label) => hold(noteEmbedHtml(label)))
.replace(/\[\[([^\n]*?)\]\]/g, (match, label) => hold(noteWikiLinkHtml(label)));
html = escapeNoteHtml(html);
html = html.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g, (match, alt, source) =>
`<img src="${source}" alt="${alt}" />`);
html = html.replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g, (match, label, href) =>
`<a href="${href}">${label}</a>`);
html = html.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
html = html.replace(/(^|[\s(])__([^_]+)__(?=[\s).,!?:;<]|$)/g, "$1<strong>$2</strong>");
html = html.replace(/(^|[^*])\*([^*]+)\*/g, "$1<em>$2</em>");
html = html.replace(/(^|[\s(])_([^_]+)_(?=[\s).,!?:;<]|$)/g, "$1<em>$2</em>");
html = html.replace(/~~([^~]+)~~/g, "<s>$1</s>");
return html.replace(/\u0000(\d+)\u0000/g, (match, position) => atoms[Number(position)]);
}
function escapeNoteHtml(value) {
return String(value)
.replace(/&/g, "&amp;")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;");
}
function notePageTitle(entry) {
return String(entry.title || "").trim() || "Untitled note";
}
// Which folder's journal a note belongs to: the note's folder id, or the empty
// string for the root notes the "Dragonroll" journal holds.
function noteFolderKey(entry) {
return entry?.folder ? String(entry.folder) : "";
}
// The journal a note belongs to is named after the folder path Dragonroll sends;
// root notes keep the journal the world calls "Dragonroll".
function noteJournalName(entry) {
const path = String(entry?.folderPath ?? "").trim();
return path || NOTES_JOURNAL_NAME;
}
function journalFolderKey(journal) {
const folder = journal.getFlag?.(MODULE_ID, "notesFolder");
return folder === undefined || folder === null ? "" : String(folder);
}
function isNotesJournal(journal) {
return Boolean(journal.getFlag?.(MODULE_ID, "notesJournal")
|| journal.getFlag?.(MODULE_ID, "notesFolder"));
}
// Every journal this module writes the campaign's notes into: the ones it flagged
// for a folder or for the root notes, plus any journal holding a page it made (a
// flag can be lost to a hand edit). The world's journals live in `game.journal`
// (singular) — there is no `game.journals`.
function notesJournals() {
return (game.journal?.contents || []).filter((journal) =>
isNotesJournal(journal)
|| journal.name === NOTES_JOURNAL_NAME
|| (journal.pages?.contents || []).some((page) => dragonrollNoteId(page)));
}
// What the module's journals and pages look like right now: the journals' names
// and each module page's id, title and text. A change here means a GM edited or
// removed something, so the reconcile has to run again even though the campaign's
// notes have not moved.
function notesJournalSignature() {
return notesJournals().map((journal) => {
const pages = (journal.pages?.contents || [])
.filter((page) => dragonrollNoteId(page))
.map((page) => `${page.id}\u0000${page.name ?? ""}\u0000${page.text?.content ?? ""}`)
.sort()
.join("\u0001");
return `${journal.id}\u0000${journal.name ?? ""}\u0000${pages}`;
}).sort().join("\u0002");
}
// The page each module page id stands as, across every journal, so a note that
// moved folders can be found in the journal it is leaving before it is written
// into the one it now belongs to.
function notePageLocations() {
const locations = new Map();
for (const journal of notesJournals()) {
for (const page of journal.pages?.contents || []) {
locations.set(String(page.id), { journal, page });
}
}
return locations;
}
// Foundry lets several journals share a name, so a world can end up holding more
// than one journal for the same folder — a GM-made one beside the module's own, or
// two the module made before this check. The reconcile writes into one of them;
// every other one it made for that folder is a duplicate and goes, so the notes
// never split across journals.
async function removeDuplicateNotesJournals(keep, folderKey) {
for (const journal of [...(game.journal?.contents || [])]) {
if (journal === keep) continue;
if (folderKey) {
if (journalFolderKey(journal) === folderKey && isNotesJournal(journal)) await journal.delete();
} else if (!journalFolderKey(journal)
&& (journal.getFlag?.(MODULE_ID, "notesJournal") || journal.name === NOTES_JOURNAL_NAME)) {
await journal.delete();
}
}
}
// The journal a note is written into, made on first use. A journal the GM already
// made under the folder's name is adopted (and flagged), and a folder journal is
// renamed with its folder so the world keeps reading the same path.
async function ensureNotesJournal(entry) {
const folderKey = noteFolderKey(entry);
const name = noteJournalName(entry);
const journals = notesJournals();
const existing = folderKey
? journals.find((journal) => journalFolderKey(journal) === folderKey)
|| journals.find((journal) => !journalFolderKey(journal)
&& !journal.getFlag?.(MODULE_ID, "notesJournal")
&& journal.name === name)
: journals.find((journal) => journal.getFlag?.(MODULE_ID, "notesJournal"))
|| journals.find((journal) => !journalFolderKey(journal) && journal.name === NOTES_JOURNAL_NAME);
if (existing) {
const updates = {};
if (String(existing.name ?? "") !== name) updates.name = name;
if (folderKey) {
if (journalFolderKey(existing) !== folderKey) {
updates[`flags.${MODULE_ID}.notesFolder`] = folderKey;
}
} else if (!existing.getFlag?.(MODULE_ID, "notesJournal")) {
updates[`flags.${MODULE_ID}.notesJournal`] = true;
}
if (Object.keys(updates).length) await existing.update(updates);
await removeDuplicateNotesJournals(existing, folderKey);
return existing;
}
const created = await JournalEntry.create({
name,
flags: { [MODULE_ID]: folderKey ? { notesFolder: folderKey } : { notesJournal: true } },
}, { renderSheet: false });
return Array.isArray(created) ? created[0] : created;
}
// The page a note stands as: rewrite what the campaign changed, and claim a page
// the campaign mapped by id but whose flag was lost.
async function applyDragonrollNotePage(page, entry) {
const title = notePageTitle(entry);
const html = notePageHtml(entry.content);
const updates = {};
if (String(page.name ?? "") !== title) updates.name = title;
if (String(page.text?.content ?? "") !== html) updates["text.content"] = html;
if (!dragonrollNoteId(page)) updates[`flags.${MODULE_ID}.noteId`] = String(entry._id);
if (Object.keys(updates).length) await page.update(updates);
}
async function createDragonrollNotePage(journal, entry) {
const pages = await journal.createEmbeddedDocuments("JournalEntryPage", [{
// A page's display title is its `name`; `title` only holds the table-of-contents
// flags (`show`/`level`). Missing `name` fails the document's validation.
name: notePageTitle(entry),
text: { content: notePageHtml(entry.content) },
flags: { [MODULE_ID]: { noteId: String(entry._id) } },
}], { renderSheet: false });
return Array.isArray(pages) ? pages[0] : pages;
}
async function mapDragonrollNote(noteId, foundryPageId) {
const token = getSyncToken();
return postDragonroll("foundry/sync/map-note", {
worldId: game.world.id,
noteId: String(noteId),
foundryPageId: String(foundryPageId),
}, token);
}
function reportNoteSyncError(error) {
if (noteSyncErrorLogged) return;
noteSyncErrorLogged = true;
console.warn(`${MODULE_ID} | Note journal sync failed and will retry.`, error);
}
async function reconcileDragonrollNotes() {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || noteSyncRunning || !isAutoSyncEnabled()) return;
noteSyncRunning = true;
try {
const { revision } = await getDragonroll("foundry/sync/notes/revision", token);
const remoteRevision = String(revision ?? "");
// Both sides are unchanged since the last reconcile: the campaign's notes hash
// the same and the journal still holds what was written to it. Stop before
// pulling every note over and rendering it again.
if (remoteRevision === lastNoteRevision && notesJournalSignature() === lastNoteJournalSignature) return;
const result = await getDragonroll("foundry/sync/notes", token);
const remoteNotes = result.notes || [];
// A campaign without notes gets no journal of its own — but ones it once had
// stay, so the pages of notes it deleted can go with them.
if (!remoteNotes.length && !notesJournals().length) {
lastNoteRevision = remoteRevision;
lastNoteJournalSignature = "";
return;
}
const pageLocations = notePageLocations();
const journalsByFolder = new Map();
const retainedPageIds = new Set();
// Every page that now holds a note, so the notes can be drawn a second time once
// they all exist: a note that links to another note needs that note's page uuid,
// and the page it points at may have been created after it in this loop.
const renderedPages = [];
for (const entry of remoteNotes) {
const folderKey = noteFolderKey(entry);
let journal = journalsByFolder.get(folderKey);
if (!journal) {
journal = await ensureNotesJournal(entry);
if (!journal) continue;
journalsByFolder.set(folderKey, journal);
}
// The note's page can be in the journal it now belongs to, or in the one of
// the folder it left: a note moved in Dragonroll takes its page along.
let location = entry.foundryPageId ? pageLocations.get(String(entry.foundryPageId)) : null;
if (!location) {
const page = (journal.pages?.contents || []).find((candidate) =>
String(dragonrollNoteId(candidate)) === String(entry._id));
if (page) location = { journal, page };
}
let page = location?.page ?? null;
if (page && location.journal !== journal) {
await page.delete();
pageLocations.delete(String(page.id));
page = null;
}
if (page) {
retainedPageIds.add(page.id);
await applyDragonrollNotePage(page, entry);
renderedPages.push({ journal, page, entry });
if (String(entry.foundryPageId ?? "") !== String(page.id)) {
await mapDragonrollNote(entry._id, page.id);
}
} else {
const created = await createDragonrollNotePage(journal, entry);
if (created) {
retainedPageIds.add(created.id);
pageLocations.set(String(created.id), { journal, page: created });
renderedPages.push({ journal, page: created, entry });
await mapDragonrollNote(entry._id, created.id);
}
}
}
// Now that every page of this pull exists, draw the notes again: only the pages
// whose wiki links just found their target are written a second time.
for (const { page, entry } of renderedPages) {
await applyDragonrollNotePage(page, entry);
}
// Pages whose note the campaign deleted go with it, and so does a page left in
// a journal the note no longer belongs to. Only pages this module made are its
// business: an unflagged page is the GM's own.
for (const journal of notesJournals()) {
for (const page of [...(journal.pages?.contents || [])]) {
const noteId = dragonrollNoteId(page);
if (!noteId || retainedPageIds.has(page.id)) continue;
await page.delete();
}
}
// A folder journal whose notes have all moved or gone goes with them, unless
// the GM keeps pages of their own in it.
for (const journal of notesJournals()) {
const folderKey = journalFolderKey(journal);
if (!folderKey || (journal.pages?.contents || []).length) continue;
if (remoteNotes.some((entry) => noteFolderKey(entry) === folderKey)) continue;
await journal.delete();
}
lastNoteRevision = remoteRevision;
lastNoteJournalSignature = notesJournalSignature();
noteSyncErrorLogged = false;
} catch (error) {
reportNoteSyncError(error);
} finally {
noteSyncRunning = false;
}
}
async function publishSnapshot() {
if (!game.user?.isGM || !game.world) return;
if (syncInProgress) {
syncRequested = true;
return;
}
const bridgeConfig = getBridgeConfig();
if (!bridgeConfig) return;
syncInProgress = true;
try {
const actorItems = Object.fromEntries(
game.actors.contents.map((actor) => [
actor.id,
actor.items.contents.map(toPlainData),
]),
);
const response = await fetch(new URL("internal/snapshot", `${bridgeConfig.url.replace(/\/+$/, "")}/`), {
method: "POST",
headers: {
"Authorization": `Bearer ${bridgeConfig.pushToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
world: api.getWorld(),
actors: api.getActors(),
items: api.getItems(),
actorItems,
}),
});
if (!response.ok) {
throw new Error(`Bridge returned HTTP ${response.status}.`);
}
} catch (error) {
console.error(`${MODULE_ID} | Could not publish the world snapshot.`, error);
scheduleSnapshotSync(15000);
} finally {
syncInProgress = false;
if (syncRequested) {
syncRequested = false;
scheduleSnapshotSync();
}
}
}
async function publishHeartbeat() {
if (!game.user?.isGM || !game.world) return;
const bridgeConfig = getBridgeConfig();
if (!bridgeConfig) return;
try {
const response = await fetch(new URL("internal/heartbeat", `${bridgeConfig.url.replace(/\/+$/, "")}/`), {
method: "POST",
headers: {
"Authorization": `Bearer ${bridgeConfig.pushToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ worldId: game.world.id }),
});
if (response.status === 409 || response.status === 503) {
scheduleSnapshotSync(0);
return;
}
if (!response.ok) throw new Error(`Bridge returned HTTP ${response.status}.`);
} catch (error) {
console.warn(`${MODULE_ID} | Bridge heartbeat failed.`, error);
scheduleSnapshotSync(15000);
}
}
Hooks.once("ready", () => {
bindDragonrollNoteRolls();
advanceDragonrollLink().then(refreshPairingStatus);
// While this world has no campaign, its sign-up link is what the GM has to
// work with: keep showing it and keep asking whether it has been answered.
setInterval(() => {
if (getSyncToken()) return;
advanceDragonrollLink();
}, LINK_POLL_MS);
setInterval(refreshPairingStatus, 60000);
scheduleSnapshotSync(0);
setInterval(publishHeartbeat, 60000);
setTimeout(initializeCharacterSync, 1000);
setInterval(reconcileDragonrollCharacters, 5000);
// Items reconcile after the character snapshot has landed so Dragonroll has
// already seen the world directory when it starts sending its own items back.
setTimeout(reconcileDragonrollItems, 2000);
setInterval(reconcileDragonrollItems, 5000);
// The campaign's notes arrive as pages of the world's Dragonroll journal. The
// recurring check only asks for a cheap revision, so a note written in the app —
// or a journal page a GM changed — is still picked up shortly, but nothing is
// pulled over or rewritten while both sides stay as the last reconcile left them.
setTimeout(reconcileDragonrollNotes, 3000);
setInterval(reconcileDragonrollNotes, 15000);
// 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",
"createItem", "updateItem", "deleteItem",
"createFolder", "updateFolder", "deleteFolder",
]) {
Hooks.on(event, (document) => {
scheduleSnapshotSync();
const isDelete = event.startsWith("delete");
if (document.documentName === "Actor") {
queueFoundryActorChange(isDelete ? "delete" : "upsert", document);
return;
}
// An item folder the GM made, renamed or nested changes the tree the campaign
// mirrors; nothing about the items themselves changed, so only the tree goes.
// A colour Dragonroll has just written into the folder is not the GM changing it.
if (document.documentName === "Folder") {
if (syncingFolderIds.has(document.id)) return;
if (document.type === "Item" && isWorldItemFolder(document)) queueFoundryItemFolders();
return;
}
if (document.documentName !== "Item") return;
// Items embedded in an actor travel with that actor's snapshot: adding or
// removing one only changes the actor, never deletes it.
if (document.parent?.documentName === "Actor") {
queueFoundryActorChange("upsert", document.parent);
return;
}
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
// menu, replacing whatever the campaign holds for them. This works with autosync on
// and off: it is the one push done on purpose.
//
// Foundry 13 replaced getActorDirectoryEntryContext with getActorContextOptions,
// which fires when the directory first renders, so the hook is registered here at
// load time rather than inside "ready". The entry is always offered and hidden with
// "visible" when it cannot apply, because the hook may only run once.
Hooks.on("getActorContextOptions", (application, menuItems) => {
menuItems.push({
label: "Dragonroll: Force Sync",
icon: "fa-solid fa-rotate",
visible: () => Boolean(game.user?.isGM && getSyncToken()),
onClick: (event, target) => {
// One entry is clicked at a time, but several can be selected: take every
// selected actor directory entry, falling back to the one the menu was
// opened for.
const clicked = target?.closest?.("[data-entry-id]") ?? target;
const ids = new Set(
[...(application?.element?.querySelectorAll?.("[data-entry-id].selected") ?? [])]
.map((entry) => entry.dataset?.entryId),
);
if (clicked?.dataset?.entryId) ids.add(clicked.dataset.entryId);
forceSyncActorsToDragonroll([...ids].map((id) => game.actors?.get(id)).filter(Boolean));
},
});
});