Maintenance script: Upload from wiki

2020-07-09T13:48:54Z

Upload from wiki

New page

= Funcdef & Function Pointers =

This tutorial explains how to set up and use funcdefs & function pointers in level scripts. The first two parts of this tutorial cover some very basic examples on use, with the last mixing arrays and function pointers to allow both calling sequences and a function at random.

=== Introduction to the "funcdef" statement ===

The [http://www.angelcode.com/angelscript/sdk/docs/manual/doc_datatypes_funcptr.html Angelscript documentation] states that ''"A function pointer is a data type that can be dynamically set to point to a global function that has a matching function signature as that defined by the variable declaration." '' In other words, you're making a '''type''' - something like ''int '' or ''string '' - but instead of this type's variables containing ''text'' or ''numbers'', it contains functions - or more specifically, pointers to functions . <br /> To understand better what a function pointer is: Consider a box, and this box contains a note telling you to look in another box somewhere else - this is your function pointer, it just contains information on where to look. The other box, the one ''referenced, '' contains the actual functional information. We can use these "extra boxes" to create variables that can be called just like functions.

The first stage in the process, is to make the type which will used to create variables later. This type is dependant on what the signature of your function is (that is, what arguments are taken in by the function, and what is returned by the function) - Below are some example funcdef statements:

<syntaxhighlight lang="cpp">
funcdef void fdSimpleFunction(); // Used for pointers to functions which take no arguments and return no vales
funcdef int fdReturningFunction(); // Used for pointers to functions which return an int and take no arguments.
funcdef int fdComplexFunction(int, int); // Used for pointers to functions which of return type int and take two ints as arguments
</syntaxhighlight>

Taking the top statement, here is a sample function which could later be pointed to:

<syntaxhighlight lang="cpp">void sfHelloWorld() {
AddDebugMessage("Hello World!", false); // Outputs: Hello World!
}
</syntaxhighlight>

With a function pointer type defined, and a function to point to - the next step is to make the function pointer:

<syntaxhighlight lang="cpp">
fdSimpleFunction@ functionVar;
</syntaxhighlight>

This is similar to just normal variable creation, except the "@" sign - The "@" symbol in angelscript literally means "Handle of" / "Address of", and is just stating that our variable is a pointer. However it currently point anywhere - it literally ''"is null"''. To make it point to a function, we use an assignment statement just like a normal variable, except the "@" symbol appears again:
<syntaxhighlight lang="cpp">// We know this line declares our functionVar
fdSimpleFunction@ functionVar;

// We now will make this point to sfHelloWorld()!
@functionVar = @sfHelloWorld;
</syntaxhighlight>

This new line is making ''functionVar '' point to the address of ''sfHelloWorld'' (in other words, we just put a note in our box saying look into the specific other box for ''sfHelloWorld''). You are actually saying '''"set the handle of function var to the handle of sfHelloWorld"''' - this is why ''functionVar '' can be called just like the function, even though it is actually a variable:
<syntaxhighlight lang="cpp">// If all has gone well:
functionVar();

// Does exactly the same as:
sfHelloWorld();
</syntaxhighlight>

Below is a sample map script file using the code covered in this section, make sure to be in developer mode to see the output.

<syntaxhighlight lang="cpp">// Make the type "fdSimpleFunction"
funcdef void fdSimpleFunction();

// Output hello world
void sfHelloWorld() {
AddDebugMessage("Hello World!", false);
}

void OnStart() {
// Call the function normally!
AddDebugMessage("Calling the function normally!", false);
sfHelloWorld();

// Call the function using our variable!
AddDebugMessage("Calling the function using the pointer!", false);
fdSimpleFunction@ functionVar;
@functionVar = @sfHelloWorld;
functionVar();
}
</syntaxhighlight>

So far, all we have managed to achieve is something we could have done already! Why go through all this hassle, to just call a function we could have called anyway? The next section shows how the variable aspect of the function can be exploited to solve a basic problem.

=== Solving a basic problem with function pointers ===

This following example can easily be solved without function pointers - however it compactly demonstrates that function pointers can point to any function with a matching signature, and gives a glimpse of what can be achieved using this. If a function pointer can change where it points to - we can effectively make one function call actually call different things to suit what we want. Take for example, the following two functions:

<syntaxhighlight lang="cpp">void bigFunction() {
subFunction();
}
void subFunction() {
//Implementing later...
}
</syntaxhighlight>

The specification is as follows: At the end of ''bigFunction'' we want to call a function called ''output1''. However, ''subFunction'' should have a random (1/4) chance of making ''bigFunction'' call ''output2'' instead. Both the output functions are defined below:
<syntaxhighlight lang="cpp">void output1() {
AddDebugMessage("Yo!", false);
}
void output2() {
AddDebugMessage("Dawg!", false);
}
</syntaxhighlight>

This problem can be solved using a function pointer. First again, the type which matches are output functions is defined:

<syntaxhighlight lang="cpp">// Create a function definition (which is actually the same as fdSimpleFunction)
// Which will matches the signature of both our output functions
funcdef void fdOutput();
</syntaxhighlight>

With the second step creating the variable which shall initially point to ''output1 '' at the start of ''bigFunction. '' Next we call ''subFunction '' as before, which will change the function pointer. Finally, we will call the function pointed to by the pointer:
<syntaxhighlight lang="cpp">
fdOutput @outputChoice;
void bigFunction() {
@outputChoice = @output1;
subFunction();
outputChoice();
}
</syntaxhighlight>

The ''subFunction'' implementation is as follows:
<syntaxhighlight lang="cpp">void subFunction() {
if(RandInt(0, 3) == 1)
{
@outputChoice = @output2; // A 1 in 4 chance of this code being reached
}
}
</syntaxhighlight>

Problem solved. You can test out the full code as with the previous section below:

<syntaxhighlight lang="cpp">// Create a function definition (which is actually the same as fdSimpleFunction)
// Which will matches the signature of both our output functions
funcdef void fdOutput();

// Our output functions
void output1() {
AddDebugMessage("Yo!", false);
}
void output2() {
AddDebugMessage("Dawg!", false);
}

// The actual stuff that does the descision making
fdOutput @outputChoice;
void bigFunction() {
@outputChoice = @output1; // Initially point to output 1
subFunction(); // Call with 1/4 chance of changing outputChoice
outputChoice(); // Call whichever output has been chosen
}

void subFunction() {
if(RandInt(0, 3) == 1)
{
@outputChoice = @output2; // A 1 in 4 chance of changing the function pointer
}
}

void OnStart() {
// Call bigFunction 20 times - notice roughly a 1/4 chance of output2?
for(int i=0; i<20; i++) bigFunction();
}
</syntaxhighlight>

It's time to move onto solving a much bigger problem: Calling a random function.

=== Arrays, function pointers, and you ===

We shall extend the above problem to have an arbitrary number of functions, and still manage calling one at random. To make things easier though, we will have each function called with an equal probablility. Obviously we could do a massive set of ifs, or a huge switch-case block (what if there are 100 choices? who would want to write that out that switch-case?). We shall re-use most of the code from the first section to get started, however, this time there are two new signature matching functions, giving us the following script file so far:

<syntaxhighlight lang="cpp">// This creates a signature called "SimpleFunction"
// Which matches functions which take no arguments, and return nothing...
funcdef void fdSimpleFunction();
// ...such as the following sample functions:
// This function will output "hello world"
void sfHelloWorld() {
AddDebugMessage("Hello World!", false);
}
// This function will output how many times it has been called
void sfDisplayTimesCalled() {
AddLocalVarInt("DTC_TimesCalled", 1);
AddDebugMessage("DisplayTimesCalled, called: " + GetLocalVarInt("DTC_TimesCalled") + " times", false);
}
//This function will play the sound of an angry brute!
void sfPlayScarySound() {
PlayGuiSound("enemy\\brute\\notice.snt", 1.0f);
}
</syntaxhighlight>

The problem of calling one of the functions at random is going to be solved by making an array. Each index is going to contain one of the above functions, we just then pick a random index, and call the function at that index. This solution scales really nicely when there is are a good number of functions to call.

An array of function pointers is declared in the following code segment - note that the {} part is not required, but merely used for the sake of compact-ness, all this section does is initialise the array with some values in it already. If you are not familiar with arrays, take a scan through the [http://www.angelcode.com/angelscript/sdk/docs/manual/doc_script.html Angelscript documentation].

<syntaxhighlight lang="cpp">
fdSimpleFunction@[] simpleFunctions = { @sfHelloWorld, @sfDisplayTimesCalled, @sfPlayScarySound };
</syntaxhighlight>

Now all is left to do is create a function that picks an index at random, and calls the function at that index:

<syntaxhighlight lang="cpp">void callRandomSimpleFunction() {
uint index = RandInt(0, simpleFunctions.length()-1); // Pick a random index from the array
fdSimpleFunction @functionToCall = simpleFunctions[index]; // Select that function
functionToCall(); // Call that function

// Note this can be simplified down to one line:
// simpleFunctions[RandInt(0, simpleFunctions.length()-1)]();
}
</syntaxhighlight>

We are also in a prime position to solve the problem of sequences here too, the following code will call each function in order in the array:

<syntaxhighlight lang="cpp">void callEachFunction(string &in asTimerName) {
uint index = GetLocalVarInt("simpleFunctionIndex"); // Get the index
if(index>= simpleFunctions.length()) return; // Don't go any further if we have called all the functions

// Access, and call like before:
fdSimpleFunction @functionToCall = simpleFunctions[index];
functionToCall();

AddLocalVarInt("simpleFunctionIndex", 1); // Increment the index, so the next function is called shortly...
AddTimer(asTimerName, 1.0f, "callEachFunction"); // Call this function again in 1 second, so the next function is called
}
</syntaxhighlight>

One potential extension for use with sequences is making each function return a float, which can then be used as the delay time before calling the next function. The sample script file for this section is below, don't forget to visit the OnStart routine and uncomment one of the two lines - or you won't see anything, and additional function is added to loop the ''callRandomSimpleFunction'' with a timer so it's effects can be seen easier:
<syntaxhighlight lang="cpp">// This creates a signature called "SimpleFunction"
// Which matches functions which take no arguments, and return nothing.
funcdef void fdSimpleFunction();
// Such as these sample functions:
void sfHelloWorld() {
AddDebugMessage("Hello World!", false); // Output hello world
}
void sfDisplayTimesCalled() {
AddLocalVarInt("DTC_TimesCalled", 1); //Display how many times function was called:
AddDebugMessage("DisplayTimesCalled, called: " + GetLocalVarInt("DTC_TimesCalled") + " times", false);
}
void sfPlayScarySound() {
PlayGuiSound("enemy\\brute\\notice.snt", 1.0f); // Play the sound of an angry brute!
}

// We now can create an array of these simple functions for further use.
fdSimpleFunction@[] simpleFunctions = { @sfHelloWorld, @sfDisplayTimesCalled, @sfPlayScarySound };

// Some example uses of this:
// Calling a random function
void callRandomSimpleFunction() {
uint index = RandInt(0, simpleFunctions.length()-1); // Pick a random index from the array
fdSimpleFunction @functionToCall = simpleFunctions[index]; // Select that function
functionToCall(); // Call that function

// Note this can be simplified down to one line:
// simpleFunctions[RandInt(0, simpleFunctions.length()-1)]();
}
// Using a timer to call one function per second in sequence.
void callEachFunction(string &in asTimerName) {
uint index = GetLocalVarInt("simpleFunctionIndex"); // Get the index
if(index>= simpleFunctions.length()) return; // Don't go any further if we have called all the functions

// Access, and call like before:
fdSimpleFunction @functionToCall = simpleFunctions[index];
functionToCall();

AddLocalVarInt("simpleFunctionIndex", 1); // Increment the index
AddTimer(asTimerName, 1.0f, "callEachFunction"); // Call this function again in 1 second
}
// Using a timer to repeatedly call a random function
void callRandTimer(string &in asTimerName) {
callRandomSimpleFunction();
AddTimer(asTimerName, 1.0f, "callRandTimer");
}
void OnStart() {
// Uncomment one of the following to test it out!
//callEachFunction("testTimer1");
//callRandTimer("testTimer2");
}
</syntaxhighlight>

=== Closing comments ===

A quick note on an earlier point - when the function pointer is defined initially, it points nowhere (as it does if an assignment fails due to mismatching signatures). This can be tested for with the following code:

<syntaxhighlight lang="cpp">if( functionPointer is null )
</syntaxhighlight>

Finally, that state of a function pointer '''is not saved when the map is - ''' there is no way to save the state of a function pointer - so keep them the same (which is fine in the case of an array - like the last example), or assume they haven't changed within the '''scope''' of the first function (E.g. the second example).

'''You should now understand a little about funcdefs. Have a play around, you can use this to make sequences, callbacks, and all sorts of fun stuff. '''

[http://www.angelcode.com/angelscript/sdk/docs/manual/doc_script.html Check out the documentation at: www.angelcode.com/angelscript/sdk/docs/manual/doc_script.html]

Hpl2:Tutorials:script:funcdef - Revision history

Maintenance script: Upload from wiki