MASTERING FUNCTION MAPPING: HOW TO IMPLEMENT IT AND HANDLE PARAMETERS ONCE AND FOR ALL

Traditional Functions

The use of functions in Construct 3 plays a crucial role in simplifying and optimizing a game's code. They are powerful tools that help organize events and actions efficiently.

Functions provide the freedom to add parameters, which are essentially internal variables for the function. They work almost the same way as a local variable; the difference is that when calling a function with parameters, the window allows you to add the values that will be manipulated inside the function.

Above is an example of a function with parameters.

Above is the dialog that appears whenever you call a function that has parameters.

In this tutorial, I will not teach you how to use traditional functions. The focus will be on how to call mapped functions with parameters without using JSON code, explaining "Forwarding parameter" and "Positioning ID" in detail.

Mapped Functions

There are also mapped functions, which are basically functions that can be triggered using a string (a sequence of characters, such as letters, numbers, and symbols used to represent text). Using mapped functions in Construct 3 offers several benefits, and a notable upside is the reduction of the need for excessive "if" and "else" statements. Here are some of the advantages of this approach:

1. Code Organization: With mapped functions, you can group related actions into separate code blocks, making your project more organized and easier to understand. This is particularly useful in complex projects where various actions need to be executed according to different situations.
2. Code Reusability: Once you define a mapped function, you can use it in various events and situations without duplicating code. This saves time and prevents errors, as you only need to make changes in a single place to affect all instances of the function.
3. Improved Readability: Avoiding long chains of "if" and "else" statements makes your code cleaner and easier to read. Instead of a long conditional branch, you can simply call the appropriate function when needed.
4. Simplified Maintenance: When you need to change a specific behavior, you just edit the mapped function instead of scouring the entire code for every related "if" and "else" occurrence. This reduces the risk of introducing bugs during maintenance.
5. Enhanced Performance: In some cases, mapped functions can improve performance, as Construct 3 can optimize them internally more efficiently than a series of conditionals.

In summary, using mapped functions in Construct 3 offers a more efficient, organized, and sustainable approach to game development, helping to avoid excessive code complexity and simplifying the creation and maintenance process.

Types of Mapped Functions

During my search for effective ways to optimize my game events, I came across mapped functions. They can be divided into two types:

Simple Mapped Functions:

They work similarly to traditional functions without parameters and can be called directly.

Mapped Functions with Parameters:

These are similar to traditional functions with parameters, but there is a challenge in how to trigger them.

The Problem When Triggering Mapped Functions with Parameters

The problem lies in the scarcity of available information on how to add values to the parameters of mapped functions. When researching the subject, it is evident that there is a significant lack of detailed resources online addressing this topic. Many users on the Scirra forums have asked how to insert values into these parameters, but most answers recommended using JSON code directly in the event to invoke the mapped function with parameters. This occurred because many found it difficult to understand how to call the mapped function and add parameters simultaneously. As a result, there have been various complaints regarding the complexity of this task.

It’s Simpler Than It Seems

First, we need to understand why it is difficult to create this specific type of function.

When we add the "Call mapped function" action, a window like the one pictured above opens. There are three options that must be filled for the event to work correctly:

1. Map name
2. String
3. Forwarding parameter

Map name is the name of the library that includes the access string for the function you mapped. String is basically the access key to the function inside the chosen library. Now comes the problem, which lies exactly in the Forwarding parameter.

If you click on the input area for the Forwarding Parameter, you will see a description of this option. The description for Forwarding Parameter says: "The index of the current function call's parameter to start forwarding to this function call. Note all parameters are always forwarded if the default is called."

If you didn't understand that, don't feel bad. In fact, the information provided is quite confusing and seems to make little sense. The way the sentence is structured makes it hard to grasp its meaning. Furthermore, the sentence seems contradictory, stating that "all parameters are always forwarded if the default is called," which is unclear and can lead to misinterpretation.

How to Call a Mapped Function with Parameters

Besides the struggle to understand what the "forwarding parameter" is, there is also the issue that nothing on the internet explains in depth how it actually works.

What you need to understand is that the "forwarding parameter" is what will forward the values to the parameters of the mapped function you are calling.

Note that if you add new parameters to a traditional function and call it directly, fields appear for you to add values to those parameters. The same does not happen when calling a mapped function because the "Call mapped function" action is not linked directly to a specific function. Therefore, we only have those three options to fill and no area to add parameter values.

To call mapped functions and input the desired values, you will need an intermediary function that will collect the values to be sent to the chosen mapped function.

In the example above, I have two functions: Intermediary - the intermediate function that collects data and uses the "Call mapped function" action. Function - the mapped function with parameters that will be filled during the call made by the Intermediary function.

Now for the interesting part: you might be wondering how this transfer is made, how the "forwarding parameter" influences it, and why it has the number 0 in it.

Pay close attention now: you need to know that the position of parameters inside a function matters, and they possess what I call a "Positioning ID."

In the example above, I placed blue numbers on each parameter. The numbering goes from top to bottom: Parameter0 is ID:0, Parameter1 is ID:1, and Parameter2 is ID:2.

Remember I said the position matters? If I change the position, the following happens:

The "Positioning IDs" stay in the same place because they never change; the only thing that changes are the parameter positions. Due to this change, in the Intermediary function, Parameter2 now has ID:0, Parameter0 has ID:1, and Parameter1 has ID:2.

Now, here is the explanation of how the "forwarding parameter" works when calling a mapped function with parameters:

Using the previous example, if the "forwarding parameter" is 0, it means it will forward all parameter values that have a Positioning ID of 0 or higher. In other words, it will forward all values and fill the mapped function in the same order. The result in the example above would be a text showing the values: 30 10 5.

Now, what if the "forwarding parameter" is 1? The system will only forward parameters that have a "Positioning ID" equal to or greater than 1. The result would be a text showing the values: 10 5 0.

You might be wondering why there is a zero at the end of this text. The explanation is this: whenever values are forwarded, they are allocated from top to bottom, regardless of the "Positioning ID." The "Positioning ID" only serves to help the forwarding parameter identify which values will be transferred. After the transfer, the system allocates the values in order from top to bottom.

Therefore, it is fundamental to observe the order of the parameters when performing transfers, since the names have no impact, but the position is crucial.

Conclusion

Using mapped functions with parameters is actually not difficult; the real problem was the lack of information, which led many developers to opt for JSON in their events. I hope the information shared in this article provides a clearer understanding and helps developers use mapped functions with parameters simply and without the need for JSON.