Editing User Defined Function


{{Template:Community_Wiki}} 

==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:
<pre>
int arg1 ; * args are optional
ref arg2
float arg3 ....

Begin Function { arg1, arg2, arg3... }
    ; * body
End 
</pre>
and called in a similar way to regular functions:
<pre>
Call SomeUDF arg1, arg2, arg3...

let SomeVariable := Call SomeOtherUDF arg1

if eval (call SomeSuitableUDF)
    ; the UDF return evaluates to true
endif
</pre>

==Examples==
<pre>
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
</pre>

<pre>
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
</pre>
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:
<pre>
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
</pre>
==Accepting any type arguments (advanced)==
In some contexts, it is useful to allow arguments of any type for a UDF. Since [[Array Variable|array]] elements can be any type, this can be conveniently achieved using the [[NVSE Expressions]], <b>*</b> ('box') and <b>&</b> ('unbox'), and the [[TypeOf]] / [[GetType]] functions.
<pre>
scn MyUDF

array_var AnyTypeArgument

Begin Function { AnyTypeArgument }

    if eval (TypeOf *AnyTypeArgument) == "form"
        ...
End
</pre>
<pre>
ref MyRef
int MyInt

call MyUDF &MyRef
call MyUDF &MyInt
</pre> 

==Notes==
*UDFs may be used recursively by saving the script once first without the sub call.

==See Also==
*[[Call]]
*[[SetFunctionValue]]
*[[Eval]]
*[[Let]]
==External Links==
*[http://www.loverslab.com/topic/26802-tutorial-nvse4-part-2-user-defined-functions-udfs/ Tutorial on User Defined Functions in NVSE 4]
[[Category:NVSE]]
[[Category:User Defined Functions]]