Chronicle Sync — Foundry VTT Module

Bidirectional real-time sync between Chronicle and Foundry VTT.

Features

• Journal Sync — Chronicle entities ↔ Foundry journal entries (with multi-page splitting)
• Map Sync — Chronicle map markers ↔ Foundry scene pins (with "View in Chronicle" for full map editor)
• Calendar Sync — Calendaria and Simple Calendar integration
• Character Sync — Actor ↔ character entity with system-aware field mapping (D&D 5e, Pathfinder 2e, or any system with annotated fields)
• Shop Widget — Browse and purchase from Chronicle shop entities in Foundry
• Sync Dashboard — 8-tab management UI with diagnostics, error logs, and health metrics
• Permission Mapping — Chronicle visibility ↔ Foundry ownership levels

Compatibility

Foundry VTT	Status
v12	Minimum supported
v13	Verified
v14	Verified

Installation

Module releases are served from your Chronicle instance, not from GitHub. The install URL is per-campaign, signed, and pinned to the version your campaign owner selected.

To install:

1. In Chronicle, open your campaign → Settings → Foundry Module tab.
2. Copy the install URL shown on that page.
3. In Foundry VTT, go to Add-on Modules → Install Module, paste the URL, and click Install.

After install, Foundry remembers that URL and re-uses it on every update check — so you'll receive whichever module version your campaign owner pins, without further configuration.

For Chronicle admins: upload new module .zip builds via /admin/modules/foundry on your Chronicle instance. Campaign owners can then pin any uploaded version per-campaign from their settings tab.

GitHub release distribution is no longer the primary channel. The repo still produces GitHub releases (Chronicle's package catalog uses them as its upstream source), but the install URL Foundry users should consume is the per-campaign Chronicle URL above — that's how per-campaign version pinning works. Existing installs pointing at GitHub continue to run but won't receive the campaign's pinned version. Open the Update Source panel (Game Settings → Module Settings → Chronicle Sync → Update Source) to check whether your install needs to be re-pointed at Chronicle.

Updating in Foundry

Once installed via your Chronicle install URL, Foundry stores that URL and uses it for every future update check — updates always come from Chronicle, reflecting whichever version your campaign owner has pinned.

Foundry's central Package Repository also lists this module with its GitHub manifest URL. On an update check, Foundry may detect the mismatch and prompt you to switch the locally-stored manifest URL to one from the Package Repository. If you see this prompt, decline it to keep your install on Chronicle. Switching to the Package Repository's URL bypasses your campaign owner's pinned version and sends update traffic to GitHub instead of Chronicle.

Configuration

1. Enable the module in your world's Module Management
2. Open Game Settings → Module Settings → Chronicle Sync
3. Enter your Chronicle API URL, API Key, and Campaign ID
4. Enable the sync categories you want (Journals, Maps, Calendar, Characters)

The module runs sync for the GM only. Players receive updates passively through Foundry.

Optional Modules

• Monk's Enhanced Journal — Enhanced journal page support
• Calendaria — Calendar sync
• Simple Calendar — Calendar sync (alternative)

For Chronicle integrators

This module ships a chronicle-package.json descriptor at the repo root. Chronicle reads it during admin install to decide how to serve the module: where the manifest lives inside the zip, what URL shape to emit when generating per-campaign install URLs, and whether per-campaign signed tokens are required.

The descriptor is the "Foundry instructs Chronicle" mechanism — every Foundry-specific assumption that would otherwise be hardcoded in Chronicle lives in this file instead, so the same Chronicle code can serve any future Foundry module (or other package type) without modification.

CI validates the descriptor on every push and pull request via tools/check-package-descriptor.mjs. The check enforces:

• chronicle-package.json is valid JSON with schemaVersion: 1
• package.id matches module.json#/id
• package.kind is "foundry-module"
• package.moduleJsonPath resolves to an actual file in the zip
• Endpoint templates include the required {campaign_id} and {token} placeholders
• Field types are correct

Bumping module.json#/id (rare) requires updating chronicle-package.json#/package/id in the same commit.

License

MIT