A plugin is a directory containing a root manifest.json and whatever assets it needs — icons, CSS files, HTML, JavaScript, translation files, or images. Installing a plugin makes its extensions, themes, locales, and presets available in Overseer.

Plugins directory

Plugins live in the Plugins/ subdirectory of the Overseer data directory. You can find (and change) the data directory path in Settings > Data and Storage.

Default locations:

Discovery

Overseer scans Plugins/ for manifest.json files at startup. Once it finds a manifest in a directory, it stops scanning deeper into that directory’s subdirectories — the manifest marks the plugin root.

You can organize plugins however you like. Scoped directories are a common convention:

Plugins/
  @yourname/
    session-timer/
      manifest.json
    dice-roller/
      manifest.json
  @someone-else/
    encounter-music/
      manifest.json

The $ref system

Manifests use { "$ref": "path/to/file" } to reference external files. Paths resolve relative to the directory containing the manifest.

• JSON files (.json) are parsed and merged inline — this is how plugin manifests reference extension and preset manifests.
• Other files (.css, .ftl, .png, .html) are loaded as-is — this is how themes reference CSS, locales reference .ftl files, and icons reference images.

Plugin structure

A typical single-extension plugin:

@yourname/session-timer/
  manifest.json             ← plugin manifest
  extensions/
    session-timer/
      manifest.json         ← extension manifest
      index.html
      assets/
        icon.png

A plugin with multiple content types:

@yourname/gm-toolkit/
  manifest.json
  extensions/
    dice-roller/
      manifest.json
      assets/icon.png
    initiative-tracker/
      manifest.json
      index.html
      assets/icon.png
  themes/
    dark-dungeon.css

Plugin manifest

For a complete reference of every field in the plugin manifest, see the Plugin Manifest reference.