Runtime functions

First of all, in runtime.js there are two places you must change to insert your plugin ID. Assuming the script is unmodified, these are on lines 9 and 16:

// line 9
cr.plugins_.MyPluginID = function(runtime)
// ...
// line 16
var pluginProto = cr.plugins_.MyPluginID.prototype;

In both cases you must replace MyPluginID with the plugin ID you specified in edittime.js. Remember to note that the ID must be unique to your plugin, and must not change after release (else all existing projects will break).

Classes

The first part of the script fairly straightforwardly defines three classes: the Plugin class, the Type class, and the Instance class. These represent the plugin, an object type, and an instance of an object type respectively. For example, "Sprite" is a kind of plugin. "Ogre", "Monster" and "Troll" may be three object types in a game, based on the Sprite plugin. In the layout there may be one Ogre, three Monsters and five Trolls - these are the instances of the object types. There is only ever one Plugin class instantiated for a project, and if your plugin flags specify pf_singleglobal, there is also only ever one object type and one instance.

You can store whatever you like in each class as necessary, but note you must not remove the runtime required members (e.g. references back to the runtime or plugin). You may also extend the prototypes of each with your own functions.

onCreate()

Each plugin, type and instance class has an onCreate method. These are called after Construct 2 has added any of its own properties to the objects. The object creation always goes:

constructor -> add Construct 2's properties -> onCreate()

For example, the runtime adds the x, y, width and height properties to world instances. These are not yet added in the constructor, but can be accessed in onCreate(). After onCreate(), your object is sealed by the runtime (see Object sealing in Runtime overview).

onDestroy() and object recycling

To reduce garbage collector overhead, Construct 2 often recycles instance objects (for both plugins and behaviors). This means the instance constructor may be re-called on a previous instance of your object, rather than a new empty javascript object. You should be aware of this - especially the fact the previous instance has already been sealed - when designing plugins and behaviors. You can also take advantage of it to help reduce garbage collector overhead, for example by testing for the existence of members in the constructor and re-using them where possible.

When your instance is destroyed at runtime, Construct 2 calls the instance's onDestroy() method if it has one. However, the object is likely still referenced in the cache for object recycling. This creates a possible problem in that even after being destroyed, the instance still exists. To save memory, you should release references to any large arrays or objects in onDestroy(). Further, you must release references to other objects in the runtime in onDestroy(), otherwise you may have dangling reference bugs. For example, the Platform behavior stores a reference to the last floor object the player landed on. This reference is set to null in onDestroy().

draw(ctx) and drawGL(glw)

If your instances appear in the layout, they need to draw themselves. The draw method has a canvas 2D context as a parameter. This context has already been translated and scaled as necessary - you simply need to draw your instance according to its x, y, width, height etc. members. The drawGL method is used when WebGL is enabled. Instead of passing the low-level WebGL context itself, a wrapper class is passed - see GLWrap.js in the install directory for a list of methods, or see how the built-in plugins draw in WebGL mode. You should make sure your plugin draws identically in both Canvas 2D and WebGL mode.

If any of your plugins actions or other functions cause a change in the rendering, you must set

this.runtime.redraw = true;

The canvas does not automatically draw every tick. Do not set the flag if the change has no effect on rendering, since this will trigger a wasteful redraw.

Bounding boxes

If you change an object's size, position or angle, its axis-aligned bounding box changes. You must indicate this to Construct 2 by following with a call to

instance.set_bbox_changed();

If you do not call this, you will cause bugs where objects do not collide properly, disappear near the edge of the screen, and so on. Try not to forget this. It must be called immediately following any changes. Example:

instance.x += 1;
instance.y += 1;
instance.set_bbox_changed();

Tags: