architecture.md

Architecture & build

What a plugin is

A Phaser Editor v5 plugin is a folder containing:

• a plugin.json manifest, and
• the JavaScript files (and optional CSS) the manifest lists.

There is no webpack and no runtime npm dependency.

myplugin.example/
├── plugin.json          # { id, scripts[], styles[] }
├── styles/              # optional CSS (registered in plugin.json "styles")
├── _out/                # build output (git-ignored)
│   └── myplugin.example.js
└── src/                 # TypeScript source (one namespace)
    ├── tsconfig.json    # outFile -> ../_out/<id>.js
    ├── ExamplePlugin.ts # the colibri.Plugin subclass
    └── editors/         # feature code

How loading works (two layers)

1. Discovery (server). On startup the editor scans its plugin directories. For every folder with a plugin.json, it injects the listed scripts and styles into the editor web page. Folders without a plugin.json (like types/) are ignored.
2. Registration (client). Your script runs in the page and calls colibri.Platform.addPlugin(MyPlugin.getInstance()). During startup the editor calls each plugin's registerExtensions(reg), where you contribute commands, editors, content types, views, and so on with reg.addExtension(new SomeExtension(...)).

The minimal plugin shape:

namespace myplugin.example {

    export class ExamplePlugin extends colibri.Plugin {

        private static _instance = new ExamplePlugin();

        static getInstance() { return this._instance; }

        constructor() { super("myplugin.example"); }

        registerExtensions(reg: colibri.ExtensionRegistry) {
            // reg.addExtension(new ...Extension(...));
        }
    }

    colibri.Platform.addPlugin(ExamplePlugin.getInstance());
}

TypeScript model: namespaces, not modules

• All files in one plugin live in the same namespace (e.g. myplugin.example) and are merged by the compiler. You can reference a class defined in another file directly — no import/export.

• The build uses outFile to concatenate everything into one _out/<id>.js. ES module syntax (import x from "...") would break this.

• To use a long namespace conveniently, alias it at the top of a file:

  import controls = colibri.ui.controls;
  import ide = colibri.ui.ide;

  (This is a TypeScript namespace alias, not an ES import.)

The bundled types

types/ holds snapshots of the editor API — one .d.ts per editor plugin (colibri.d.ts, phasereditor2d.files.d.ts, phasereditor2d.phaser.d.ts, and every other plugin). They let you compile against the full editor API without a checkout of the editor source.

• Treat them as the API source of truth. If a class/method isn't there, it isn't available to you.
• They are all included by myplugin.example/src/tsconfig.json via the ../../types/*.d.ts glob, so every plugin's API is in scope. (The /// <reference path=... /> at the top of ExamplePlugin.ts is just for editor IntelliSense.)

Updating the bundled types

A script regenerates the whole types/ folder from your editor source. Set PHASEREDITOR5_HOME to the folder that contains phaser-editor-v5:

export PHASEREDITOR5_HOME=/path/to/parent
npm run update-types

It copies every <plugin>/_out/<plugin>.d.ts from $PHASEREDITOR5_HOME/phaser-editor-v5/workbench/source/editor/plugins into types/. The editor must have been built first (its _out folders must exist).

Build, run, install

npm install      # once
npm run build    # tsc -b  -> _out/<id>.js
npm run watch    # rebuild on change
npm run clean    # remove build output

Make the editor load the plugin in any one of these ways:

• User plugins folder: cp -r myplugin.example ~/.phasereditor2d/plugins/ then restart the editor.
• Launcher flag (best for dev): PhaserEditor -plugins /path/to/template — the editor scans each subfolder for a plugin.json.
• Per-project: add the plugin path to the project's phasereditor2d.config.json plugins array.

Renaming the plugin

Change the id everywhere so the manifest, compiled file, namespace, and build reference stay in sync:

1. Rename the folder myplugin.example/ to your id (e.g. com.acme.tools).
2. plugin.json: set "id" and the scripts path.
3. src/tsconfig.json: update outFile to ../_out/com.acme.tools.js.
4. src/*.ts: rename the namespace, the super("...") id, and all command/category/content-type ids.
5. Root tsconfig.json: update the references path.

Use a unique, reverse-domain id to avoid clashing with other plugins.