Construct 3: When to use functions?

Introduction

If you are a Construct 3 user and aren't using functions, this is for you!

This tutorial is intended to explain when to use functions and why you should, as well as show you how, of course!

What does this tutorial cover?

Of course, this tutorial will demonstrate how to use functions in Construct 3, but more importantly, it will cover When and Why to use functions.

We will briefly review when to use functions and then jump into some examples. The examples will discuss why to use functions by showing the benefits.

Table of Contents

• Who is this tutorial for?
• When to use Functions?
• Example 1: Updating The Score
  • Example Project
  • Creating a Function
  • DRYing Up The Code
  • Function Parameters
  • More DRY with Parameters
  • Score Multiplier
• Example 2: Taking Damage
• Summary

Who is this tutorial for?

This tutorial is for anyone who uses Construct 3 but does not use functions. So if you already use functions in Construct or programming elsewhere, you probably won't find much value here.

This tutorial should be beginner friendly, but if you are an absolute beginner, I'd advise looking at other tutorials first. I'll be jumping right in and not taking the time to explain aspects not related to the functions.

When to use Functions?

To make this easy to understand and remember, since you are new to functions, let's sum it up in one word:

D.R.Y.

DRY is an acronym for Don't Repeat Yourself. This is a common programming term, but as I've said, this tutorial is aimed at non-programmers.

One of the function's main uses and benefits is organizing your code into reusable blocks.

That sounds great. But what does it actually look like? How will you know when to create these reusable blocks?

Copy & Pasting

When you find yourself copying and pasting events, that is your signal that you may want to use a function.

If you feel like you are creating the same events over and over, a function can probably help! Don't Repeat Yourself - use a function!

Let's get to some examples!

Example #1: Updating The Score

Here we have a simple project setup:

• Green: Player
• Red: Enemy
• Blue: Power Up
• Arrows/WASD to move
• Click to fire projectile
• Projectile destroys enemies

example project

What we are focusing on in this example is updating the score.

It is very simple:

• The score is shown in the top right corner
• Destroying each enemy increases the score by 100 points
• Collecting a powerup increases the score by 50 points

The events to update the score are very simple as well, only taking two events:

• Increase the score global variable
• Text element which is set to “Score: “ & score (Global Variable)

What could go wrong?

With events so few and simple, it might seem like there isn't much to gain here. I wouldn't blame you for keeping it like it is, but let's show what can go wrong, even if it is the worst-case scenario.

Maybe you make a few updates after you copy the line of code:

• Set text to “score:” & score
• Set text to “score: “ & score - adding in the space
• Set text to “Score: “ & score - deciding to capitalize score

Each time you make a change, you need to update in three different locations. If you forget a spot, there are inconsistencies depending on how they score last.

Creating a function

The steps to creating and calling functions are pretty simple, but I'll show each step of the way to avoid anyone getting lost.

How do you create a function in Construct 3?

Right-click on any event sheet and select Add function.

Name your function in the open dialogue box, and then click ok. There are some other options and fields, but don't worry about those for now.

Note that you can right-click on a function and click the edit function. If you rename a function, Construct should automatically update the name everywhere, as in where the function is called.

To clarify for anyone completely new to functions: You have now created a function, but the code inside the function will never run until you call the function. Hopefully, this will become clear once you see the final setup for this example.

How do you call a function in Construct 3?

To call a function, click add action. After adding your first function to the project, you should see the Functions action shows up in the add action window.

On the next screen - Add Functions Action - you will see all the functions you have created in the bottom portion, which is simply titled functions.

Note: in the screenshot above, I have created 3 functions. The screenshot was taken after finishing the tutorial project.

DRYing Up The Code

Now that we have walked through how to create and call a function, let's DRY up this code - which means removing repetition.

To show again, so you don't have to scroll up, here are the events before the function is added:

Here are the steps to transition the above events to the below events that utilize functions:

• Add function: I named this function "update score" as all we are doing for now is updating the score in the UI.
• Add actions to function: The function will update the score UI, just as we were doing before. If you already created the actions, like we did here, you can just drag them over to the function.
• Call function: Each of the events now call the function.
• Cleanup: Remove the other set text actions, as now the function will do that for you.

You can see in the above events that there is now no room for any inconsistencies to happen when setting the text.

Also, if you wish to make any more changes, you only need to do that in one spot. We will demonstrate that later!

Function Parameters

Looking at the code above, you may notice another bit of repetition.

Typically, the only reason you need to update the score is that the score has changed. So why not add that to the functionality of the function?

A function parameter is a value that is passed to the function. You choose the value to pass when calling the function.

How do I add a parameter to a function in Construct 3?

Right-click the function you want to add a parameter to and select Add Parameter.

A dialogue box will open up where you need to choose the name and type.

You may notice this is similar to adding a variable, and the parameters will be read in the same way as local variables.

After creating a new parameter, you will see everywhere that you have already called the function and that the default value is passed to the function.

How do I use a parameter in Construct 3?

After creating a parameter for a function, there will be a prompt to enter that parameter when you call a function.

Note: I did not add a description to the parameter. You can see that it shows no description in the prompt. When creating more complex functions, you can help yourself from getting confused down the road.

You can double-click on the function to re-open the prompt and edit the value.

DRYing Up The Events More Using Parameters

Using the same concept that I did when creating the function, I moved the logic from each event into the function:

First off, you may have noticed that I changed the name from update score to add to the score. It is always helpful to yourself when you name functions descriptively. It is usually difficult to find a perfectly descriptive name when first creating the function, but don't be hesitant to go back and rename it once you have a clearer idea of its purpose.

You can see that the add-to score function is called in three different events. Each time, a different value is passed into the function. I named that parameter "increase" as this is the amount that the score global variable is increased.

The function now has two actions. The first line takes the value passed to the function and adds it to the score global variable. The second one is the same as before.

Score Multiplier

Optimizing two lines of code doesn't seem to have a huge payoff. So let's show another example of something that could change and how this setup saves time.

If we wanted to add a Score Multiplier Power-Up to the game, here is how we can update this function:

The only change to the function is on the line where we increase the score. Now the increase is multiplied by a Global Variable named scoreMultiplier.

The benefit is that this update must be made in one location due to the function. If we were working with the event before implementing the function, we would need to make this change in three different spots. And how many more spots would that increase over the life of a project?

Of course, there are a couple of other aspects to set up to get this working completely, but those would be the same regardless of having this function or not.

This part is unrelated to demonstrating the benefits of functions, but for completeness's sake, here are the other events used to complete the score multiplier functionality:

Example 2: Take Damage Function

In the first example, I walked you through every step of the way so that you, hopefully, didn't get lost.

For this example, let me simply show you the events. Think of it like a knowledge test - did you learn enough from the first example to understand this one?

Here is the "Take Damage" Function:

Here are two examples of the function being called:

The right-click event simulates something like a grenade, explosion, or another aoe attack. I didn't add in any animation or other indicators to make it visually make sense, though.

You can also see the use of a couple of instance variables:

• Health: I set the enemy health to 3. Now it will take 3 shots from the projectile to destroy an enemy, but one grenade blast, aka right click, will destroy any close enemy.
• Damage: I set this instance variable on the player and it is set to 1. This isn't really utilized here, but could be easily adjusted for mechanics like using different weapons.

Scalability

The benefit I hope to demonstrate with this example is scalability.

Though we do not have much implemented in this example, I hope you can see how this function can be utilized down the road.

Now, if we want the player to pick up a stronger weapon or some kind of boost, we only need to adjust the instance variable on the player.

The right click functionality was quickly added after the take damage function was created. As you can see, there is a couple conditions that need to be checked to make sure only the correct enemies are picked, but there is only one action needed: calling the take damage function.

Summary

To summarize, we use functions to create reusable peices of code. The benefits of keeping it DRY, aka not repeating yourself, are as follows:

• Consistency: Being a programmer, I've seen first hand how important it is that your code be easy to update. This includes having code easy to read and also only needing to update code in one spot.
• Organization: Similar to above, you can organize your functions however and wherever makes sense to you, as you can call them from anywhere.
• Scalability: If planning ahead, you should be able to setup functions to not only make blocks of code reusable, but flexible using parameters. This will help you to implement new features efficiently.

Happy Coding!