User Defined Function
Overview
User defined functions (UDF) are added by NVSE V4. They must be saved as 'object' type scripts that must use the "Function" block type only. Although 'object' type, they must not be attached to any object and are instead called directly by script name from within other scripts, using the Call command.
UDFs may optionally return a single value of any type, using the SetFunctionValue command within them. They may optionally accept up to 15 arguments of any type, which are defined within curly braces:
scn SomeUDF
int arg1 ; * args are optional
ref arg2
float arg3 ....
Begin Function { arg1, arg2, arg3... }
; * do whatever like any other script
End
and called in a similar way to regular functions:
scn SomeOtherScript ... call SomeUDF arg1, arg2, arg3...
However, to assign the return to a variable, Let must be used rather than set .. to .., and to use in a conditional, if eval rather than simply if:
let SomeVariable := call SomeOtherUDF arg1 if eval (call SomeSuitableUDF) ; the UDF return evaluates to true endif
Examples
scn GetRandomForm
; *** This script accepts a form list and returns one random form from it
; local variables
int iCount
int iChoice
ref RandomForm
; arguments
ref rFormList
Begin Function { rFormList }
let iCount := ListGetCount rFormList
let iChoice := Rand 0, iCount
let RandomForm := ListGetNthForm rFormList, iChoice
SetFunctionValue RandomForm
End
scn fnShuffle
; *** This script accepts a list array and returns it in a shuffled order
; ***
; * local vars
array_var aNew
int iKey
int iLast
; * args
array_var aList
Begin Function { aList }
let aNew := Ar_Construct "array" ; * get a new empty list array
while (Ar_Size aList) > 0 ; * while input array contains an element
let iLast := Ar_Size aList ; * get size of input array
let iKey := Rand 0, iLast ; * get random valid key for input array
Ar_Append aNew, aList[iKey] ; * append the random choice element to output array
Ar_Erase aList, iKey ; * erase that element from input array
loop
SetFunctionValue aNew ; * return the shuffled array
return
End
The above example shows a user defined function that accepts a list array and returns it in a shuffled order. This might be called in another script, like:
scn SomeOtherScript
array_var aBeatles
Begin GameMode ; * or some other block type
let aBeatles := Ar_List JohnREF, PaulREF, GeorgeREF, RingoREF
let aBeatles := Call fnShuffle aBeatles
; * The Beatles array is now in a shuffled order
End
Accepting any type arguments (advanced)
In some contexts, it is useful to allow arguments of any type for a UDF. Since array elements can be any type, this can be conveniently achieved using the NVSE Expressions, * ('box') and & ('unbox'), and the TypeOf / GetType functions.
scn MyUDF
array_var AnyTypeArgument
Begin Function { AnyTypeArgument }
if eval (TypeOf *AnyTypeArgument) == "form"
...
End
ref MyRef int MyInt call MyUDF &MyRef call MyUDF &MyInt
Notes
- UDFs may be used recursively by saving the script once first without the sub call.