Plugins
Extend Fey-Gate with custom scripts — from small quality-of-life tools to full battle simulators for your favourite TTRPG system.
What Plugins Are
Custom Scripts, First-Class Citizens
Plugins are JavaScript files that extend Fey-Gate with new behavior — custom TTRPG system support, simulation tools, bespoke overlays, extra panels. They run inside the app against a documented API: they can read and move tokens, draw on the map canvas, store campaign data, add toolbar panels, and exchange messages in multiplayer sessions.
They Travel With Your Campaign
Plugins live as plain .js files inside your campaign folder. If you sync that folder between machines (Syncthing, Dropbox, a USB stick), your plugins come along — though each machine approves them independently.
The Flagship Example
Fey-Gate ships with a complete example plugin — the Naval Battle Simulator — that demonstrates every part of the API: ship tokens with headings and sails, wind, animated turn resolution, and cannon-arc overlays.
Installing Plugins
1. Grant Folder Access
Plugins load from your campaign folder, so the app needs File System Access. Open Settings → Storage and connect a project folder if you haven't already. (Chromium-based browsers only — the File System Access API is required.)
2. Create the plugins/ Subfolder
Inside your campaign folder, create a subfolder named plugins and drop plugin .js files into it:my-campaign/
assets/ ← image files
db/ ← mirrored campaign data
plugins/ ← your plugin .js files
3. Scan and Approve
Restart the app (or press Rescan plugins folder in Settings → Plugins). New files appear in the plugin list as untrusted. Click Review…, read what the plugin claims to be, and enable it. Nothing runs until you approve it.
The Trust Model
Plugins Can Do Anything the App Can
There is no sandbox. An enabled plugin runs with full access to everything Fey-Gate can touch — your campaign data, the canvas, the network session. Only enable plugin files from sources you trust, exactly as you would a mod for any desktop game.
Approval Is Per File Content
When you enable a plugin, Fey-Gate records a fingerprint (SHA-256 hash) of the exact file contents. If the file changes in any way — an update, an edit, or something tampering with it — the plugin stops loading and asks for re-approval, showing a changed status in Settings.
Approval Is Per Device
Trust decisions are stored on each machine, not in the synced folder. A plugin approved on your desktop still needs one-time approval on your laptop. This is deliberate: the folder can be modified by other machines, so each device decides for itself.
Misbehaving Plugins Are Contained
If a plugin throws an error while loading or running, Fey-Gate disables it, shows a toast naming the plugin, and carries on. One broken plugin never takes down the session or other plugins.
Plugins in Multiplayer
The DM's Plugins Are Offered to Players
When you join a session, your client learns which plugins the DM has enabled and asks you — once per plugin — whether to run each of them. Accepting downloads the code from the DM, verifies its fingerprint against what was announced, and runs it for the session. Accepting means trusting your DM's code: it runs with the same full access as a locally installed plugin.
Your Choices
Run plugin remembers this exact version — it won't ask again until the DM updates the file. Not now skips it for this session only. Never permanently silences this exact version. You can review and remove DM-sent plugins any time in Settings → Plugins, where they're marked from DM (this session).
Session-Only, Nothing Written to Disk
DM-sent plugin code lives in memory and unloads when the session ends or the DM disables the plugin. It is never written into your plugins folder or browser storage — only the accept/decline decision itself is remembered on your device.
Updates Re-Prompt
If the DM edits a plugin mid-campaign, its fingerprint changes and every player is asked again before the new version runs — the same rule as local files.
Managing Plugins
Settings → Plugins
Every discovered file is listed with its name, version, file name, fingerprint prefix, and status: loaded, disabled, untrusted, changed, or error. Enable and disable plugins with one click; disabling keeps the trust record so re-enabling is instant.
Rescan
The plugins folder is read at app start. After adding, editing, or deleting files while the app is open, press Rescan plugins folder to pick up the changes.
In the VTT
Plugins that register a panel add a button to the VTT toolbar. DM-only panels are invisible to connected players — in a session, plugin UI belongs to whoever runs the plugin.
Troubleshooting
The plugin list is empty
Check that folder access is granted (Settings → Storage), the subfolder is named exactly plugins, and the files end in .js. Then Rescan.
A plugin shows "error"
The error message is displayed on the plugin card. Typical causes: the file isn't an ES module with a default export, it targets a newer plugin API version, or its onLoad threw. Fix the file, Rescan, and re-approve.
A plugin keeps asking for approval
Something rewrites the file between scans — often a sync tool mid-transfer, or an editor that saves on a timer. Wait for sync to settle, then approve once.
Players don't see plugin effects
Each player must accept the plugin prompt when joining the session — check Settings → Plugins on their machine for a declined or missing entry (Remove + rejoin re-prompts). Effects that go through core features — token positions, rotations, images — sync to everyone regardless.