UnrealScript Language Reference/Variables

UnrealScript Language Reference

This subpage is part of a document by Tim Sweeney. The Unreal Wiki has been granted permission to host it. Please don't make any edits to these pages other than basic formatting of the text. If you have more to say on a topic here, please start a new Wiki page on it, for example from UnrealScript or Unreal Engine, and then add a "related topics" section to the very end of a page here.

Tim Sweeney
Epic MegaGames, Inc.
tim@epicgames.com
http://www.epicgames.com

Variables

Simple Variables

Here are some examples of instance variable declarations in UnrealScript:

var int a; // Declare an integer variable named "A".
var byte Table[64]; // Declare an array of 64 bytes named "Table".
var string[32] PlayerName; // Declare a max 32-character string.
var actor Other; // Declare a variable referencing an actor.

Variables can appear in two kinds of places in UnrealScript: Instance variables, which apply to an entire object, appear immediately after the class declarations. Local variables appear within a function, and are only active while that function executes. Instance variables are declared with the "var" keyword. Local variables are declared with the "local" keyword.

Here are the basic variable types supported in UnrealScript:

byte: A single-byte value ranging from 0 to 255.
int: A 32-bit integer value.
bool: A boolean value: either "true" or "false".
float: A 32-bit floating point number.
string: A string of characters.
name: The name of an item in Unreal (such as the name of a function, state, class, etc). Names are stored as a 16-bit index into the global name table. Names correspond to simple strings of 1-31 characters. Names are not like strings: strings can be modified dynamically, but names can only take on predefined name values.
enum: A variable that can take on one of several predefined name values. For example, the ELightType enumeration defined in the Actor script describes a dynamic light and takes on a value like LT_None, LT_Pulse, LT_Strobe, and so on.
struct: Similar to C structures, UnrealScript structs let you create new variable types that contain sub-variables. For example, two commonly-used structs are "vector", which consists of an X, Y, and Z component; and "rotator", which consists of a pitch, yaw, and roll component. Note that structs are passed by value.
object and actor references: A variable that refers to another object or actor in the world. For example, the Pawn class has an "Enemy" actor reference that specifies which actor the pawn should be trying to attack. Object and actor references are very powerful tools, because they enable you to access the variables and functions of another actor. For example, in the Pawn script, you can write "Enemy.Damage(123)" to call your enemy's Damage function – resulting in the enemy taking damage. Object references may also contain a special value called "None", which is the equivalent of the C "NULL" pointer: it says "this variable doesn't refer to any object".

Variables may also contain additional specifiers such as "const" that further describe the variable. Actually, there are quite a lot of specifiers which you wouldn't expect to see in a general-purpose programming language, mainly as a result of wanting UnrealScript to natively support many game- and environment-specific concepts:

const: Advanced. Treats the contents of the variable as a constant. In UnrealScript, you can read the value of const variables, but you can't write to them. "Const" is only used for variables which the engine is responsible for updating, and which can't be safely updated from UnrealScript, such as an actor's Location (which can only be set by calling the SetLocation or MoveActor functions).
editconst: Advanced. The variable can be seen in UnrealEd but not edited. A variable that is editconst is not implictly "const".
input: Advanced. Makes the variable accessible to Unreal's input system, so that input (such as button presses and joystick movements) can be directly mapped onto it. Only relevant with variables of type "byte" and "float".
transient: Advanced. Declares that the variable is for temporary use, and isn't part of the object's persistent state. Transient variables are not saved to disk. Transient variables are initialized to zero when an actor is loaded.
native: Advanced. Declares that the variable is loaded and saved by C++ code, rather than by UnrealScript.
private: The variable is private, and may only be accessed by the class's script; no other classes (including subclasses) may access it.
travel: Advanced. "Travel" is supported only for the player's PlayerPawn derived class and Inventory-derived classes in his linked Inventory list. It means "this variable should be saved and restored when switching levels, so that it isn't forgotten". This is the mechanism that keeps your health and ammo counts intact when switching levels. The combination of "transient" and "travel" isn't sensible (and isn't used in Unreal), since transient objects are non persistent between savegames, and "travel" implies the thing should persist between levels.
skip: Advanced. Only used for logical operators like && and ||. (More details only available for Unreal licensees.)
export: Advanced. Only meaningful for the Brush variable in Actor classes. (More details only available for Unreal licensees.)

Arrays

Arrays are declared using the following syntax:

var int MyArray[20]; // Declares an array of 20 ints.

UnrealScript supports only single-dimensional arrays, though you can simulate multidimensional arrays by carrying out the row/column math yourself. For information on Dynamic Arrays, see below in the /Advanced Language Features section.

Editability

In UnrealScript, you can make an instance variable "editable", so that users can edit the variable's value in UnrealEd. This mechanism is responsible for the entire contents of the "Actor Properties" dialog in UnrealEd: everything you see there is simply an UnrealScript variable, which has been declared editable.

The syntax for declaring an editable variable is as follows:

var() int MyInteger; // Declare an editable integer in the default
                     // category.

var(MyCategory) bool MyBool; // Declare an editable bool in
                             // "MyCategory".

You can also declare a variable as "editconst", which means that the variable should be visible but not editable UnrealEd. Note that this only prevents the variable from being changed in the editor, not in script. If you want a variable that is truly "const" but still visible in the editor, you must declare it "const editconst":

// MyBool is visible but not editable in UnrealEd
var(MyCategory) editconst bool MyBool;

// MyBool is visible but not editable in UnrealEd and
// not changeable in script
var(MyCategory) const editconst bool MyBool;

Object and actor reference variables

You can declare a variable that refers to an actor or object like this:

var actor A; // An actor reference.
var pawn P; // A reference to an actor in the Pawn class.
var texture T; // A reference to a texture object.

The variable "P" above is a reference to an actor in the Pawn class. Such a variable can refer to any actor that belongs to a subclass of Pawn. For example, P might refer to a Brute, or a Skaarj, or a Manta. It can be any kind of Pawn. However, P can never refer to a Trigger actor (because Trigger is not a subclass of Pawn).

One example of where it's handy to have a variable referring to an actor is the Enemy variable in the Pawn class, which refers to the actor that the Pawn is trying to attack.

When you have a variable that refers to an actor, you can access that actor's variables, and call its functions. For example:

// Declare two variables that refer to a pawns.
var pawn P, Q;

// Here is a function that makes use of P.
// It displays some information about P.
function MyFunction()
{
   // Set P's enemy to Q.
   P.Enemy = Q;

   // Tell P to play his running animation.
   P.PlayRunning();
}

Variables that refer to actors always either refer to a valid actor (any actor that actually exists in the level), or they contain the value "None". None is equivalent to the C/C++ "NULL" pointer. However, in UnrealScript, it is safe to access variables and call functions with a "None" reference; the result is always zero.

Note that an object or actor reference "points to" another actor or object, it doesn't "contain" an actor or object. The C equivalent of an actor reference is a pointer to an object in the AActor class (in C, you'd say an AActor*). For example, you could have two monsters in the world, Bob and Fred, who are fighting each other. Bob's "Enemy" variable would "point to" Fred, and Fred's "Enemy" variable would "point to" Bob.

Unlike C pointers, UnrealScript object references are always safe and infallible. It is impossible for an object reference to refer to an object that doesn't exist or is invalid (other than the special-case "None" value). In UnrealScript, when an actor or object is destroyed, all references to it are automatically set to "None".

Class Reference Variables

In Unreal, classes are objects just like actors, textures, and sounds are objects. Class objects belong to the class named "class". Now, there will often be cases where you'll want to store a reference to a class object, so that you can spawn an actor belonging to that class (without knowing what the class is at compile-time). For example:

var() class C;
var actor A;
A = Spawn( C ); // Spawn an actor belonging to some arbitrary class C.

Now, be sure not to confuse the roles of a class C, and an object O belonging to class C. To give a really shaky analogy, a class is like a pepper grinder, and an object is like pepper. You can use the pepper grinder (the class) to create pepper (objects of that class) by turning the crank (calling the Spawn function)... but, a pepper grinder (a class) is not pepper (an object belonging to the class), so you must not try to eat it!

When declaring variables that reference class objects, you can optionally use the special class<classlimiter> syntax to limit the variable to only containing references to classes which extend a given superclass. For example, in the declaration:

var class<actor> ActorClass;

The variable ActorClass may only reference a class that extends the "actor" class. This is useful for improving compile-time type checking. For example, the Spawn function takes a class as a parameter, but only makes sense when the given class is a subclass of Actor, and the class<classlimiter> syntax causes the compiler to enforce that requirement.

As with dynamic object casting, you can dynamically cast classes like this:

class<actor>( SomeFunctionCall() )

Enumerations

Enumerations exist in UnrealScript as a convenient way to declare variables that can contain "one of" a bunch of keywords. For example, the actor class contains the enumeration EPhysics which describes the physics which Unreal should apply to the actor. This can be set to one of the predefined values like PHYS_None, PHYS_Walking, PHYS_Falling, and so on.

Internally, enumerations are stored as byte variables. In designing UnrealScript, enumerations were not seen as a necessity, but it makes code so much easier to read to see that an actor's physics mode is being set to "PHYS_Swimming" than (for example) "3".

Here is sample code that declares enumerations.

// Declare the EColor enumeration, with three values.
enum EColor
{
       CO_Red,
       CO_Green,
       CO_Blue
};
 
// Now, declare two variables of type EColor.
var EColor ShirtColor, HatColor;

// Alternatively, you can declare variables and
// enumerations together like this:
var enum EFruit
{
       FRUIT_Apple,
       FRUIT_Orange,
       FRUIT_Bannana
} FirstFruit, SecondFruit;

In the Unreal source, we always declare enumeration values like LT_Steady, PHYS_Falling, and so on, rather than as simply "Steady" or "Falling". This is just a matter of programming style, and is not a requirement of the language.

UnrealScript only recognizes unqualified enum tags (like FRUIT_Apple) in classes where the enumeration was defined, and in its subclasses. If you need to refer to an enumeration tag defined somewhere else in the class hierarchy, you must "qualify it":

FRUIT_Apple // If Unreal can't find this enum tag...
EFruit.FRUIT_Apple // Then qualify it like this.

Structs

An UnrealScript struct is a way of cramming a bunch of variables together into a new kind of super-variable called a struct. UnrealScript structs are just like C structs, in that they can contain any simple variables or arrays.

You can declare a struct as follows:

// A point or direction vector in 3D space.

struct Vector
{
       var float X;
       var float Y;
       var float Z
};

Once you declare a struct, and only after you have declared it, you are ready to start declaring specific variables of that struct type:

// Declare a bunch of variables of type Vector.
var Vector Position;
var Vector Destination;

To access a component of a struct, use code like the following.

function MyFunction()
{
       Local Vector A, B, C;
       
       // Add some vectors.
       C = A + B;

       // Add just the x components of the vectors.
       C.X = A.X + B.X;

       // Pass vector C to a function.
       SomeFunction( C );

       // Pass certain vector components to a function.
       OtherFunction( A.X, C.Z );
}

You can do anything with Struct variables that you can do with other variables: you can assign variables to them, you can pass them to functions, and you can access their components.

There are several Structs defined in the Object class which are used throughout Unreal. You should become familiar with their operation, as they are fundamental building blocks of scripts:

Vector: A unique 3D point or vector in space, with an X, Y, and Z component.
Plane: Defines a unique plane in 3D space. A plane is defined by its X, Y, and Z components (which are assumed to be normalized) plus its W component, which represents the distance of the plane from the origin, along the plane's normal (which is the shortest line from the plane to the origin).
Rotator: A rotation defining a unique orthogonal coordinate system. A rotator contains Pitch, Yaw, and Roll components.
Coords: An arbitrary coordinate system in 3D space.
Color: An RGB color value.
Region: Defines a unique convex region within a level.

Prev Page: /Introduction – Section 2 of 9 – Next Page: /Expressions