Construct 3 icon

Construct 3

Documentation

Functions

Ashley's avatar
Medal
Construct Team Founder
Published 29 Apr, 2019
1,182 words
~5-8 mins

Functions are special kinds of events that can be called from actions. They are designed to be analogous to functions in real programming languages. Using functions can help you organise events and avoid having to duplicate groups of actions or events.

Adding a function

In the event sheet, functions are represented as a different type of event block. To create one, use the Add function menu option instead of Add event.

When you select this the Add function dialog will appear for you to fill in details about the function. It appears in the event sheet similar to a normal event, but with a special function icon and On function text at the top.

You can add conditions, actions and sub-events to functions, just like you can with normal events. However functions do not run unless you call them in an action. Once you've added a function to your project, a new special Functions object appears in the Add action dialog, next to the System object.

When you choose this object, it displays the functions in your project as if they are actions. (There are also some other built-in actions that relate to functions.)

Choosing the function adds an action that calls (runs) the function.

Functions are essentially custom actions. This action will run the corresponding On function event, including testing its conditions, running actions, and running any sub-events, and then return to the original action and continue from where it left off.

Using functions

A good example of using functions is to eliminate repeated sets of actions or events. For example suppose you create an enemy with random properties every 5 seconds using this event:

Event to create an enemy

Suppose there are two other events where you want to create an enemy the exact same way: one when a player walks in to a trap, and another one every 4 seconds when in a boss fight. Without functions, you may have to copy-and-paste the same actions multiple times, like this:

Multiple events all creating an enemy the same way

Notice this is becoming inconvenient. There may be times you need to repeat the actions in even more places. If you want to make a change, you then have to find every place you repeated the actions, and repeat the change. We can remove the repetition using functions. By creating a CreateEnemy function which has the repeated actions, we can replace all the repeated actions with function calls, like this:

This works identically to the previous events, but is much shorter and more convenient. We can call the CreateEnemy function anywhere in our events we want to create an enemy, and it uses the same set of actions in the corresponding On function event.

It is often useful to split many parts of your events in to functions like this, so they can be conveniently re-used across event sheets.

Parameters

When calling a function, you can also pass parameters. These are simply numbers or strings that are made available to the function. For example, the CreateEnemy function from the previous example could be modified to take two parameters: the X and the Y co-ordinates at which to create the enemy. This helps functions to be made more general purpose by using extra information from the action calling the function.

To add a parameter to a function, use the Add parameter menu option when right-clicking the function. (Note you need to right-click on the header or margin, since if you right-click a condition, it will show a menu for the condition instead.)

When you select this the Add function parameter dialog appears for you to fill in details about the parameter, including its name, description and type. Parameters appear similar to local variables, but inside the function block.

Parameters work very similarly to local variables - you can use them in expressions, compare them, and set them just like any other kind of local variable. Similar to local variables they are limited in scope to just the function event and its sub-events.

Now when you call the function, you can also provide the parameters. Notice the name and description you set for the parameters are used. These appear like parameters for any other action, but they will set the values of the parameters when calling the function.

Returning values from functions

Functions can also return a result. For example, a factorial function could calculate the mathematical result and return it.

By default, functions have a return type of None, meaning they don't return any value. This also means they are used as actions. However if you set a return type of Number, String or Any, the function returns a value. This also means it is used as an expression instead, so it won't appear as an action.

A function can set its return value using the Set return value action in the built-in Functions object. It can then be called using it as an expression, such as:

Functions.MyFunction

Parameters can also be added in parentheses, e.g.:

Functions.MyFunction(1, 2, 3)

The expression returns the value set by the Set return value action in the function call.

Functions which return a value will also appear in the Expressions dictionary, also show up in autocomplete, and also show call tips when entering parameters, just like other expressions. In summary, while functions with no return type are essentially custom actions, functions with a return type are essentially custom expressions.

Function maps

Sometimes it's useful to be able to call a function depending on a string determined at runtime. The function maps feature allows for this. Try out the Function Maps example to see how it works.

Nesting and recursion

Like in programming languages, functions support calling functions from other functions, and functions calling themselves (recursion). Functions calling other functions or recursing create a new call stack entry with their own unique variables. In other words, like in programming languages, local variables and parameters are unique at each level of function call. This does not apply to static local variables or global variables.

JavaScript integration

It is strongly recommended to use the Addon SDK to integrate JavaScript code with Construct. However it is possible to trigger a function from JavaScript using the following function:

c3_callFunction("name", ["param1", "param2"]);

The function with the given "name" is called by this method. Parameters are optional and can be omitted, but must be provided as an array in the second argument, and parameters may only be string, number or boolean values. The method also returns the return value set in Construct (if any), and also can only return a string or number.