plugin.json

The complete reference for plugin.json, the manifest in every plugin folder. For an explanation with examples, see The manifest. The file is JSON; comments (// and /* */) and trailing commas are allowed, and property names are case sensitive.

Fields

Field	Type	Required	Default	Description
id	string	yes		Unique, stable id: lowercase letters and digits in groups separated by ., - or _, such as coral-cove.spinners.
name	string	no	the id	Name shown in the editor.
version	string	no	1.0.0	The plugin's version, major[.minor[.patch]]; missing parts are 0.
description	string	no	empty	One or two sentences shown on the plugin's card.
authors	list of strings	no	empty	Shown on the plugin's card.
license	string	no		Ideally an SPDX expression, such as MIT.
homepage	string	no		An absolute http or https address. The card links to it.
icon	string	no		An image file inside the plugin folder, such as icon.png, shown on the card.
assembly	string	yes		File name of the runtime assembly, a .dll directly in the plugin folder.
editorAssembly	string	no		File name of the editor assembly, a different .dll directly in the plugin folder. Only the editor loads it.
contractVersion	integer	yes		The engine contract version the plugin was built against, 1 or more. Must equal the engine's (1) or the plugin is skipped.
minEngineVersion	string	no	any	The oldest engine version the plugin runs on, such as 0.1.0.
dependencies	list of objects	no	empty	Other plugins this plugin uses; see below.
permissions	list of strings	no	empty	Permission names; see Permissions.
extensions	list of strings	no	empty	Extension point ids the plugin contributes to, shown on its card; see Extension ids.
assets	string	no		A folder inside the plugin folder with files the plugin ships.
enabled	boolean	no	true	false installs the plugin switched off until a game's plugins.json lists it under enabled.

Paths in icon and assets are relative to the plugin folder, use / or \, and may not contain .., a drive or a root.

Dependency objects

Field	Type	Required	Default	Description
id	string	yes		The dependency's plugin id.
version	string	no	*	A version range the installed version must satisfy.
optional	boolean	no	false	Whether the plugin also loads without the dependency.
minimumVersion	string	no		Older form of "version": ">=…"; not together with version.

Permission names

fileSystem, network, processExecution, editorUi, runtimeScene, assetWrite, renderBackend. See Permissions for what each means and what is checked.

Extension ids

The well-known ids, with the name the editor shows for them. Other ids in the same format are allowed, such as an extension point of another plugin.

Id	Shown as
systems	Systems
components	Components
scripts	Script types
scenes	Scenes
scene.listeners	Scene lifecycle hooks
services	Services
importers	Asset importers
overlays	Game overlays
particles.modules	Particle modules
lighting	Lighting features
render.passes	Render passes
editor.panels	Editor panels
editor.commands	Editor commands
editor.menus	Menu entries
editor.toolbar	Toolbar items
editor.inspectors	Inspector property editors
editor.tools	Viewport tools
tile.tools	Tile map tools

The constants are in PluginExtensionPoints. The list is informational: it does not change what the plugin can register.

Version range syntax

Range	Accepts
1.2.3, =1.2.3	exactly 1.2.3
1.2, 1.2.x, 1.2.*	1.2.0 up to, not including, 1.3.0
>1.2.3, >=1.2, <2.0, <=1.2	comparisons; a partial version stands for all its versions, so <=1.2 is below 1.3.0 and >1.2 from 1.3.0
^1.2.3	1.2.3 up to 2.0.0; for 0.x, up to the next minor (^0.2.3 is below 0.3.0) and for 0.0.x only that patch
~1.2.3, ~1.2	1.2.3 (or 1.2.0) up to 1.3.0
>=1.2 <2.0	space-separated comparisons must all hold
1.0 || ^3.0	either side of ||
*, x	any version

More examples and their results are in Dependencies and versions.

Examples

A minimal manifest:

plugin.json

{
  "id": "acme.weather",
  "assembly": "Weather.dll",
  "contractVersion": 1
}

The manifest of the cutscene sample:

samples/Talesmith.Samples.Cutscenes/plugin.json

{
  "id": "samples.cutscenes",
  "name": "Cutscenes and dialogue",
  "version": "1.0.0",
  "description": "Plays scripted cutscenes with camera moves and dialogue choices when the player enters a map trigger with a 'cutscene' property.",
  "authors": [ "Talesmith" ],
  "assembly": "Talesmith.Samples.Cutscenes.dll",
  "contractVersion": 1,
  "minEngineVersion": "0.1.0",
  "permissions": [ "runtimeScene" ],
  "extensions": [ "importers", "systems", "scene.listeners", "overlays", "services" ]
}

A manifest with every field:

plugin.json

{
  "id": "coral-cove.spinners",
  "name": "Spinners",
  "version": "1.2.0",
  "description": "Turns entities with a Spinner component, with editor tools to place and tune them.",
  "authors": [ "Dylan de Beer" ],
  "license": "MIT",
  "homepage": "https://example.com/spinners",
  "icon": "icon.png",
  "assembly": "Spinners.dll",
  "editorAssembly": "Spinners.Editor.dll",
  "contractVersion": 1,
  "minEngineVersion": "0.1.0",
  "dependencies": [
    { "id": "samples.hexquest", "version": "^1.0", "optional": true }
  ],
  "permissions": [ "runtimeScene", "editorUi" ],
  "extensions": [ "components", "systems", "editor.panels", "editor.commands", "editor.tools" ],
  "assets": "assets",
  "enabled": true
}

Validation errors

A manifest with errors makes the plugin Failed; the reason starts with the file's path and is invalid:, then lists every problem. Messages, with x standing for the value found:

Field	Message
the file	is not valid JSON: … (the parser's message)
the file	the file must contain a JSON object.
any	unknown property "x"; did you mean "y"? or unknown property "x" (expected one of: …).
any string	x must be a string.
id	id is required., id must not be empty.
id	id "x" must be lowercase letters and digits separated by '.', '-' or '_', such as "talesmith.cutscenes".
version, minEngineVersion	version "x" must be a version such as "1.2.0".
authors	authors must be a list of names, such as ["Ada Lovelace"].
homepage	homepage "x" must be an http or https address, such as "https://example.com/my-plugin".
icon	icon "x" must be an image file inside the plugin folder, such as "icon.png", without ".." or a drive or root.
assets	assets "x" must be a folder inside the plugin folder, such as "assets", without ".." or a drive or root.
assembly, editorAssembly	assembly is required., assembly "x" must be the file name of a .dll in the plugin folder, such as "MyPlugin.dll".
editorAssembly	editorAssembly must be a separate assembly from assembly, so games never load editor code.
contractVersion	contractVersion is required (this engine uses 1)., contractVersion must be a whole number such as 1.
dependencies	dependencies must be a list such as [{ "id": "talesmith.dialogue", "version": "^1.0" }].
dependencies	dependencies[0] must be an object with an id, an optional version range and an optional "optional" flag.
dependencies	dependencies[0] id is required., dependencies[0] id "x" is not a valid plugin id., a plugin cannot depend on itself.
dependencies	dependencies[0] version: … followed by a range error below
dependencies	dependencies[0] has both version and minimumVersion; use only version, such as ">=1.0.0".
dependencies	dependencies[0] minimumVersion "x" must be a version such as "1.0.0"., dependencies[0] optional must be true or false.
dependencies	dependency "x" is listed more than once.
permissions	permissions must be a list of permission names (fileSystem, network, …).
permissions	permission "x" is unknown; did you mean "y"?, permission "x" is listed more than once.
extensions	extensions must be a list of extension point ids, such as ["systems", "editor.panels"].
extensions	extension "x" must be lowercase letters and digits separated by '.', '-' or '_', such as "editor.panels"., extension "x" is listed more than once.
enabled	enabled must be true or false.

Range errors:

Message	Cause
a version range must not be empty; use "*" for any version.	"version": ""
"1.0 ||" has an empty alternative around "||".	nothing on one side of ||
"-" in "1.0 - 2.0" is not a version or comparison; use forms such as "1.2.0", "^1.2", "~1.2", ">=1.2 <2.0" or "*".	a part that is not a version or comparison, including pre-release tags

These do not invalidate the manifest but are shown as warnings on the plugin:

Warning	Cause
it ships an editor assembly (X.dll) but does not declare the "editorUi" permission.	editorAssembly without editorUi
its assets folder "x" does not exist.	assets names a missing folder
its icon "x" does not exist.	icon names a missing file
its editor assembly X.dll was not found, so its editor features are unavailable.	editorAssembly names a missing file (editor only)

Related

• The manifest
• Dependencies and versions
• Plugin files