Sync toggle on foundry #8

Closed
opened 2026-10-13 21:44:27 +00:00 by Syndria98 · 10 comments
Owner

Can you add on the foundry module an option on each actor to force sync onto dragonroll and a toggle to autosync (that is on by default) that does what the current implementation is already doing (that is synchronizing with CRUD requests the actors with dragonroll). If it is off, do not make it sync.

Can you add on the foundry module an option on each actor to force sync onto dragonroll and a toggle to autosync (that is on by default) that does what the current implementation is already doing (that is synchronizing with CRUD requests the actors with dragonroll). If it is off, do not make it sync.
Syndria98 added the ai-ready label 2026-10-13 21:44:27 +00:00
Collaborator

I'll start by exploring the repository structure and the Foundry module.

I'll start by exploring the repository structure and the Foundry module.
Collaborator

Now let me implement the changes in the Foundry module.

Now let me implement the changes in the Foundry module.
Collaborator

Now the module README documentation:

Now the module README documentation:
Collaborator

Now let me build a verification harness that stubs the Foundry globals, to actually exercise the new gating logic:

Now let me build a verification harness that stubs the Foundry globals, to actually exercise the new gating logic:
Collaborator

All six checks pass. Now let me put the test into the repo in a clean, permanent form:

All six checks pass. Now let me put the test into the repo in a clean, permanent form:
Collaborator

Let me refine the force-sync action to respect Foundry's multi-select context-menu convention:

Let me refine the force-sync action to respect Foundry's multi-select context-menu convention:
Collaborator

I renamed that function, so I need to update its call site in the context menu.

I renamed that function, so I need to update its call site in the context menu.
Collaborator

One inconsistency to fix: the actor path drops changes while autosync is off, but the item path queues them. Let me make both paths behave the same way:

One inconsistency to fix: the actor path drops changes while autosync is off, but the item path queues them. Let me make both paths behave the same way:
Collaborator

Done. Here's what I implemented for Syndria98/dragonroll#8:

Changes

dragonroll-foundry/scripts/api.js — the whole feature is client-side, in the module:

  1. Autosync toggle (on by default) — new autoSync module setting (Dragonroll Auto-sync, config: true, default: true, client scope like the module's other sync settings). When off:

    • flushActorChanges / flushItemChanges return early, so Foundry create/update/delete events no longer reach /foundry/sync/*;
    • the startup full snapshot (initializeCharacterSync) and both periodic reconciles (/sync/characters, /sync/items) do not run, so Dragonroll also stops rewriting Foundry documents;
    • edits made while it is off stay in the existing queues and are delivered when it is switched back on, which also re-runs the full reconcile so both sides converge again.
  2. Per-actor force sync — a Dragonroll: Force Sync entry in the actor directory's context menu (getActorDirectoryEntryContext, GM-only, shown once the world is paired). It pushes the selected actor(s) immediately with fullSync: false — an upsert, so it never prunes other campaign actors — and notifies success/failure. Actors Dragonroll does not import (anything that is not character/NPC/creature) are refused with a notification instead of silently doing nothing.

Also bumped module.json to 0.4.0 and documented the toggle and the menu entry in dragonroll-foundry/README.md; AGENTS.md was updated where it documented the sync rules and the (now no longer absent) test command.

Tests

Added tests/foundry-sync-toggle.test.js (Node's built-in runner, npm test at the root, no dependencies): it loads the module script into a node:vm context with stubbed Foundry globals (game, Hooks, ui, fetch, fake timers) so every queued push/reconcile is observable. 10 tests, all passing (# pass 10 / # fail 0 on Node v20.20.2): setting defaults to on, CRUD syncs while on, nothing is sent or reconciled while off (including at world start), queued edits land on re-enable, force sync works with the toggle off and on, multi-select sends one push, and unsupported actor types are refused.

Interpretation notes (flagging in case you wanted otherwise)

  • I read "a toggle to autosync" as one world-level switch in the module settings rather than a per-actor on/off. A per-actor autosync flag is deliberately not included: a full snapshot prunes campaign actors missing from it, so excluding one actor from sync would make its next full snapshot delete its Dragonroll row — that needs a backend rule, not just a Foundry flag. Say the word and I'll add it together with the backend change that keeps excluded actors out of pruning.
  • The optional read-only snapshot bridge keeps publishing regardless of the toggle: it is a separate feature (the world snapshot behind /api/foundry/*) and never writes into the campaign. Easy to gate it too if you want the switch to stop all outbound traffic.

Nothing is committed or pushed.

Done. Here's what I implemented for **Syndria98/dragonroll#8**: ## Changes **`dragonroll-foundry/scripts/api.js`** — the whole feature is client-side, in the module: 1. **Autosync toggle (on by default)** — new `autoSync` module setting (`Dragonroll Auto-sync`, `config: true`, `default: true`, client scope like the module's other sync settings). When off: - `flushActorChanges` / `flushItemChanges` return early, so Foundry create/update/delete events no longer reach `/foundry/sync/*`; - the startup full snapshot (`initializeCharacterSync`) and both periodic reconciles (`/sync/characters`, `/sync/items`) do not run, so Dragonroll also stops rewriting Foundry documents; - edits made while it is off stay in the existing queues and are delivered when it is switched back on, which also re-runs the full reconcile so both sides converge again. 2. **Per-actor force sync** — a **Dragonroll: Force Sync** entry in the actor directory's context menu (`getActorDirectoryEntryContext`, GM-only, shown once the world is paired). It pushes the selected actor(s) immediately with `fullSync: false` — an upsert, so it never prunes other campaign actors — and notifies success/failure. Actors Dragonroll does not import (anything that is not character/NPC/creature) are refused with a notification instead of silently doing nothing. Also bumped `module.json` to `0.4.0` and documented the toggle and the menu entry in `dragonroll-foundry/README.md`; `AGENTS.md` was updated where it documented the sync rules and the (now no longer absent) test command. ## Tests Added `tests/foundry-sync-toggle.test.js` (Node's built-in runner, `npm test` at the root, no dependencies): it loads the module script into a `node:vm` context with stubbed Foundry globals (`game`, `Hooks`, `ui`, `fetch`, fake timers) so every queued push/reconcile is observable. **10 tests, all passing** (`# pass 10 / # fail 0` on Node v20.20.2): setting defaults to on, CRUD syncs while on, nothing is sent or reconciled while off (including at world start), queued edits land on re-enable, force sync works with the toggle off and on, multi-select sends one push, and unsupported actor types are refused. ## Interpretation notes (flagging in case you wanted otherwise) - I read "a toggle to autosync" as one world-level switch in the module settings rather than a per-actor on/off. A per-actor autosync flag is deliberately **not** included: a full snapshot prunes campaign actors missing from it, so excluding one actor from sync would make its next full snapshot delete its Dragonroll row — that needs a backend rule, not just a Foundry flag. Say the word and I'll add it together with the backend change that keeps excluded actors out of pruning. - The optional read-only snapshot bridge keeps publishing regardless of the toggle: it is a separate feature (the world snapshot behind `/api/foundry/*`) and never writes into the campaign. Easy to gate it too if you want the switch to stop all outbound traffic. Nothing is committed or pushed.
Collaborator

Implementation is ready for review: #9

Implementation is ready for review: https://git.aranroig.com/Syndria98/dragonroll/pulls/9
Sign in to join this conversation.
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Syndria98/dragonroll#8