Plugin settings

At the top of edittime.js is the function GetPluginSettings() which tells Construct 2 some important information about the plugin or behavior. Here is the settings function for Sprite:

    function GetPluginSettings()
    {
    	return {
    		"name":			"Sprite",
    		"id":			"Sprite",
    		"version":		"1.0",
    		"description":	"An animated object that is the building block of most projects.",
    		"author":		"Scirra",
    		"help url":		"http://www.scirra.com",
    		"category":		"General",
    		"type":			"world",
    		"rotatable":	true,
    		"flags":		pf_animations | pf_position_aces | pf_size_aces | pf_angle_aces | pf_appearance_aces
    	};
    };

Each field is as follows:

name
This is the name of your plugin as it appears in the dialogs in Construct 2. Note it is separate to the id.

id
This is a string identifying your plugin. All plugins must have a unique id. The id, not the name, is saved in the project XML to identify a plugin. This means you can safely change the plugin's name without breaking existing projects. However, if you change the id, Construct 2 will consider it to be a different kind of plugin, and all existing projects using the plugin will no longer load. Therefore, you should choose an appropriate id when starting development of a new plugin, and never change it.

version
This is a float in the format x.y which identifies the version of your plugin. You should keep this updated whenever you make a new release. Construct 2 uses it to verify projects are compatible when opening. For example, Construct 2 will show a warning if a project was saved with version 2 of a plugin, but is opened with version 1 of the plugin installed.

description
Some text describing the purpose of the plugin. This is displayed in the dialog when choosing a plugin.

author
You or your organisation.

help url
When the user clicks 'help' in the editor for your plugin, this is the URL they are sent to.

category
In the editor dialogs, all plugins and behaviors are grouped in to categories. This specifies which category your plugin belongs to. It is advisable to use an existing category whenever relevant, but you can set this to anything you like and Construct 2 will put it in its own category. The category is case sensitive.

type (not used in behaviors)
This can take one of the following values, depending on what kind of plugin you want to make:

"world"
The plugin appears in the layout, and therefore draws something to the screen (e.g. Sprite, Tiled Background, Text).

"object"
The plugin does not appear in the layout, and therefore does not draw anything (e.g. Array). The draw methods will not be called, and the user cannot place the object in the layout - they must access it via the Object Bar or Project Bar.

rotatable (not used in behaviors)
When the type is "object", this setting is ignored. When the type is "world", this specifies if the object has an angle. The user may also rotate the object in the layout editor. For example, Sprite is rotatable, but Text is not.

flags
Flags describing additional settings. These can be combined with bitwise OR (e.g. pf_position_aces | pf_size_aces), or set to 0 for no flags. The following flags are available for plugins:

pf_singleglobal
Specifies a single global type of plugin. When inserted, these are available project-wide, and there is only ever one instance of the object (additional instances cannot be created). This is ideal for input objects or other non-object based features, e.g. Mouse, Keyboard, Audio. pf_singleglobal cannot be used with "world" type plugins.

pf_texture
The plugin uses a single texture. Tiled Background uses this flag. Construct 2 will open the image editor when inserting the plugin.

pf_animations
The plugin uses Construct 2's animation system. Sprite uses this flag. Construct 2 will open the animations editor when inserting the plugin.

pf_tiling
Only valid when pf_texture or pf_animations is also used. Specifies that the plugin will tile its texture. This alters the image editor's functionality to better suit tiled textures. Tiled Background uses this flag.

pf_position_aces
Only valid with "world" type plugins. Automatically inherit actions, conditions and expressions for the object position (such as Set X and Set Y).

pf_size_aces
Only valid with "world" type plugins. Automatically inherit actions, conditions and expressions for the object size (such as Set Width and Set Height).

pf_appearance_aces
Only valid with "world" type plugins. Automatically inherit actions, conditions and expressions for the object appearance (such as Set Visible and Set Opacity).

pf_zorder_aces
Only valid with "world" type plugins. Automatically inherit actions, conditions and expressions for the object Z order (such as Set Layer and Move To Front).

The following flags are available for behaviors:

bf_onlyone
The behavior can only be added to an object once. Normally the user can add a behavior as many times as they like, but this flag prevents them from adding it again. For example, the Solid behavior uses this flag, because it does not make sense for an object to have two Solid behaviors.

dependency
This one isn't listed above, but if you need external files bundled with your plugin (e.g. a javascript library) you can specify one or more dependency files with:

    "dependency": "file1.js;file2.js;file3.html"

You must provide these files in the plugin's folder. Construct 2 will then copy them out when exporting the project, and make them available on the preview server for testing. Construct 2 will also automatically insert a script tag in to the HTML page before the runtime for any files ending in .js, so you do not need to worry about loading them yourself.

Changes after publishing

You should not change the id, type, rotatable or flags settings after releasing your plugin or behavior (other than to add new 'aces' flags), as this will break all existing projects using it. All the other settings can be changed at any time.

Tags: