Difference between revisions of "Variables"

Revision as of 01:50, 21 April 2010

Variables are named storage slots for pieces of data. All UnrealScript variables are staticly-typed, that means you can only store a specific type of data in them and the type of data is defined in the variable declaration.

There are three basic types of variables in UnrealScript:

• Class variables, which can only be declared at the class scope, before any function, operator, delegate or state declaration.
• Struct members, which are declared inside their struct's declaration block.
• Local variables, which can be declared at the start of function, operator and delegate bodies before any code statements. (For readability's sake, this article will imply operators and delegates when it mentions functions, unless otherwise noted.)

Declaration

A simple class or struct member variable declaration looks like this:

var [modifiers] type variablename;

The variablename can be any combination of the letters A-Z (case-insensitive), the digits 0-9 and the underscore character _ with two restrictions:

• The name may not start with a digit.
• The name must be shorter than 64 characters.

The type can not only be a type specification, but also a struct or enum declaration.

You can declare multiple variables of the same type in one declaration:

var [modifiers] type variablename1, variablename2, ...;

Each of the variable names may optionally have an array size specification to create a static array:

variablename[arraysize]

You can mix static arrays and non-array variables in a single declaration. The array size only applies to the variable you appended it to.

Editable variables

To make the variable accessible from within UnrealEd's property windows, use the following syntax:

var([groupname]) [modifiers] type variablename;

The groupname must be an identifier if specified. If omitted, the class name is used as group name. For struct members, the group name has no effect.

Local variables

Local variable declarations in function bodies are similar, but a bit simpler:

local type variablename;

You can declare static arrays and multiple variables of the same type as described for class and struct variables above. The type must be an existing type. It is not allowed to declare new structs or enums here.

After declaration, a local variable is initially null, which can mean different things, depending on the variable type. (Zero for numeric types, False, empty string or array, None, etc.)

Modifiers

For class and struct variables you are allowed to specify one or more variable modifiers. These change the way the variable works in certain situations.

• ^S – The modifier can be used for struct members.
• ¹ – 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 later Unreal Engine 3 versions, such as the UDK.
• (no number) – The modifier is available in all Unreal Engine generations.

Inner type modifiers

Later versions of the Unreal Engine 3, such as the UDK, also allow certain variable modifiers for the inner type of a dynamic array declaration. The only currently known instances of this are in two classes of the UDK's Engine package (NxForceField and NxGenericForceFieldBrush) and the type declarations read array<const native transient pointer>. Nothing official is known about this feature yet, but presumably the modifiers apply to the individual elements instead of the array variable as a whole. Typically, any modifiers for the array variable itself also apply to the array elements, so you will probably never use this feature yourself.

Access modifiers

The following modifiers only apply to class variables and specify, which other classes are allowed to access the variable. The access rules are enforced by the compiler.

const^S

Prevents any changes to this variable from within UnrealScript. You are still allowed to specify a value in the defaultproperties block and access the variable's value in your code. This property is mostly used to protect variables with a special meaning to native code. Classes with const variables usually have a corresponding setter function for each variable.

deprecated^2,3

Signals that this variable should no longer be used. Accessing deprecated variables will throw a compiler warning. Unreal Engine 3 will load the value of a deprecated variable, but ignore it during save.

private^S,2,3

Private variables can only be accessed from within the class they were declared in. Other classes, even subclasses, can't access them.

protected^S,2,3

Access to protected variables is only allowed from within the same class and its subclasses. Sibling classes, parent classes and other, unrelated classes can't "see" protected variables.

public^S,2,3

The default access rule. If no other access rule is specified, this is one is implied. Public variables can be accessed from any other class. Usually you will see this modifier in Unreal Engine 3, along with a native code snippet. One of the most common examples is public{private}, which means the variable is declared as public for UnrealScript, but as private for native code.

Modifiers affecting values

These modifiers affect the default value of the variable in some way.

automated^UT2004

Only meaningful for object variables in GUIMultiComponent classes. Indicates that any GUIComponent object(s) referenced by this variable should automatically be added to the Controls array. Also works for static and dynamic arrays. Objects that aren't GUIComponents are ignored. Implies noexport, editinline, editinlineuse and editinlinenotify, and FYI: any object variable(even parameters and locals) referencing GUIComponents implies export and editinline.

config^S

Makes the variable configurable. The default variable value is read from an INI file when the class is loaded. Each subclass has its own version of the variable value in its INI file section. If the class is declared with the PerObjectConfig modifier, the initial instance value of the variable is read from a separate INI section for that object instance.

databinding³

The variable can be manipulated by Unreal Engine 3's data store system.

duplicatetransient³

Similar to transient (see below) but applies to object duplication.

globalconfig^S

Similar to the config modifier, but a globalconfig variable's default value is always read from the INI section of its declaring class, even for subclasses.

input

Attaches the variable to the input system. This is only meaningful for float and byte variables, which can be tied to axis and button input respectively. Input variables are only filled for the local player actor.

instanced³

Only meaningful for reference variables. Subobjects assigned to instanced variables are duplicated when an instance of the class is created.

localized^S

Makes the variable localizable. The default value of the variable is read from a localization file when the class is loaded. Each subclass can have its own localized versions of the variable value. In Unreal Engine 1 and 2 and if the class is declared as PerObjectLocalized in Unreal Engine 3, each instance of the class can have its own set of localized variable values. This is useful for actors placed in a map.

transient^S

The variables is set to its null value when initializing object instances. The variable's value is never saved to disk in any way.

travel^1,2

For single player gametypes where a player advances from one map to the next, carrying over all inventory items. Instance variables marked as travel will keep their value across the map change. Only has an effect for the PlayerPawn in UE1 (or the PlayerController and its Pawn in UE2) and its Inventory chain.

Modifiers affecting UnrealEd

These modifiers have some kind of effect in UnrealEd, usually in the actor properties window.

edfindable^S,2

Adds a 'Find' button to the variable in the property window, which can be used to select an actor from the UnrealEd viewports. For obvious reasons this only makes sense for variables of type Actor or any of its subclasses.

editconst^S

The variable is read-only in the property window.

editconstarray^S,2, editfixedsize^S,3

For dynamic arrays, removes the buttons from the properties window that would change the array length.

edithide^S,3+

Hide in UnrealEd property lists.^[confirm]

editinline^S,2,3

Only meaningful for object variables. Displays the referenced object's properties as a subgroup below the variable in the property window. If the variable has the value None, a drop-down list of allowed (editinlinenew, non-abstract) classes can be used to create a new object which is assigned to this variable.

editinlineuse^S,2,3

Same as editinline, but also adds a 'Use' button to the variable to apply the object selected in the relevant browser for this type of object. Note that the 'Use' button is always available in Unreal Engine 3.

editoronly³⁺

The variable value is only loaded for UnrealEd.

edittextbox^S?,3+

Replaces the usual input box with a button for opening a separate dialog with a multi-line text box for entering. Probably only useful for string variables.

interp³

The variable can be manipulated by Unreal Engine 3's Matinee system. Only really meaningful for float and vector variables.

noclear^S,3

Instructs the editor to prevent the user from setting this variable to None. Only really meaningful for object variables.

noimport^S,3

The variable's value will not be imported from text representation, i.e. when importing from a T3D file or pasting from clipboard.

nontransactional^S,3

The variable is not affected by UnrealEd's undo/redo features.

Other modifiers

cache^UT2004

Marks properties of certain classes that should be included in UCL file entries for that class. This is used e.g. for weapon and mutator names and descriptions.

editinlinenotify^S,2

Seems to provide special feedback to native code if the variable is edited in a property window. Seems only relevant for native classes and implies editinline.

export^S,2,3

For object properties. Objects assigned to this variable are exported as subobjects when exporting class scripts or when exporting actors to T3D files or clipboard.

init^S,3

Changes the way string and dynamic array variables are exported to headers for native classes. Default values for this kind of variable are ignored when creating instances of the class.

native

The variable is loaded and saved in native code. Only valid in native classes.

noexport^S,2,3

Prevents the variable's value from being exported when exporting class scripts or when exporting actors to T3D files or clipboard.

notforconsole³⁺

The variable value is discarded on console platforms.

repretry³⁺

If replication of this variable was not successful the replication will be tried again.

repnotify³

Can be used on replicated actor variables to instruct the engine to call the ReplicatedEvent function whenever a value was received for the variable.

The following modifiers can be found in the UDK, but their effect is currently unknown:

crosslevelpassive³⁺

Probably related to level streaming or multiple levels loaded at the same time.

protectedwrite³⁺

Might be related to the protected access modifier. Maybe causes the variable to be assignable only by the class itself and subclasses, while otherwise being publicly accessible by other classes as well.

serializetext³⁺

Effect unknown. Used only for the StaticMeshComponent.LODData variable.

Initial values

The initial values of class variables can be specified in the defaultproperties block. The initial value can be different in subclasses without affecting the value of parent classes. Some class variables, for example Name, Outer, Tag or Location, are initialized with other values when an instance of the class is created.

Initial values of struct members can be specified in thee structdefaultproperties. In structs that extend other structs, the initial value can differ from the value in the parent struct. Since structs are data types and only exist as values of other variables, initial member values for those variables may differ from the default struct member value.

The initial value of a local variable is always the null value for the declared variable type. The initial value for function parameters is the value passed in when the function is called. Omitted optional parameters initially contain the type's null value. In Unreal Engine 3 it is also possible to specify a different initial value for omitted optional parameters.

Accessing variables

Class variables can be accessed directly by just specifying their name from instance functions, state code or the replication block inside the declaring class or any of its subclasses.

The default value for a class variable can be accessed directly by using the keyword default and the context operator '.' from anywhere inside the class, including static functions:

default.variablename

The default value of another class can be accessed by providing a different class context to the default keyword:

objectreference.default.variablename

The object reference can be an object literal or an object reference variable. If the type of the object reference is a Class or a class limiter, that class is used, otherwise the referenced object's class type is used to access the default variable value. When using an object literal is usually doesn't make sense to use a non-class literal because you usually know the class of the referenced object and the engine really doesn't care about the actual object if it is only interested in the class anyway.

Struct member variables and class variables of other classes or other instances of the same class can be accessed with the context operator '.', like in the following example:

function getX(vector V)
{
  return V.X;
}

This accesses the struct member variable X of the vector value passed to the function as parameter V. The parameter V is a local variable to the function getX. Local variables can only be accessed inside their containing function.

Variables accessed as described in this section can be used as an L-value, i.e. used on the left side of an assignment operator or as an out parameter in a function call.