Functions

Syntax

A regular function declaration looks like this:

[modifiers] function [returntype] functionname ( [parameter declarations] ) body_or_semicolon

If the function does not return any value, the return type can be omitted. In this case return statements 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 or dynamic array.

Parameter declarations have the following syntax:

[parameter modifiers] type parametername

As with other variable declarations, 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 typecasts 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³

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^1,2

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.
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³

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.
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 && and || 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.

• ¹ – The modifier is available in Unreal Engine 1.
• ² – The modifier is available in Unreal Engine 2.
• ³ – The modifier is available in Unreal Engine 3.
• ³⁺ – The modifier is available in Unreal Engine 3, starting with UT3 patch 2.0.
• (no number) – The modifier is available in all Unreal Engine generations.

Access modifiers

private^2,3

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^2,3

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^2,3

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 Self 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 loops.

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.
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.
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

These modifiers affect function replication in Unreal Engine 3. Earlier engine generations use the replication block to define these.

client³

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³⁺

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³

Replicated functions will be replicated reliably when marked with this modifier.

server³

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³

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³

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 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 eventNameOfUnrealScriptFunction and their parameters and possible return type reflects the UnrealScript function declaration.

intrinsic^1,2

See native.

intrinsic(number)^1,2

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 execNameOfUnrealScriptFunction. 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.
Even if you can write native code for your mod, you should never specify numbers for your native functions!

noexport³

Prevents this function from being exported to native headers.

virtual³

This modifier is just passed through to exported native headers and has no effect in UnrealScript.