Using plugins

General idea

Starting with Mar 2019 update, GMEdit supports plugins.

For convenience and implementation constraints, GMEdit plugins are pretty much just JavaScript running in program's scope, so treat them as executables (with caution).

Installing plugins

Much like themes, plugins are installed by placing their directories into "plugins" directory in GMEdit's application data directory (%APPDATA%\AceGM\GMEdit\plugins on Windows, /Users/username/Library/Application Support/AceGM/GMEdit/plugins on macOS). You can quickly get to the directory by clicking "manage" next to theme list in Preferences, going one folder up, and then entering the "plugins" folder.

Expected layout is like so:

plugins/
plugins/myplugin/
plugins/myplugin/config.json
plugins/myplugin/myplugin.js

Plugins are loaded on startup. When developing plugins, you can force-restart GMEdit by pressing Ctrl+Shift+R with developer tools (Ctrl+Shift+I) focused.

Making plugins

A plugin consists of a config.json file, one or more JS files, and zero or more CSS files.

config.json structure is as following:

{
    "name": "plugin-name",
    "scripts": ["one.js", "two.js"],
    "stylesheets": ["one.css", "two.css"],
    "dependencies": ["other-plugin-name"]
}

• name is a unique plugin identifier. One of your JS files will need to call GMEdit.register with the same name.
• scripts is an array of relative paths to your plugin's JS files (usually in same directory)
• stylesheets (optional) is an array of relative paths to your plugin's CSS files (if any)
• dependencies (optional) is an array of names of plugins that should be loaded before yours (if any)

Startup

As previously mentioned, plugins are pretty much plain JS, so a simple plugin may look like so:

(function() {
    GMEdit.register("plugin-name", {
        init: function() {
            window.alert("hello!");
        }
    });
})();

GMEdit.register matches your plugin name to a data-object that can be accessed by GMEdit (or other plugins).

The most important thing here is the init function, which will be called after all of your plugin's files and dependencies have finished loading, and it's good to go.

API

• Supported plugin data-object fields (passed to GMEdit.register)
• General GMEdit events - these are used like so:

  GMEdit.on("projectOpen", function(e) {
    console.log("Project opened: ", e.project);
  });
  // and GMEdit.off to unbind

• Global GMEdit class
• Ace: ace global object, aceEditor (GMEdit's primary editor instance), GMEdit.aceTools (GMEdit-specific helpers)
• Anything else: you can access arbitrary Haxe-generated code through $gmedit object - for example, if you wanted to call Preferences.open(), you would do $gmedit["ui.Preferences"].open().
  For repeated access you would usually assign a Haxe class into a variable in your plugin.

Examples

GMEdit comes with a set of example plugins that you can pick apart

• ini-editor: introduces a new Ace syntax highlighter and binds it to several file types.
• image-viewer: introduces a non-code custom editor.
• gen-enum-names: introduces a macro to command palette (Ctrl+Shift+T) to work with code editor.
• show-aside: a demo of instantiating new Ace editors and carrying over editor sessions to them.
• gms2-sort: introduces a treeview menu item for sorting GMS2 resources
• outline-view: a bigger plugin - displays an outline/document map for quick navigation in sidebar.