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.

See Also

• Call
• SetFunctionValue
• Eval
• Let
• Script Compiler Override

External Links

• Tutorial on User Defined Functions in NVSE 4