Actions, Conditions and Expressions

These are often called ACEs for short, or ACE to refer to 'an action, condition or expression'. In your edittime.js, you can specify any ACEs your plugin or behavior uses. Remember behavior ACEs are merged with the object's ACEs in the editor dialog.

Parameters

If your ACE takes parameters, you must first add them using the following functions. The name and description parameters are required for all parameters. The name appears as a label to the left of the parameter. The description appears at the top of the dialog when the parameter has focus. The description is actualy very important: you can save the user a trip to the manual by including some vital information, like the units being used (e.g. pixels vs. texture coordinates). Try to include anything the user might wonder about the parameter in the description. Hopefully you'll have found descriptions useful in using Construct 2 - try to do the same with your parameter descriptions!

Some parameters also take an initial_str. This is an optional string (always a string, even for number parameters) that is pasted in to the parameter as a default. Try to set a common or useful default, e.g. "100" for a percentage. This can also help save the user time and also indicate what a reasonable entry is. Never let the default give a syntax error! If not provided, it is 0 for number/any type parameters, and "" (an empty string) for strings.

All parameters also take an optional id number parameter at the end. This should not normally be used, but can allow you to modify parameters after releasing your plugin. All parameter ids are by default their index, and you can maintain compatibility with existing projects by explicitly assigning ids to match old parameters to new ones.

Parameters are all passed to the corresponding runtime function as ordinary javascript values. They are passed in the same order as they are added with these functions.

AddNumberParam(name, description, initial_str);

A typed number parameter, which accepts integers or floats.

AddStringParam(name, description, initial_str);

A typed string parameter.

AddAnyTypeParam(name, description, initial_str);

A typed parameter that accepts either integers, floats or strings. Wherever possible, prefer number or string parameters, since they force the correct type to be entered, reducing the chance of a mistake. The runtime function must check the actual type passed using javascript's typeof operator.

AddCmpParam(name, description);

A combo box parameter with the following standard items: Equal, Not equal, Less, Less or equal, Greater, Greater or equal.

AddComboParamOption(text);

AddComboParam(name, description, initial);

A combo box parameter with custom items. Call AddComboParamOption once per item before AddComboParam to set the items. Note initial specifies the integer index of the default item, rather than a string like other parameters. The runtime function receives the integer index of the chosen item.

AddObjectParam(name, description);

A button that allows the user to pick an object type in the project. The runtime function receives a reference to the object type in the runtime. Construct 2 may also pass null for this parameter, so always check the parameter is not null before using it.

AddLayerParam(name, description);

A typed parameter where the user can enter a layer's name (string), or number (0-based index). The runtime receives a reference to the layer in the runtime. Construct 2 may also pass null for this parameter so always check the parameter is valid before using it.

AddLayoutParam(name, description);

A combo box with all the layouts in the project. The runtime receives a reference to the layout in the runtime. Construct 2 may also pass null for this parameter so always check the parameter is valid before using it.

AddKeybParam(name, description);

A button the user can click and hit a key. The runtime receives the virtual key (VK) code.

AddAnimationParam(name, description, initial_str);

A typed string parameter where the user can enter the name of one of the object's animations. Only valid when the plugin specifies pf_animations. Construct 2 may also pass null for this parameter so always check the parameter is not null before using it.

AddAudioFileParam(name, description);

A combo box with all the audio files in the project. The runtime receives a string of the filename without the extension. For example, if MyFile.ogg is chosen, then "MyFile" is passed. If the browser supports Vorbis, you should append .ogg; if not, append .m4a. The .m4a file is not guaranteed to exist: Construct 2 considers .ogg files to be the project's audio files, and .m4a are only used as a backup for .ogg files if the browser does not support Vorbis. However, the user may not have created a .m4a backup file.

AddCondition(id, flags, list_name, category, display_string, description, script_name);

id

A number uniquely identifying this condition. This is saved to the project XML, so you may change the rest of the parameters after releasing your plugin, but not the id.

flags

This may be zero for no flags, or a combination of the following values combined with bitwise OR (|):

cf_trigger

A triggered condition. Events with triggers are not evaluated every tick; instead, they are run by the runtime.trigger() function. There are some limitations on triggers: an event cannot contain two triggered conditions, and a trigger is always the first condition.

cf_fake_trigger

Appears and works exactly like a trigger in the editor, but is passively evaluated every tick in the runtime like an ordinary condition. You cannot specify both cf_trigger and cf_fake_trigger. Fake triggers are useful for conditions like "Every X milliseconds", where the condition should work like a trigger in the editor, but it is most convenient to implement it as an ordinary condition in the runtime. Fake triggers cannot be triggered by runtime.trigger(): they are identical to ordinary events in the runtime. This flag only affects the editor.

cf_static

Normally, the condition function at runtime is called once per instance, to 'filter' the picked objects. Static conditions (those specifying this flag) only have their function called once, no matter how many instances there are. You must then perform any picking yourself in the function. For example, 'Pick random instance' would be most conveniently implemented as a static condition.

cf_not_invertible

Prevents the user inverting the condition. This is useful if the inverted condition does not make sense, e.g. 'Pick random instance'.

cf_deprecated

Hides the condition from the dialog. If you wish to replace a condition in your plugin with different features, you must not remove it entirely: this will break all existing projects using it. Instead, marking it deprecated prevents any new projects from using it, while letting old projects load correctly and continue using it.

cf_incompatible_with_triggers

Prevents the user adding the condition to an event with a trigger in it. This is not generally useful for plugins - the runtime uses it for certain special conditions like 'trigger once'.

cf_looping

Shows a looping icon next to the condition. This does not affect the functionality of the condition in any way - it is purely cosmetic. Construct 2 will assume your condition function is implemented as a looping condition.

list_name

This is the name of the condition in the Add condition dialog, e.g. "Compare X".

category

The category the condition belongs to in the dialog. This may be empty for behavior conditions, where the category name will be the name of the behavior. It must not be empty for plugin conditions.

display_string

The string displayed in the event sheet view. {0}, {1}, {2} etc. are substituted with the corresponding parameter. These can each only appear once in the display string. You can also use bold and italic HTML tags (but no other HTML is valid). Try to follow conventions in the rest of Construct 2's plugins and behaviors when using bold and italic.

description

A string appearing at the top of the Add condition dialog when the user has selected the condition. As with parameter descriptions, try to be as helpful as possible for the user with this.

script_name

The name of the condition function in the runtime script. For example, if it is "MyCondition", the runtime function must be cnds.MyCondition. Since dot syntax must be used for properties (see Google Closure Compiler compatibility), make sure this does not contain any spaces etc.

Adding conditions

By convention, the plugin's conditions are listed first. Once any parameters have been added using the above functions, the following function adds a condition:

AddCondition(id, flags, list_name, category, display_string, description, script_name);

id

A number uniquely identifying this condition. This is saved to the project XML, so you may change the rest of the parameters after releasing your plugin, but not the id.

flags

This may be zero for no flags, or a combination of the following values combined with bitwise OR (|):

cf_trigger

A triggered condition. Events with triggers are not evaluated every tick; instead, they are run by the runtime.trigger() function. There are some limitations on triggers: an event cannot contain two triggered conditions, and a trigger is always the first condition.

cf_fake_trigger

Appears and works exactly like a trigger in the editor, but is passively evaluated every tick in the runtime like an ordinary condition. You cannot specify both cf_trigger and cf_fake_trigger. Fake triggers are useful for conditions like "Every X milliseconds", where the condition should work like a trigger in the editor, but it is most convenient to implement it as an ordinary condition in the runtime. Fake triggers cannot be triggered by runtime.trigger(): they are identical to ordinary events in the runtime. This flag only affects the editor.

cf_static

Normally, the condition function at runtime is called once per instance, to 'filter' the picked objects. Static conditions (those specifying this flag) only have their function called once, no matter how many instances there are. You must then perform any picking yourself in the function. For example, 'Pick random instance' would be most conveniently implemented as a static condition.

cf_not_invertible

Prevents the user inverting the condition. This is useful if the inverted condition does not make sense, e.g. 'Pick random instance'.

cf_deprecated

Hides the condition from the dialog. If you wish to replace a condition in your plugin with different features, you must not remove it entirely: this will break all existing projects using it. Instead, marking it deprecated prevents any new projects from using it, while letting old projects load correctly and continue using it.

cf_incompatible_with_triggers

Prevents the user adding the condition to an event with a trigger in it. This is not generally useful for plugins - the runtime uses it for certain special conditions like 'trigger once'.

cf_looping

Shows a looping icon next to the condition. This does not affect the functionality of the condition in any way - it is purely cosmetic. Construct 2 will assume your condition function is implemented as a looping condition.

list_name

This is the name of the condition in the Add condition dialog, e.g. "Compare X".

category

The category the condition belongs to in the dialog. This may be empty for behavior conditions, where the category name will be the name of the behavior. It must not be empty for plugin conditions.

display_string

The string displayed in the event sheet view. {0}, {1}, {2} etc. are substituted with the corresponding parameter. These can each only appear once in the display string. You can also use bold and italic HTML tags (but no other HTML is valid). Try to follow conventions in the rest of Construct 2's plugins and behaviors when using bold and italic.

description

A string appearing at the top of the Add condition dialog when the user has selected the condition. As with parameter descriptions, try to be as helpful as possible for the user with this.

script_name

The name of the condition function in the runtime script. For example, if it is "MyCondition", the runtime function must be cnds.MyCondition. Since dot syntax must be used for properties (see Google Closure Compiler compatibility), make sure this does not contain any spaces etc.

Adding actions

By convention, the plugin's actions are listed second. Once any parameters have been added, the following function adds an action:

AddAction(id, flags, list_name, category, display_string, description, script_name);

id

A number uniquely identifying this action. This is saved to the project XML, so you may change the rest of the parameters after releasing your plugin, but not the id.

flags

This may be zero for no flags, or:

af_deprecated

Hides the action from the dialog. If you wish to replace an action in your plugin with different features, you must not remove it entirely: this will break all existing projects using it. Instead, marking it deprecated prevents any new projects from using it, while letting old projects load correctly and continue using it.

list_name

This is the name of the action in the Add action dialog, e.g. "Set X".

category

The category the action belongs to in the dialog. This may be empty for behavior actions, where the category name will be the name of the behavior. It must not be empty for plugin actions.

display_string

The string displayed in the event sheet view. {0}, {1}, {2} etc. are substituted with the corresponding parameter. These can each only appear once in the display string. You can also use bold and italic HTML tags (but no other HTML is valid). Try to follow conventions in the rest of Construct 2's plugins and behaviors when using bold and italic.

description

A string appearing at the top of the Add action dialog when the user has selected the condition. As with parameter descriptions, try to be as helpful as possible for the user with this.

script_name

The name of the action function in the runtime script. For example, if it is "MyAction", the runtime function must be acts.MyAction. Since dot syntax must be used for properties (see Google Closure Compiler compatibility), make sure this does not contain any spaces etc.

Adding expressions

By convention, the plugin's expressions are listed third. Expressions can only use number, string or 'any type' parameters, since expression parameters are all entered as text. Once any parameters have been added, the following function adds an expression:

AddExpression(id, flags, list_name, category, expression_name, description);

id

A number uniquely identifying this action. This is saved to the project XML. After releasing your plugin you cannot change the id or expression_name, but the other parameters can be changed.

flags

This may not be zero - at least one flag specifying the return type must be set. The available flags are:

ef_return_number

The expression returns either an integer or float, using the runtime ret.set_int() or ret.set_float() functions.

ef_return_string

The expression returns a string, using the runtime ret.set_string() function.

ef_return_any

The expression can return either an integer, float or string. Either ef_return_number or ef_return_string should be preferred where possible, since Construct 2's expression parser cannot verify the correct types are used when ef_return_any expressions are involved.

ef_variadic_parameters

Construct 2 will allow the expression to be used with additional 'any type' parameters past the end of those specified. Any parameters that are specified will still be required and type checked. If no parameters are specified, the expression can be used with any number of parameters at all.

ef_deprecated

Hides the expression from the object panel and autocomplete, and raises a syntax error if the user tries to type it in. If you wish to replace an expression in your plugin with different features, you must not remove it entirely: this will break all existing projects using it. Instead, marking it deprecated prevents any new projects from using it, while letting old projects load correctly and continue using it.

list_name

This is intended to be equivalent to the condition and action list_name. However, in the current release of Construct 2, it is not used. It may be displayed in a future release though, so it should still be set appropriately.

category

The category the expression belongs to in the dialog. This may be empty for behavior expressions, where the category name will be the name of the behavior. It must not be empty for plugin expressions.

expression_name

The name of the expression. This follows the dot in the expression syntax. For plugins, the expression is used as MyObject.expression_name. For behaviors, it is used as MyObject.MyBehavior.expression_name. It also serves as the script name: if it is "MyExpression", the runtime function must be exps.MyExpression. Since dot syntax must be used for properties (see Google Closure Compiler compatibility), make sure this does not contain any spaces etc.

description

The description that appears next to the expression in the Expressions Panel. As with parameter descriptions, try to be as helpful as possible for the user with this.

Finishing up

Once all your ACEs are added, call the following function:

ACESDone();

You cannot add any more ACEs after this line.

Implementing the runtime functions

Each ACE must have a corresponding function in runtime.js. These functions must be added to the prototypes of the Cnds, Acts and Exps objects. Despite the fact the functions are added to an empty object's prototype, they are invoked with this referencing an instance of your plugin.

Conditions are declared like so:

    Cnds.prototype.ScriptName = function (params)
    {
    	return true;
    };

    Acts.prototype.ScriptName = function (params)
    {
    	// do something
    };

    Exps.prototype.ExpressionName = function(ret[, params])
    {
    	ret.set_int(0);
    	// or:
    	// ret.set_float
    	// ret.set_string
    	// ret.set_any
    };