Contents
Function Declaration
The general function declaration looks like this:
<function modifiers> function/event/delegate <return type> <function name>
(<parameter modifier> <type> <parameter name>, ...)
{
...
}
- <function modifiers>
- Keywords that specify aspects of the function's overall nature and behaviour.
- <return type>
- The variable type the function returns. You can't return static arrays due to the way they have to be declared. However, you can use an out variable in this case. See Parameter Modifiers further down this page.
- <function name>
- The name of the function, chosen by the coder. For advice on naming conventions see Coding Guidelines.
- <parameter modifier>
- Changes the nature of individual parameters.
- <type>
- The type of each parameter.
Example:
final function bool MyFunction( bool FirstParam , out int SecondParam, optional string ThirdParam ) { // function code }
You can declare up to 16 parameters for each function. If you need to pass more variables or values you might consider putting those in a struct or array and pass that to the function.
Function Calls
There are different ways of calling a function:
local bool bReturn, bHaveIt; local int Number; MyFunction(True, 34, "Hello World!"); // parameters passed as literals MyFunction(bHaveIt, Number); // parameters passed as variables bReturn = MyFunction(False, Number, "Hi there!"); // save function's return value in another variable
The third version is only allowed when the function has a return value. Note, that any return value you don't save in a variable will be thrown away. For (non-actor) objects this means they are lost and will be garbage collected.
Function vs Event
The event keyword is similar to function, but it creates a C++ header so you can call the function from C++ code. See UnrealScript Language Reference/Functions.
Delegates
Delegates could be described as a mixture between a function and a class variable. Delegates can be called like functions, but you can also assign "something" to them. This "something would be another function, but see Delegate for details since this topic is worth a whole new page.
The delegate keyword also includes the effect of the event keyword.
Function Modifiers
- final
- This function can't be overridden in subclasses or states of this class. Functions that are static and final are automatically simulated as well.
- iterator
- This function is an iterator function for the use with ForEach. Only native functions can be iterator functions.
- latent
- Latent functions require some time to be executed. Typical examples are Sleep which waits for the specified amount of time before returning and FinishAnim which returns when the current animation has finished.
Latent functions can only be called from state code and may not be called from within ForEach loops. Latent functions have to be native.
See Latent Function.
- native (or intrinsic in older Unreal versions)
- The function is written in native C++ code.
- native(<number>)
- The number is a unique identifier for the function. Functions in UScript get numbers automatically, except for native functions, which can "reserve" a function number with this syntax. This is useful because this number must appear in the native code, and if it is not fixed in this fashion it could fluctuate with different builds.
- simulated
- The function can be executed on the server or a client in a network game. Any function not declared simulated is ignored on the client.
See Simulated Function.
Note: Simulated functions are not automatically executed on the server and all clients. See Replication for details. - singular
- prevents reentrancy (recursively calling the same function, in the same object). It can be very useful to prevent certain types of 'endless recursion loop' crashes, but it usefulness is limited by a few caveats. When an object enters a singular function, a flag is set on the object itself that prevents it from re-entering a singular function. This means that any other singular functions that are called on that object will not be executed until the initial singular function has returned, and the 'i'm in a singular function' flag has been unset on the object. This includes base versions of the same function declared in super classes. For example:
class Base extends Object; singular function DoSomething() { log("blah"); } ... ... class Derived extends Base; singular function DoSomething() { Super.DoSomething(); }
When Derived.DoSomething() is called, Super.DoSomething() will not be called, since the object already has a 'singular' function in its call stack.
- static
- Declares the function as static. See Static Function.
- exec
- The function can be called from the console.
- protected
- The function is only visible from the class it was declared in and in all subclasses.
- private
- The function is only visible from the class it was declared in, but not in any of its subclasses.
Parameter Types
You can use any built-in variable types, structs, enums, static and dynamic arrays or objects as type. However, you can't use out bool or optional dynamic arrays. See Parameter Modifiers below.
Parameter Modifiers
- out
When you pass a variable to a function, its value is copied to a local variable in that function. The out modifier will copy the modified local value back to the original variable when the function returns.
You can use this modifier when you want a function to return more than one variable. Don't try to use it as performance improvement, though. Especially with larger variable types like dynamic arrays it tends to actually slow things down.
Here's a simple test case to demonstrate how the out modifier works:
class TestCommandlet extends Commandlet; var int i; function int Main(string Args) { i = 1; log(i); testout(i); log(i); return 0; } function testout(out int j) { log(i@j); j++; log(i@j); }
Call UCC YourPackage.Test at the command line and you get:
1 1 1 1 2 2
As you can see, the global variable didn't change while the testout function was executed. But it changed right after the function returned.
- optional
- This parameter may be skipped in a call. If a parameter should be skipped add commas as normal. If the skipped parameter is the last one the comma can be left out as well. This modifier is ignored for dynamic arrays.
- coerce
- Automatically casts the parameter to the specified type. (see Typecasting for details)
- skip
- Only valid as modifier of the second parameter of a native operator. If the first parameter already is enough to decide the operators return value then the second one will not be evaluated. This is used for the
{|
|- | |} and && operators.
Empty Functions
Two reasons to declare an 'empty' function:
- declare an "abstract" empty function that can then be "specialised" in a subclass or a state
- override a function with one that does nothing, in a subclass or state
Both of the following types of syntax work for both applications:
function Foo( float MyParam ) {} function Foo( float MyParam ) ;
When such a function is called, it does nothing. If it is declared to return a value, that value is the respective data type's "empty" value (0, "", None or the like).
Note: There's not much use in making an empty function simulated. The simulated keyword (like most other function modifiers) isn't inherited and when there's no code, there's nothing to be executed on a client. ;)
Vitaloverdose I cant seem to find any example of how to overwrite a function with a return value. Can this be done without recieving a warning in the log?
Wormbo: What do you mean? UT is full of overridden functions that have a return value and use the super version's return value in some way as well.
Sweavo: @vital: do you mean overriding a function that hasn't got a return value with one that has? (I don't have the answer, I just thought that was a version of the question that might make sense!)
Wormbo: That'd involve changing the function prototype, which is not allowed in UnrealScript.