Plugin files (studio.json and plugin descriptors)

Experimental. A project can add its own tools and editors to cTurtle Studio, written in BT. studio.json in the project root lists them; each entry points to a plugin descriptor that names the plugin's BT source. How plugins work is covered in Game plugins; this page lists the file fields.

Only Studio reads these files. Exported games don't include them unless you add them to package.copy.

Example

studio.json:

{
  "plugins": ["studio/plugins/authoring/plugin.json"]
}

studio/plugins/authoring/plugin.json:

{
  "id": "mygame.authoring",
  "name": "My Game authoring tools",
  "version": "0.1.0",
  "studio_api": 1,
  "source": "main.bt",
  "requires": ["ui.embedded", "views.tools", "documents.transactions"]
}

studio.json

Field	Type	Default	Description
format	object	none	Optional file format version.
plugins	array of strings	[]	Paths to plugin descriptors, relative to the project root. Loaded in this order.

Without studio.json, the project has no plugins. Studio doesn't search folders for plugins; only listed descriptors load.

Plugin descriptor

Field	Type	Default	Description
studio_api	integer	—	Required. Must be 1.
format	object	none	Optional file format version.
id	string	—	Required. Unique plugin ID: 1–128 characters from letters, digits, ., - and _. Keep it stable; saved layouts and shortcuts refer to it.
source	string	—	Required. The plugin's entry .bt file, relative to the descriptor. It must define studioPluginMain.
requires	array of strings	[]	Studio features the plugin uses; see Capabilities.
name	string	—	Display name. Currently unused.
version	string	—	Your plugin's own version, such as "0.1.0". Not a file format version. Currently unused.
program	string	—	Not implemented. A descriptor with program is rejected.

Paths (in plugins and source) must be relative, with no . or .. parts and no drive letters. \ is accepted as a separator.

Capabilities

List what your plugin uses in requires. Studio refuses a plugin that asks for something it doesn't offer, so this catches a plugin written for a newer Studio. It doesn't limit what the plugin can do.

Capability	Lets the plugin
ui.embedded	Show its UI inside Studio's docks.
views.tools	Add tool views that open with the project.
views.factories	Add views that are created when the user opens them.
editors.documents	Provide editors for project files ("Open With").
documents.transactions	Make grouped edits to documents (one Undo step).
documents.changes	Be notified when a document changes.
documents.save	Ask Studio to save a document.
source.reveal	Jump to a location in the Source Editor.
assets.project	Show project images.
games.run	Start the game in Studio's Play session.

Errors

Errors appear in Problems under Plugins and in the status bar. One broken plugin doesn't stop the others from loading.

Message	Cause
studio.json: "schema": 1 is no longer used (also plugin descriptor: …)	Delete the schema line (an older file).
studio.json uses format version X; this cTurtle reads format … (also plugin descriptor …)	The file was written for a newer Studio; see File format versions.
Invalid plugin ID: <id>	id empty, too long, or has other characters.
Duplicate plugin ID: <id>	Two descriptors use the same id.
Unsupported Studio API	studio_api isn't 1.
Plugins currently require one source package	source is missing, or program is present.
Plugin capability unavailable: <name>	requires lists an unknown capability.
document URI must be project-relative / cannot contain dot segments	A path breaks the path rules above.
Plugin source package failed to load	Your plugin's BT code has errors.
studioPluginMain returned without activating its tools	Call studio_plugin_activate() before studioPluginMain returns.
Plugin bootstrap timed out after 10000 ms without activating its tools	The plugin took more than 10 seconds to activate.
Duplicate tool view: <view>	Two tools have the same ID.

See also

• Game plugins
• cturtle/studio
• game.json, .ctproject