Functions

• Why would a function be useful?
• Creating a Function
• The RETURN Command
• Calling a Function
  • Using Arguments in a Function
    • The Function
    • Calling the Function
    • The Result/Return
    • Passing Arrays as Arguments
    • Calling Function as a Script Command
  • Special Notes

Why would a function be useful?

A function is mainly a chunk of code that either is used for multiple actions
of the same item, or a simple way to check the status of something. This
eliminates lots of code from the main script and makes it a bit cleaner for
you to see and debug.

Creating a Function

In order to create a function, you can do one of many things. Many scripters
place their functions in 1 of 2 locations. I, myself, place my functions in a
functions.txt script file and load that independently. By doing this, you can
organize your functions and keep all your other scripts clean and free of
clutter. Another method is to simply place them inside the script itself,
however, I find this to lengthen the script quite a bit, and makes it
complicated to find where the function is located in case another script file
is calling it.

function(TAB)script(TAB)name(TAB){
    //  code
}

The RETURN Command

Sometimes it's necessary to send back information that you retrieved from your
function. Such as a TRUE/FALSE 0/1 response, or sometimes even more. In order
to do this, your function needs a return statement.

return <Value>;
return <Variable>;

Calling a Function

There are a few ways to call functions, depends on what information you are
retrieving.

callfunc "MyFunction";

// Simply calls the function that does not use a RETURN command

Using Arguments in a Function

Sometimes it's helpful to pass variables or values to a function in order to
retrieve the information that you would like. These values are called
arguments. Many people use these in order to make calculations.

The Function

function(TAB)script(TAB)calc(TAB){
    set @a, getarg(0) + getarg(1);
    return @a;
}

Calling the Function

set @a, callfunc("calc",1,2)
mes @a;

The Result/Return

3

Passing Arrays as Arguments

Calling the Function:

callfunc "calc", MyArrayName;

The Function:

function(TAB)script(TAB)calc(TAB){
  getelementofarray(getarg(0), 1);
}

• Please note, that npc variable arrays will not function in the same manner (this will be updated at a later date)

Calling Function as a Script Command

prontera,150,150,5<TAB>script<TAB>Calculator<TAB>999,{

    function<TAB>Add<TAB>{
        return (getarg(0)+getarg(1));
    }

    mes Add(1,2);
}

Special Notes

Variables are passed to functions by reference

This means that you can do normal variable operations on a variable reference
returned by getarg.

Ex:

function<tab>script<tab>F_Increment<tab>-1,{
    // getarg(0) returns a reference to the .@num variable in NPC_Test
    // NOTE: you can't use .@num directly, it's a different variable from the .@num in NPC_Test
    set getarg(0), getarg(0) + 1;
    return;
}

prontera,156,156,4<tab>script<tab>NPC_Test<tab>56,{
    // initial number
    set .@num, 123;
    mes .@num;

    // increment inside the function
    callfunc("F_Increment", .@num);
    mes .@num;

    close;
}

Operators always return values, so this would provoke an error on the set
inside F_Increment:

callfunc("F_Increment", .@num + 1);

It's important to note the difference between the reference of the variable
and the value of the variable:

• reference : the variable itself. It knows it's name, value and index. The type of variable is determined from the name.
• value : the value of the variable (string or number).

[Category:Scripting]