Extension Manifest

The extension manifest defines what a tile displays, how users configure it, and how it communicates with other extensions. It is a JSON file referenced from the plugin manifest via $ref.

Required fields

Field	Type	Description
`id`	string	Unique identifier for the extension.
`label`	string	Display name in the extension picker.
`description`	string	Short description shown in the picker.
`category`	string	Picker category: `Audio`, `Character Sheets`, `Combat`, `Dice`, `Organization`, `VTT`, `Video`, or `Other`.
`version`	string	Semantic version (`X.Y.Z`).
`icon`	object	Icon image: `{ "$ref": "assets/icon.png" }`. Path resolves relative to the manifest file.
`source`	string or object	How content is loaded. See Source configuration.

Optional fields

Field	Type	Default	Description
`author`	string	–	Extension author. Format: `"Name <email>"`.
`baseUrl`	string	–	Base URL for URL template resolution (available as `{src}`).
`config`	object	–	User-configurable fields shown in the tile editor. See Config fields.
`permissions`	object	–	Events the extension can send and receive. See Permissions.
`transparent`	boolean	`false`	Render the tile with a transparent background.
`fullScreen`	boolean	`false`	Enable full-screen mode for the tile.
`visible`	boolean	`true`	Show the extension in the picker. Set `false` to hide.
`associatedFileTypes`	array	–	File types this extension can open. Each entry: `{ "mimeTypes": [...], "extensions": [...] }`. See example.
`consumes`	string[]	–	Dataset IDs this extension reads. Each entry must match `@pluginId:localId`. See Consuming datasets.

Source configuration

The source field determines how content loads in the tile.

Iframe

Loads a URL in an iframe. No SDK access.

{
  "source": "iframe",
  "iframe": {
    "src": "{config.url}",
    "style": { "width": "100%", "height": "100%" },
    "frameBorder": "0",
    "allow": "autoplay",
    "allowFullScreen": true
  }
}

The iframe object accepts standard HTML iframe attributes:

Attribute	Type	Description
`src`	string	URL to load. Supports URL templates.
`style`	object	Inline CSS styles.
`allow`	string	Permissions policy (e.g., `"autoplay; fullscreen"`).
`allowFullScreen`	boolean	Allow the iframe to enter fullscreen.
`referrerPolicy`	string	Referrer policy.
`frameBorder`	string	Frame border (`"0"` to hide).
`title`	string	Accessible title for the iframe.
`sandbox`	string	Sandbox restrictions.

Webview

Loads a URL with SDK access. Enables the event system.

{
  "source": "webview",
  "webview": {
    "src": "https://example.com/room/{config.roomId}"
  }
}

Field	Type	Description
`src`	string	URL to load. Supports URL templates.
`injectJavaScript`	string	JavaScript to inject into the page. Triggers a user permission prompt.

Bundled

Loads local HTML files shipped with the plugin. Has SDK access.

{
  "source": { "$ref": "dist/index.html" }
}

The $ref path resolves relative to the manifest file’s directory.

URL templates

Insert dynamic values into source URLs with {path.to.value} syntax. Templates are resolved before the URL is loaded.

Template	Resolves to
`{config.fieldName}`	The user-configured value for `fieldName`.
`{src}`	The resolved base URL (from `baseUrl`).

Templates can be combined: "{src}/campaign/{config.campaignId}".

If a template variable has no value, the placeholder remains as-is.

Config fields

Config fields create user-editable inputs in the tile editor. The config object maps field names to field definitions.

Common properties

Property	Type	Default	Description
`type`	string	–	(Required) Field type. See Field types.
`required`	boolean	`false`	Whether the field must have a value.
`label`	string	–	Display label in the editor.
`description`	string	–	Help text below the field.
`placeholder`	string	–	Placeholder text when empty.
`defaultValue`	string, number, or boolean	–	Pre-filled default value.
`hidden`	boolean	`false`	Hide this field from the editor UI.
`autoFocus`	boolean	`false`	Focus this field when the editor opens.
`transform`	object	–	Advanced. A `$ref` to a JavaScript function that transforms the value before it reaches the extension.

Field types

`string`

Text input.

{ "type": "string", "label": "Room ID", "placeholder": "Enter room ID" }

`url`

URL input. Automatically adds https:// if no protocol is provided.

{ "type": "url", "label": "Sheet URL", "placeholder": "https://www.dndbeyond.com/characters/12345" }

`number`

Numeric input.

{ "type": "number", "label": "Initiative Bonus", "defaultValue": 0 }

`checkbox`

Boolean toggle.

{ "type": "checkbox", "label": "Show hit points", "defaultValue": true }

`color`

Color picker.

{ "type": "color", "label": "Accent Color", "defaultValue": "#e63946" }

`json`

JSON editor for structured data.

{ "type": "json", "label": "Custom Data" }

`select`

Dropdown menu. options can be an array of { label, value } objects, or the string "font-family" to populate with available fonts.

{
  "type": "select",
  "label": "Dice Type",
  "defaultValue": "d20",
  "options": [
    { "label": "d4", "value": "d4" },
    { "label": "d6", "value": "d6" },
    { "label": "d8", "value": "d8" },
    { "label": "d10", "value": "d10" },
    { "label": "d12", "value": "d12" },
    { "label": "d20", "value": "d20" }
  ]
}

`file`

File picker. Optional accept restricts file types.

{ "type": "file", "label": "Token Image", "accept": ".jpg,.png,.gif,.webp" }

Permissions

Permissions declare which events the extension can send and receive through the event system. Only relevant for webview and bundled extensions.

{
  "permissions": {
    "send": ["dice-result", "status-update"],
    "receive": ["dice-roll", "combat-start"]
  }
}

Field	Type	Description
`send`	string[]	Event names this extension can broadcast via `Overseer.send()`.
`receive`	string[]	Event names this extension can listen for via `Overseer.subscribe()`.

Consuming datasets

Extensions can read datasets that plugins publish – monster stat blocks, spell lists, remote API endpoints. Declare each dataset you read in the consumes array:

{
  "consumes": [
    "@me/dnd5e-srd:monsters",
    "@me/dnd5e-srd:monsters-live"
  ]
}

Each entry must be a dataset ID in the format @pluginId:localId.

If a user has your extension installed but not the plugin that provides a listed dataset, Overseer shows a warning in the Plugin Manager and a toast on startup. The extension still loads; the warning is informational.

Read the data at runtime through the SDK’s Data API. See Datasets for how datasets are declared by plugins and Data Providers for the full model.

Associated file types

Declare file types your extension can open. Each entry specifies MIME types and/or file extensions:

{
  "associatedFileTypes": [
    { "mimeTypes": ["application/pdf"], "extensions": [".pdf"] },
    { "mimeTypes": ["image/png", "image/jpeg"], "extensions": [".png", ".jpg", ".jpeg"] }
  ]
}

Complete examples

Iframe extension – Video player

{
  "id": "@myname/video-player",
  "version": "1.0.0",
  "category": "Video",
  "label": "Video Player",
  "description": "Embed any video URL.",
  "icon": { "$ref": "assets/icon.png" },
  "source": "iframe",
  "iframe": {
    "src": "{config.url}",
    "style": { "width": "100%", "aspectRatio": "16/9" },
    "frameBorder": "0",
    "title": "Video player",
    "allow": "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture",
    "referrerPolicy": "strict-origin-when-cross-origin",
    "allowFullScreen": true
  },
  "config": {
    "url": {
      "type": "url",
      "required": true,
      "label": "Video URL",
      "placeholder": "https://www.youtube.com/embed/dQw4w9WgXcQ",
      "autoFocus": true
    }
  }
}

Webview extension – Dice roller with events

{
  "id": "@myname/dice-roller",
  "version": "1.0.0",
  "category": "Dice",
  "label": "Dice Roller",
  "description": "Roll dice and share results with other extensions.",
  "icon": { "$ref": "assets/icon.png" },
  "source": "webview",
  "webview": {
    "src": "https://dice.example.com/room/{config.roomId}"
  },
  "config": {
    "roomId": {
      "type": "string",
      "required": true,
      "label": "Room ID",
      "placeholder": "Enter your room ID"
    }
  },
  "permissions": {
    "send": ["dice-result"],
    "receive": ["dice-roll"]
  }
}

Bundled extension – Initiative tracker

{
  "id": "@myname/initiative-tracker",
  "version": "1.0.0",
  "category": "Combat",
  "label": "Initiative Tracker",
  "description": "Track turn order during encounters.",
  "icon": { "$ref": "assets/icon.png" },
  "source": { "$ref": "dist/index.html" },
  "config": {
    "columns": {
      "type": "select",
      "label": "Columns",
      "defaultValue": "compact",
      "options": [
        { "label": "Compact", "value": "compact" },
        { "label": "Full", "value": "full" }
      ]
    },
    "showHp": {
      "type": "checkbox",
      "label": "Show hit points",
      "defaultValue": true
    }
  },
  "permissions": {
    "send": ["turn-changed", "combat-ended"],
    "receive": ["combat-start", "dice-result"]
  }
}

Publishing a Plugin

Building Extensions

Developers

Overseer Studio

Title here

Extension Manifest

Required fields

Optional fields

Source configuration

Iframe

Webview

Bundled

URL templates

Config fields

Common properties

Field types

`string`

`url`

`number`

`checkbox`

`color`

`json`

`select`

`file`

Permissions

Consuming datasets

Associated file types

Complete examples

Iframe extension – Video player

Webview extension – Dice roller with events

Bundled extension – Initiative tracker

Extension Manifest

Required fields#

Optional fields#

Source configuration#

Iframe#

Webview#

Bundled#

URL templates#

Config fields#

Common properties#

Field types#

string#

url#

number#

checkbox#

color#

json#

select#

file#

Permissions#

Consuming datasets#

Associated file types#

Complete examples#

Iframe extension – Video player#

Webview extension – Dice roller with events#

Bundled extension – Initiative tracker#

Required fields

Optional fields

Source configuration

Iframe

Webview

Bundled

URL templates

Config fields

Common properties

Field types

`string`

`url`

`number`

`checkbox`

`color`

`json`

`select`

`file`

Permissions

Consuming datasets

Associated file types

Complete examples

Iframe extension – Video player

Webview extension – Dice roller with events

Bundled extension – Initiative tracker