View source for Functions

{{expand}}

==Syntax==
A regular function declaration looks like this:
 ''[[#Modifiers|[modifiers]]]'' '''function''' ''[[types|[returntype]]]'' functionname '''(''' ''[[#Parameters|[parameter declarations]]]'' ''')''' ''body_or_semicolon''
If the function does not return any value, the return type can be omitted. In this case [[return statement]]s in the function body may not specify any value. Otherwise, if a return value was specified, any return statement must specify an expression that evaluates to that type. Starting with [[Unreal Engine 2]] the compiler will emit a warning if a return type was specified, but the function body does not contain any return statement.
Alternatively, the keyword '''event''' can be used instead of '''function''' without any difference at the UnrealScript level. The '''event''' keyword will only become relevant when writing [[native code]].

'''Note:''' The compiler is not very strict about the order of modifiers and the keywords '''function''' and '''event'''. Especially in the UT3 source code you will sometimes see modifiers between the keyword '''function''' and the return type or function name. This can be very confusing to anyone reading your code, so please always make '''function''' or '''event''' the last keyword before the return type or function name.

===Parameters===
A function may have zero to sixteen parameters. If you need to pass more values to your function, consider using combining some or all of them to a [[struct]]-type parameter or passing them as a [[static array|static]] or [[dynamic array]].

Parameter declarations have the following syntax:
 ''[parameter modifiers]'' [[type]] parametername
As with other [[variable declaration]]s, the parameter name may optionally followed by a number in square brackets to declare the parameter as [[static array]]:
 ''[parameter modifiers]'' [[type]] parametername'''['''arraysize''']'''
If more than one parameter is specified, the individual parameters must be separated by commas. The type and any modifiers only apply to the parameter they were specified for.

Possible parameter modifiers are:
; coerce: Automatically [[typecast]]s values passed to this parameter, if possible. Note that the built-in numeric types are automatically typecasted to each other even without this modifier.
; const<sup>3</sup>: For native functions this modifier is passed to the generated native headers. It has no effect in UnrealScript.
; optional: Specifying the parameter in function calls is optional. Omitted parameters assume a default value, which is the parameter type's null value. In Unreal Engine 3 it is also possible to specify a different default value:
 '''optional''' [[type]] parametername '''=''' defaultvalue
; out<sup>1,2</sup>: If the parameter is a variable or an array element or struct member accessed through a variable (as opposed to a literal, or function return value or an array element or struct member accessed through a function return value), any modification to the parameter inside the function is copied back into the variable originally passed to the function after the function returns.<br/>'''Note:''' This is not "pass by reference" as one might expect! Instead of only copying the value when passing the parameter in, it needs to be copied again when returning from the function, so declaring a parameter as '''out''' is actually more expensive in UnrealScript prior to Unreal Engine 3. (see below)
; out<sup>3</sup>: The parameter is passed by reference instead of being copied. Any changes to the parameter inside the function become immediately visible in the variable, struct member or (static) array element originally passed to the function. For large dynamic arrays or structs passing by reference (via '''out''' parameter) may be more efficient than passing by value.<br/>'''Note:''' Due to the way dynamic arrays are implemented, you can't pass dynamic array elements or parts of them to an '''out''' parameter. Passing an entire dynamic array via '''out''' parameter is possible, and for large arrays even recommended.
; skip: Only allowed for the second parameter of a native [[operator]] declaration. The native implementation of the operator may choose to not evaluate the second operand if the operator result can be determined by evaluating only the first operand. This is used for the operators <code>&&</code> and <code><nowiki>||</nowiki></code> to skip evaluating the second boolean expression if it is not required.

===Modifiers===
Before the actual function declaration you are allowed to specify one or more function modifiers. These change the way the function works in certain situations.
* <sup>1</sup> &ndash; The modifier is available in [[Unreal Engine 1]].
* <sup>2</sup> &ndash; The modifier is available in [[Unreal Engine 2]].
* <sup>3</sup> &ndash; The modifier is available in [[Unreal Engine 3]].
* <sup>3+</sup> &ndash; The modifier is available in [[Unreal Engine 3]], starting with [[UT3]] patch 2.0.
* (no number) &ndash; The modifier is available in all Unreal Engine generations.

====Access modifiers====
; private<sup>2,3</sup>: The function is only accessible within the same class. Not even subclasses can "see" it, which means the usual rules for overriding functions don't apply - subclasses may change the return type and the number and type of parameters. Since they don't see the parent class function, they cannot call it via the [[Super]] keyword.
; protected<sup>2,3</sup>: Restricts access to this function to the current class and its subclasses. Subclasses may override the function unless it is also declared as '''final'''.
; public<sup>2,3</sup>: The default access rule. If neither '''private''' nor '''protected''' is specified, this is one is implied. Public functions can be called from non-related classes and may be overridden in subclasses, unless the function is also declared as '''final'''.
; static: Static functions are not tied to specific objects, but to a class. The object literal <code>Self</code> is not allowed within static functions and instance functions (i.e. functions not declared with the '''static''' modifier) can only be called through object references, this includes iterator functions in [[ForEach loop]]s.
; final: As the name suggests, function declarations with this modifier are "final" and can't be overridden in subclasses.

====Call modifiers====
; exec: Marks the function as potential console command. Note that exec functions are only really called via console commands for certain objects, such as the local PlayerController, that player's HUD, Pawn or selected Weapon and a few other places. The possible places for exec functions may vary from game to game, so have a look at the [[UnrealScript source code]] of your game to find out where you can put exec functions that actually work.<br/>When overriding functions, you must also declare the new function with the '''exec''' modifier if and only if the overridden function was declared with it. This means you cannot turn a regular function into a console command!
; simulated: Marks the function as valid for execution on clients if the actor containing it was replicated to that client and the local [[role]] of that client is either ROLE_SimulatedProxy or ROLE_DumbProxy.<br/>'''Note:''' The modifier '''simulated''' does not imply any kind or replication or even broadcast! Also, this modifier is not inherited when overriding functions - every super function call evaluates that super function's '''simulated''' modifier separately, potentially breaking the chain of super calls on clients!
; singular: Restricts recursive function calls by only ever allowing a single singular function to execute per object instance. If a singular function is called, the engine first checks if the object instance the function was called on already executes a singular function. If it does, the new function call is ignored.

====Network modifiers====
; client<sup>3</sup>: Specifies that this function should be replicated to the client owning the actor if it is called on the server. This modifier automatically makes the function '''simulated''' as well.
; demorecording<sup>3+</sup>: Specifies that this function should be replicated to the demorecording driver. It will only be executed during demo playback. This modifier automatically makes the function '''simulated''' as well, which makes sense since demo playback essentially is a client environment.
; reliable<sup>3</sup>: Replicated functions will be replicated reliably when marked with this modifier.
; server<sup>3</sup>: Specifies that this function should be replicated to the server if it was called on a replicated actor that is owned by the local client.
; unreliable<sup>3</sup>: Replicated functions will be replicated unreliably when marked with this modifier, i.e. they may be dropped due to packet loss or bandwidth saturation.

====Native implementation modifiers====
; const<sup>3</sup>: This modifier is actually placed after the closing parenthesis of the parameter list. It will be passed to the generated native header file, but has no effect in UnrealScript.
; event: As mentioned in the [[#Syntax|Syntax]] section above, the keyword '''event''' may replace the keyword '''function''' without any effect on the UnrealScript level. However, when exporting native header files from script code, '''event''' functions will have calling stubs generated so the UnrealScript function can be called more easily from C++ code. These generated C++ methods have the name <code>event''NameOfUnrealScriptFunction''</code> and their parameters and possible return type reflects the UnrealScript function declaration.
; intrinsic<sup>1,2</sup>: See '''native'''.
; intrinsic(''number'')<sup>1,2</sup>: See '''native(''number'')'''.
; iterator: Native functions with the '''iterator''' modifier can only be used as the iterator function of a [[ForEach loop]]. This modifier may not be used for non-native functions.
; latent: Native functions with the '''latent''' modifier may only be called directly from [[state code]] and usually interrupt state code execution at least until the next tick, possibly even longer. This modifier may not be used for non-native functions.
; native: The actual implementation of this function resides in native code in a C++ function with the name <code>exec''NameOfUnrealScriptFunction''</code>. Very early [[Unreal Engine 1]] versions used the keyword '''intrinsic''' instead.
; native(''number''): Same as the plain '''native''' modifier, but additionally the function gets its own UnrealScript bytecode token.<br/>''Even if you can write native code for your mod, you should never specify numbers for your native functions!''
; noexport<sup>3</sup>: Prevents this function from being exported to native headers.
; virtual<sup>3</sup>: This modifier is just passed through to exported native headers and has no effect in UnrealScript.

{{navbox unrealscript}}