Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
gdevelop5:events:functions [2019/04/13 16:20]
4ian
gdevelop5:events:functions [2019/06/18 22:25] (current)
nilarjun
Line 1: Line 1:
 #Functions #Functions
  
-An "​Events Function"​ or simply Function ​us a powerful feature of GDevelop. [[gdevelop5:​interface|External events]], [[gdevelop5:​events:​link|links]] and [[gdevelop5:​events:​group|groups]] are useful to organize the events of your game, and even reuse some in more than one place in your game. For example, you could put common events to manage the enemies in some external events, and include these events, using a link, in various scenes.+An "​Events Function"​ or simply Function ​is a powerful feature of GDevelop. [[gdevelop5:​interface|External events]], [[gdevelop5:​events:​link|links]] and [[gdevelop5:​events:​group|groups]] are useful to organize the events of your game, and even reuse somein more than one place in your game. For example, you could put common eventsto manage the enemies in some external events, and include these events, using a link, in various scenes.
  
 Functions are going one step further: they allow you to declare **new conditions**,​ **new actions** and even **new expressions**,​ using events. Functions are going one step further: they allow you to declare **new conditions**,​ **new actions** and even **new expressions**,​ using events.
Line 15: Line 15:
 ## Creating a new function ## Creating a new function
  
-Functions are grouped into "​extensions"​. They work similarly to [[gdevelop5:​extending-gdevelop|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 [[gdevelop5:​interface:​project-manager|Project Manager]]:+Functions are grouped into "​extensions"​. They are the same as [[gdevelop5:​extensions:​search|the extensions that you can install for your game]]. You can see the list of extensions that the game has, as well as add a new extension in the [[gdevelop5:​interface:​project-manager|Project Manager]]:
  
-{{ :​gdevelop5:​events:​project-manager-functions-extensions.png?nolink&​400 ​|}}+{{ :​gdevelop5:​events:​project-manager-functions-extensionsnew.png?nolink |}}
  
 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 "​+"​ 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:+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 left:
  
-{{ :​gdevelop5:​events:​empty-events-functions-extension.png?nolink |}}+{{ :​gdevelop5:​events:​add-new-function.png?nolink |}}
  
-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).+A new function is added. You can rename itto 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. Click on the function to edit it: you'll be able to change its configuration and its events.
Line 31: Line 31:
 ## Editing the configuration and the events of the function ## 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:+When a function is selected, on the topyou 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.+* 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 conditionswhen editing your events in the 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. * 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.+* Enter the description that will be given in the windowwhen 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): * 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):
  
Line 42: Line 42:
 </​code>​ </​code>​
  
-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.+This is an example for a function named "​RotateObjects",​ which is an action, with the description "​Rotate the given objects",​ and with a single parameter, the objects to be rotated.
  
 ### Parameters ### Parameters
Line 54: Line 54:
 For each parameter, you can enter: For each parameter, you can enter:
  
-  * The name, that will be used to access ​to the parameter in the *events of the function*. +  * The name, that will be used to access 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. +  * 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 object to receive. 
-  * A description,​ that will be shown in the window when configuration ​the action/​condition or expression.+  * A description,​ that will be shown in the window when configuring ​the action/​condition or expression.
  
-For example, we can add a parameter ​which are the objects to be rotated:+For example, we can add a parameter, that would return ​the objects to be rotated:
  
 {{ :​gdevelop5:​events:​events-function-example-parameter.png?​nolink |}} {{ :​gdevelop5:​events:​events-function-example-parameter.png?​nolink |}}
Line 68: Line 68:
 * 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. * 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.+* 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. * **Links** are not available in functions, because a function is autonomous and is in theory not even tied to a project.
Line 76: Line 76:
 {{ :​gdevelop5:​events:​events-function-example-rotate-objects.png?​nolink |}} {{ :​gdevelop5:​events:​events-function-example-rotate-objects.png?​nolink |}}
  
-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!+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). Butwhen you add more complex logic inside, a function'​s strength can be seen. It's then super easy to reuse this logic from the rest of the game!
  
 ## Using the function in your game ## Using the function in your game
Line 86: Line 86:
 {{ :​gdevelop5:​events:​events-functions-used-as-action.png?​nolink |}} {{ :​gdevelop5:​events:​events-functions-used-as-action.png?​nolink |}}
  
-That's it! The function is usable as any other condition, action or expression in the [[gdevelop5:​interface:​events-editor|Events Editor]].+That's it! The function is used like any other condition, action or expression in the [[gdevelop5:​interface:​events-editor|Events Editor]]. 
 + 
 +<WRAP round info 99%> 
 +The **Object Groups** feature, while creating functions, helps grouping similar object parameters. This way you can apply an action/​condition to a group of object parameters (parameters pointing at objects) at once.</​WRAP>​
  
 ## Advanced usages ## 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.+This page gave a basic overview of what functions are. They are one of the more powerful ​features ​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 ### Recursive functions
Line 96: Line 100:
 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. 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.
  
-<note important>​Be very careful when writing recursive function. If you don't add conditions, the function could call itself infinitely, blocking your game.</​note>​+<note important>​Be very careful when writing ​recursive function. If you don't add conditions, the function could call itself infinitely, blocking your game.</​note>​
  
 ### Sharing functions ### Sharing functions
  
-Functions can be shared across projects (like actions/​conditions that are built in GDevelop).+Functions can be shared across projects (like actions/​conditions that are built in GDevelop). The simplest way to do it is just to copy/paste them. But if you've created a useful set of functions, you may consider [[gdevelop5:​extensions:​share|sharing them with the community]].
  
 <note tip>See [[gdevelop5:​events:​functions:​replace-external-events|an example of replacing external events by a function]], which is reusable and shareable. You can also **[[gdevelop5:​events:​functions:​extract-events|automatically extract events to a function]]**.</​note>​ <note tip>See [[gdevelop5:​events:​functions:​replace-external-events|an example of replacing external events by a function]], which is reusable and shareable. You can also **[[gdevelop5:​events:​functions:​extract-events|automatically extract events to a function]]**.</​note>​