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 one or more 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
Example
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
Notes
- UDFs may be used recursively by saving the script once first without the sub call.
- This article is a simple overview, seek external documentation for further information.