Funciónes

Una “función de eventos” o simplemente una función es una característica poderosa de GDevelop. Los eventos externos, los enlaces de eventos y los grupos son útiles para organizar los eventos de su juego e incluso reutilizar algunos en más de un lugar de su juego. Por ejemplo, podría colocar eventos comunes para administrar a los enemigos en algunos eventos externos e incluir estos eventos, mediante un enlace, en varias escenas.

Las funciones van un paso más allá: le permiten declarar nuevas condiciones , nuevas acciones e incluso nuevas expresiones , usando eventos.

Cuando registra una función, puede elegir si es una condición, una acción o una expresión. La función contiene eventos, como una escena o eventos externos, que se ejecutarán cuando se inicie la condición o la acción durante el juego.

Además de los eventos, las funciones también tienen parámetros, al igual que las condiciones, acciones y expresiones habituales. Los parámetros pueden ser objetos, números o texto.

See an example of functions being used in this video by gamefromscratch.

Creating a new function

Functions are grouped into “extensions”. They work similarly to extensions that you can write for GDevelop, except that they are entirely composed of functions powered by events. You can see the list of extensions that the game have, as well as add a new extension in the Project Manager:

Click on the “+” button on the bottom to create a new extension. You can right click on it to rename it. It's a good idea to have functions related to the same thing in a single extension.

Click on the extension in the list to open its editor. By default, there are no functions in the extensions. Add one by clicking on “Add a new function”, on the right:

A new function is added. You can rename it to give it a name according to what you want to do inside. For example, if your function will be a condition that checks if the object passed as parameter is ready to fight, you can call it IsReadyToFight (only alphanumeric characters and underscores are allowed in names).

Click on the function to edit it: you'll be able to change its configuration and its events.

Editing the configuration and the events of the function

When a function is selected, on the top you can see the configuration of the function:

  • The first parameter is the type of the function: “Action”, “Condition”, “Expression” or “String Expression”. If you choose Action or Condition, you'll find the function in the list of actions and conditions when editing your events in the whole game. If you choose Expression (or String Expression), you'll find it in the list of expressions when you edit a formula.
  • You can then configure the name that will be displayed in the list.
  • Enter the description that will be given in the window when choosing the parameters for the function.
  • For Action or Condition, you can enter the sentence that will be displayed in the events sheet. In case your function takes parameters (see below to learn more about these), you can include them by writing PARAMx between underscores, replacing x by the parameter number (starting at 1):
Rotate objects _PARAM1_

This is an example for a function named “RotateObjects”, which is an action, with description “Rotate the given objects”, and with a single parameter, the objects to be rotated.

Parameters

Functions are becoming really useful and powerful when you use parameters. Under the configuration of the function, you can add parameters. These parameters will be available when you use the action, condition or expression in the events sheet. It's just like the usual action/condition/expressions you're used to!

Add a parameter with the button “Add a parameter”:

For each parameter, you can enter:

  • The name, that will be used to access to the parameter in the events of the function.
  • The type. The parameter can be objects, a number or a text. If you choose objects, you'll also be able to choose the type of the object to receive.
  • A description, that will be shown in the window when configuration the action/condition or expression.

For example, we can add a parameter which are the objects to be rotated:

Adding the events to the function and using the parameters

When your function is configured, you can add events to it. These events will be launched when the condition, action or expression is used in the rest of the game.

  • You can use all the existing events, actions, conditions and expressions, but you are limited to the objects that you entered as parameters. This is to ensure that your function is only acting on them, and has no “side-effects” on the rest of the game - which would be a bad practice and make functions hard to reuse and to generate.
  • Note that functions can be reused everywhere, and are not limited to a scene. You won't have the list of variables of your scenes in them. You can still manipulate them by using the usual actions and manually writing the variable you want to modify.
  • Links are not available in functions, because a function is autonomous and is in theory not even tied to a project.

Here is an example of a function to rotate some objects:

This is a really simple and not really useful example of a function (you could as well use the action to rotate objects directly without writing a function). But the power of functions is showing when you add more complex logic inside. It's then super easy to reuse this logic from the rest of the game!

Using the function in your game

When you have configured and created the events for your function, you can use it in the rest of your game.

Simply create a new action (or condition) and find in the list the name of your extension, then choose the function that you've created:

That's it! The function is usable as any other condition, action or expression in the Events Editor.

Advanced usages

This page gave a basic overview of what functions are. They are one of the more powerful feature of GDevelop, as you can extend the events by using them, enabling to create very readable and concise events sheets. By using them, you can reduce the amounts of events that you write for your game, avoid copy pasting them and even reduce bugs by ensuring that functions are always used for common tasks on your objects.

Recursive functions

A function can call itself! In the events of a function, you can use the same action/condition/expression as in the rest of the game. This is called a “recursive” function.

Be very careful when writing recursive function. If you don't add conditions, the function could call itself infinitely, blocking your game.

Sharing functions

Functions can be shared across projects (like actions/conditions that are built in GDevelop).