User Functions

User-Defined Functions - a feature added with OBSE v18

OBSE allows scripters to define their own functions, which can be called from other scripts.

A simple function script might look like:

ScriptName Multiply            ; the name of this function

float arg1                     ; holds an argument passed to the function
float arg2                     ; second arg
float localVar                 ; a local variable
   
Begin Function {arg1, arg2}    ; function body, with parameter list in {braces}
  Let localVar := arg1 * arg2
  SetFunctionValue localVar    ; this is the value that will be returned  
  Return                       ; optional, causes the function to return immediately
End

To call this function you would use:

Call Multiply 10 5

To store the result (50, in this case):

Let someVar := Multiply 10 5

When a function is called, script execution passes to the function and resumes after the function call when a return statement is encountered or execution reaches the end of the function script.

Factoring commonly-used code out into a function prevents repetitious code and shortens scripts. Encapsulating complicated routines into stand-alone functions results in simplified, more readable code.

Functions are defined as Object scripts but are treated as a distinct type with special limitations.

A function script can contain only one block. The name of the script is the name of the function.

Parameters are stored in local variables and must be indicated within {braces} in the function definition.

A set of empty braces indicates the function takes no arguments.

When parsing a function call, the compiler will verify that the number and type of the arguments match those expected by the function's parameter list.

If the called function is specified as a ref variable this validation cannot be performed; it is the scripter's responsibility to ensure the argument list is valid to avoid errors at run-time.

Notes

• Function scripts should never be attached to any object.

• All variables in a function script must be declared before the function body.

• Local variables and argument variables retain their values only until the function returns.

• Numbers, references and strings passed as parameters are copied to their proper local variables. Changing these copies do not change the original variables in the calling script.

• Arrays, on the other hand, are passed as pointers to the original arrays, therefore changes to arrays passed as parameters will persist after the user function returns.

• Clean up
  • Strings passed as parameters are destroyed when the function returns.
  • Any other string stored in local variables must be explicitly destroyed with sv_Destruct before the function execution ends (or else they will bloat the savegame).
  • Arrays passed as parameters are pointers to the original arrays, so no clean up is necessary (the pointer, itself, is destroyed automatically).
  • Local arrays are destroyed automatically when the function execution ends.
  • All other local variables (shorts, floats, refs etc.) are also destroyed when the function execution ends.

Functions have some useful properties.

• Because they are object scripts, you can call them on references using someRef.Call someFunc; any commands used inside the function will then operate implicitly on the calling reference.
• Because they are scripts, they can be stored in and called using ref variables, and even passed as arguments to other functions.
• Functions can call other functions, including themselves (i.e. recursively);

for instance:

ScriptName Pow            ; calculates base to the exp power
float base
short exp
short val

begin Function {base, exp}
  if exp == 0
    let val := 1
  else
    let val := base * Call Pow base, exp - 1
  endif
  SetFunctionValue val
end

OBSE allows a maximum of 30 nested function calls. This means the above function will only work with exponents less than 30.

Function

A blocktype which precedes the body of a function.

Begin Function {arg1, arg2, ... arg10}
    ; function body
End

This blocktype is only valid within function scripts.

A parameter list consisting of up to ten local variables used to hold arguments passed to the function must follow this keyword enclosed in curly braces;

if the function takes no arguments the braces should be empty.

SetFunctionValue

Specifies the value to be returned from a function.

(nothing) SetFunctionValue returnValue:expr

Valid only within a Function block.

If a function does not specify a return value, the return value is assumed to be numeric zero.

If multiple calls to SetFunctionValue are processed within a single Function block, the most recent value specified will be returned.

Call

Calls a user-defined function.

(returnValue:multi) ref.Call function:ref arg1:multi arg2:multi ... arg10:multi

Should be followed by a list of arguments matching the types expected by the function.

If a calling reference is specified, commands within the function body will operate on that reference.

Call returns whatever value is returned by the function.

See also

• List of User Functions
• Event Handler Functions