Functions - Revision history

SeriousBarbie: baaah, anchor set at wrong keyword...

2016-10-07T04:20:38Z

baaah, anchor set at wrong keyword...

SeriousBarbie: added anchor

2016-10-07T04:16:53Z

added anchor

SeriousBarbie: probe function -> Legacy:probe function

2016-04-03T22:41:30Z

probe function -> Legacy:probe function

WGH: /* Network modifiers */

2014-03-01T22:17:20Z

‎Network modifiers

Pbrown: /* Parameter modifiers */

2013-05-18T00:14:12Z

‎Parameter modifiers

Wormbo: /* Modifiers */ DLLImport probably fits better as "implementation modifier" than "call modifier"

2011-03-07T13:20:28Z

‎Modifiers: DLLImport probably fits better as "implementation modifier" than "call modifier"

Eliot: /* Call modifiers */ sup

2011-02-24T20:06:19Z

‎Call modifiers: sup

Eliot: /* Call modifiers */ Added DLLImport

2011-02-24T20:05:34Z

‎Call modifiers: Added DLLImport

Mr Evil: "const" does have an effect in UnrealScript.

2010-11-13T17:33:45Z

"const" does have an effect in UnrealScript.

Eliot: /* Modifiers */ K2Override and some uncofirmed info.

2010-09-14T21:00:09Z

‎Modifiers: K2Override and some uncofirmed info.

@@ Line 69: / Line 69: @@
   '''optional''' [[type]] parametername '''=''' defaultvalue
 :The ''defaultvalue'' can be any expression you could use on the right side of a variable assignment. It will be evaluated as if it was placed between the last local variable declaration and the first executable code statement of the function. In other words, you can call functions here and use any of the function's parameters or local variables. Evaluation of the expression is skipped if that parameter was specified when calling the function.
-; 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 "call by reference", but actually [[wp:Evaluation strategy#Call by copy-restore|call by value-result]]. 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)
+;<span ID="out_parameter"></span> 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 "call by reference", but actually [[wp:Evaluation strategy#Call by copy-restore|call by value-result]]. 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)
-;<span ID="out_parameter"></span>out<sup>3</sup>: The parameter is passed [[wp:Evaluation strategy#Call by reference|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.
+;out<sup>3</sup>: The parameter is passed [[wp:Evaluation strategy#Call by reference|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.

@@ Line 70: / Line 70: @@
 :The ''defaultvalue'' can be any expression you could use on the right side of a variable assignment. It will be evaluated as if it was placed between the last local variable declaration and the first executable code statement of the function. In other words, you can call functions here and use any of the function's parameters or local variables. Evaluation of the expression is skipped if that parameter was specified when calling the function.
 ; 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 "call by reference", but actually [[wp:Evaluation strategy#Call by copy-restore|call by value-result]]. 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 [[wp:Evaluation strategy#Call by reference|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.
+;<span ID="out_parameter"></span>out<sup>3</sup>: The parameter is passed [[wp:Evaluation strategy#Call by reference|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.

@@ Line 108: / Line 108: @@
 If the function has [[replication]] logic attached, the engine checks if it needs to replicate the call. If that's the case, the function's argument values are wrapped up along with the function name in a network packet, which is sent to the remote side. The ''local'' function call then returns immediately and if the function has a return type, it returns that type's null value. When the remote side receives the function call, it first checks whether it actually wants it (in case something strange happened) and then continues to process the function call similar to a local function call as described below.
-Now that the function's argument values are known and the is to be executed locally, the engine checks if and how it should actually execute the function. If the function is neither ''native'' nor ''simulated'', but the context object is an actor with <code>[[Role]] <= ROLE_SimulatedProxy</code>, then the function is not executed. Similarly, if the function is ''singular'' and the context object already executes the same or another ''singular'' function, the function is not executed. And lastly, if the function is a [[probe function]] and the probe event with the same name was disabled, then the function is not executed. In all these cases, if the function has a return type, the corresponding null value is returned.
+Now that the function's argument values are known and the is to be executed locally, the engine checks if and how it should actually execute the function. If the function is neither ''native'' nor ''simulated'', but the context object is an actor with <code>[[Role]] <= ROLE_SimulatedProxy</code>, then the function is not executed. Similarly, if the function is ''singular'' and the context object already executes the same or another ''singular'' function, the function is not executed. And lastly, if the function is a [[Legacy:Probe_Function|probe function]] and the probe event with the same name was disabled, then the function is not executed. In all these cases, if the function has a return type, the corresponding null value is returned.
 If the engine found that the function should be executed, it initializes all parameters (except '''out''' parameters in [[Unreal Engine 3]]) as local variables with an initial value equal to the corresponding argument value. Omitted optional parameters with a default value expression are initialized accordingly at this point. Any other optional parameters and local variables are initialized with their type's corresponding null value. After that is done, the code in the function body is [[code execution|executed]] until either a [[return statement]] or the end of the function body is reached. If the function has a return type, but code execution did not reach any return statement, the function's return value is the return type's corresponding null value.

@@ Line 34: / Line 34: @@
 These modifiers affect function [[replication]] in [[Unreal Engine 3]]. Earlier engine generations use the [[replication block]] to define these.
 ; 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-x1</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.
+; DemoRecording<sup>3-x1</sup>: Specifies that this function should be replicated to the demorecording driver (applicable to server-side demo recording only). 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. Note that '''Client''' function calls are also replicated to the demorecording driver, whereas '''DemoRecording''' ones are replicated only to the driver, not to the real clients.
 ; 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.

@@ Line 74: / Line 74: @@
 Parameters are evaluated at the time the function is called, before deciding if or where to execute the function body. Parameter expressions are evaluated from left to right in the context of the calling code and with the exception of parameters declared with the '''out''' modifier, UnrealScript always uses the [[wp:Evaluation strategy#Call by value|call-by-value evaluation strategy]].
-Note that reference type values are no objects, but object references! Passing objects to functions duplicates the object reference, not the object itself.
+Note that reference type values are not objects, but object references! Passing objects to functions duplicates the object reference, not the object itself.
 ===Locals===

@@ Line 24: / Line 24: @@
 ====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!
 ; K2Call<sup>3-x3</sup> : Allows the function to be referenced and called via [[Kismet 2]]{{confirm}}.
@@ Line 40: / Line 39: @@
 ; 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====
+====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'''.

@@ Line 63: / Line 63: @@
 ====Parameter modifiers====
 ; coerce: Automatically performs [[typecasting]] of values passed to this parameter, if the parameter is of a primitive type other than [[enum]]. Note that the built-in numeric types [[int]], [[float]] and [[byte]] are automatically typecasted to each other even without this modifier. Enum conversion to these numeric types is automatic as well. This modifier can also be applied to the return type of the function.
-; const<sup>3</sup>: For native functions this modifier is passed to the generated native headers. It has no effect in UnrealScript.
+; const<sup>3</sup>: For native functions this modifier is passed to the generated native headers. In UnrealScript, it prevents changes to the parameter within the function body, i.e. the value of the parameter must remain as the value that was passed when the function was called.
 ; init<sup>3-x2</sup>: Effect unknown.
 ; 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:

@@ Line 17: / Line 17: @@
 ====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.
+; 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'''.
+; 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'''.
+; 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. Because static functions are not executed in the context of any object instance, they can also not be subject to [[replication]].
+; 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. Because static functions are not executed in the context of any object instance, they can also not be subject to [[replication]].
-; final: As the name suggests, function declarations with this modifier are "final" and can't be overridden in subclasses.
+; 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!
+; 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 of 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!
+; K2Call<sup>3-x3</sup> : Allows the function to be referenced and called via [[Kismet 2]]{{confirm}}.
-; 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.
+; K2Override<sup>3-x3</sup> : Related to [[Kismet 2]]{{confirm}}. Effect unknown.
 ====Network modifiers====
 These modifiers affect function [[replication]] in [[Unreal Engine 3]]. Earlier engine generations use the [[replication block]] to define these.
-; 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.
+; 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-x1</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.
+; DemoRecording<sup>3-x1</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.
-; k2call<sup>3-x3</sup> : '''???'''.
+; Reliable<sup>3</sup>: Replicated functions will be replicated reliably when marked with this modifier.
-; k2pure<sup>3-x3</sup> : '''???'''.
+; 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.
-; reliable<sup>3</sup>: Replicated functions will be replicated reliably when marked with this modifier.
+; 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.
-; 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.
+; 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.
+; 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<sup>1,2</sup>: See '''native'''.
-; intrinsic(''number'')<sup>1,2</sup>: See '''native(''number'')'''.
+; 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.
+; 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]] (but not within any [[ForEach loop]]) and usually pause state code execution at least until the next tick, possibly even longer. 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]] (but not within any [[ForEach loop]]) and usually pause 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.<br/>Similar to '''simulated''' functions, native functions can be called clientsidely on replicated actors even if the local [[role]] is ''ROLE_SimulatedProxy'' or ''ROLE_DumbProxy''.
+; 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.<br/>Similar to '''simulated''' functions, native functions can be called clientsidely on replicated actors even if the local [[role]] is ''ROLE_SimulatedProxy'' or ''ROLE_DumbProxy''.
-; 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!''
+; 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>, noexportheader<sup>3-x2</sup>: Prevents this function from being exported to native headers.
+; NoExport<sup>3</sup>, NoExportHeader<sup>3-x2</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.
+; Virtual<sup>3</sup>: This modifier is just passed through to exported native headers and has no effect in UnrealScript.
 ===Parameters===