Since I just made a very simple example of a function and how to call it in another post. Ill add it here as well, as functions are actually very easy to use, the moment you get them.
1. Add function plugin
You first have to add the function object to your project. You find it in the list where you also add mouse, keyboard etc.
2. Create a function
Once the plugin is added it will be available for your whole project. To create one you add it like you would any other event. And you have 2 options to choose from:
For now you only need "On function" and this can be compared to adding an "On mouse click" event, but instead of "On mouse click" already being added for you, you can decide what it should be called, and when to trigger it, which is done by calling it.
So after you select the "On function" you will be able to give it a name.
"Name" is just a reference so C2 know which function you are calling whenever you do a function call. So you can make it whatever you like.
In the above example I want the function to give me the license plate of a car. So giving it a name of "Get car license plate" describe what the function does so I can remember it. But in theory I could have called it "Moon rising" and still make it return the license plate of a car.
3. What a function does
Now that you have added a function it will be empty and not very useful. To make it useful you want it to do something for you. And you can see a function like a machine you put something into it, and it does something and then it might throw something out.
In the above example I throw in a car, and I want the function to give me the license plate of that particular car.
Input = Car
Output = license plate
4. Calling a function
A call to a function is an action, so like you would set the text of an text object, you will make the function call as an action.
When you press "Add action" you can again select function, but this time you will have two other options "Call function" and "Set return value". Since we need to call a function you just select "Call function"
And again It ask you for a name. Now this name need to be the name of the function you want to call. So in this case "Get car license plate". This will make C2 aware that this is the function it should look for.
In this window you can also add parameters. Which would be the input, so in our case we want to throw in a car, since we want the license plate of a car. We need to tell the function which car we want the license plate from.
So if you press "Add parameter" there will be added a field called "Parameter 0" These names are locked, so you can't change them. But you need to be aware of the order in which you add them. But for now since we only need 1 it doesn't matter.
Since we want a specific license plate of a car, we need something that is unique for a car. So the UID of the car objects works very well, as its unique for any object. So we throw that into the parameter 0.
6. Make the function do something
So now the function call is ready and will do what it is suppose to, however since our function is empty it doesn't do anything.
So the first thing we have to do, since a function isn't that clever even though we have already thrown it a "Car object" it still doesn't know what that parameter is for. So to make sure it knows, we add:
"Car pick instance with UID function.param(0)"
Since we stored the UID in parameter 0, we can also use it to select a car which match this UID. Now the function know what car we are talking about.
7. Return value
The same way as we added the function call, we now add an action of "Set return value", when you add it you get the possibility to set a Value. This is what will be returned when the function is done, doing what I does. In our case we want it to simply return the license plate of a car.
Since we have already told it what car we want the license plate of. We can simply set the return value to "Car.license_plate"
8. Using the return value
Now that it have returned the license plate we want to use it for something. So what we can do is to check the return value and then act on it.
In this case we want to check if the returned license plate is "12345678" and if that's the case then do something.
That is the basic of using functions and in this example we returned a license plate, however its perfectly fine to not have a function return anything.
When C2 reads your code and it gets to a function call, it actually jumps into that function, and will not continue reading your code, until it gets back from the function. So you could actually add everything that are in the function instead of the function call, and it would be exactly the same.