1 Commits

Author SHA1 Message Date
Gitea OpenCode Agent
8510a93027 Fix issue #101: Add lights to maps
All checks were successful
Test / test (push) Successful in 2s
2026-10-16 01:59:57 +00:00
25 changed files with 1544 additions and 1913 deletions

View File

@@ -83,12 +83,11 @@ campaign, and handlers check ownership with a `userOwnsCampaign(campaignId, user
- `User` — `name*`, `username*`, `email*` (both unique), `password` (bcrypt, 10 rounds), `admin`, `image`, `setupCode`, `settings`
- `Campaign` — `name*`, `createdBy*`→User, `description`, `color`, `settings`, `foundryWorldId`/`foundryWorldTitle`/`foundrySystem`, `foundrySyncTokenHash` (`select: false`), `discordGuildId`
- `Note` — `title`, `content` (markdown source), `campaign*`, `folder` (null = root), `color`, `foundryPageId`
- `Note` — `title`, `content` (markdown source), `campaign*`, `folder` (null = root), `color`
- `Folder` — `name*`, `campaign*`, `parentFolder` (null = root, self-ref), `color`
- `Actor` — `name*`, `campaign*`, `foundryActorId` (unique per campaign), `discordUserId` (the Discord player holding the character, unique per campaign — set only by `routes/discord.js`), plus free-form sheet fields (`type`, `species`, `className`, `level`, `abilityScores`, `armorClass`, `speed`, `proficiencies`, `traits`, `spells`, `image`) and `inventory[{name,quantity,weight}]` (flattened Foundry items, **not** `Item` docs)
- `Item` — `name*`, `campaign*`, `foundryItemId` (unique per campaign), `foundryNames`, `category`, `rarity`, `quantity`, `weight`, `properties`, `description`
- `Map` — `name*`, `campaign*`, `image` (filename in `src/uploads`, or a full URL a synced scene's
picture arrives as), `gridSize`/`offsetX`/`offsetY`/`scale` (image px), `pins[{note→Note, x, y}]` (addressed by the pin's own `_id`), `tokens[{actor→Actor, x, y}]` (the centre of the grid cell the token stands in, also addressed by its own `_id`), `foundrySceneId` (the Foundry scene this map mirrors, unique per campaign)
- `Map` — `name*`, `campaign*`, `image` (filename in `src/uploads`), `gridSize`/`offsetX`/`offsetY`/`scale` (image px), `pins[{note→Note, x, y}]` (addressed by the pin's own `_id`), `tokens[{actor→Actor, x, y}]` (the centre of the grid cell the token stands in, also addressed by its own `_id`)
- `ServiceLinkRequest` — the pending/completed service pairings of §4; `DiscordGuildLink` maps a Discord guild to the Dragonroll user who claimed it
**API surface** (all under `/api`, all `{status,msg}`):
@@ -115,15 +114,11 @@ rest, expire after 10 min, and Obsidian gets a long-lived (365 d) token back.
Foundry then syncs with that token on `/api/foundry/sync/*` (`routes/foundry-link.js`, mounted before
the JWT guard; CORS opened for it): `snapshot` (actors + world items, `fullSync` also prunes),
`item-snapshot`, `item-delete`, `scenes` (the world's scenes as the campaign's maps, `fullSync` also
prunes), `scene-delete`, `characters`, `items`, `notes` / `map-note`, `status`,
`map` / `map-item`, `delete`. Rules:
`item-snapshot`, `item-delete`, `characters`, `items`, `status`, `map` / `map-item`, `delete`. Rules:
- **Identity** is `foundryActorId` / `foundryItemId` (unique per campaign, partial index); a Foundry document carrying the `dragonroll-foundry.actorId` / `.itemId` flag adopts the matching Dragonroll row.
- **Only the world's item directory reaches the item list** (Syndria98/dragonroll#67) — `snapshotItemSources` reads `body.items` (`game.items`) alone; gear embedded in a character is that actor's `inventory` (see the `Actor` model), not an `Item`. A world item still folds into a hand-made or renamed row it matches by name (`foundryNames`), so a rename does not resurrect a duplicate. `services/item-foundry.js` returns `null` for non-gear types and those are skipped.
- **Item folders mirror the world's item directory** (`Folder.foundryFolderId`, target `item`): every push carries the whole tree and the world owns its names and nesting. `color` is the one field the campaign sets too, so it travels back with the folders `GET /foundry/sync/items` answers with (`{items, folders}`) and the module writes it onto the world's folder.
- **A world's scenes arrive as its campaign's maps** (Syndria98/dragonroll#99): `POST /foundry/sync/scenes` writes one `Map` per scene through `saveFoundryScene`, and only the scene's background picture and grid cross over (`services/map-foundry.js`: `gridSize` from `grid`/`grid.size`, the offsets from `flags.core.shiftX`/`.shiftY`) — `scale`, the folder, the pins and the tokens stay with the campaign and nothing of a map goes back to the world. Identity is `Map.foundrySceneId` (unique per campaign), a `dragonroll-foundry.mapId` flag or a hand-made unmapped map of the same name; a scene with no picture makes no map. `POST /foundry/sync/scene-delete` drops the map of a deleted scene, and only the full list the module sends when the world links or loads prunes.
- **Notes reach the world as journal pages, one way** (Syndria98/dragonroll#98): the module reads `GET /sync/notes` and stands every campaign note as a page of one world `JournalEntry` named Dragonroll — the page carries the note's id in a `dragonroll-foundry.noteId` flag, the note keeps the page's id in `foundryPageId` (`POST /sync/map-note`). The reconcile rewrites pages from the notes and drops the page of a deleted note; journal edits never travel back.
- **`fullSync` preserves Dragonroll edits** (only new rows are overwritten); live Foundry events overwrite. Only a full snapshot can prune.
- **Autosync is a Foundry-side setting** (`autoSync`, on by default): off = no CRUD push, no periodic reconcile, no startup snapshot; the actor directory's *Dragonroll: Force Sync* still upserts the selection (`fullSync:false`).
- `GET /api/foundry/*` (`routes/foundry.js`) is unrelated: a JWT-protected proxy over the read-only bridge. Its one write, `POST /import`, pulls the bridge's actors or world items into the campaign through the same writers as a sync push.

View File

@@ -27,6 +27,32 @@ const MapSchema = new Schema({
x: { type: Number, default: 0 },
y: { type: Number, default: 0 }
}],
// Lights placed on the map. x/y are image pixels like a pin — a light is not tied to a cell — and
// `radius` is how far it reaches in image pixels, of which `bright` is the part that is bright
// light and the rest dim light. The walls below are what stops one, see the viewer's
// services/MapLighting.js.
lights: [{
x: { type: Number, default: 0 },
y: { type: Number, default: 0 },
radius: { type: Number, min: 1, default: 150 },
bright: { type: Number, min: 0, default: 75 },
// Tint of the light, like '#ffc46b'; empty for a plain white light.
color: { type: String, default: '' },
// The Foundry AmbientLight document this light mirrors, when the world sent it (see
// routes/foundry-link.js). Empty for a light the campaign placed itself.
foundryLightId: { type: String, default: '' }
}],
// The line segments that block the lights above. Endpoints are image pixels, and the app draws
// them from corner to corner of the grid so a wall follows its lines.
walls: [{
x1: { type: Number, default: 0 },
y1: { type: Number, default: 0 },
x2: { type: Number, default: 0 },
y2: { type: Number, default: 0 },
// The Foundry Wall document this segment came from, when the world sent it. The world owns its
// walls, so a synced one is drawn back over by the next push of that scene.
foundryWallId: { type: String, default: '' }
}],
campaign: {
type: Schema.Types.ObjectId,
ref: 'Campaign',
@@ -39,15 +65,10 @@ const MapSchema = new Schema({
ref: 'Folder',
default: null
},
// The Foundry scene this map mirrors, set by the scene sync only
// (see routes/foundry-link.js). Only the picture and the grid follow the world.
foundrySceneId: { type: String },
// The Foundry scene whose lights and walls this map mirrors (see routes/foundry-link.js). Empty for
// a map the campaign made for itself, which is the one kind of light a world never hears about.
foundrySceneId: { type: String, default: '' },
date: { type: Date, default: Date.now }
});
MapSchema.index(
{ campaign: 1, foundrySceneId: 1 },
{ unique: true, partialFilterExpression: { foundrySceneId: { $type: 'string' } } }
);
module.exports = mongoose.model('Map', MapSchema);

View File

@@ -14,16 +14,7 @@ const NoteSchema = new Schema({
ref: 'Folder'
},
color: { type: String },
// The journal page this note is written as in the linked Foundry world: the
// page of the one "Dragonroll" journal whose rows carry this note's id in
// their `dragonroll-foundry.noteId` flag (see the module's notes sync).
foundryPageId: { type: String },
date: { type: Date, default: Date.now }
});
NoteSchema.index(
{ campaign: 1, foundryPageId: 1 },
{ unique: true, partialFilterExpression: { foundryPageId: { $type: 'string' } } }
);
module.exports = mongoose.model('Note', NoteSchema);

View File

@@ -6,13 +6,12 @@ const router = express.Router();
const Campaign = require('../models/Campaign');
const Actor = require('../models/Actor');
const Item = require('../models/Item');
// Not `Map`: this route builds plain `Map`s of its own to mirror the world's folder tree.
const MapModel = require('../models/Map');
const Folder = require('../models/Folder');
const Note = require('../models/Note');
// Named for what it is: the plain `Map` of this module's own scope would hide the built-in `Map` the
// item folder sync below builds its trees out of.
const MapModel = require('../models/Map');
const { foundryActorToCharacter } = require('../services/actor-foundry');
const { foundryItemToItemData } = require('../services/item-foundry');
const { foundrySceneToMapData } = require('../services/map-foundry');
const { joinFoundryAssetUrl } = require('../services/foundry-icons');
// Upper bound for the Foundry names remembered per synced item (see Item model).
@@ -68,9 +67,9 @@ function resolveWorldAssets(fields, campaign) {
}
}
async function saveFoundryActor(campaign, source, fullSync = false, replace = false) {
async function saveFoundryActor(campaign, source, fullSync = false) {
const foundryActorId = String(source?._id || source?.id || '').trim().slice(0, 120);
const fields = foundryActorToCharacter(source || {}, replace);
const fields = foundryActorToCharacter(source || {});
if (!foundryActorId || !fields.name) return null;
resolveWorldAssets(fields, campaign);
@@ -272,45 +271,185 @@ function resolveFoundryItemFolder(source, folders) {
return folders.get(foundryFolderId.trim())?._id || null;
}
// --- Maps -------------------------------------------------------------------
// A scene of the world becomes one of the campaign's maps (Syndria98/dragonroll#99):
// services/map-foundry.js says what of a scene travels — its background picture and the
// grid laid over it, and nothing else, so the map's pins, its tokens, the folder it
// stands in and what one of its cells means stay the campaign's own.
// --- Scene lighting ------------------------------------------------------------
// A Foundry scene lights its own ground, and the campaign mirrors that onto the map standing for that
// scene: the world's ambient lights and the walls that stop them arrive there, so a torch lit in the
// world is a torch on the map the campaign reads, and the dark behind its walls is the same dark.
//
// The module sends its coordinates as pixels of the scene's background image at the size that image
// has on disk, and its reaches likewise. The campaign keeps everything as pixels of its own map image,
// so the grid cell is the unit the two agree on: one scene pixel is worth as many map pixels as that
// map's cell is wider or narrower than the scene's.
async function saveFoundryScene(campaign, source, fullSync = false) {
const foundrySceneId = String(source?._id || source?.id || '').trim().slice(0, 120);
const fields = foundrySceneToMapData(source || {});
if (!foundrySceneId || !fields) return null;
resolveWorldAssets(fields, campaign);
function sceneNumber(value, fallback = 0) {
const number = Number(value);
return Number.isFinite(number) ? number : fallback;
}
let map = await MapModel.findOne({ campaign: campaign._id, foundrySceneId });
const dragonrollMapId = source?.flags?.['dragonroll-foundry']?.mapId;
if (!map && mongoose.isValidObjectId(dragonrollMapId)) {
const flagged = await MapModel.findOne({ _id: dragonrollMapId, campaign: campaign._id });
// Only adopt a flagged map while no other scene owns its mapping.
if (flagged && (!flagged.foundrySceneId || flagged.foundrySceneId === foundrySceneId)) map = flagged;
// The scene a push describes: enough of it to mirror a map after it, and to scale its lighting onto
// the grid of whichever map that turns out to be.
function readSceneSource(source) {
const id = String(source?.id || '').trim().slice(0, 120);
if (!id) return null;
return {
id,
title: String(source?.title || '').trim().slice(0, 200),
// How wide one of the scene's cells is in its image pixels, and how much distance it stands
// for: the map the scene is mirrored onto keeps both of these under the same names.
grid: Math.max(1, Math.round(sceneNumber(source?.grid, 50))),
gridDistance: Math.max(0.01, sceneNumber(source?.gridDistance, 5)),
image: typeof source?.image === 'string' ? source.image.trim() : ''
};
}
// The map a scene's lighting belongs to: the one already mirroring that scene, or the campaign's own
// map of the same name — the same courtesy the item sync extends a hand-written row, so whoever drew
// the map by hand is not made to start over — and, when the scene has lighting of its own and the
// campaign has no map for it yet, a new map mirroring the scene. A scene with nothing to send never
// invents a map nobody asked for.
async function sceneMap(campaign, scene, create) {
const mapped = await MapModel.findOne({ campaign: campaign._id, foundrySceneId: scene.id });
if (mapped) return mapped;
if (scene.title) {
const namesakes = await MapModel.find({ campaign: campaign._id, name: scene.title }).limit(4);
const claiming = namesakes.filter((map) => !map.foundrySceneId);
// Only a name the campaign uses once claims the scene; two maps of that name would make it a
// guess which of them the world is talking about.
if (claiming.length === 1) {
const map = claiming[0];
map.foundrySceneId = scene.id;
return map;
}
if (!map) {
// The campaign drew this place by hand before the scene of it ever arrived: a scene
// naming the one unmapped map the campaign holds folds into that row instead of
// adding a second copy of the same room.
const sameName = await MapModel.find({
}
if (!create) return null;
return new MapModel({
campaign: campaign._id,
name: fields.name,
foundrySceneId: { $exists: false }
}).limit(2);
map = sameName.length === 1 ? sameName[0] : new MapModel({ campaign: campaign._id });
name: scene.title || 'Foundry scene',
// The scene's own artwork, read against its world like every other Foundry image (see
// worldAssetUrl), so the campaign is looking at the same picture the players are.
image: worldAssetUrl(scene.image, campaign?.settings?.integrations?.foundryUrl),
gridSize: scene.grid,
scale: scene.gridDistance,
foundrySceneId: scene.id
});
}
// A scene pixel as a coordinate of the campaign's map: whole pixels, never negative, and scaled by the
// two grids' difference in cell width.
function scenePixelToMap(value, ratio) {
const number = sceneNumber(value, 0) * ratio;
return Math.max(0, Math.round(number));
}
// The tint of a light, or none: the viewer paints with it, so anything that is not a hex colour is
// dropped rather than trusted.
function sceneLightColor(value) {
const color = typeof value === 'string' ? value.trim().toLowerCase() : '';
return /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/.test(color) ? color : '';
}
// A wall of the map is kept at its corners of the grid, the way a wall drawn in Dragonroll is, so the
// lines a scene sends and the lines a campaign draws follow the same grid.
function toMapGridVertex(value, offset, size) {
const steps = Math.round((Math.max(0, Math.round(value)) - offset) / size);
return Math.max(0, Math.round(offset + steps * size));
}
// The lights of a scene written onto its map. A light the world sent before is written over — the
// world owns its own lighting, so unlike an actor's fields a move lands on every push — one it never
// sent is added, and one it has let go of goes. A light the campaign placed itself (no foundryLightId)
// is none of the world's business and stays.
function writeSceneLights(map, scene, sources) {
const ratio = map.gridSize / scene.grid;
const kept = new Set();
let changed = false;
for (const source of sources) {
const id = String(source?.id || '').trim().slice(0, 120);
if (!id || kept.has(id)) continue;
kept.add(id);
const radius = Math.max(1, scenePixelToMap(source?.radius, ratio));
const spot = {
x: scenePixelToMap(source?.x, ratio),
y: scenePixelToMap(source?.y, ratio),
radius,
bright: Math.max(0, Math.min(radius, scenePixelToMap(source?.bright, ratio))),
color: sceneLightColor(source?.color)
};
const light = map.lights.find((entry) => entry.foundryLightId && String(entry.foundryLightId) === id);
if (light) {
Object.assign(light, spot);
} else {
map.lights.push({ ...spot, foundryLightId: id });
}
changed = true;
}
map.foundrySceneId = foundrySceneId;
// `created` says whether this row is new, like the actor and item writers answer it.
const created = map.isNew;
// A full snapshot runs when a GM reconnects: the grid the campaign lined up for a map
// it already has survives that. Live scene edits continue to overwrite normally.
if (!fullSync || map.isNew) Object.assign(map, fields);
await map.save();
return { foundrySceneId, mapId: map.id, created };
// Only the world's own lights are pruned, and only by a push that speaks of lights at all.
const remaining = map.lights.filter((entry) => !entry.foundryLightId || kept.has(String(entry.foundryLightId)));
if (remaining.length !== map.lights.length) changed = true;
map.lights = remaining;
return changed;
}
// The walls of a scene, likewise: the world drew them, so its own walls arrive whole with every push.
function writeSceneWalls(map, scene, sources) {
const ratio = map.gridSize / scene.grid;
const kept = new Set();
let changed = false;
for (const source of sources) {
const id = String(source?.id || '').trim().slice(0, 120);
if (!id || kept.has(id)) continue;
kept.add(id);
const corner = {
x1: toMapGridVertex(scenePixelToMap(source?.x1, ratio), map.offsetX, map.gridSize),
y1: toMapGridVertex(scenePixelToMap(source?.y1, ratio), map.offsetY, map.gridSize),
x2: toMapGridVertex(scenePixelToMap(source?.x2, ratio), map.offsetX, map.gridSize),
y2: toMapGridVertex(scenePixelToMap(source?.y2, ratio), map.offsetY, map.gridSize)
};
// A wall from a corner to itself blocks nothing, and neither does its twin drawn backwards.
if (corner.x1 === corner.x2 && corner.y1 === corner.y2) continue;
const wall = map.walls.find((entry) => entry.foundryWallId && String(entry.foundryWallId) === id);
if (wall) Object.assign(wall, corner);
else map.walls.push({ ...corner, foundryWallId: id });
changed = true;
}
const remaining = map.walls.filter((entry) => !entry.foundryWallId || kept.has(String(entry.foundryWallId)));
if (remaining.length !== map.walls.length) changed = true;
map.walls = remaining;
return changed;
}
// The maps the module reconciles its scenes against: which campaign lights belong in which world
// scene, and how far a pixel of that map is worth. Only the maps that speak of lighting are sent, and
// a map mirroring a scene is sent even empty of lights, because that is what tells the world its
// campaign has put every one of its lights out.
function sceneLightingList(maps) {
return maps
.filter((map) => (map.lights?.length ?? 0) > 0 || map.foundrySceneId)
.map((map) => ({
_id: map._id,
name: map.name,
foundrySceneId: map.foundrySceneId || '',
gridSize: map.gridSize,
scale: map.scale,
lights: (map.lights ?? []).map((light) => ({
_id: light._id,
x: light.x,
y: light.y,
radius: light.radius,
bright: light.bright,
color: light.color || '',
foundryLightId: light.foundryLightId || ''
}))
}));
}
@@ -349,16 +488,12 @@ router.post('/sync/snapshot', async (req, res) => {
}
const fullSync = req.body.fullSync === true;
// A forced actor sync from the module's context menu replaces the campaign's
// row for the actors it sends entirely (Syndria98/dragonroll#96). It stays
// clear of fullSync: it never prunes, unlike a reconnect's full snapshot.
const replace = req.body.replace === true;
// A module that knows nothing about item folders sends neither the tree
// nor the folder of an item, and then nothing here touches the folders.
const folderSources = Array.isArray(req.body.folders) ? req.body.folders : null;
const actors = [];
for (const source of actorSources || []) {
const mapping = await saveFoundryActor(campaign, source, fullSync, replace);
const mapping = await saveFoundryActor(campaign, source, fullSync);
if (mapping) actors.push(mapping);
}
const itemFolders = folderSources ? await syncFoundryItemFolders(campaign, folderSources) : null;
@@ -483,59 +618,6 @@ router.post('/sync/item-delete', async (req, res) => {
}
});
// The world's scenes, upserted as the campaign's maps (Syndria98/dragonroll#99). Like a
// world item push, this one prunes only when it is told it carries every scene: that push
// alone sees the whole scene list, so it alone knows which synced maps the world has let go
// of. A map the campaign made by hand has no scene of its own and is never pruned.
router.post('/sync/scenes', async (req, res) => {
try {
const campaign = await syncCampaign(req, res);
if (!campaign) return;
if (!requestMatchesWorld(campaign, req.body.worldId) || !Array.isArray(req.body.scenes)) {
return res.json({ status: 'error', msg: 'errors.missing-data' });
}
const fullSync = req.body.fullSync === true;
const maps = [];
for (const source of req.body.scenes) {
const mapping = await saveFoundryScene(campaign, source, fullSync);
if (mapping) maps.push(mapping);
}
if (fullSync) {
const currentIds = req.body.scenes
.map((source) => String(source?._id || source?.id || '').trim())
.filter(Boolean);
await MapModel.deleteMany({
campaign: campaign._id,
foundrySceneId: { $exists: true, $nin: currentIds }
});
}
res.json({ status: 'ok', maps });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
// A scene the world deleted takes its map with it. Only the world says so; deleting a map
// in the campaign leaves the world's scene alone, which is the campaign's own to do.
router.post('/sync/scene-delete', async (req, res) => {
try {
const campaign = await syncCampaign(req, res);
if (!campaign) return;
const foundrySceneId = String(req.body.foundrySceneId || '').trim();
if (!requestMatchesWorld(campaign, req.body.worldId) || !foundrySceneId) {
return res.json({ status: 'error', msg: 'errors.missing-data' });
}
await MapModel.deleteOne({ campaign: campaign._id, foundrySceneId });
res.json({ status: 'ok' });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
// The item list the world reconciles against, together with the folders its rows are
// grouped into — the same shape the campaign's own `/item/list` answers with. The folders
// travel back for their colour: the world owns the tree's name and nesting, while whoever
@@ -579,51 +661,76 @@ router.post('/sync/map-item', async (req, res) => {
}
});
// --- Note pages ------------------------------------------------------------
// The campaign's notes are read where their authors' table sits: every note
// stands as a page of the one journal the world calls "Dragonroll". Notes are
// written in Dragonroll, so this copy runs one way — the module reads the notes
// and rewrites their pages; nothing of the journal travels back. Its pages keep
// the note's id in a `dragonroll-foundry.noteId` flag, and the note keeps the
// page's id here, so either side recognises the pairing again after a restart.
// Every note of the campaign, content included: enough for the module to write
// each one as a page. Folders of the notes do not travel — the journal is flat.
router.get('/sync/notes', async (req, res) => {
// The lighting of one of the world's scenes: its ambient lights and the walls that stop them, sent
// whole so the campaign's map of that scene reads like the ground the players are standing on.
router.post('/sync/scene', async (req, res) => {
try {
const campaign = await syncCampaign(req, res);
if (!campaign) return;
const notes = await Note.find({ campaign: campaign._id })
.select('_id title content foundryPageId date')
.sort({ date: -1 })
.lean();
res.json({ status: 'ok', notes });
const scene = readSceneSource(req.body.scene);
const lights = Array.isArray(req.body.lights) ? req.body.lights : null;
const walls = Array.isArray(req.body.walls) ? req.body.walls : null;
if (!requestMatchesWorld(campaign, req.body.worldId) || !scene || (!lights && !walls)) {
return res.json({ status: 'error', msg: 'errors.missing-data' });
}
const map = await sceneMap(campaign, scene, (lights?.length ?? 0) + (walls?.length ?? 0) > 0);
// A world pushing a scene empty of lighting onto a campaign that has no map for it: there is
// nothing here to remember, so nothing is remembered.
if (!map) return res.json({ status: 'ok', map: null, lights: 0, walls: 0 });
// A push owns the lighting it carries and nothing else: not the map's name, not its picture,
// not the grid whoever lined it up by hand settled on.
if (lights) writeSceneLights(map, scene, lights);
if (walls) writeSceneWalls(map, scene, walls);
await map.save();
res.json({
status: 'ok',
map: { _id: map.id, name: map.name, gridSize: map.gridSize, scale: map.scale, foundrySceneId: map.foundrySceneId },
lights: map.lights.filter((entry) => entry.foundryLightId).length,
walls: map.walls.filter((entry) => entry.foundryWallId).length
});
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
// The page the module made for a note, kept on the note so the next reconcile —
// or a world whose page flags were lost — writes that page instead of a second
// one under the same title.
router.post('/sync/map-note', async (req, res) => {
// The campaign's lighting as the world reads it: which of its lights stand in which scene, at the map
// pixels the module scales back onto the world's own grid.
router.get('/sync/scenes', async (req, res) => {
try {
const campaign = await syncCampaign(req, res);
if (!campaign) return;
const { noteId, foundryPageId, worldId } = req.body;
if (!requestMatchesWorld(campaign, worldId) || !noteId || !foundryPageId) {
const maps = await MapModel.find({ campaign: campaign._id }).sort({ name: 1 }).lean();
res.json({ status: 'ok', scenes: sceneLightingList(maps) });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
// A light the campaign placed and the world has taken on: the AmbientLight document standing for it, so
// the next write of that light knows which document to move instead of adding a second one.
router.post('/sync/map-scene-light', async (req, res) => {
try {
const campaign = await syncCampaign(req, res);
if (!campaign) return;
const { map, light, foundryLightId, worldId } = req.body;
if (!requestMatchesWorld(campaign, worldId) || !map || !light || !foundryLightId) {
return res.json({ status: 'error', msg: 'errors.missing-data' });
}
const note = await Note.findOne({ _id: noteId, campaign: campaign._id });
if (!note) return res.json({ status: 'error', msg: 'errors.notfound' });
const existing = await Note.findOne({ campaign: campaign._id, foundryPageId, _id: { $ne: note._id } });
if (existing) return res.json({ status: 'error', msg: 'foundry.errors.note-already-synced' });
const mapDoc = await MapModel.findOne({ _id: map, campaign: campaign._id });
if (!mapDoc) return res.json({ status: 'error', msg: 'errors.notfound' });
const entry = mapDoc.lights.find((current) => String(current._id) === String(light));
if (!entry) return res.json({ status: 'error', msg: 'errors.notfound' });
note.foundryPageId = String(foundryPageId).trim().slice(0, 120);
await note.save();
res.json({ status: 'ok', note });
entry.foundryLightId = String(foundryLightId).trim().slice(0, 120);
await mapDoc.save();
res.json({ status: 'ok', light: { _id: entry._id, foundryLightId: entry.foundryLightId } });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });

View File

@@ -238,4 +238,205 @@ router.post('/remove-token', async (req, res) => {
}
});
// --- Lights ---
// A light shines from one spot of the image and is as free as a pin: it is not tied to a cell, so it
// lands wherever it is placed. Its reach is measured in image pixels too, so it covers the same ground
// whatever the zoom is, and it is that reach the viewer cuts its shadow against the walls below with.
// How far a light of the map reaches when nothing is asked for: about three cells of the default grid.
const DEFAULT_LIGHT_RADIUS = 150;
function toReach(value, fallback) {
const number = Number(value);
if (!Number.isFinite(number) || number <= 0) return fallback;
return Math.max(1, Math.round(number));
}
// The bright core of a light: never wider than the light itself, and never negative. A light with no
// core is still a light, so 0 is a value of its own here and not a missing one.
function toBright(value, radius, fallback) {
if (value === undefined || value === null || value === '') return Math.min(radius, Math.round(fallback));
const number = Number(value);
if (!Number.isFinite(number)) return Math.min(radius, Math.round(fallback));
return Math.max(0, Math.min(radius, Math.round(number)));
}
// A tint is a hex colour and nothing else: the viewer paints the light with it, so a value carrying
// more than colour codes is dropped instead of trusted.
function toColor(value) {
const color = String(value ?? '').trim().toLowerCase();
return /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/.test(color) ? color : '';
}
router.post('/place-light', async (req, res) => {
try {
const { id, x, y, radius, bright, color } = req.body;
if (!id) return res.json({ status: 'error', msg: 'errors.missing-data' });
const map = await Map.findById(id);
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
const reach = toReach(radius, DEFAULT_LIGHT_RADIUS);
map.lights.push({
x: toCoordinate(x),
y: toCoordinate(y),
radius: reach,
bright: toBright(bright, reach, reach / 2),
color: toColor(color)
});
await map.save();
res.json({ status: 'ok', map });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
router.post('/update-light', async (req, res) => {
try {
const { id, light, x, y, radius, bright, color } = req.body;
if (!id || !light) return res.json({ status: 'error', msg: 'errors.missing-data' });
const map = await Map.findById(id);
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
const current = map.lights.find((entry) => String(entry._id) === String(light));
if (!current) return res.json({ status: 'error', msg: 'errors.notfound' });
if (x !== undefined) current.x = toCoordinate(x);
if (y !== undefined) current.y = toCoordinate(y);
if (color !== undefined) current.color = toColor(color);
if (radius !== undefined) {
current.radius = toReach(radius, current.radius);
// A light shrunk below its own core takes the core with it, unless this request is
// setting the core as well, which is clamped to the new reach below.
current.bright = Math.min(current.bright, current.radius);
}
if (bright !== undefined) current.bright = toBright(bright, current.radius, current.bright);
await map.save();
res.json({ status: 'ok', map });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
router.post('/remove-light', async (req, res) => {
try {
const { id, light } = req.body;
if (!id || !light) return res.json({ status: 'error', msg: 'errors.missing-data' });
const map = await Map.findById(id);
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
// `_id` stays with the lights that remain, the same way the tokens are removed.
map.lights = map.lights
.filter((entry) => String(entry._id) !== String(light))
.map((entry) => ({
_id: entry._id,
x: entry.x,
y: entry.y,
radius: entry.radius,
bright: entry.bright,
color: entry.color,
foundryLightId: entry.foundryLightId
}));
await map.save();
res.json({ status: 'ok', map });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
// --- Walls ---
// The segments that stop a light. They are drawn from one corner of the grid to another — the same
// corners the tokens' cells are counted from — so a wall lines up with the grid of the map it belongs
// to. A world's walls travel to the map they light (routes/foundry-link.js) and arrive at the corners
// of the grid the same way.
function toGridVertex(value, offset, size) {
const grid = Math.max(1, Number(size) || 50);
const origin = Number(offset) || 0;
const steps = Math.round((toCoordinate(value) - origin) / grid);
return Math.max(0, Math.round(origin + steps * grid));
}
// The two ends of a wall are corners of this map's grid, whatever the pointer asked for.
function wallCorners(body, map) {
return {
x1: toGridVertex(body.x1, map.offsetX, map.gridSize),
y1: toGridVertex(body.y1, map.offsetY, map.gridSize),
x2: toGridVertex(body.x2, map.offsetX, map.gridSize),
y2: toGridVertex(body.y2, map.offsetY, map.gridSize)
};
}
function isSameWall(wall, corner) {
return (String(wall.x1) === String(corner.x1) && String(wall.y1) === String(corner.y1)
&& String(wall.x2) === String(corner.x2) && String(wall.y2) === String(corner.y2))
// A wall drawn backwards is the same wall.
|| (String(wall.x1) === String(corner.x2) && String(wall.y1) === String(corner.y2)
&& String(wall.x2) === String(corner.x1) && String(wall.y2) === String(corner.y1));
}
router.post('/wall', async (req, res) => {
try {
const { id } = req.body;
if (!id) return res.json({ status: 'error', msg: 'errors.missing-data' });
const map = await Map.findById(id);
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
const corner = wallCorners(req.body, map);
// A wall from a corner to itself blocks nothing and cannot be clicked off again.
if (corner.x1 === corner.x2 && corner.y1 === corner.y2) {
return res.json({ status: 'error', msg: 'errors.missing-data' });
}
// Drawing over a wall that is already there does not add a second one.
if (map.walls.some((wall) => isSameWall(wall, corner))) return res.json({ status: 'ok', map });
map.walls.push(corner);
await map.save();
res.json({ status: 'ok', map });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
router.post('/remove-wall', async (req, res) => {
try {
const { id, wall } = req.body;
if (!id || !wall) return res.json({ status: 'error', msg: 'errors.missing-data' });
const map = await Map.findById(id);
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
// `_id` stays with the walls that remain, like everything else hanging off a map.
map.walls = map.walls
.filter((entry) => String(entry._id) !== String(wall))
.map((entry) => ({
_id: entry._id,
x1: entry.x1,
y1: entry.y1,
x2: entry.x2,
y2: entry.y2,
foundryWallId: entry.foundryWallId
}));
await map.save();
res.json({ status: 'ok', map });
} catch (err) {
console.error(err);
res.json({ status: 'error', msg: 'errors.internal' });
}
});
module.exports = router;

View File

@@ -130,11 +130,7 @@ function foundryTraits(source, items) {
return features.length ? features.join('\n\n') : undefined;
}
// `replace` is a forced actor sync from the module's context menu (Syndria98/dragonroll#96):
// it replaces everything the campaign holds for this actor, so the fields a live edit
// leaves out when the world says nothing are written empty instead of kept. A live Foundry
// change passes `false` and keeps the campaign's own toggles and text.
function foundryActorToCharacter(foundryActor, replace = false) {
function foundryActorToCharacter(foundryActor) {
const system = foundryActor.system || {};
const details = system.details || {};
const abilities = system.abilities || {};
@@ -173,9 +169,7 @@ function foundryActorToCharacter(foundryActor, replace = false) {
])),
armorClass: numberOr(attributes.ac?.value ?? attributes.ac, 10),
speed: numberOr(movement.walk ?? movement.value, 30),
// A replace takes the world's text even when it has none, so what Dragonroll
// cached on the actor's flag does not survive it; a live edit keeps that text.
proficiencies: foundryProficiencies || (replace ? '' : asText(savedDragonrollFields.proficiencies)),
proficiencies: foundryProficiencies || asText(savedDragonrollFields.proficiencies),
// What the character carries: gear, and gear only (Syndria98/dragonroll#89). A feat
// is a trait — its tab shows it — and a race is the species; standing them in the
// inventory next to the longswords is how traits and items got mixed up.
@@ -207,21 +201,9 @@ function foundryActorToCharacter(foundryActor, replace = false) {
const currency = foundryCurrency(system);
if (currency) fields.currency = currency;
const worldTraits = foundryTraits(foundryActor, items);
const campaignTraits = replace ? '' : asText(savedDragonrollFields.traits);
const campaignTraits = asText(savedDragonrollFields.traits);
if (worldTraits || campaignTraits) fields.traits = worldTraits || campaignTraits;
// A replace writes the fields a live edit would leave out when the world says
// nothing, so the campaign's toggles, lists and text for this actor go with it and
// the row reads as the Foundry actor alone (Syndria98/dragonroll#96).
if (replace) {
if (fields.skills === undefined) fields.skills = {};
if (fields.savingThrows === undefined) fields.savingThrows = {};
if (fields.tools === undefined) fields.tools = [];
if (fields.languages === undefined) fields.languages = [];
if (fields.currency === undefined) fields.currency = {};
if (fields.traits === undefined) fields.traits = '';
}
return fields;
}

View File

@@ -1,49 +0,0 @@
const { numberOr, asText } = require('./foundry-fields');
// A Foundry scene is one of the campaign's maps (Syndria98/dragonroll#99): its background
// picture and the grid laid over it travel to Dragonroll. Everything else a scene holds —
// its padding, its lighting, the tokens standing on it — belongs to the world's table, and
// so does what one of its cells stands for (`gridDistance` with its units): the campaign
// sets its own scale and keeps it.
// The scene's background picture: `background.src` since Foundry V13, plain `img` before.
function sceneImage(scene) {
return asText(scene?.background?.src).trim() || asText(scene?.img).trim();
}
// How many pixels of the picture one grid cell covers. Foundry keeps it under `grid.size`
// since V13 and under plain `grid` before; 50 px is its own default cell size, and
// Dragonroll's is the same, so a scene that says nothing gets the grid it draws.
function sceneGridSize(scene) {
const size = numberOr(scene?.grid?.size ?? scene?.grid, 0);
return size >= 1 ? Math.round(size) : 50;
}
// Where that grid starts on the picture. A world shifts it with the core flags of its own
// (`flags.core.shiftX` / `.shiftY`, what it uses to line a hexagonal grid up); one that says
// nothing has its grid at the corner of the picture. The scene's padding is blank canvas
// *outside* the picture, so it is no part of the grid the campaign lays on the picture itself.
function sceneGridOffset(scene, axis) {
return Math.round(numberOr(scene?.flags?.core?.[`shift${axis}`], 0));
}
// Returns null for a scene that is not a map: one with no name, or with no background
// picture. A Dragonroll map without a picture is an empty viewer, so those scenes stay in
// the world — their id is still listed by the snapshot that carries them, so nothing of the
// campaign is pruned because of one.
function foundrySceneToMapData(scene) {
const name = asText(scene?.name).trim();
const image = sceneImage(scene);
if (!name || !image) return null;
return {
name,
// The module sends Foundry's picture as an absolute URL, like actors do.
image,
gridSize: sceneGridSize(scene),
offsetX: sceneGridOffset(scene, 'X'),
offsetY: sceneGridOffset(scene, 'Y')
};
}
module.exports = { foundrySceneToMapData };

View File

@@ -3,7 +3,7 @@
Foundry modules run in the game client, so the module cannot bind an HTTP port on the Foundry host.
This integration uses a small companion bridge process on that host:
1. A linked GM client syncs character Actors, world Items and Scenes directly with the Dragonroll campaign.
1. A linked GM client syncs character Actors and world Items 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/*`.
@@ -73,11 +73,9 @@ queued while it was off are sent as the world catches up.
With autosync off — or any time a single character needs to cross over right now — right-click an
actor (or several selected ones) in the Foundry actor directory and pick **Dragonroll: Force Sync**.
Those actors, together with the gear carried inside them, are pushed to the campaign immediately even
when autosync is off, **replacing everything that campaign holds for them** (Syndria98/dragonroll#96):
what the campaign had edited on those actors is written over by what the world says. It replaces
those actors only — it never prunes the campaign's other actors, which a full snapshot does and a
forced sync never claims to. Actors Dragonroll does not import (anything that is not a character, NPC
or creature) are refused with a notification.
when autosync is off. It is an upsert only: it never prunes the campaign's other actors, which a full
snapshot does and a forced sync never claims to. Actors Dragonroll does not import (anything that is
not a character, NPC or creature) are refused with a notification.
The optional read-only snapshot bridge is not affected: it keeps publishing the world snapshot behind
`/api/foundry/*`, which is never written into the campaign.
@@ -107,42 +105,6 @@ 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.
### Notes
The campaign's notes read like the campaign's journal in the world (Syndria98/dragonroll#98): every
note stands as a page of one JournalEntry named **Dragonroll**. The module creates that journal — or
adopts one the GM already made under that name, marking it as the notes' journal — and renders each
note's markdown into page HTML with Foundry's own renderer. Notes are written in Dragonroll, so this
copy runs one way: a note made or edited in the campaign rewrites its page on the next reconcile, and
a note deleted there takes its page with it. A page standing under a note's title but carrying no
Dragonroll mark is claimed as that note's page, so a lost pairing does not double it. Any other page in
that journal — the GM's own — is left alone, and nothing written in the journal travels back. Autosync
off stops it too, like the rest of the sync.
The module calls these Dragonroll routes with the campaign sync token (no Dragonroll login):
| Route | Use |
@@ -150,20 +112,14 @@ The module calls these Dragonroll routes with the campaign sync token (no Dragon
| `POST /api/foundry/sync/snapshot` | Actors and world items upsert; `fullSync` also prunes |
| `POST /api/foundry/sync/item-snapshot` | Live world item edits, upsert only |
| `POST /api/foundry/sync/item-delete` | A world item was deleted |
| `POST /api/foundry/sync/scenes` | The world's scenes upsert as the campaign's maps; `fullSync` also prunes |
| `POST /api/foundry/sync/scene-delete` | A scene was deleted |
| `GET /api/foundry/sync/characters` | Characters to apply back in Foundry |
| `GET /api/foundry/sync/items` | Items, and the item folders with their Dragonroll colours, to apply back in Foundry |
| `GET /api/foundry/sync/notes` | The campaign's notes, markdown and all, and the journal page each stands as |
| `POST /api/foundry/sync/map-note` | Store a note's journal page id after creating that page |
| `GET /api/foundry/sync/status` | The campaign this world's token belongs to, for the module's pairing status |
| `POST /api/foundry/sync/map` / `map-item` | Store an id mapping after creating a document |
| `POST /api/foundry/sync/delete` | An actor was deleted |
Foundry documents keep the Dragonroll id in the `dragonroll-foundry.actorId` / `dragonroll-foundry.itemId`
flag, and a journal page the module made for a note keeps its note's id in the `dragonroll-foundry.noteId`
flag, so the notes reconcile recognises its own pages. World items are marked with
`dragonroll-foundry.syncMutation` while Dragonroll writes them so
flag, and world items are marked with `dragonroll-foundry.syncMutation` while Dragonroll writes them so
the write is not echoed back. A folder colour is written with that folder held in the client's set of
folders being synced, for the same reason.

View File

@@ -2,7 +2,7 @@
"id": "dragonroll-foundry",
"title": "Dragonroll Foundry API",
"description": "Links a Foundry world to a Dragonroll campaign and exposes a client-side API for world data.",
"version": "0.6.0",
"version": "0.4.0",
"library": true,
"compatibility": {
"minimum": "12",

View File

@@ -33,13 +33,15 @@ 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();
// The lighting of the scene being played: queued while the GM drags walls about, and written back into
// the world from the campaign on a timer.
let sceneLightingTimeout;
let sceneLightingRunning = false;
let sceneLightingErrorLogged = false;
const syncingLightIds = new Set();
function getCollectionContents(collection, collectionName) {
if (!collection) {
@@ -304,7 +306,6 @@ 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";
@@ -446,8 +447,7 @@ function handleAutoSyncChange(value) {
clearTimeout(actorSyncTimeout);
clearTimeout(itemSyncTimeout);
clearTimeout(folderSyncTimeout);
clearTimeout(sceneSyncTimeout);
clearTimeout(sceneSyncRetryTimeout);
clearTimeout(sceneLightingTimeout);
return;
}
if (!game.user?.isGM || !getSyncToken()) return;
@@ -457,8 +457,10 @@ function handleAutoSyncChange(value) {
initializeCharacterSync();
reconcileDragonrollItems();
queueFoundryItemFolders(400);
reconcileDragonrollNotes();
initializeSceneSync();
// The lighting of the scene the campaign mirrors converges too: a wall or a lamp moved while
// autosync was off is the world's, and the campaign's own lights are written back into the scene.
queueSceneLightingChange(400);
reconcileDragonrollSceneLighting();
if (queuedActorChanges.size) {
clearTimeout(actorSyncTimeout);
actorSyncTimeout = setTimeout(flushActorChanges, 400);
@@ -467,10 +469,6 @@ function handleAutoSyncChange(value) {
clearTimeout(itemSyncTimeout);
itemSyncTimeout = setTimeout(flushItemChanges, 400);
}
if (queuedSceneChanges.size) {
clearTimeout(sceneSyncTimeout);
sceneSyncTimeout = setTimeout(flushSceneChanges, 400);
}
}
function dragonrollActorId(actor) {
@@ -579,7 +577,7 @@ function reportActorSyncError(error) {
console.warn(`${MODULE_ID} | Character sync failed and will retry.`, error);
}
async function pushFoundryActors(actors, fullSync = false, replace = false) {
async function pushFoundryActors(actors, fullSync = false) {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || (!actors.length && !fullSync)) return;
if (game.system.id !== "dnd5e") {
@@ -598,9 +596,6 @@ async function pushFoundryActors(actors, fullSync = false, replace = false) {
// 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 || []) {
@@ -623,9 +618,8 @@ async function deleteDragonrollActor(foundryActorId) {
}
// 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.
// GM asks for. It upserts those actors 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()) {
@@ -641,7 +635,7 @@ async function forceSyncActorsToDragonroll(actors) {
if (!supported.length) return;
try {
await pushFoundryActors(supported, false, true);
await pushFoundryActors(supported);
ui.notifications?.info(supported.length === 1
? `${supported[0].name} was sent to the Dragonroll campaign.`
: `${supported.length} actors were sent to the Dragonroll campaign.`);
@@ -1078,6 +1072,371 @@ async function reconcileDragonrollItems() {
}
}
// --- Scene lighting ------------------------------------------------------------
// The lights of the scene being played, and the walls that stop them, travel to the Dragonroll map
// mirroring that scene; the lights the campaign places on that map travel back into the scene as
// ambient lights. Lighting belongs to a world the same way whatever system it runs, so unlike the
// actors and the items this asks for no particular one.
//
// Foundry measures a scene in canvas pixels (its background image as it is drawn) and a light's reach
// in the scene's distance units; Dragonroll measures both in pixels of the map image and of its grid.
// So a scene goes over as pixels of its own background image, and comes back through the grid cell,
// which is the one unit the two share.
// The canvas of the scene being played. `canvas` is a global only where a scene has been drawn, and
// only in a game client at that, so it is asked for the way the module asks for any global it cannot
// be sure of.
function foundryCanvas() {
return typeof canvas === "undefined" ? null : canvas;
}
// The scene whose lighting travels: the one being played. Foundry loads the walls and lights of a scene
// when it draws it, so nothing else of the world's is at hand to send.
function currentScene() {
return foundryCanvas()?.scene ?? game.scenes?.active ?? game.scenes?.current ?? null;
}
// A scene's embedded documents of one kind. Which collection holds them has moved about between Foundry
// versions, so each way is tried, best first, and only documents of the kind asked for are taken.
function sceneDocuments(scene, kind) {
if (!scene) return [];
for (const candidate of [
scene.getEmbeddedCollection?.(kind)?.contents,
scene[kind === "Wall" ? "walls" : "lighting"]?.contents,
scene.embedded?.[kind]?.contents,
scene.embeddedContents,
]) {
if (!Array.isArray(candidate)) continue;
return candidate.filter((document) => document?.documentName === kind);
}
return [];
}
function findSceneDocument(scene, kind, id) {
return sceneDocuments(scene, kind).find((document) => String(document.id) === String(id)) ?? null;
}
// Scene canvas pixels → pixels of the scene's background image at the size it has on disk, which is
// what a Dragonroll map is measured in. `dimensions.sceneRatio` is the scale that image is drawn at.
function sceneImageScale() {
const ratio = Number(foundryCanvas()?.dimensions?.sceneRatio);
return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
}
function toSceneImagePixels(value) {
const number = Number(value);
return Number.isFinite(number) ? Math.round(number / sceneImageScale()) : 0;
}
// How wide one of the scene's cells is, in its image pixels.
function sceneImageGrid(scene) {
const grid = Number(scene?.grid ?? foundryCanvas()?.dimensions?.grid);
return Number.isFinite(grid) && grid > 0 ? Math.round(grid) : 50;
}
function sceneGridDistance(scene) {
const distance = Number(scene?.gridDistance);
return Number.isFinite(distance) && distance > 0 ? distance : 5;
}
// A light's reach, which Foundry measures in the scene's distance units, as pixels of its image: so
// many cells, at the scene's own pixels per cell.
function lightReachToImagePixels(value, scene) {
const reach = Number(value);
if (!Number.isFinite(reach) || reach <= 0) return 0;
return Math.round((reach / sceneGridDistance(scene)) * sceneImageGrid(scene));
}
// A colour of a Foundry light as its document writes it: a hex string, or a number in the versions
// that stored one that way. Empty for a light with no tint of its own.
function sceneLightColor(color) {
if (typeof color === "string") return /^#[0-9a-f]{3,8}$/i.test(color.trim()) ? color.trim().toLowerCase() : "";
if (Number.isFinite(color) && color > 0) return `#${Math.round(color).toString(16).padStart(6, "0")}`;
return "";
}
// Foundry's wall kinds and restrictions: a wall that lets the players see through it lights whatever
// it is drawn over, a wall only sensing shapes what a sensor reaches and lets light through, and a
// door left open lets the light through along with whoever opened it.
const WALL_KIND_SENSES = "sense";
const WALL_MOVEMENT_OPEN = 2;
const WALL_RESTRICTION_BLOCK = 2;
function blocksSceneLight(wall) {
if (String(wall?.wall ?? "walls") === WALL_KIND_SENSES) return false;
if (Number(wall?.move) === WALL_MOVEMENT_OPEN) return false;
return Number(wall?.sight) === WALL_RESTRICTION_BLOCK || Number(wall?.light) === WALL_RESTRICTION_BLOCK;
}
function serializeSceneLight(light, scene) {
const config = light?.config ?? {};
return {
id: String(light.id),
x: toSceneImagePixels(light.x),
y: toSceneImagePixels(light.y),
radius: lightReachToImagePixels(config.dim, scene),
bright: lightReachToImagePixels(config.bright, scene),
color: sceneLightColor(config.color),
};
}
function serializeSceneWall(wall) {
const corner = wall?.c ?? {};
return {
id: String(wall.id),
x1: toSceneImagePixels(corner.x),
y1: toSceneImagePixels(corner.y),
x2: toSceneImagePixels(corner.x2),
y2: toSceneImagePixels(corner.y2),
};
}
function sceneLightingMeta(scene) {
return {
id: scene.id,
title: String(scene.title ?? scene.name ?? ""),
grid: sceneImageGrid(scene),
gridDistance: sceneGridDistance(scene),
image: sceneBackgroundImage(scene),
};
}
// The scene's own artwork, as an address a campaign outside the world can read — the same as every
// other image the module sends (see serializeFoundryActor).
function sceneBackgroundImage(scene) {
const image = scene?.texture?.src ?? scene?.img ?? "";
if (typeof image !== "string" || !image || /^(https?:|data:|\/\/)/i.test(image)) return image || "";
return new URL(image, window.location.origin).toString();
}
// What a scene is lit by, whole. A scene with neither lights nor walls is worth sending for what it
// takes off the campaign; it is the campaign's own business whether that is worth a map of.
function sceneLightingSnapshot(scene) {
const target = scene ?? currentScene();
if (!target) return null;
return {
scene: sceneLightingMeta(target),
lights: sceneDocuments(target, "AmbientLight").map((light) => serializeSceneLight(light, target)),
walls: sceneDocuments(target, "Wall").filter(blocksSceneLight).map(serializeSceneWall),
};
}
async function pushSceneLighting() {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world) return;
const snapshot = sceneLightingSnapshot();
if (!snapshot) return;
await postDragonroll("foundry/sync/scene", { worldId: game.world.id, ...snapshot }, token);
}
function queueSceneLightingChange(delay = 400) {
clearTimeout(sceneLightingTimeout);
sceneLightingTimeout = setTimeout(flushSceneLighting, delay);
}
async function flushSceneLighting() {
// Autosync off: the lighting edits wait with the actor and item ones, so turning it back on sends them.
if (!isAutoSyncEnabled()) return;
try {
await pushSceneLighting();
sceneLightingErrorLogged = false;
} catch (error) {
if (!sceneLightingErrorLogged) {
sceneLightingErrorLogged = true;
console.warn(`${MODULE_ID} | Scene lighting sync failed and will retry.`, error);
}
queueSceneLightingChange(5000);
}
}
// Writing into the world from the campaign is marked the same way every other Dragonroll write is, so
// the world does not echo it straight back to the campaign.
function dragonrollLightId(light) {
return light.getFlag?.(MODULE_ID, "lightId") || light.flags?.[MODULE_ID]?.lightId || "";
}
function isSceneLightingMutation(document) {
return document?.flags?.[MODULE_ID]?.syncMutation === true || syncingLightIds.has(document?.id);
}
async function withLightSyncSuppressed(light, callback) {
if (!light?.id) return callback();
syncingLightIds.add(light.id);
try {
return await callback();
} finally {
syncingLightIds.delete(light.id);
}
}
// How many canvas pixels one pixel of the campaign's map is worth in the scene being written to: cells
// first, then the cell as the world's canvas draws it.
function mapPixelsToSceneCanvas(value, mirror) {
const cell = Number(mirror?.gridSize) || sceneImageGrid(currentScene());
const gridPixels = Number(foundryCanvas()?.dimensions?.gridPixels) || sceneImageGrid(currentScene()) * sceneImageScale();
const number = Number(value);
if (!Number.isFinite(number)) return 0;
return Math.round((number / Math.max(1, cell)) * gridPixels);
}
// A reach of the campaign's map, in its pixels, as so many of the scene's distance units. `scale` is
// how much distance one cell of the map stands for, which is what Foundry measures a light in.
function mapPixelsToSceneDistance(value, mirror) {
const cell = Number(mirror?.gridSize) || sceneImageGrid(currentScene());
const perCell = Number(mirror?.scale) || sceneGridDistance(currentScene());
const number = Number(value);
if (!Number.isFinite(number) || number <= 0) return 0;
return Math.round(((number / Math.max(1, cell)) * perCell * 100)) / 100;
}
function sceneLightUpdateData(entry, mirror) {
return {
x: mapPixelsToSceneCanvas(entry.x, mirror),
y: mapPixelsToSceneCanvas(entry.y, mirror),
"config.dim": mapPixelsToSceneDistance(entry.radius, mirror),
"config.bright": mapPixelsToSceneDistance(entry.bright, mirror),
"config.color": entry.color || null,
};
}
// Whether a light of the world already says what the campaign's light says — within a pixel, and within
// a hundredth of a distance unit. Writing a light that is already where it belongs is how a sync would
// never come to rest: the two sides measure in different units and round differently doing it.
function sceneLightMatches(light, entry, mirror) {
const updates = sceneLightUpdateData(entry, mirror);
const near = (foundry, wanted, tolerance) => Math.abs(Number(foundry ?? 0) - Number(wanted ?? 0)) <= tolerance;
return near(light.x, updates.x, 1)
&& near(light.y, updates.y, 1)
&& near(light.config?.radius?.dim, updates["config.dim"], 0.01)
&& near(light.config?.radius?.bright, updates["config.bright"], 0.01)
&& sceneLightColor(light.config?.color) === String(entry.color ?? "").toLowerCase();
}
async function mapDragonrollSceneLight(mapId, lightId, foundryLightId) {
const token = getSyncToken();
return postDragonroll("foundry/sync/map-scene-light", {
worldId: game.world.id,
map: String(mapId),
light: String(lightId),
foundryLightId: String(foundryLightId),
}, token);
}
function makeSceneLightData(entry, mirror) {
return {
name: String(mirror?.name || "Dragonroll") + " light",
hidden: false,
x: mapPixelsToSceneCanvas(entry.x, mirror),
y: mapPixelsToSceneCanvas(entry.y, mirror),
config: {
alpha: 1,
dim: mapPixelsToSceneDistance(entry.radius, mirror),
bright: mapPixelsToSceneDistance(entry.bright, mirror),
color: entry.color || null,
},
flags: { [MODULE_ID]: { lightId: String(entry._id), syncMutation: true } },
};
}
async function createSceneLightFromDragonroll(scene, entry, mirror) {
const LightDocument = CONFIG.AmbientLight?.documentClass ?? (typeof AmbientLight === "undefined" ? null : AmbientLight);
if (!LightDocument?.create) return null;
const created = await LightDocument.create(makeSceneLightData(entry, mirror), { parent: scene });
const light = Array.isArray(created) ? created[0] : created;
if (!light) return null;
await withLightSyncSuppressed(light, async () => {
await light.update({ [`flags.${MODULE_ID}.syncMutation`]: false });
});
await mapDragonrollSceneLight(mirror._id, entry._id, light.id);
return light;
}
async function applyDragonrollSceneLight(light, entry, mirror) {
const retag = dragonrollLightId(light) !== String(entry._id)
? { [`flags.${MODULE_ID}.lightId`]: String(entry._id) }
: null;
// Already where the campaign says it is: nothing is written, which is what keeps this from
// rewriting the world's lighting every few seconds for the rest of the evening.
if (sceneLightMatches(light, entry, mirror)) {
if (retag) await light.update(retag);
return;
}
await withLightSyncSuppressed(light, async () => {
await light.update(sceneLightUpdateData(entry, mirror));
if (retag) await light.update(retag);
});
}
// Which of the campaign's maps the scene being played mirrors: the one that says it does, failing that
// a map of the same name — the same courtesy the item sync offers a hand-written row, and refused the
// moment two maps of that name leave it a guess.
function sceneMirrorMap(scenes, scene) {
const rows = Array.isArray(scenes) ? scenes : [];
const mapped = rows.find((row) => row.foundrySceneId && String(row.foundrySceneId) === String(scene.id));
if (mapped) return mapped;
const title = String(scene.title ?? scene.name ?? "").trim();
if (!title) return null;
const namesakes = rows.filter((row) => !row.foundrySceneId && String(row.name ?? "").trim() === title);
return namesakes.length === 1 ? namesakes[0] : null;
}
async function reconcileDragonrollSceneLighting() {
const token = getSyncToken();
if (!token || !game.user?.isGM || !game.world || sceneLightingRunning || !isAutoSyncEnabled()) return;
const scene = currentScene();
if (!scene) return;
sceneLightingRunning = true;
try {
const result = await getDragonroll("foundry/sync/scenes", token);
const mirror = sceneMirrorMap(result.scenes, scene);
if (!mirror) return;
const entries = Array.isArray(mirror.lights) ? mirror.lights : [];
const wanted = new Set(entries.map((entry) => String(entry._id)));
const localByRemoteId = new Map(sceneDocuments(scene, "AmbientLight")
.map((light) => [String(dragonrollLightId(light)), light])
.filter(([lightId]) => lightId));
const retained = new Set();
for (const entry of entries) {
let light = entry.foundryLightId ? findSceneDocument(scene, "AmbientLight", entry.foundryLightId) : null;
if (!light) light = localByRemoteId.get(String(entry._id));
if (light) {
retained.add(light.id);
await applyDragonrollSceneLight(light, entry, mirror);
if (!entry.foundryLightId) await mapDragonrollSceneLight(mirror._id, entry._id, light.id);
} else if (entry.foundryLightId) {
// A light of another world's scene, or one the campaign read from a scene that is not this one:
// its own scene owns it, so cloning it here would light the room twice.
continue;
} else {
const created = await createSceneLightFromDragonroll(scene, entry, mirror);
if (created) retained.add(created.id);
}
}
// A light the campaign put out is taken out of the world along with it — only one the world was
// told it wrote, never a lamp the GM lit themselves.
for (const light of sceneDocuments(scene, "AmbientLight")) {
const lightId = dragonrollLightId(light);
if (!lightId || retained.has(light.id) || wanted.has(String(lightId))) continue;
await withLightSyncSuppressed(light, () => light.delete());
}
sceneLightingErrorLogged = false;
} catch (error) {
if (!sceneLightingErrorLogged) {
sceneLightingErrorLogged = true;
console.warn(`${MODULE_ID} | Scene lighting reconcile failed and will retry.`, error);
}
} finally {
sceneLightingRunning = false;
}
}
function getDragonrollImageUrl(image) {
if (!image) return "";
if (/^(https?:|data:|\/\/)/i.test(image)) return image;
@@ -1373,276 +1732,6 @@ 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);
}
}
// --- Note pages ------------------------------------------------------------
// The campaign's notes read like the campaign's journal in the world: every note
// stands as a page of one JournalEntry named "Dragonroll". 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. A page the module made carries the `dragonroll-foundry.noteId`
// flag; one without it that stands under a note's title is claimed as that note's
// page rather than doubled, and any other page is the GM's own and left alone.
const NOTES_JOURNAL_NAME = "Dragonroll";
let noteSyncRunning = false;
let noteSyncErrorLogged = false;
function dragonrollNoteId(page) {
return page.getFlag?.(MODULE_ID, "noteId") || page.flags?.[MODULE_ID]?.noteId || "";
}
// A note is markdown, a journal page is HTML. Foundry's own renderer keeps the
// page readable in the journal and in its styles; where this Foundry does not
// offer one, escaped paragraphs keep the text legible until it does.
function notePageHtml(content) {
const markdown = String(content ?? "");
if (!markdown.trim()) return "";
if (typeof TextEditor !== "undefined" && typeof TextEditor._getMarkdown === "function") {
const html = TextEditor._getMarkdown(markdown);
if (html) return html;
}
return markdown
.split(/\n\s*\n/)
.map((block) => `<p>${escapeNoteHtml(block.trim()).replace(/\n/g, "<br />")}</p>`)
.join("\n");
}
function escapeNoteHtml(value) {
return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
}
function notePageTitle(entry) {
return String(entry.title || "").trim() || "Untitled note";
}
// The journal this module writes the campaign's notes into: the one it flagged as
// its own, or one the GM already made under that name. An unflagged one is
// flagged on use, so renaming it afterwards still leaves the notes' home findable.
function notesJournal() {
const journals = game.journals?.contents || [];
return journals.find((journal) => journal.getFlag?.(MODULE_ID, "notesJournal"))
|| journals.find((journal) => journal.name === NOTES_JOURNAL_NAME)
|| null;
}
async function ensureNotesJournal() {
const existing = notesJournal();
if (existing) {
if (!existing.getFlag?.(MODULE_ID, "notesJournal")) {
await existing.update({ [`flags.${MODULE_ID}.notesJournal`]: true });
}
return existing;
}
const created = await JournalEntry.create(
{ name: NOTES_JOURNAL_NAME, flags: { [MODULE_ID]: { 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 result = await getDragonroll("foundry/sync/notes", token);
const remoteNotes = result.notes || [];
// A campaign without notes gets no journal of its own — but one it once had
// stays, so the pages of notes it deleted can go with them.
if (!remoteNotes.length && !notesJournal()) return;
const journal = await ensureNotesJournal();
if (!journal) return;
const remoteById = new Map(remoteNotes.map((entry) => [String(entry._id), entry]));
const localByRemoteId = new Map((journal.pages?.contents || [])
.map((page) => [String(dragonrollNoteId(page)), page])
.filter(([noteId]) => noteId));
const retainedPageIds = new Set();
for (const entry of remoteNotes) {
let page = entry.foundryPageId ? journal.pages?.get(entry.foundryPageId) : null;
if (!page) page = localByRemoteId.get(String(entry._id));
if (page) {
retainedPageIds.add(page.id);
await applyDragonrollNotePage(page, entry);
if (!entry.foundryPageId) await mapDragonrollNote(entry._id, page.id);
} else {
// A page under the note's title that carries no Dragonroll mark — one the
// module made before the campaign kept its mapping, or one whose flag was
// lost — is claimed as that note's page instead of adding a second page of
// the same name. Like the item sync's same-name adoption, this is what keeps
// a note from being written as a new page on every reconcile.
const sameName = (journal.pages?.contents || []).find((candidate) => (
String(candidate.name ?? "") === notePageTitle(entry)
&& !dragonrollNoteId(candidate)
&& !retainedPageIds.has(candidate.id)
));
if (sameName) {
retainedPageIds.add(sameName.id);
await applyDragonrollNotePage(sameName, entry);
await mapDragonrollNote(entry._id, sameName.id);
} else {
const created = await createDragonrollNotePage(journal, entry);
if (created) {
retainedPageIds.add(created.id);
// The create carries the note's flag, but a world that drops it would leave
// the page unclaimed and the next reconcile would make another: mark it
// again the way the rest of the sync marks its documents.
await applyDragonrollNotePage(created, entry);
await mapDragonrollNote(entry._id, created.id);
}
}
}
}
// Pages whose note the campaign deleted go with it. Only pages this module
// made are its business: an unflagged page is the GM's own.
for (const page of journal.pages?.contents || []) {
const noteId = dragonrollNoteId(page);
if (!noteId || retainedPageIds.has(page.id) || remoteById.has(String(noteId))) continue;
await page.delete();
}
noteSyncErrorLogged = false;
} catch (error) {
reportNoteSyncError(error);
} finally {
noteSyncRunning = false;
}
}
async function publishSnapshot() {
if (!game.user?.isGM || !game.world) return;
if (syncInProgress) {
@@ -1735,19 +1824,17 @@ 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 notes arrive as pages of the world's Dragonroll journal on
// the same rhythm: a note written in the app is on the journal within seconds.
setTimeout(reconcileDragonrollNotes, 3000);
setInterval(reconcileDragonrollNotes, 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);
// The scene being played is lit once its canvas is drawn: send what lights it, and write back the
// lights the campaign has placed on the map mirroring it.
queueSceneLightingChange(3000);
setInterval(reconcileDragonrollSceneLighting, 5000);
for (const event of [
"createActor", "updateActor", "deleteActor",
"createItem", "updateItem", "deleteItem",
"createFolder", "updateFolder", "deleteFolder",
"createAmbientLight", "updateAmbientLight", "deleteAmbientLight",
"createWall", "updateWall", "deleteWall",
]) {
Hooks.on(event, (document) => {
scheduleSnapshotSync();
@@ -1757,6 +1844,13 @@ Hooks.once("ready", () => {
queueFoundryActorChange(isDelete ? "delete" : "upsert", document);
return;
}
// A wall the GM draws or a lamp they move changes how the scene reads, so the whole of its
// lighting goes over. A light Dragonroll has just written into the scene is not the GM's doing.
if (document.documentName === "AmbientLight" || document.documentName === "Wall") {
if (isSceneLightingMutation(document)) return;
queueSceneLightingChange();
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.
@@ -1776,18 +1870,19 @@ 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));
}
// Moving to another scene changes which of the world's lighting the campaign mirrors: what lights the
// new scene is sent, and the lights the campaign placed on its map are written back into it. A canvas
// is not worth reading the moment it is initialised, so both are asked for a little later.
Hooks.on("canvasInit", () => {
if (!game.user?.isGM || !getSyncToken()) return;
queueSceneLightingChange(1200);
setTimeout(reconcileDragonrollSceneLighting, 1500);
});
// 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.
// menu. This works with autosync on and off: it is the one push done on purpose.
Hooks.on("getActorDirectoryEntryContext", (html, options) => {
if (!game.user?.isGM || !getSyncToken()) return;

View File

@@ -22,6 +22,11 @@ $themes: (
note-border: #202324,
// A map's lighting: the dark the lights are carved out of, and the walls that cut them. The map
// canvas reads both off these variables (see components/viewer/map/MapViewerPane.vue).
map-darkness: #000000d9,
map-wall: #e06c75,
hover: #21262d,
selected: #4a4a4b,
border-color: #819796,
@@ -70,6 +75,11 @@ $themes: (
note-border: #e0e0e0,
// Same lighting keys as the dark map; the dark over a map is the dark of a room whichever theme
// the app is drawn in, and its walls are darkened to stay readable over a light image.
map-darkness: #000000d9,
map-wall: #c62828,
border-color: #e0e0e0,
border: #f0f0f0,
hover: #e9e9e9,

View File

@@ -5,6 +5,7 @@ import { ClearWindow, CreateWindow, GetFirstWindowId } from '@/services/Windows'
import { HideContextMenu, ShowContextMenu } from '~/services/ContextMenu';
import { BuildNoteOptions, OptionLabel, ToImagePoint, ToScreenPoint } from '~/services/MapPins';
import { ActorDragId, CellCentre, IsActorDrag, MoveByCells, TokenSize } from '~/services/MapTokens';
import { CastLight, SnapToGridVertex, WallAt } from '~/services/MapLighting';
import { DisplayToast } from '~/services/Toaster';
import Server, { getBaseUrl } from '~/services/Server';
import { emitter } from '~/services/Emitter';
@@ -29,6 +30,15 @@ const zoom = ref(1);
const pan = ref({ x: 0, y: 0 });
const imageSize = ref({ width: 0, height: 0 });
const showGrid = ref(true);
// Lighting over the map: the dark the lights are carved out of. Off by default, so a map reads as the
// picture it is until whoever is running the table asks for the dark.
const showLighting = ref(false);
// Drawing walls instead of panning the map: a wall is dragged from one corner of the grid to another.
const wallMode = ref(false);
// The wall being drawn — the corner it starts at and the one the pointer has reached. It is written
// once, when the pointer lets go, so drawing a wall is not one request per mouse move.
const drawingWall = ref(null);
let wallPointerId = null;
const dragging = ref(false);
const minZoom = 0.05;
@@ -114,6 +124,8 @@ let lastPointer = { x: 0, y: 0 };
function onPointerDown(event) {
if (event.button !== 0 || !viewport.value) return;
// The wall tool takes the pointer for itself: holding the map then draws a wall instead of moving it.
if (wallMode.value && startWallDrag(event)) return;
dragging.value = true;
pointerId = event.pointerId;
lastPointer = { x: event.clientX, y: event.clientY };
@@ -121,12 +133,14 @@ function onPointerDown(event) {
}
function onPointerMove(event) {
if (moveWallDrag(event)) return;
if (!dragging.value || event.pointerId !== pointerId) return;
pan.value = { x: pan.value.x + (event.clientX - lastPointer.x), y: pan.value.y + (event.clientY - lastPointer.y) };
lastPointer = { x: event.clientX, y: event.clientY };
}
function onPointerUp(event) {
async function onPointerUp(event) {
if (await endWallDrag(event)) return;
if (event.pointerId !== pointerId) return;
dragging.value = false;
pointerId = null;
@@ -195,12 +209,10 @@ function onMapContextMenu(event) {
const spot = ToImagePoint({ x: event.clientX - bounds.left, y: event.clientY - bounds.top }, viewState());
if (!spot) return;
if (!noteOptions.value.length) {
ShowContextMenu([{ name: t('campaigns.map.pins.none'), action: () => HideContextMenu() }]);
return;
}
ShowContextMenu([{
const items = [];
if (!noteOptions.value.length) items.push({ name: t('campaigns.map.pins.none'), action: () => HideContextMenu() });
else {
items.push({
name: t('campaigns.map.pins.add'),
icon: '/icons/iconoir/regular/map-pin-plus.svg',
context: noteOptions.value.map((option) => ({
@@ -208,7 +220,26 @@ function onMapContextMenu(event) {
icon: '/icons/iconoir/regular/notes.svg',
action: () => { HideContextMenu(); savePin(option.value, spot); }
}))
}]);
});
}
items.push({ divider: true });
items.push({
name: t('campaigns.map.lights.add'),
icon: '/icons/iconoir/regular/fire-flame.svg',
action: () => { HideContextMenu(); placeLight(spot); }
});
// A wall is a line, not a marker to hold: right clicking along it is how it is taken off again.
const wall = WallAt(spot, walls.value, WALL_PICK_PX / Math.max(0.05, zoom.value));
if (wall) {
items.push({
name: t('campaigns.map.walls.remove'),
icon: '/icons/iconoir/regular/xmark-circle.svg',
action: () => { HideContextMenu(); removeWall(wall); }
});
}
ShowContextMenu(items);
}
function onPinContextMenu(pin) {
@@ -503,6 +534,328 @@ function handleActorEntry({ entityType, entry }) {
actors.value = [entry, ...actors.value.filter((current) => String(current._id) !== String(entry._id))];
}
// --- Lights, and the walls that stop them ---
// A light shines from one spot of the image and is as free to place as a pin. The walls of the map are
// what cuts its reach into a shadow: CastLight works out the shape a light paints and the canvas below
// paints that shape out of the dark laid over the map.
// A new light covers this much of the map it is placed on, and half of that is bright light.
const LIGHT_CELLS = 3;
// How near a line a right click has to come to mean that wall, in screen pixels (it is divided by the
// zoom to become image pixels, so picking a wall is as easy zoomed out as zoomed in).
const WALL_PICK_PX = 10;
const lightingCanvas = ref(null);
const lights = computed(() => map.value?.lights ?? []);
const walls = computed(() => map.value?.walls ?? []);
// The light a pointer is holding, and the spot it holds it at: like a token, the move stays local until
// the pointer lets go, so dragging a light across the map is one save and not one per mouse move.
const movingLight = ref(null);
let lightPointerId = null;
// A colour from the theme the canvas paints with. The canvas cannot be styled with `var(--color-…)`
// like a stylesheet, so it asks the document for the same variable the stylesheets use.
function themeColor(name, fallback) {
if (typeof window === 'undefined' || typeof getComputedStyle !== 'function') return fallback;
return getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback;
}
// A hex colour with an alpha end ('#ffc46b' + '4d'), because a canvas gradient needs its stops spelled
// out. Anything that is not a plain hex colour is painted as it is.
function withAlpha(color, alpha) {
const value = String(color ?? '').trim();
if (/^#[0-9a-f]{6}$/i.test(value)) return `${value}${alpha}`;
if (/^#[0-9a-f]{3}$/i.test(value)) return `#${value.slice(1)}${value.slice(1)}${alpha}`;
return value;
}
// The light a marker is drawn for: the spot it is being held at while a pointer drags it, and its own
// spot otherwise.
function heldLight(light) {
if (movingLight.value && String(movingLight.value.light?._id) === String(light?._id)) return movingLight.value;
return { x: Number(light?.x) || 0, y: Number(light?.y) || 0 };
}
function lightStyle(light) {
const point = ToScreenPoint(heldLight(light), viewState());
return { left: `${point.x}px`, top: `${point.y}px` };
}
// The reach a light is given when it is placed: enough of the map to matter at the grid it stands on.
function defaultLightReach() {
const cell = Math.max(1, Number(map.value?.gridSize) || 50);
const radius = Math.round(cell * LIGHT_CELLS);
return { radius, bright: Math.round(radius / 2) };
}
async function placeLight(spot) {
const reach = defaultLightReach();
await updateMap('/map/place-light', {
id: map.value?._id, x: spot.x, y: spot.y, ...reach
}, t('campaigns.map.lights.error'));
}
async function removeLight(light) {
await updateMap('/map/remove-light', { id: map.value?._id, light: light?._id }, t('campaigns.map.lights.error'));
}
function onLightPointerDown(event, light) {
// Holding a light moves the light, never the map.
event.stopPropagation();
if (event.button !== 0) return;
lightPointerId = event.pointerId;
event.currentTarget.setPointerCapture?.(event.pointerId);
movingLight.value = { light: { ...light }, x: Number(light.x) || 0, y: Number(light.y) || 0 };
}
function onLightPointerMove(event) {
if (!movingLight.value || event.pointerId !== lightPointerId) return;
const spot = imagePointOf(event);
// Dragged off the image, the light keeps its spot: a light is never lost over the edge.
if (!spot) return;
movingLight.value = { ...movingLight.value, x: spot.x, y: spot.y };
}
async function onLightPointerUp(event) {
if (!movingLight.value || event.pointerId !== lightPointerId) return;
const { light, x, y } = movingLight.value;
lightPointerId = null;
movingLight.value = null;
event.currentTarget?.releasePointerCapture?.(event.pointerId);
if (x === Number(light.x) && y === Number(light.y)) return;
await updateMap('/map/update-light', { id: map.value?._id, light: light._id, x, y }, t('campaigns.map.lights.error'));
}
function onLightContextMenu(light) {
ShowContextMenu([{
name: t('campaigns.map.lights.remove'),
icon: '/icons/iconoir/regular/xmark-circle.svg',
action: () => { HideContextMenu(); removeLight(light); }
}]);
}
// Delete takes a focused light off the map, like it does a focused token.
async function onLightKeydown(event, light) {
if (event.key === 'Delete' || event.key === 'Backspace') {
event.preventDefault();
await removeLight(light);
}
}
// --- Drawing walls ---
// With the wall tool on, the pointer draws instead of panning: it is held down at one corner of the
// grid and let go at another, and the wall between those two corners is what gets saved.
// Holds down the first corner of a wall, or says the wall tool has nothing to hold (off the image).
function startWallDrag(event) {
const spot = imagePointOf(event);
if (!spot) return false;
const corner = SnapToGridVertex(spot, grid.value);
if (!corner) return false;
wallPointerId = event.pointerId;
viewport.value?.setPointerCapture?.(event.pointerId);
drawingWall.value = { x1: corner.x, y1: corner.y, x2: corner.x, y2: corner.y };
return true;
}
function moveWallDrag(event) {
if (!drawingWall.value || event.pointerId !== wallPointerId) return false;
const spot = imagePointOf(event);
// Off the image the wall keeps the end it had: a wall cannot hang outside of the map.
if (!spot) return true;
const corner = SnapToGridVertex(spot, grid.value);
if (!corner) return true;
if (corner.x === drawingWall.value.x2 && corner.y === drawingWall.value.y2) return true;
drawingWall.value = { ...drawingWall.value, x2: corner.x, y2: corner.y };
return true;
}
async function endWallDrag(event) {
if (!drawingWall.value || event.pointerId !== wallPointerId) return false;
const wall = drawingWall.value;
wallPointerId = null;
drawingWall.value = null;
viewport.value?.releasePointerCapture?.(event.pointerId);
// Dragged out and back to the same corner is not a wall: it stops nothing and cannot be picked
// up again, so it is dropped where it was drawn.
if (wall.x1 === wall.x2 && wall.y1 === wall.y2) return true;
await saveWall(wall);
return true;
}
async function saveWall(wall) {
await updateMap('/map/wall', { id: map.value?._id, ...wall }, t('campaigns.map.walls.error'));
}
async function removeWall(wall) {
await updateMap('/map/remove-wall', { id: map.value?._id, wall: wall?._id }, t('campaigns.map.walls.error'));
}
// --- Painting the lights ---
// One canvas over the map, drawn in screen pixels like the pins and the tokens, and repainted whenever
// the view or the map changes. With the lighting on it lays the dark over the image and erases the shape
// of every light out of it, so what is left dark is exactly what its walls hide. With the lighting off
// the same shapes are drawn as thin outlines, which is what makes reaching for a light's size possible
// while it is still being placed.
function imageScreenRect() {
const origin = ToScreenPoint({ x: 0, y: 0 }, viewState());
return {
x: origin.x,
y: origin.y,
width: imageSize.value.width * zoom.value,
height: imageSize.value.height * zoom.value
};
}
function tracePolygon(context, points, view) {
context.beginPath();
points.forEach((point, index) => {
const screen = ToScreenPoint(point, view);
if (index) context.lineTo(screen.x, screen.y);
else context.moveTo(screen.x, screen.y);
});
context.closePath();
}
function paintDarkness(context, image) {
const view = viewState();
context.save();
context.fillStyle = themeColor('--color-map-darkness', '#000000d9');
context.fillRect(image.x, image.y, image.width, image.height);
// The lights erase the dark they stand in: only how much a gradient is transparent matters here, so
// a light fades from fully lit at its middle to nothing at the end of its reach.
context.globalCompositeOperation = 'destination-out';
for (const light of lights.value) {
const shape = CastLight(light, walls.value);
if (!shape.length) continue;
const centre = ToScreenPoint(heldLight(light), view);
const reach = Math.max(1, (Number(light.radius) || 0) * zoom.value);
const core = Math.max(0, Math.min(1, (Number(light.bright) || 0) / (Number(light.radius) || 1)));
context.save();
tracePolygon(context, shape, view);
context.clip();
const gradient = context.createRadialGradient(centre.x, centre.y, 0, centre.x, centre.y, reach);
gradient.addColorStop(0, '#000000ff');
gradient.addColorStop(core, '#000000f5');
gradient.addColorStop(1, '#00000000');
context.fillStyle = gradient;
context.fillRect(image.x, image.y, image.width, image.height);
context.restore();
}
// The tint of a coloured light, laid back over the light it colours: a lantern reads warm and a
// spell cold, and a light with no colour of its own leaves the map as it is.
context.globalCompositeOperation = 'source-over';
for (const light of lights.value) {
if (!light.color) continue;
const shape = CastLight(light, walls.value);
if (!shape.length) continue;
const centre = ToScreenPoint(heldLight(light), view);
const reach = Math.max(1, (Number(light.radius) || 0) * zoom.value);
context.save();
tracePolygon(context, shape, view);
context.clip();
const gradient = context.createRadialGradient(centre.x, centre.y, 0, centre.x, centre.y, reach);
gradient.addColorStop(0, withAlpha(light.color, '33'));
gradient.addColorStop(1, withAlpha(light.color, '00'));
context.fillStyle = gradient;
context.fillRect(image.x, image.y, image.width, image.height);
context.restore();
}
context.restore();
}
function paintLightOutlines(context) {
const view = viewState();
context.save();
context.lineWidth = 1;
for (const light of lights.value) {
const shape = CastLight(light, walls.value);
if (!shape.length) continue;
tracePolygon(context, shape, view);
context.strokeStyle = withAlpha(light.color || '#ffffff', '59');
context.stroke();
}
context.restore();
}
function paintWalls(context) {
if (!walls.value.length && !drawingWall.value) return;
const view = viewState();
context.save();
context.lineCap = 'round';
context.strokeStyle = themeColor('--color-map-wall', '#e06c75');
// The wall tool asks for a firmer line: it is the tool that has to see what it has drawn already.
context.lineWidth = wallMode.value ? 3 : 2;
for (const wall of walls.value) {
const from = ToScreenPoint({ x: Number(wall.x1) || 0, y: Number(wall.y1) || 0 }, view);
const to = ToScreenPoint({ x: Number(wall.x2) || 0, y: Number(wall.y2) || 0 }, view);
context.beginPath();
context.moveTo(from.x, from.y);
context.lineTo(to.x, to.y);
context.stroke();
}
// The wall being drawn, along the grid corners the pointer has reached so far.
if (drawingWall.value) {
context.setLineDash([6, 4]);
const from = ToScreenPoint({ x: drawingWall.value.x1, y: drawingWall.value.y1 }, view);
const to = ToScreenPoint({ x: drawingWall.value.x2, y: drawingWall.value.y2 }, view);
context.beginPath();
context.moveTo(from.x, from.y);
context.lineTo(to.x, to.y);
context.stroke();
}
context.restore();
}
function drawLighting() {
const canvas = lightingCanvas.value;
const bounds = viewport.value?.getBoundingClientRect();
if (!canvas || !bounds) return;
const width = Math.max(1, Math.round(bounds.width));
const height = Math.max(1, Math.round(bounds.height));
if (canvas.width !== width) canvas.width = width;
if (canvas.height !== height) canvas.height = height;
const context = canvas.getContext?.('2d');
if (!context) return;
context.clearRect(0, 0, width, height);
if (!imageUrl.value) return;
if (showLighting.value) paintDarkness(context, imageScreenRect());
else paintLightOutlines(context);
paintWalls(context);
}
// Every move of the view, and every light or wall that changes, is painted again.
watch(
[zoom, pan, imageSize, showLighting, wallMode, drawingWall, lights, walls, imageUrl],
() => nextTick(drawLighting),
{ deep: true }
);
onMounted(() => {
window.addEventListener('resize', drawLighting);
nextTick(drawLighting);
});
onBeforeUnmount(() => {
window.removeEventListener('resize', drawLighting);
});
// A different map was anchored while this pane was already mounted.
watch(() => props.map, (incoming, previous) => {
if (incoming === previous) return;
@@ -510,6 +863,9 @@ watch(() => props.map, (incoming, previous) => {
imageSize.value = { width: 0, height: 0 };
movingToken.value = null;
draggingActor.value = false;
movingLight.value = null;
drawingWall.value = null;
wallPointerId = null;
});
watch(campaignId, () => {
@@ -550,6 +906,14 @@ onBeforeUnmount(() => {
:aria-label="$t('campaigns.map.toggle-grid')" :aria-pressed="showGrid.toString()" @click="showGrid = !showGrid">
<img class="tool-icon" src="/icons/iconoir/regular/view-grid.svg" alt="" aria-hidden="true">
</button>
<button class="viewer-tool" :class="{ selected: showLighting }" type="button" :title="$t('campaigns.map.toggle-lighting')"
:aria-label="$t('campaigns.map.toggle-lighting')" :aria-pressed="showLighting.toString()" @click="showLighting = !showLighting">
<img class="tool-icon" src="/icons/iconoir/regular/light-bulb-on.svg" alt="" aria-hidden="true">
</button>
<button class="viewer-tool" :class="{ selected: wallMode }" type="button" :title="$t('campaigns.map.toggle-walls')"
:aria-label="$t('campaigns.map.toggle-walls')" :aria-pressed="wallMode.toString()" @click="wallMode = !wallMode">
<img class="tool-icon" src="/icons/iconoir/regular/linear.svg" alt="" aria-hidden="true">
</button>
<button class="viewer-tool" type="button" :title="$t('campaigns.map.zoom-out')" :aria-label="$t('campaigns.map.zoom-out')" @click="zoomFromToolbar(false)">
<img class="tool-icon" src="/icons/iconoir/regular/minus.svg" alt="" aria-hidden="true">
</button>
@@ -573,7 +937,7 @@ onBeforeUnmount(() => {
<div
ref="viewport"
class="map-viewport"
:class="{ dragging }"
:class="{ dragging, 'wall-mode': wallMode }"
@wheel.prevent="onWheel"
@pointerdown="onPointerDown"
@pointermove="onPointerMove"
@@ -587,6 +951,28 @@ onBeforeUnmount(() => {
<template v-if="imageUrl">
<img class="map-image" :src="imageUrl" :style="stageStyle" :alt="map?.name" draggable="false" @load="onImageLoaded">
<div class="map-grid" :style="gridStyle" aria-hidden="true"></div>
<canvas ref="lightingCanvas" class="map-lighting" aria-hidden="true"></canvas>
<div class="map-lights">
<button
v-for="light in lights"
:key="light._id"
class="map-light"
:class="{ moving: movingLight && String(movingLight.light?._id) === String(light._id) }"
type="button"
:style="lightStyle(light)"
:title="$t('campaigns.map.lights.light')"
:aria-label="$t('campaigns.map.lights.light')"
draggable="false"
@pointerdown="onLightPointerDown($event, light)"
@pointermove="onLightPointerMove"
@pointerup="onLightPointerUp"
@pointercancel="onLightPointerUp"
@contextmenu.stop.prevent="onLightContextMenu(light)"
@keydown="onLightKeydown($event, light)"
>
<img class="light-icon" src="/icons/iconoir/regular/fire-flame.svg" alt="" aria-hidden="true">
</button>
</div>
<div class="map-pins">
<button
v-for="pin in pins"
@@ -629,6 +1015,7 @@ onBeforeUnmount(() => {
</button>
</div>
<div v-if="draggingActor" class="map-drop-hint">{{ $t('campaigns.map.tokens.drop-hint') }}</div>
<div v-if="wallMode" class="map-drop-hint">{{ $t('campaigns.map.walls.hint') }}</div>
</template>
<div v-else class="map-empty">
{{ $t('campaigns.map.no-image') }}
@@ -654,6 +1041,23 @@ onBeforeUnmount(() => {
.map-viewport.dragging { cursor: grabbing; }
.map-image { position: absolute; top: 0; left: 0; max-width: none; transform-origin: top left; user-select: none; }
.map-grid { position: absolute; top: 0; left: 0; opacity: .55; pointer-events: none; }
.map-viewport.wall-mode { cursor: crosshair; }
/* The lights are painted on a canvas over the image and in screen space, like the pins: the dark over
the map and the shape each light cuts in it are redrawn whenever the view moves (see drawLighting).
The canvas never catches the mouse; the light markers below do that. */
.map-lighting { position: absolute; top: 0; left: 0; pointer-events: none; }
.map-lights { position: absolute; inset: 0; pointer-events: none; }
.map-light {
position: absolute; transform: translate(-50%, -50%); pointer-events: auto;
display: flex; align-items: center; justify-content: center; width: 26px; height: 26px;
margin: 0; padding: 0; border: 1px solid var(--color-link); border-radius: 50%;
background: var(--color-background-soft); color: var(--color-text);
cursor: grab; user-select: none; box-shadow: 0px 0px 6px -1px rgba(0,0,0,0.55);
}
.map-light:hover { background: var(--color-button-hover); }
.map-light:focus-visible { outline: 1px solid var(--color-link); outline-offset: 2px; }
.map-light.moving { cursor: grabbing; }
.light-icon { width: 14px; height: 14px; filter: invert(var(--color-icon-invert)); }
/* Pins live in image pixels but are drawn in screen space (see ToScreenPoint), so the overlay stays
unscaled and their markers are readable at every zoom. Only the markers catch the mouse. */
.map-pins { position: absolute; inset: 0; pointer-events: none; }

View File

@@ -49,18 +49,3 @@ the actor it stands for, and **Enter** does the same on a token focused with the
Tokens belong to the map, not to the actor: the same character can stand on several maps, and taking a
token off does not remove the character from the campaign.
## Maps from a linked Foundry world
With a Foundry world linked to the campaign, its scenes arrive as maps of their own: each one with the
scene's background picture and the grid laid over it, in the scene's own cell size and where the world
shifts that grid onto the picture. That is all a scene lends a map — what one of your cells stands
for, the folder a map stands in, and whatever you pin or stand on it stay yours, and nothing about a
map goes back to the world.
A scene renamed in Foundry, or its grid moved, updates its map. Take the background picture off a
scene and its map keeps the one it has; delete the scene and its map goes with it the next time the
world sends its whole scene list, which is when the world loads. For the same reason a map you delete
in the campaign comes back on the next world load while its scene is still there — take the scene off
in Foundry to be rid of the map. A map you made yourself is never doubled by the scene of it: a scene
arriving with the name of an unmapped map adopts that one. See [Foundry VTT](/docs/foundry).

View File

@@ -1,8 +1,8 @@
# Foundry VTT
The Foundry integration keeps a Dragonroll campaign and a Foundry world in step: the world's
characters, item directory and scenes arrive in the campaign, and what you change in Dragonroll of
those characters and items goes back to the world.
characters and item directory arrive in the campaign, and what you change in Dragonroll goes back to
the world.
There are two separate parts, and you only need the first of them:
@@ -51,23 +51,12 @@ Worth knowing:
| The world's **item directory** (the items tab) | The campaign's item list, with category, rarity, quantity, weight, properties and description |
| The folders grouping that item directory | Item folders with the same names and nesting |
| A folder's colour | The campaign's folder colour — and the other way round, what you colour in Dragonroll lands on the world's folder |
| The world's **scenes** | The campaign's maps: the scene's background picture and the grid laid over it, in the scene's own cell size |
| A journal called **Dragonroll** — one page per note | Your campaign's notes. They arrive **from** Dragonroll: what you write in the journal does not go back |
The item list is the world's item directory and nothing else. The gear a character carries is that
character's inventory: it travels with the character and stays on its sheet, so a sword a fighter owns
does not turn up in the campaign's item list. Spells, classes, subclasses, backgrounds, feats and
species are not gear and are not imported.
The world's scenes are the campaign's maps, and only their **background picture** and their **grid**
cross over: a map arrives with the scene's picture and its cell size, and with the grid where the
world shifts it. That is where the two stop — what one of your cells stands for, the folder a map
stands in, the notes pinned onto it and the characters standing on it as tokens stay in the campaign,
and nothing about a map is written back into the world. The scene list goes over when the world links
and when it loads, which is also when the map of a scene the GM deleted goes with it; scenes changed
afterwards arrive as they happen. A scene with no background picture makes no map, and the full list
leaves a map the campaign already had alone, so a grid you lined up yourself survives a reload.
An actor or item keeps the Dragonroll id it was given in a `dragonroll-foundry.actorId` /
`dragonroll-foundry.itemId` flag, and that is what makes the two sides recognise each other. A world
item that carries no flag is matched by name, so a hand-written item in Dragonroll is adopted instead of
@@ -78,13 +67,6 @@ few seconds. A **full** snapshot — the one taken when the world links, or forc
directory — is the only thing that prunes: it is the only moment either side can see the whole list and
notice what is gone. Live edits never delete anything.
Notes are the exception that runs one way, because notes are written in Dragonroll: every note stands
as a page of a single journal called **Dragonroll**. A note you make or edit in the app appears on that
journal within a few seconds, and deleting one takes its page with it. A page that stands under a note's
title but carries no Dragonroll mark is claimed as that note's page, so a pairing that was lost does not
double it. Any other page — one the GM made in that journal themselves — is left alone, and nothing
written in the journal travels back to the campaign.
## Auto-sync, and sending one actor on purpose
**Dragonroll Auto-sync** is what keeps the two in step: actors and world items you create, change or

View File

@@ -0,0 +1,200 @@
// The rules behind the lights of a map (place a light, draw the walls that stop it, know which wall a
// click landed on). Like the pins and the tokens, a light is stored in image pixels, so these helpers
// only work out geometry: they hold no state and talk to no API.
//
// The shadow of a light is the standard visibility polygon: rays are aimed at every corner of every
// wall (just past it, so a corner never leaves a slit open) and at the midpoints between them, and each
// ray stops at the first wall it meets or at the reach of the light. Joining where those rays end gives
// the shape the light paints, walls cutting it wherever they stand.
// Aiming a hair to either side of a wall corner, so the ray passes it instead of landing on it.
const RAY_EPSILON = 0.0001;
// How finely an open arc is drawn where no wall corner asks for a ray of its own (about 7.5°).
const MAX_ARC_STEP = Math.PI / 24;
// A wall touching the light itself does not hide it, and a ray that close has nothing to say.
const MIN_HIT = 1e-6;
// The walls of a map as plain segments: only the ones with two real ends count, and a light is not
// asked to block anything it is standing on.
function ToWallSegments(walls) {
return (walls ?? [])
.map((wall) => ({
x1: Number(wall?.x1),
y1: Number(wall?.y1),
x2: Number(wall?.x2),
y2: Number(wall?.y2)
}))
.filter((wall) => [wall.x1, wall.y1, wall.x2, wall.y2].every(Number.isFinite)
&& (wall.x1 !== wall.x2 || wall.y1 !== wall.y2));
}
// The corner of the grid a point of the image is closest to, in image pixels: this is where a wall end
// is kept, so a wall runs along the lines of the grid it was drawn on. The backend snaps the same way,
// so a wall does not move when the line that drew it is saved.
function SnapToGridVertex(point, grid) {
const size = Math.max(1, Number(grid?.gridSize) || 50);
const offsetX = Number(grid?.offsetX) || 0;
const offsetY = Number(grid?.offsetY) || 0;
const x = Number(point?.x);
const y = Number(point?.y);
if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
// Spots off the top left corner count from the corner itself, and only whole pixels count: both
// the way the route reads a coordinate, like the cells a token stands in.
const column = Math.round((Math.max(0, Math.round(x)) - offsetX) / size);
const row = Math.round((Math.max(0, Math.round(y)) - offsetY) / size);
return {
x: Math.max(0, Math.round(offsetX + column * size)),
y: Math.max(0, Math.round(offsetY + row * size))
};
}
// Wrapping an angle into [-PI, PI), so the rays of a light are counted once round and not twice.
function NormalizeAngle(angle) {
const full = Math.PI * 2;
let wrapped = angle % full;
if (wrapped >= Math.PI) wrapped -= full;
if (wrapped < -Math.PI) wrapped += full;
return wrapped;
}
// The directions to aim a ray: every wall corner from the light, a hair either side, and enough
// midpoints between them that the lit arc stays round instead of turning into a star.
function RayAngles(centre, segments) {
const angles = [];
for (const segment of segments) {
for (const corner of [{ x: segment.x1, y: segment.y1 }, { x: segment.x2, y: segment.y2 }]) {
const angle = Math.atan2(corner.y - centre.y, corner.x - centre.x);
if (!Number.isFinite(angle)) continue;
angles.push(NormalizeAngle(angle - RAY_EPSILON), NormalizeAngle(angle), NormalizeAngle(angle + RAY_EPSILON));
}
}
if (!angles.length) return EvenAngles();
// Two corners in a line from the light ask for the same ray: keep it once.
angles.sort((a, b) => a - b);
const ordered = [];
for (const angle of angles) {
if (ordered.length && angle - ordered[ordered.length - 1] < RAY_EPSILON) continue;
ordered.push(angle);
}
// The first and the last angle can be the same ray seen across the wrap round.
if (ordered.length > 1 && (ordered[0] + Math.PI * 2) - ordered[ordered.length - 1] < RAY_EPSILON) ordered.pop();
const rays = [];
for (let index = 0; index < ordered.length; index += 1) {
const current = ordered[index];
// The last angle wraps round to the first: a light shines the whole way round.
const next = index + 1 < ordered.length ? ordered[index + 1] : ordered[0] + Math.PI * 2;
rays.push(current);
const steps = Math.max(1, Math.ceil((next - current) / MAX_ARC_STEP));
for (let step = 1; step < steps; step += 1) rays.push(NormalizeAngle(current + ((next - current) * step) / steps));
}
return rays;
}
// A light with no walls in sight still has an edge, so it is drawn as a circle of as many rays as an
// open arc is cut into.
function EvenAngles() {
const angles = [];
const steps = Math.ceil((Math.PI * 2) / MAX_ARC_STEP);
for (let step = 0; step < steps; step += 1) angles.push(NormalizeAngle((Math.PI * 2) * (step / steps)));
return angles;
}
// How far along the ray from `centre` (aimed at unit direction `dx`/`dy`) a segment stands, or null
// when the ray misses it. Parallel rays miss, and so does a segment behind the light.
function RaySegmentDistance(centre, dx, dy, segment) {
const bx = segment.x2 - segment.x1;
const by = segment.y2 - segment.y1;
const cross = dx * by - dy * bx;
if (Math.abs(cross) < 1e-12) return null;
const ax = segment.x1 - centre.x;
const ay = segment.y1 - centre.y;
const along = (ax * by - ay * bx) / cross;
const across = (ax * dy - ay * dx) / cross;
if (along <= MIN_HIT || across < 0 || across > 1) return null;
return along;
}
// The first wall a ray runs into, or Infinity when it reaches into the open.
function RayDistance(centre, angle, segments) {
const dx = Math.cos(angle);
const dy = Math.sin(angle);
let nearest = Infinity;
for (const segment of segments) {
const hit = RaySegmentDistance(centre, dx, dy, segment);
if (hit !== null && hit < nearest) nearest = hit;
}
return nearest;
}
// The shape a light paints, in image pixels: the points of its visibility polygon, aimed round from
// the light itself. Nothing is lit where a wall stands between it and the light, and a light that
// cannot be placed lights nothing at all.
function CastLight(light, walls) {
const centre = { x: Number(light?.x), y: Number(light?.y) };
const radius = Number(light?.radius);
if (!Number.isFinite(centre.x) || !Number.isFinite(centre.y) || !Number.isFinite(radius) || radius <= 0) return [];
const segments = ToWallSegments(walls);
const points = [];
for (const angle of RayAngles(centre, segments)) {
const reached = Math.min(radius, RayDistance(centre, angle, segments));
// A wall crossing the light itself leaves that ray with no lit pixel of its own to end on.
if (reached <= MIN_HIT) continue;
points.push({
x: centre.x + Math.cos(angle) * reached,
y: centre.y + Math.sin(angle) * reached
});
}
return points;
}
// How far a point of the image stands from a wall, in image pixels.
function DistanceToWall(point, wall) {
const x = Number(point?.x);
const y = Number(point?.y);
const x1 = Number(wall?.x1);
const y1 = Number(wall?.y1);
const x2 = Number(wall?.x2);
const y2 = Number(wall?.y2);
if (![x, y, x1, y1, x2, y2].every(Number.isFinite)) return Infinity;
const bx = x2 - x1;
const by = y2 - y1;
const length = bx * bx + by * by;
if (!length) return Math.hypot(x - x1, y - y1);
// The closest point of the segment is the perpendicular foot, held inside its own ends.
const along = Math.max(0, Math.min(1, ((x - x1) * bx + (y - y1) * by) / length));
return Math.hypot(x - (x1 + bx * along), y - (y1 + by * along));
}
// The wall a point is standing on — the one nearest to it within `tolerance` image pixels, or null
// when there is no wall there. This is what lets a right click pick the wall it meant.
function WallAt(point, walls, tolerance) {
const limit = Number(tolerance);
if (!Number.isFinite(limit)) return null;
let nearest = null;
let nearestDistance = Math.max(0, limit);
for (const wall of walls ?? []) {
const distance = DistanceToWall(point, wall);
if (distance > nearestDistance) continue;
nearest = wall;
nearestDistance = distance;
}
return nearest;
}
export {
CastLight,
DistanceToWall,
NormalizeAngle,
SnapToGridVertex,
ToWallSegments,
WallAt
};

View File

@@ -99,6 +99,7 @@
"save-error": "No s'ha pogut desar aquest mapa.",
"no-image": "Aquest mapa encara no té imatge.",
"zoom-in": "Apropar", "zoom-out": "Allunyar", "fit": "Ajustar a la finestra", "toggle-grid": "Mostrar la quadrícula",
"toggle-lighting": "Mostrar la il·luminació", "toggle-walls": "Dibuixar murs",
"open-window": "Obre en una finestra", "anchored": "Ancorat",
"pins": {
"add": "Fixa una nota aquí", "none": "Encara no hi ha notes per fixar",
@@ -111,6 +112,15 @@
"drop-hint": "Deixa anar per posar l'actor en aquest mapa",
"open": "Obre la fitxa de personatge", "remove": "Treu la fitxa",
"error": "No s'han pogut canviar les fitxes d'aquest mapa."
},
"lights": {
"light": "Llum", "add": "Afegeix una llum aquí", "remove": "Treu la llum",
"error": "No s'han pogut canviar les llums d'aquest mapa."
},
"walls": {
"remove": "Treu el mur d'aquí",
"hint": "Arrossega d'una cantonada de la quadrícula a l'altra per dibuixar un mur",
"error": "No s'han pogut canviar els murs d'aquest mapa."
}
},
"character-sheet": {

View File

@@ -103,6 +103,7 @@
"save-error": "Unable to save this map.",
"no-image": "This map has no image yet.",
"zoom-in": "Zoom in", "zoom-out": "Zoom out", "fit": "Fit to window", "toggle-grid": "Show grid",
"toggle-lighting": "Show lighting", "toggle-walls": "Draw walls",
"open-window": "Open in window", "anchored": "Anchored",
"pins": {
"add": "Pin a note here", "none": "No notes to pin yet",
@@ -115,6 +116,15 @@
"drop-hint": "Drop to place the actor on this map",
"open": "Open character sheet", "remove": "Remove token",
"error": "Unable to change the tokens of this map."
},
"lights": {
"light": "Light", "add": "Add light here", "remove": "Remove light",
"error": "Unable to change the lights of this map."
},
"walls": {
"remove": "Remove wall here",
"hint": "Drag from one corner of the grid to another to draw a wall",
"error": "Unable to change the walls of this map."
}
},
"character-sheet": {

View File

@@ -99,6 +99,7 @@
"save-error": "No se pudo guardar este mapa.",
"no-image": "Este mapa aún no tiene imagen.",
"zoom-in": "Acercar", "zoom-out": "Alejar", "fit": "Ajustar a la ventana", "toggle-grid": "Mostrar cuadrícula",
"toggle-lighting": "Mostrar iluminación", "toggle-walls": "Dibujar muros",
"open-window": "Abrir en una ventana", "anchored": "Anclado",
"pins": {
"add": "Fija una nota aquí", "none": "Aún no hay notas que fijar",
@@ -111,6 +112,15 @@
"drop-hint": "Suelta para colocar al actor en este mapa",
"open": "Abrir hoja de personaje", "remove": "Quitar la ficha",
"error": "No se pudieron cambiar las fichas de este mapa."
},
"lights": {
"light": "Luz", "add": "Añadir luz aquí", "remove": "Quitar la luz",
"error": "No se pudieron cambiar las luces de este mapa."
},
"walls": {
"remove": "Quitar el muro de aquí",
"hint": "Arrastra de una esquina de la cuadrícula a otra para dibujar un muro",
"error": "No se pudieron cambiar los muros de este mapa."
}
},
"character-sheet": {

View File

@@ -410,36 +410,6 @@ test("an actor that holds no traits does not clear what the campaign has", () =>
assert.ok(!("traits" in character), "a live edit that knows nothing about traits leaves the tab as it is");
});
// A forced actor sync from the module's context menu replaces everything the campaign
// holds for that actor (Syndria98/dragonroll#96): the fields a live edit leaves out when
// the world says nothing are written empty instead of kept, and the campaign's own text
// on the actor's flag does not survive it.
test("a forced sync writes empty the fields a live edit would leave out", () => {
const actor = {
name: "Thalia",
system: {},
items: [],
flags: { [MODULE_ID]: { traits: "What the campaign typed", proficiencies: "Armour, tools" } },
};
const live = foundryActorToCharacter(actor);
assert.equal(live.traits, "What the campaign typed", "a live edit fills the traits tab from the actor's flag");
assert.equal(live.proficiencies, "Armour, tools", "and the free-text proficiencies from it too");
assert.ok(
!("tools" in live) && !("languages" in live) && !("skills" in live) && !("savingThrows" in live) && !("currency" in live),
"and says nothing about the toggles and lists the world has no data for"
);
const replaced = foundryActorToCharacter(actor, true);
assert.equal(replaced.traits, "", "a forced sync clears the traits the campaign typed");
assert.equal(replaced.proficiencies, "", "down to the free-text proficiencies");
assert.deepEqual(replaced.tools, []);
assert.deepEqual(replaced.languages, []);
assert.deepEqual(replaced.skills, {});
assert.deepEqual(replaced.savingThrows, {});
assert.deepEqual(replaced.currency, {});
});
// --- The module sends the names a sheet outside Foundry can read -----------------
function makeWorld({ actor, config = {}, worldItems = [] }) {

View File

@@ -133,8 +133,6 @@ function loadFoundryWriters({ seed = {}, settings } = {}) {
"../models/Actor": fakeModel("actor", seeded(seed.actors)),
"../models/Item": fakeModel("item", seeded(seed.items)),
"../models/Folder": fakeModel("folder", seeded(seed.folders)),
"../models/Note": fakeModel("note", seeded(seed.notes)),
"../models/Map": fakeModel("map", seeded(seed.maps)),
};
const requireStub = (id) => {
@@ -145,7 +143,8 @@ function loadFoundryWriters({ seed = {}, settings } = {}) {
if (id === "../services/actor-foundry") return repoRequire(path.join("backend", "src", "services", "actor-foundry.js"));
if (id === "../services/item-foundry") return repoRequire(path.join("backend", "src", "services", "item-foundry.js"));
if (id === "../services/foundry-icons") return repoRequire(path.join("backend", "src", "services", "foundry-icons.js"));
if (id === "../services/map-foundry") return repoRequire(path.join("backend", "src", "services", "map-foundry.js"));
// The Map model is only there for the scene lighting sync, which these tests do not run.
if (id === "../models/Map") return { find: () => mongooseQuery([]), findOne: async () => null };
if (models[id]) return models[id];
throw new Error(`require("${id}") is not stubbed`);
};

View File

@@ -271,8 +271,6 @@ function loadFoundryWriters({ seed = {} } = {}) {
"../models/Actor": fakeModel("actor", seeded(seed.actors)),
"../models/Item": fakeModel("item", seeded(seed.items)),
"../models/Folder": fakeModel("folder", seeded(seed.folders)),
"../models/Note": fakeModel("note", seeded(seed.notes)),
"../models/Map": fakeModel("map", seeded(seed.maps)),
};
const requireStub = (id) => {
@@ -283,7 +281,8 @@ function loadFoundryWriters({ seed = {} } = {}) {
if (id === "../services/actor-foundry") return repoRequire(path.join("backend", "src", "services", "actor-foundry.js"));
if (id === "../services/item-foundry") return repoRequire(path.join("backend", "src", "services", "item-foundry.js"));
if (id === "../services/foundry-icons") return repoRequire(path.join("backend", "src", "services", "foundry-icons.js"));
if (id === "../services/map-foundry") return repoRequire(path.join("backend", "src", "services", "map-foundry.js"));
// The Map model is only there for the scene lighting sync, which these tests do not run.
if (id === "../models/Map") return { find: () => mongooseQuery([]), findOne: async () => null };
if (models[id]) return models[id];
throw new Error(`require("${id}") is not stubbed`);
};
@@ -331,46 +330,6 @@ test("an actor the world has never been seen as becomes one row, and the next im
assert.equal(sync.models["../models/Actor"].rows[0].foundryActorId, "actor-9");
});
// A forced sync from the module's context menu (Syndria98/dragonroll#96) replaces
// everything the campaign holds for the actor; a live change is a merge and leaves the
// fields the world says nothing about to the campaign.
test("a forced actor sync clears what the campaign wrote; a live change keeps it", async () => {
const sync = loadFoundryWriters({
seed: { actors: [{
_id: "actor-1",
name: "Thalia",
foundryActorId: "actor-1",
traits: "A trait the campaign wrote",
tools: ["Thieves' tools"],
languages: ["Elvish"],
skills: { perception: true },
savingThrows: { dex: true },
currency: { gp: 50 },
}] },
});
// The world says nothing about any of those: the fields a live edit leaves out.
const worldActor = { _id: "actor-1", name: "Thalia", type: "character", system: {} };
await sync.writers.saveFoundryActor(sync.campaign, worldActor, false, false);
let row = sync.models["../models/Actor"].rows[0];
assert.equal(row.traits, "A trait the campaign wrote", "a live push leaves what the campaign wrote alone");
assert.deepEqual(row.tools, ["Thieves' tools"]);
assert.deepEqual(row.languages, ["Elvish"]);
assert.deepEqual(row.skills, { perception: true });
assert.deepEqual(row.savingThrows, { dex: true });
assert.deepEqual(row.currency, { gp: 50 });
await sync.writers.saveFoundryActor(sync.campaign, worldActor, false, true);
row = sync.models["../models/Actor"].rows[0];
assert.equal(row.name, "Thalia", "the actor is still the one the world sent");
assert.equal(row.traits, "", "a forced sync clears the trait the campaign wrote");
assert.deepEqual(row.tools, [], "and the tools, languages, skills, saving throws and coin it held");
assert.deepEqual(row.languages, []);
assert.deepEqual(row.skills, {});
assert.deepEqual(row.savingThrows, {});
assert.deepEqual(row.currency, {});
});
test("a hand-made item folds into the import instead of doubling, and keeps being updated", async () => {
const sync = loadFoundryWriters({
seed: { items: [{ _id: "item-1", name: "Longsword", quantity: 1 }] },

View File

@@ -1,605 +0,0 @@
// Tests for the campaign's notes reaching the Foundry world as journal pages
// (Syndria98/dragonroll#98): every Dragonroll note stands as a page of the one
// journal the world calls "Dragonroll", written by the module and kept in step with
// the campaign. The copy runs one way — notes are written in Dragonroll — so the
// backend answers with the notes and remembers each note's page; the module reads
// them, renders the markdown, and prunes the page of a note the campaign deleted.
//
// Both sides are loaded the way the other Foundry tests do it: the sync route runs
// against a stubbed `require` (models answer with plain objects and a small filter
// matcher), and the Foundry module is loaded into a `node:vm` context holding
// stubbed Foundry globals (`game.journals` and `JournalEntry` included) with fake
// timers, like tests/item-folder-sync.test.js.
//
// Run with `npm test` from the repository root, or `node --test tests/`.
const { test } = require("node:test");
const assert = require("node:assert/strict");
const fs = require("node:fs");
const path = require("node:path");
const vm = require("node:vm");
const MODULE_ID = "dragonroll-foundry";
const read = (...parts) => fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
const repoRequire = (relative) => require(path.join(__dirname, "..", relative));
// --- The sync route against stubbed models -------------------------------------
// A mongoose query answers whatever `await query` and `query.lean()` answer with, and
// lets `select()`, `sort()` and `limit()` sit in between.
function mongooseQuery(value) {
const result = {
select: () => result,
sort: () => result,
limit: (count) => mongooseQuery(value.slice(0, count)),
lean: () => Promise.resolve(value),
then: (onFulfilled, onRejected) => Promise.resolve(value).then(onFulfilled, onRejected),
};
return result;
}
// Enough of the query language the note routes use: equality, $or, $in, $nin,
// $exists, $ne. Anything else is a filter this test did not expect and says so.
function matches(document, filter = {}) {
return Object.entries(filter).every(([key, expected]) => {
if (key === "$or") return expected.some((part) => matches(document, part));
const value = document?.[key];
if (expected && typeof expected === "object" && !Array.isArray(expected)) {
return Object.entries(expected).every(([operator, wanted]) => {
if (operator === "$exists") return (value !== undefined && value !== null) === wanted;
if (operator === "$in") return wanted.some((entry) => String(value) === String(entry));
if (operator === "$nin") return !wanted.some((entry) => String(value) === String(entry));
if (operator === "$ne") return String(value ?? "") !== String(wanted ?? "");
throw new Error(`filter operator "${key}.${operator}" is not stubbed`);
});
}
return String(value ?? "") === String(expected ?? "");
});
}
function fakeModel(table, seed = [], campaignId) {
const rows = [];
let counter = 0;
function Document(data = {}) {
counter += 1;
this._id = `${table}-${counter}`;
this.isNew = true;
this.foundryNames = [];
Object.assign(this, data);
}
Document.prototype.save = async function save() {
if (this.isNew) rows.push(this);
this.isNew = false;
return this;
};
Object.defineProperty(Document.prototype, "id", { get() { return this._id; } });
for (const data of seed) {
// A seeded row belongs to the campaign the requests are made against unless the
// seed says otherwise: the routes scope every lookup by campaign.
const row = new Document({ campaign: campaignId, ...data });
row.isNew = false;
rows.push(row);
}
const model = function Model(data) { return new Document(data); };
model.rows = rows;
model.findOne = async (filter) => rows.find((row) => matches(row, filter)) ?? null;
model.find = (filter) => mongooseQuery(rows.filter((row) => matches(row, filter)));
model.deleteOne = async (filter) => {
const hit = rows.filter((row) => matches(row, filter));
for (const row of hit) rows.splice(rows.indexOf(row), 1);
return { deletedCount: hit.length };
};
model.deleteMany = async (filter) => {
const hit = rows.filter((row) => matches(row, filter));
for (const row of hit) rows.splice(rows.indexOf(row), 1);
return { deletedCount: hit.length };
};
model.updateMany = async (filter, update) => {
const hit = rows.filter((row) => matches(row, filter));
for (const row of hit) Object.assign(row, update.$set ?? {});
return { modifiedCount: hit.length };
};
return model;
}
// The Foundry sync route with every model it requires stubbed. `seed` pre-fills the
// tables with documents the campaign already holds.
function loadSyncRoute({ seed = {}, worldId = "world-1" } = {}) {
const routes = new Map();
const router = {
get: (route, ...handlers) => routes.set(`GET ${route}`, handlers),
post: (route, ...handlers) => routes.set(`POST ${route}`, handlers),
};
const campaign = { _id: "campaign-1", id: "campaign-1", name: "Test Campaign", foundryWorldId: worldId };
const seeded = (rows = []) => rows.map((row) => ({ campaign: campaign._id, ...row }));
const models = {
"../models/Actor": fakeModel("actor", seeded(seed.actors)),
"../models/Item": fakeModel("item", seeded(seed.items)),
"../models/Folder": fakeModel("folder", seeded(seed.folders)),
"../models/Note": fakeModel("note", seeded(seed.notes)),
"../models/Map": fakeModel("map", seeded(seed.maps)),
};
const requireStub = (id) => {
if (id === "express") return { Router: () => router };
if (id.startsWith("node:")) return require(id); // crypto: the sync token is hashed, not stubbed
if (id === "mongoose") return { isValidObjectId: (value) => typeof value === "string" && value.length > 20 };
if (id === "../models/Campaign") return { findOne: async () => campaign };
if (id === "../services/actor-foundry") return { foundryActorToCharacter: (actor) => ({ name: actor?.name ?? "" }) };
if (id === "../services/item-foundry") return repoRequire(path.join("backend", "src", "services", "item-foundry.js"));
if (id === "../services/foundry-icons") return repoRequire(path.join("backend", "src", "services", "foundry-icons.js"));
if (id === "../services/map-foundry") return repoRequire(path.join("backend", "src", "services", "map-foundry.js"));
if (models[id]) return models[id];
throw new Error(`require("${id}") is not stubbed`);
};
const moduleStub = { exports: {} };
vm.compileFunction(read("backend", "src", "routes", "foundry-link.js"), ["require", "module", "exports"])(
requireStub, moduleStub, moduleStub.exports
);
async function call(route, body = {}) {
const handlers = routes.get(route);
assert.ok(handlers, `${route} is not mounted`);
const res = { payload: null, json(payload) { this.payload = payload; }, set: () => {} };
const req = { body, get: (name) => (String(name).toLowerCase() === "authorization" ? "Bearer sync-token" : "") };
await handlers[handlers.length - 1](req, res);
return res.payload;
}
return { call, models, campaign };
}
// --- The sync route: the notes it answers and the page ids it keeps ---------------
test("the world reads the campaign's notes with their content and page mapping", async () => {
const sync = loadSyncRoute({
seed: {
notes: [
{ _id: "note-1", title: "Session 1", content: "**The start**", foundryPageId: "page-9" },
{ _id: "note-2", title: "Tavern Brawl", content: "- rope" },
],
},
});
const response = await sync.call("GET /sync/notes");
assert.equal(response.status, "ok");
assert.deepEqual(response.notes.map((note) => note.title), ["Session 1", "Tavern Brawl"]);
assert.equal(response.notes[0].content, "**The start**", "the markdown source travels: the module renders it");
assert.equal(response.notes[0].foundryPageId, "page-9", "and the note says which page it already stands as");
});
test("mapping a note to the page the module made keeps them paired", async () => {
const sync = loadSyncRoute({ seed: { notes: [{ _id: "note-1", title: "Session 1", content: "hi" }] } });
const response = await sync.call("POST /sync/map-note", {
worldId: "world-1", noteId: "note-1", foundryPageId: "page-9",
});
assert.equal(response.status, "ok");
assert.equal(sync.models["../models/Note"].rows[0].foundryPageId, "page-9");
// Mapping the same pair again is the module checking, not a conflict.
const again = await sync.call("POST /sync/map-note", {
worldId: "world-1", noteId: "note-1", foundryPageId: "page-9",
});
assert.equal(again.status, "ok");
});
test("a page already mapped to another note is refused", async () => {
const sync = loadSyncRoute({
seed: {
notes: [
{ _id: "note-1", title: "Session 1", content: "hi", foundryPageId: "page-9" },
{ _id: "note-2", title: "Tavern Brawl", content: "ho" },
],
},
});
const response = await sync.call("POST /sync/map-note", {
worldId: "world-1", noteId: "note-2", foundryPageId: "page-9",
});
assert.equal(response.status, "error");
assert.equal(response.msg, "foundry.errors.note-already-synced");
assert.equal(sync.models["../models/Note"].rows.find((row) => row._id === "note-2").foundryPageId, undefined,
"the first note keeps its page");
});
test("map-note wants this world's note and a page for it", async () => {
const sync = loadSyncRoute({ seed: { notes: [{ _id: "note-1", title: "Session 1", content: "hi" }] } });
assert.equal((await sync.call("POST /sync/map-note", { worldId: "world-1" })).msg, "errors.missing-data");
assert.equal((await sync.call("POST /sync/map-note", { noteId: "note-1", foundryPageId: "page-9" })).msg, "errors.missing-data",
"another world cannot map this campaign's note");
const gone = await sync.call("POST /sync/map-note", {
worldId: "world-1", noteId: "note-gone", foundryPageId: "page-9",
});
assert.equal(gone.msg, "errors.notfound");
});
// --- The Foundry module writes the journal ---------------------------------------
// Foundry's `update` takes dotted paths ("flags.dragonroll-foundry.noteId"); an
// embedded document's own id is not a path to set.
function writeFoundryPaths(target, data) {
for (const [key, value] of Object.entries(data)) {
if (key === "_id") continue;
const parts = key.split(".");
const last = parts.pop();
let node = target;
for (const part of parts) node = node[part] ??= {};
node[last] = value;
}
return target;
}
function makeWorld({ markdown = true, keepCreateFlags = true, failMapNote = false } = {}) {
const state = {
hooks: new Map(),
registered: new Map(),
requests: [],
timers: new Map(),
intervals: new Map(),
keepCreateFlags,
failMapNote,
// What Dragonroll answers the notes reconcile with. Mapping a page answers
// like the real backend: the note keeps the page id, so later reads carry it.
remoteNotes: [],
nextId: 1,
};
const journals = [];
const makePage = (journal, data = {}) => {
const page = {
id: `page-${state.nextId++}`,
documentName: "JournalEntryPage",
name: data.name,
text: { content: data.text?.content ?? "" },
flags: data.flags ?? {},
writes: 0,
getFlag(module, key) { return this.flags?.[module]?.[key]; },
async update(update) {
page.writes += 1;
writeFoundryPaths(page, update);
return page;
},
async delete() {
const index = journal.pages.contents.indexOf(page);
if (index >= 0) journal.pages.contents.splice(index, 1);
},
};
return page;
};
const makeJournal = (data = {}) => {
const pages = [];
return {
id: `journal-${state.nextId++}`,
name: data.name,
documentName: "JournalEntry",
flags: data.flags ?? {},
getFlag(module, key) { return this.flags?.[module]?.[key]; },
pages: { contents: pages, get: (id) => pages.find((page) => page.id === id) },
async update(update) { return writeFoundryPaths(this, update); },
async createEmbeddedDocuments(documentName, docs) {
assert.equal(documentName, "JournalEntryPage", "the notes' pages are journal pages");
// Foundry's own page validation refuses a page without a name.
for (const doc of docs) assert.ok(doc.name, "a journal page needs a non-empty name");
// A world that does not keep the flags a create was handed: the page
// exists but carries no mark, which is what a lost pairing looks like.
const created = docs.map((doc) => makePage(this, keepCreateFlags ? doc : { ...doc, flags: {} }));
pages.push(...created);
return created;
},
};
};
const settingsStore = { autoSync: true, syncToken: "sync-token-1", dragonrollApiUrl: "http://backend.test:5000" };
const sandbox = {
console: { log() {}, info() {}, warn() {}, error() {} },
URL,
CONFIG: {},
window: { location: { origin: "http://vtt.test" } },
ui: { notifications: { info() {}, warn() {}, error() {} } },
Hooks: {
once(name, fn) { state.hooks.set(name, [fn]); },
on(name, fn) { state.hooks.set(name, [...(state.hooks.get(name) || []), fn]); },
},
setTimeout: (fn, delay = 0) => {
const id = state.nextId++;
state.timers.set(id, { fn, delay });
return id;
},
clearTimeout: (id) => state.timers.delete(id),
setInterval: (fn, delay = 0) => {
// Recorded, never run by itself: tests ask for a periodic reconcile with
// `runIntervals`, so the ones watching single pushes stay on their own.
const id = state.nextId++;
state.intervals.set(id, { fn, delay });
return id;
},
clearInterval: (id) => state.intervals.delete(id),
fetch: async (url, options = {}) => {
const href = String(url);
const body = options.body ? JSON.parse(options.body) : null;
state.requests.push({ href, method: options.method, body });
if (href.includes("foundry/sync/map-note")) {
if (state.failMapNote) return { ok: false, status: 500, json: async () => ({ status: "error", msg: "errors.internal" }) };
const note = state.remoteNotes.find((entry) => String(entry._id) === String(body.noteId));
if (note) note.foundryPageId = body.foundryPageId;
return { ok: true, status: 200, json: async () => ({ status: "ok", note }) };
}
if (href.includes("foundry/sync/notes")) {
return { ok: true, status: 200, json: async () => ({ status: "ok", notes: state.remoteNotes }) };
}
return { ok: true, status: 200, json: async () => ({ status: "ok", actors: [], items: [] }) };
},
Actor: { async create() { return null; } },
Item: { async create() { return null; } },
JournalEntry: {
async create(data) {
const journal = makeJournal(data);
journals.push(journal);
return [journal];
},
},
};
if (markdown) sandbox.TextEditor = { _getMarkdown: (md) => `<marked>${md}</marked>` };
sandbox.game = {
user: { isGM: true },
world: { id: "world-1", title: "Test World" },
system: { id: "dnd5e" },
modules: { get: () => ({}) },
actors: { contents: [], get: () => null },
items: { contents: [], get: () => null },
folders: { contents: [], get: () => null },
journals: { contents: journals, get: (id) => journals.find((journal) => journal.id === id) },
settings: {
register(module, key, definition) {
state.registered.set(key, definition);
if (!(key in settingsStore)) settingsStore[key] = definition.default;
},
get(module, key) { return settingsStore[key]; },
async set(module, key, value) {
settingsStore[key] = value;
await state.registered.get(key)?.onChange?.(value);
},
},
};
vm.createContext(sandbox);
vm.runInContext(read("dragonroll-foundry", "scripts", "api.js"), sandbox);
state.game = sandbox.game;
state.journals = () => journals;
state.addJournal = (name, flags = {}) => {
const journal = makeJournal({ name, flags });
journals.push(journal);
return journal;
};
state.addPage = (journal, data) => {
const page = makePage(journal, data);
journal.pages.contents.push(page);
return page;
};
state.mapNoteRequests = () => state.requests.filter((request) => request.href.includes("foundry/sync/map-note"));
state.notesReads = () => state.requests.filter((request) => request.href.includes("foundry/sync/notes"));
const drain = async () => { await new Promise((resolve) => setImmediate(resolve)); };
state.fire = async (name, ...args) => {
for (const handler of state.hooks.get(name) || []) await handler(...args);
await drain();
};
state.runTimers = async () => {
for (let round = 0; round < 6; round += 1) {
if (!state.timers.size && round > 2) break;
const due = [...state.timers.values()];
state.timers.clear();
for (const timer of due) await timer.fn();
await drain();
}
};
// The reconciles `setInterval` registered: what runs every few seconds on a
// linked world, and so what carries each note into its journal page.
state.runIntervals = async () => {
for (const interval of [...state.intervals.values()]) await interval.fn();
await drain();
};
state.linkedSetup = async () => {
await state.fire("init");
await state.fire("ready");
await state.runTimers();
state.requests.length = 0;
return state;
};
return state;
}
// The fetch stub updates a note with the page it maps, like the real backend
// does, so every test works on notes of its own.
const sessionNote = (over = {}) => ({ _id: "note-1", title: "Session 1", content: "**The start**", ...over });
const tavernNote = (over = {}) => ({ _id: "note-2", title: "Tavern Brawl", content: "A rope, a chandelier.", ...over });
test("the campaign's notes become pages of one Dragonroll journal", async () => {
const world = await makeWorld().linkedSetup();
world.remoteNotes = [sessionNote(), tavernNote()];
await world.runIntervals();
assert.equal(world.journals().length, 1, "one journal carries the campaign's notes");
const journal = world.journals()[0];
assert.equal(journal.name, "Dragonroll");
assert.deepEqual(journal.pages.contents.map((page) => [page.name, page.text.content]), [
["Session 1", "<marked>**The start**</marked>"],
["Tavern Brawl", "<marked>A rope, a chandelier.</marked>"],
], "each note is a page, its markdown rendered by Foundry's own renderer");
assert.deepEqual(journal.pages.contents.map((page) => page.getFlag(MODULE_ID, "noteId")), ["note-1", "note-2"],
"each page keeps the note it stands for");
assert.deepEqual(world.mapNoteRequests().map((request) => [request.body.noteId, request.body.foundryPageId]), [
["note-1", journal.pages.contents[0].id],
["note-2", journal.pages.contents[1].id],
], "and the campaign remembers each note's page");
});
test("reconciling again does not double the journal or its pages", async () => {
const world = await makeWorld().linkedSetup();
world.remoteNotes = [sessionNote(), tavernNote()];
await world.runIntervals();
await world.runIntervals();
await world.runIntervals();
assert.equal(world.journals().length, 1, "the journal is made once, not per reconcile");
assert.equal(world.journals()[0].pages.contents.length, 2, "and each note stands as the one page it was given");
assert.equal(world.mapNoteRequests().length, 2, "an already-mapped note is not mapped again");
});
test("an existing journal named Dragonroll is used, not doubled", async () => {
const world = await makeWorld().linkedSetup();
const gmsOwn = world.addJournal("Dragonroll");
world.remoteNotes = [sessionNote()];
await world.runIntervals();
assert.equal(world.journals().length, 1, "the journal the world already had is the notes' one");
assert.deepEqual(gmsOwn.pages.contents.map((page) => page.name), ["Session 1"]);
assert.equal(gmsOwn.getFlag(MODULE_ID, "notesJournal"), true, "and it is marked, so renaming it keeps the notes' home findable");
});
test("a note edited in Dragonroll rewrites its page", async () => {
const world = await makeWorld().linkedSetup();
world.remoteNotes = [sessionNote()];
await world.runIntervals();
const first = world.remoteNotes[0];
world.remoteNotes = [{ ...first, title: "Session 1 — revisited", content: "**A different start**" }];
await world.runIntervals();
const journal = world.journals()[0];
assert.equal(journal.pages.contents.length, 1, "the note still stands as the same single page");
assert.deepEqual(journal.pages.contents[0].name, "Session 1 — revisited");
assert.equal(journal.pages.contents[0].text.content, "<marked>**A different start**</marked>");
assert.equal(world.mapNoteRequests().length, 1, "the pairing the world reads back needs no remapping");
});
test("a note deleted in Dragonroll takes its page with it", async () => {
const world = await makeWorld().linkedSetup();
world.remoteNotes = [sessionNote(), tavernNote()];
await world.runIntervals();
const journal = world.journals()[0];
const gmsPage = world.addPage(journal, { name: "My own notes", text: { content: "not from Dragonroll" } });
world.remoteNotes = world.remoteNotes.filter((note) => note._id !== "note-2");
await world.runIntervals();
assert.deepEqual(journal.pages.contents.map((page) => page.name), ["Session 1", "My own notes"],
"the deleted note's page goes; the GM's own page stays");
assert.ok(journal.pages.contents.includes(gmsPage));
});
test("pages already in step with the campaign are not rewritten", async () => {
const world = await makeWorld().linkedSetup();
world.remoteNotes = [sessionNote()];
await world.runIntervals();
const [page] = world.journals()[0].pages.contents;
assert.equal(page.writes, 0, "the page was created whole, not patched");
await world.runIntervals();
assert.equal(page.writes, 0, "a reconcile that changes nothing leaves the page alone");
});
test("the campaign's page mapping claims a page whose flag was lost", async () => {
const world = await makeWorld().linkedSetup();
const journal = world.addJournal("Dragonroll");
const orphan = world.addPage(journal, { name: "Old name", text: { content: "old" } });
world.remoteNotes = [{ _id: "note-1", title: "Session 1", content: "**The start**", foundryPageId: orphan.id }];
await world.runIntervals();
assert.equal(journal.pages.contents.length, 1, "no second page under the same title");
assert.equal(orphan.name, "Session 1");
assert.equal(orphan.getFlag(MODULE_ID, "noteId"), "note-1", "and the page is marked again");
});
test("a page under the note's title with no mark is claimed, not doubled", async () => {
const world = await makeWorld().linkedSetup();
const journal = world.addJournal("Dragonroll");
const existing = world.addPage(journal, { name: "Session 1", text: { content: "an older copy" } });
// The campaign has no page id for the note, and the page carries no flag: this
// is a page the module made before the pairing was kept, or one whose flag was
// lost. It is claimed instead of a second page being made under the same title.
world.remoteNotes = [sessionNote()];
await world.runIntervals();
assert.equal(journal.pages.contents.length, 1, "no second page under the note's title");
assert.equal(existing.text.content, "<marked>**The start**</marked>", "the note's text lands on the page the world already had");
assert.equal(existing.getFlag(MODULE_ID, "noteId"), "note-1", "and the page is marked as the note's");
assert.deepEqual(world.mapNoteRequests().map((request) => request.body.foundryPageId), [existing.id],
"the campaign is told which page the note now stands as");
await world.runIntervals();
assert.equal(journal.pages.contents.length, 1, "reconciling again does not add another");
});
test("two notes of one title do not share a single page", async () => {
const world = await makeWorld().linkedSetup();
const journal = world.addJournal("Dragonroll");
const existing = world.addPage(journal, { name: "Session 1", text: { content: "an older copy" } });
world.remoteNotes = [sessionNote(), { _id: "note-9", title: "Session 1", content: "second" }];
await world.runIntervals();
assert.equal(journal.pages.contents.length, 2, "the second note gets a page of its own");
assert.equal(existing.getFlag(MODULE_ID, "noteId"), "note-1", "the world's page is claimed by the first note");
assert.equal(journal.pages.contents[1].getFlag(MODULE_ID, "noteId"), "note-9");
});
test("a page whose mark and mapping were both lost is claimed again, not doubled", async () => {
// Both ways of recognising the pairing are gone: the create's flag did not stick,
// and the campaign never got to keep the page id. Without claiming the page it
// already made, every reconcile would write another one.
const world = await makeWorld({ keepCreateFlags: false, failMapNote: true }).linkedSetup();
world.remoteNotes = [sessionNote()];
await world.runIntervals();
await world.runIntervals();
await world.runIntervals();
const journal = world.journals()[0];
assert.equal(journal.pages.contents.length, 1, "one note stands as the one page it was given");
assert.equal(journal.pages.contents[0].getFlag(MODULE_ID, "noteId"), "note-1",
"and the page keeps the note it stands for even though the create did not mark it");
});
test("without Foundry's markdown renderer the fallback keeps the text legible", async () => {
const world = await makeWorld({ markdown: false }).linkedSetup();
world.remoteNotes = [{ _id: "note-1", title: "Session 1", content: "a & b < c\nline two\n\nsecond para" }];
await world.runIntervals();
assert.equal(
world.journals()[0].pages.contents[0].text.content,
"<p>a &amp; b &lt; c<br />line two</p>\n<p>second para</p>",
"escaped paragraphs instead of nothing, until this Foundry offers a renderer",
);
});
test("autosync off: the campaign's notes are not written into the world", async () => {
const world = await makeWorld().linkedSetup();
await world.game.settings.set(MODULE_ID, "autoSync", false);
world.remoteNotes = [sessionNote()];
await world.runIntervals();
assert.deepEqual(world.journals(), [], "no journal is made");
assert.deepEqual(world.notesReads(), [], "and the campaign is not even asked");
});

View File

@@ -207,7 +207,6 @@ test("autosync on: Foundry CRUD events keep syncing with Dragonroll", async () =
const pushes = world.syncRequests();
assert.equal(pushes.length, 1);
assert.equal(pushes[0].body.actors[0]._id, "actor-1");
assert.equal(pushes[0].body.replace, false, "a live actor change never asks Dragonroll to replace the campaign's edits");
});
test("autosync off: CRUD requests stop syncing", async () => {
@@ -261,7 +260,6 @@ test("force sync sends selected actors to Dragonroll even with autosync off", as
const pushes = world.syncRequests();
assert.equal(pushes.length, 1);
assert.equal(pushes[0].body.fullSync, false, "a forced actor never prunes the campaign");
assert.equal(pushes[0].body.replace, true, "a forced sync replaces everything the campaign holds for those actors");
assert.deepEqual(pushes[0].body.actors.map((actor) => actor._id), ["actor-2"]);
assert.deepEqual(world.notifications.filter(([kind]) => kind !== "info"), []);
});

View File

@@ -132,8 +132,6 @@ function loadSyncRoute({ seed = {}, worldId = "world-1" } = {}) {
"../models/Actor": fakeModel("actor", seeded(seed.actors)),
"../models/Item": fakeModel("item", seeded(seed.items)),
"../models/Folder": fakeModel("folder", seeded(seed.folders)),
"../models/Note": fakeModel("note", seeded(seed.notes)),
"../models/Map": fakeModel("map", seeded(seed.maps)),
};
const requireStub = (id) => {
@@ -144,7 +142,8 @@ function loadSyncRoute({ seed = {}, worldId = "world-1" } = {}) {
if (id === "../services/actor-foundry") return { foundryActorToCharacter: (actor) => ({ name: actor?.name ?? "" }) };
if (id === "../services/item-foundry") return repoRequire(path.join("backend", "src", "services", "item-foundry.js"));
if (id === "../services/foundry-icons") return repoRequire(path.join("backend", "src", "services", "foundry-icons.js"));
if (id === "../services/map-foundry") return repoRequire(path.join("backend", "src", "services", "map-foundry.js"));
// The Map model is only there for the scene lighting sync, which these tests do not run.
if (id === "../models/Map") return { find: () => mongooseQuery([]), findOne: async () => null };
if (models[id]) return models[id];
throw new Error(`require("${id}") is not stubbed`);
};

View File

@@ -1,599 +0,0 @@
// Tests for the world's scenes arriving as the campaign's maps (Syndria98/dragonroll#99).
// Only a scene's background picture and the grid laid over it travel: the campaign keeps its
// own scale, its folders, its pinned notes and the tokens standing on the map, and none of it
// goes back to the world.
//
// Same set-up as tests/item-folder-sync.test.js, which the repository root runs without
// installing anything: the sync route is loaded into `node:vm` with express, mongoose and its
// models stubbed (plain rows and a small filter matcher), so creating, adopting and pruning
// maps is observable without a database. The Foundry module is loaded into a `node:vm` context
// holding stubbed Foundry globals (`game.scenes` included) with fake timers, like
// tests/foundry-sync-toggle.test.js.
//
// Run with `npm test` from the repository root, or `node --test tests/`.
const { test } = require("node:test");
const assert = require("node:assert/strict");
const fs = require("node:fs");
const path = require("node:path");
const vm = require("node:vm");
const read = (...parts) => fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
const repoRequire = (relative) => require(path.join(__dirname, "..", relative));
// --- The sync route against stubbed models -------------------------------------
// A mongoose query answers whatever `await query` and `query.lean()` answer with, and
// lets `select()`, `sort()` and `limit()` sit in between.
function mongooseQuery(value) {
const result = {
select: () => result,
sort: () => result,
limit: (count) => mongooseQuery(value.slice(0, count)),
lean: () => Promise.resolve(value),
then: (onFulfilled, onRejected) => Promise.resolve(value).then(onFulfilled, onRejected),
};
return result;
}
// Enough of the query language the scene sync uses: equality, $in, $nin, $exists.
// Anything else is a filter this test did not expect and says so.
function matches(document, filter = {}) {
return Object.entries(filter).every(([key, expected]) => {
const value = document?.[key];
if (expected && typeof expected === "object" && !Array.isArray(expected)) {
return Object.entries(expected).every(([operator, wanted]) => {
if (operator === "$exists") return (value !== undefined && value !== null) === wanted;
if (operator === "$in") return wanted.some((entry) => String(value) === String(entry));
if (operator === "$nin") return !wanted.some((entry) => String(value) === String(entry));
throw new Error(`filter operator "${key}.${operator}" is not stubbed`);
});
}
return String(value ?? "") === String(expected ?? "");
});
}
function fakeModel(table, seed = [], campaignId) {
const rows = [];
let counter = 0;
function Document(data = {}) {
counter += 1;
this._id = `${table}-${counter}`;
this.isNew = true;
Object.assign(this, data);
}
Document.prototype.save = async function save() {
if (this.isNew) rows.push(this);
this.isNew = false;
return this;
};
Object.defineProperty(Document.prototype, "id", { get() { return this._id; } });
for (const data of seed) {
// A seeded row belongs to the campaign the requests are made against unless the seed
// says otherwise: the sync scopes every lookup by campaign.
const row = new Document({ campaign: campaignId, name: undefined, ...data });
row.isNew = false;
rows.push(row);
}
const model = function Model(data) { return new Document(data); };
model.rows = rows;
model.findOne = async (filter) => rows.find((row) => matches(row, filter)) ?? null;
model.find = (filter) => mongooseQuery(rows.filter((row) => matches(row, filter)));
model.deleteOne = async (filter) => {
const hit = rows.filter((row) => matches(row, filter));
for (const row of hit) rows.splice(rows.indexOf(row), 1);
return { deletedCount: hit.length };
};
model.deleteMany = async (filter) => {
const hit = rows.filter((row) => matches(row, filter));
for (const row of hit) rows.splice(rows.indexOf(row), 1);
return { deletedCount: hit.length };
};
return model;
}
// The Foundry sync route with every model it requires stubbed. `seed` pre-fills the tables
// with documents the campaign already holds.
function loadSyncRoute({ seed = {}, worldId = "world-1", settings } = {}) {
const routes = new Map();
const router = {
get: (route, ...handlers) => routes.set(`GET ${route}`, handlers),
post: (route, ...handlers) => routes.set(`POST ${route}`, handlers),
};
const campaign = {
_id: "campaign-1", id: "campaign-1", name: "Test Campaign", foundryWorldId: worldId,
...(settings ? { settings } : {}),
};
const seeded = (rows = []) => rows.map((row) => ({ campaign: campaign._id, ...row }));
const models = {
"../models/Actor": fakeModel("actor", seeded(seed.actors)),
"../models/Item": fakeModel("item", seeded(seed.items)),
"../models/Folder": fakeModel("folder", seeded(seed.folders)),
"../models/Note": fakeModel("note", seeded(seed.notes)),
"../models/Map": fakeModel("map", seeded(seed.maps)),
};
const requireStub = (id) => {
if (id === "express") return { Router: () => router };
if (id.startsWith("node:")) return require(id); // crypto: the sync token is hashed, not stubbed
if (id === "mongoose") return { isValidObjectId: (value) => typeof value === "string" && value.length > 20 };
if (id === "../models/Campaign") return { findOne: async () => campaign };
if (id === "../services/actor-foundry") return { foundryActorToCharacter: (actor) => ({ name: actor?.name ?? "" }) };
if (id === "../services/item-foundry") return { foundryItemToItemData: () => null };
if (id === "../services/foundry-icons") return repoRequire(path.join("backend", "src", "services", "foundry-icons.js"));
if (id === "../services/map-foundry") return repoRequire(path.join("backend", "src", "services", "map-foundry.js"));
if (models[id]) return models[id];
throw new Error(`require("${id}") is not stubbed`);
};
const moduleStub = { exports: {} };
vm.compileFunction(read("backend", "src", "routes", "foundry-link.js"), ["require", "module", "exports"])(
requireStub, moduleStub, moduleStub.exports
);
async function call(route, body = {}) {
const handlers = routes.get(route);
assert.ok(handlers, `${route} is not mounted`);
const res = { payload: null, json(payload) { this.payload = payload; }, set: () => {} };
const req = { body, get: (name) => (String(name).toLowerCase() === "authorization" ? "Bearer sync-token" : "") };
await handlers[handlers.length - 1](req, res);
return res.payload;
}
return { call, models, campaign };
}
// A scene of the world, as the module sends it: plain document data with its picture read
// from the world. This one is 70 px cells and the picture of the ruined keep.
function worldScene(over = {}) {
return {
_id: "scene-1",
name: "The Ruined Keep",
img: "http://vtt.test/images/keep.webp",
grid: 70,
flags: {},
...over,
};
}
const maps = (sync) => sync.models["../models/Map"].rows;
// --- A scene arrives as a map -------------------------------------------------------
test("a world scene arrives as a map of the campaign", async () => {
const sync = loadSyncRoute();
const response = await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()] });
assert.equal(response.status, "ok");
const [map] = maps(sync);
assert.equal(map.name, "The Ruined Keep");
assert.equal(map.image, "http://vtt.test/images/keep.webp", "the scene's background picture is the map's");
assert.equal(map.gridSize, 70, "the scene's own cell size is the grid the campaign draws");
assert.equal(map.offsetX, 0);
assert.equal(map.offsetY, 0, "a scene that shifts nothing has its grid at the corner of the picture");
assert.equal(map.foundrySceneId, "scene-1");
assert.equal(map.campaign, sync.campaign._id, "the map belongs to the campaign the world is linked to");
assert.deepEqual(response.maps, [{ foundrySceneId: "scene-1", mapId: map._id, created: true }]);
});
test("a scene keeps the grid its world shifted onto the picture", async () => {
const sync = loadSyncRoute();
await sync.call("POST /sync/scenes", {
worldId: "world-1",
scenes: [worldScene({ grid: 64, flags: { core: { shiftX: 12, shiftY: -8 } } })],
});
const [map] = maps(sync);
assert.equal(map.gridSize, 64);
assert.equal(map.offsetX, 12);
assert.equal(map.offsetY, -8, "a grid that starts off the corner of the picture arrives where the world puts it");
});
test("a scene of a newer Foundry still arrives", async () => {
const sync = loadSyncRoute();
// Since Foundry V13 the picture sits under `background.src` and the cell size under
// `grid.size`.
await sync.call("POST /sync/scenes", {
worldId: "world-1",
scenes: [worldScene({ img: undefined, background: { src: "http://vtt.test/images/keep.webp" }, grid: { size: 128 } })],
});
const [map] = maps(sync);
assert.equal(map.image, "http://vtt.test/images/keep.webp");
assert.equal(map.gridSize, 128);
});
test("a scene's picture is read against the world the campaign knows", async () => {
// An older module sends Foundry's own relative path; it is read against the world's
// address, the way an actor's portrait is (Syndria98/dragonroll#89).
const sync = loadSyncRoute({ settings: { integrations: { foundryUrl: "http://vtt.test:30000" } } });
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene({ img: "images/keep.webp" })] });
assert.equal(maps(sync)[0].image, "http://vtt.test:30000/images/keep.webp");
});
test("a scene with no picture is not a map", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-1", name: "The Ruined Keep", foundrySceneId: "scene-1", image: "http://vtt.test/images/keep.webp" }] },
});
// The GM took the picture off the scene: its id still travels with the snapshot, so its
// map is neither made blank nor dropped, and no new row is made for it either.
const response = await sync.call("POST /sync/scenes", {
worldId: "world-1",
scenes: [worldScene({ img: "" })],
fullSync: true,
});
assert.deepEqual(response.maps, []);
assert.equal(maps(sync).length, 1);
assert.equal(maps(sync)[0].image, "http://vtt.test/images/keep.webp");
});
test("what one of the map's cells stands for stays the campaign's", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-1", name: "The Ruined Keep", foundrySceneId: "scene-1", gridSize: 50, scale: 1.5 }] },
});
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene({ gridDistance: 1500, gridUnits: "m" })] });
assert.equal(maps(sync)[0].gridSize, 70, "the world's cell size arrives");
assert.equal(maps(sync)[0].scale, 1.5, "and the distance the campaign says a cell covers is left alone");
});
// --- One map per scene ---------------------------------------------------------------
test("the same scene is never made into two maps", async () => {
const sync = loadSyncRoute();
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()] });
const response = await sync.call("POST /sync/scenes", {
worldId: "world-1",
scenes: [worldScene({ name: "The Ruined Keep, II", grid: 80 })],
});
assert.equal(maps(sync).length, 1, "the scene was written over, not doubled");
assert.equal(maps(sync)[0].name, "The Ruined Keep, II");
assert.equal(maps(sync)[0].gridSize, 80);
assert.equal(response.maps[0].created, false, "the push says it wrote a map it already had");
});
test("a live scene edit lands on the map, however the campaign had it", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-1", name: "Old name", foundrySceneId: "scene-1", image: "old.png", gridSize: 40 }] },
});
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()] });
const [map] = maps(sync);
assert.equal(map.image, "http://vtt.test/images/keep.webp");
assert.equal(map.gridSize, 70);
assert.equal(map.name, "The Ruined Keep");
});
test("a full snapshot leaves the picture and grid the campaign lined up alone", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-1", name: "My keep", foundrySceneId: "scene-1", image: "my-keep.png", gridSize: 40 }] },
});
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()], fullSync: true });
const [map] = maps(sync);
assert.equal(map.image, "my-keep.png", "a GM reconnecting does not write over a map the campaign already had");
assert.equal(map.gridSize, 40);
assert.equal(map.name, "My keep");
});
test("a scene takes over the map the campaign drew by hand", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-1", name: "The Ruined Keep", image: "hand-made.png", gridSize: 50 }] },
});
const response = await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()] });
assert.equal(maps(sync).length, 1, "the room the campaign drew first is not doubled by its scene");
assert.equal(maps(sync)[0]._id, "map-1");
assert.equal(maps(sync)[0].foundrySceneId, "scene-1", "and it is the scene's map from then on");
assert.equal(response.maps[0].mapId, "map-1");
});
test("a scene carrying the campaign's map id adopts that row", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-0123456789abcdef0123456789", name: "Keep under way", image: "hand-made.png" }] },
});
const response = await sync.call("POST /sync/scenes", {
worldId: "world-1",
scenes: [worldScene({ name: "Somewhere else", flags: { "dragonroll-foundry": { mapId: "map-0123456789abcdef0123456789" } } })],
});
assert.equal(maps(sync).length, 1);
assert.equal(response.maps[0].mapId, "map-0123456789abcdef0123456789", "the flag says which map the scene is");
});
// --- Pruning --------------------------------------------------------------------------
test("a full snapshot prunes the maps whose scene this world let go of", async () => {
const sync = loadSyncRoute({
seed: {
maps: [
{ _id: "map-1", name: "Cellar", foundrySceneId: "scene-gone" },
{ _id: "map-2", name: "Homebrew ford" },
{ _id: "map-3", name: "The Ruined Keep", foundrySceneId: "scene-1" },
],
},
});
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()], fullSync: true });
assert.deepEqual(maps(sync).map((map) => map._id).sort(), ["map-2", "map-3"],
"the scene that is gone takes its map with it, and the campaign's own maps stay");
});
test("a live scene push never prunes", async () => {
const sync = loadSyncRoute({
seed: { maps: [{ _id: "map-1", name: "Cellar", foundrySceneId: "scene-gone" }] },
});
await sync.call("POST /sync/scenes", { worldId: "world-1", scenes: [worldScene()] });
assert.equal(maps(sync).length, 2, "a push of one scene says nothing about the world's other scenes");
});
test("a scene the world deleted takes its map with it", async () => {
const sync = loadSyncRoute({
seed: {
maps: [
{ _id: "map-1", name: "The Ruined Keep", foundrySceneId: "scene-1" },
{ _id: "map-2", name: "Homebrew ford" },
],
},
});
const response = await sync.call("POST /sync/scene-delete", { worldId: "world-1", foundrySceneId: "scene-1" });
assert.equal(response.status, "ok");
assert.deepEqual(maps(sync).map((map) => map._id), ["map-2"], "only the map of that scene goes");
});
// --- What the route refuses -----------------------------------------------------------
test("a push that is not the campaign's world, or names no scenes, is refused", async () => {
const sync = loadSyncRoute();
assert.equal((await sync.call("POST /sync/scenes", { worldId: "another-world", scenes: [worldScene()] })).msg, "errors.missing-data");
assert.equal((await sync.call("POST /sync/scenes", { worldId: "world-1" })).msg, "errors.missing-data");
assert.deepEqual(maps(sync), [], "nothing was written");
});
test("a delete from another world, or naming no scene, is refused", async () => {
const sync = loadSyncRoute({ seed: { maps: [{ _id: "map-1", name: "Keep", foundrySceneId: "scene-1" }] } });
assert.equal((await sync.call("POST /sync/scene-delete", { worldId: "another-world", foundrySceneId: "scene-1" })).msg, "errors.missing-data");
assert.equal((await sync.call("POST /sync/scene-delete", { worldId: "world-1" })).msg, "errors.missing-data");
assert.equal(maps(sync).length, 1, "and the map is still there");
});
test("a map remembers which scene of the world it mirrors", () => {
const model = read("backend", "src", "models", "Map.js");
assert.match(model, /foundrySceneId:\s*{\s*type:\s*String\s*}/, "the scene a map mirrors is kept on the map");
assert.match(model, /\{\s*campaign:\s*1,\s*foundrySceneId:\s*1\s*\}/, "and is unique within the campaign");
});
// --- The Foundry module sends its scenes ---------------------------------------------
const MODULE_ID = "dragonroll-foundry";
function makeWorld({ autoSync = true } = {}) {
const state = {
hooks: new Map(),
registered: new Map(),
requests: [],
timers: new Map(),
intervals: new Map(),
nextTimerId: 1,
};
// A Scene document: the plain data `toObject()` answers with, which since V13 carries
// the picture under `background` rather than `img`.
const makeScene = (id, name, over = {}) => ({
id, name, documentName: "Scene", img: "", grid: 50, flags: {},
toObject() {
return {
_id: this.id, name: this.name, img: this.img, grid: this.grid, flags: this.flags,
...(this.background ? { background: this.background } : {}),
};
},
...over,
});
const scenes = [
makeScene("scene-keep", "The Ruined Keep", { img: "images/keep.webp", grid: 70 }),
// A newer Foundry keeps its picture under `background`, and this one is already an
// absolute URL, which travels as it is.
makeScene("scene-tavern", "Tavern", { img: undefined, background: { src: "http://other.test/tavern.jpg" }, grid: 50 }),
];
const settingsStore = { autoSync, syncToken: "sync-token-1", dragonrollApiUrl: "http://backend.test:5000" };
const sandbox = {
console: { log() {}, info() {}, warn() {}, error() {} },
URL,
CONFIG: {},
window: { location: { origin: "http://vtt.test" } },
ui: { notifications: { info() {}, warn() {}, error() {} } },
Hooks: {
once(name, fn) { state.hooks.set(name, [fn]); },
on(name, fn) { state.hooks.set(name, [...(state.hooks.get(name) || []), fn]); },
},
setTimeout: (fn, delay = 0) => {
const id = state.nextTimerId++;
state.timers.set(id, { fn, delay });
return id;
},
clearTimeout: (id) => state.timers.delete(id),
setInterval: (fn, delay = 0) => {
const id = state.nextTimerId++;
state.intervals.set(id, { fn, delay });
return id;
},
clearInterval: (id) => state.intervals.delete(id),
fetch: async (url, options = {}) => {
state.requests.push({
href: String(url),
method: options.method,
body: options.body ? JSON.parse(options.body) : null,
});
return { ok: true, status: 200, json: async () => ({ status: "ok" }) };
},
Actor: { async create() { return null; } },
Item: { async create() { return null; } },
};
sandbox.game = {
user: { isGM: true },
world: { id: "world-1", title: "Test World" },
system: { id: "dnd5e" },
modules: { get: () => ({}) },
actors: { contents: [], get: () => null },
items: { contents: [], get: () => null },
scenes: { contents: scenes, get: (id) => scenes.find((scene) => scene.id === id) },
settings: {
register(module, key, definition) {
state.registered.set(key, definition);
if (!(key in settingsStore)) settingsStore[key] = definition.default;
},
get(module, key) { return settingsStore[key]; },
async set(module, key, value) {
settingsStore[key] = value;
await state.registered.get(key)?.onChange?.(value);
},
},
};
vm.createContext(sandbox);
vm.runInContext(read("dragonroll-foundry", "scripts", "api.js"), sandbox);
state.game = sandbox.game;
state.scene = (id) => scenes.find((scene) => scene.id === id);
// The two routes the maps travel on: the campaign's reads live under the same prefix and
// tell nothing about what the world sent.
state.sceneRequests = () => state.requests.filter((request) => request.href.includes("foundry/sync/scenes")
|| request.href.includes("foundry/sync/scene-delete"));
state.pushes = (route) => state.requests.filter((request) => request.href.includes(route));
const drain = async () => { await new Promise((resolve) => setImmediate(resolve)); };
state.fire = async (name, ...args) => {
for (const handler of state.hooks.get(name) || []) await handler(...args);
await drain();
};
state.runTimers = async () => {
for (let round = 0; round < 6; round += 1) {
if (!state.timers.size && round > 2) break;
const due = [...state.timers.values()];
state.timers.clear();
for (const timer of due) await timer.fn();
await drain();
}
};
// A world that is already linked: init, ready, and the pushes the world makes as it loads.
state.setup = async () => {
await state.fire("init");
await state.fire("ready");
await state.runTimers();
return state;
};
// The same, with the world's own pushes out of the way, so a test only sees what it causes.
state.linkedSetup = async () => {
await state.setup();
state.requests.length = 0;
return state;
};
return state;
}
test("the world sends its whole scene list as the campaign's maps when it loads", async () => {
const world = await makeWorld().setup();
const [push] = world.pushes("foundry/sync/scenes");
assert.ok(push, "a linked world pushes its scenes as it loads");
assert.equal(push.body.fullSync, true, "the whole list travels, which is the push that lets the campaign prune");
assert.deepEqual(push.body.worldId, "world-1");
assert.deepEqual(push.body.scenes.map((scene) => [scene._id, scene.name]), [
["scene-keep", "The Ruined Keep"],
["scene-tavern", "Tavern"],
]);
assert.equal(push.body.scenes[0].img, "http://vtt.test/images/keep.webp",
"the picture is read from this world, so it travels as an absolute URL");
assert.equal(push.body.scenes[0].grid, 70, "the scene's own cell size travels with it");
assert.equal(push.body.scenes[1].background.src, "http://other.test/tavern.jpg",
"a picture that is already absolute is left as it is");
});
test("a scene the GM changes reaches the campaign as that map", async () => {
const world = await makeWorld().linkedSetup();
const keep = world.scene("scene-keep");
keep.name = "The Sunken Keep";
keep.grid = 100;
await world.fire("updateScene", keep);
await world.runTimers();
const [push] = world.pushes("foundry/sync/scenes");
assert.equal(push.body.fullSync, false, "a live scene edit never prunes the campaign's other maps");
assert.deepEqual(push.body.scenes.map((scene) => [scene._id, scene.name, scene.grid]), [
["scene-keep", "The Sunken Keep", 100],
]);
});
test("a scene the GM deletes takes its map off the campaign", async () => {
const world = await makeWorld().linkedSetup();
await world.fire("deleteScene", world.scene("scene-tavern"));
await world.runTimers();
const [push] = world.pushes("foundry/sync/scene-delete");
assert.equal(push.body.foundrySceneId, "scene-tavern");
assert.deepEqual(world.pushes("foundry/sync/scenes"), [], "a deleted scene is not sent as a map to keep");
});
test("autosync off: the world's scenes stop syncing, at world start and afterwards", async () => {
const world = makeWorld({ autoSync: false });
await world.fire("init");
await world.fire("ready");
await world.runTimers();
assert.deepEqual(world.sceneRequests(), [], "a world with autosync off sends no scene list");
await world.fire("updateScene", world.scene("scene-keep"));
await world.fire("deleteScene", world.scene("scene-tavern"));
await world.runTimers();
assert.deepEqual(world.sceneRequests(), []);
});
test("the scene edits queued while autosync was off are sent when it is turned back on", async () => {
const world = await makeWorld({ autoSync: false });
await world.fire("init");
await world.fire("ready");
await world.runTimers();
await world.fire("updateScene", world.scene("scene-keep"));
await world.runTimers();
assert.deepEqual(world.sceneRequests(), []);
await world.game.settings.set(MODULE_ID, "autoSync", true);
await world.runTimers();
assert.ok(world.pushes("foundry/sync/scenes").some((push) => push.body.fullSync === true
&& push.body.scenes.length === 2),
"turning autosync back on sends this world's whole scene list again");
assert.ok(world.pushes("foundry/sync/scenes").some((push) => push.body.fullSync === false
&& push.body.scenes.map((scene) => scene._id).includes("scene-keep")),
"and the scene edit queued while it was off is sent");
});