UnrealScript Expressions & Operators

Overview

An expression is any combination of literal values, variables, function calls, operators, etc. For instance, x + 2, x - y, y = x * 2, SetCollision(true, true, true), and x = Gethealth() are all expressions. Expressions are what makes up all of the code within functions and what performs all of the actions within UnrealScript that make up the game. When a function is executed, the code within the function, and thus the expressions the make up that code, are evaluated by the UnrealScript virtual machine. In most cases, when an expression is evaluated, it produces a value that can be used by other expressions contained within the same line of code. The exception to this is calling a function that does not return a value.

One important aspect in expressions is the use of operators. Operators are essentially specialized functions that perform a specific operation on one (unary), two (binary), or sometimes three (ternary) inputs and return the result of the operation. Some of the most common operators are the addition (+), subtraction (-), multiplcation (*), and division (/) operators. These are familiar to practically everyone from mathematics. These all take two inputs, left and right, and perform some operation using those. Some operators only have a single input, left or right, while others may require 3 inputs (such as in the case of the ternary operator).

A complete line of code in UnrealScript, which can be comprised of any number of expressions, is called a statement

Built-in Operators

UnrealScript provides a wide variety of C/C++/Java-style operators for such operations as adding numbers together, comparing values, and incrementing variables. The complete set of operators is defined in Object.u, but here is a recap. Note that all of the C style operators have the same precedence as they do in C.

Assignment (=)

To assign a value to a variable, use the = operator with the value to be assigned on the right and the variable to assign the value to on the left:

function Test()
{
   local int i;
   local string s;
   local vector v, q;

   i = 10;		// Assign a value to integer variable i.
   s = "Hello!";	// Assign a value to string variable s.
   v = q;		// Copy value of vector q to v.
}

In UnrealScript, whenever a function or other expression requires a certain type of data (for example, a "float"), and you specify a different type of data (for example, an "int"), the compiler will try to automatically convert the value you give to the proper type. Conversions among all the numerical data types (byte, int, and float) happen automatically, without any work on your part. UnrealScript is also able to convert many other built-in data types to other types, if you explicitly convert them in code.

function Test()
{
   local int i;
   local string s;
   local vector v, q;
   local rotator r;

   s = string(i);	// Convert integer i to a string, and assign it to s.
   s = string(v);	// Convert vector v to a string, and assign it to s.
   v = q + vector(r);	// Convert rotator r to a vector, and add q.
}

Here is the complete set of non-automatic conversions you can use in UnrealScript:

• String to Byte, Int, Float: Tries to convert a string like "123" to a value like 123. If the string doesn't represent a value, the result is 0.
• Byte, Int, Float, Vector, Rotator to String: Converts the number to its textual representation.
• String to Vector, Rotator: Tries to parse the vector or rotator's textual representation.
• String to Bool: Converts the case-insensitive words "True" or "False" to True and False; converts any non-zero value to True; everything else is False.
• Bool to String: Result is either "True" or "False".
• Byte, Int, Float, Vector, Rotator to Bool: Converts nonzero values to True; zero values to False.
• Bool to Byte, Int, Float: Converts True to 1; False to 0.
• Name to String: Converts the name to the text equivalent.
• Rotator to Vector: Returns a vector facing "forward" according to the rotator.
• Vector to Rotator: Returns a rotator pitching and yawing in the direction of the vector; roll is zero.
• Object (or Actor) to Int: Returns an integer that is guaranteed unique for that object.
• Object (or Actor) to Bool: Returns False if the object is None; True otherwise.
• Object (or Actor) to String: Returns a textual representation of the object.

See Type Casting for complete details on this concept.

Mathematic Operators

Negation (-)

Unary. Negates the value of the input. It is equivalent to multiplying the value of the input by -1. The syntax for this operator is shown below:

   -Input1
   

Addition, Subtraction, Multiplication, Division (+, -, *, /)

Binary. Perform the corresponding mathematical operations on the two inputs. The syntax for this operator is shown below:

   Input1 + Input2
   Input1 - Input2
   Input1 * Input2
   Input1 / Input2
   

Power (*)*

Binary. Raises the left input to the power of the right input. For instance, the mathematical expression x² would be written x ** 2 in UnrealScript. The syntax for this operator is shown below:

   Input1 ** Input2
   

Modulo (%)

Binary. Returns the remainder of the division of the left input by the right input. For instance, the result of 6 % 4 is 2 because 4 goes into 6 one time with 2 remaining. The syntax for this operator is shown below:

   Input1 % Input2
   

Add/Subtract/Multiply/Divide and Assign (+=, -=, *=, /=)

Binary. Perform the corresponding mathematical operation and then assign the result to the first input (requires the left input to be a variable). For instance, if x has a value of 2 and you perform x *= 4, the value of x will be 8 afterward. The multiplication is performed first and then the result is assigned to the left input, in this case x. The syntax for this operator is shown below:

   Input1 += Input2
   Input1 -= Input2
   Input1 *= Input2
   Input1 /= Input2
   

String Operators

Concatenation/Concatenate and Assign ($/$=)

Binary. Appends the right input string to the left input string and returns the result. The "assign" version assigns the result to the left input (requires the left input to be a variable). The syntax for this operator is shown below:

   Input1 $ Input2
   Input1 $= Input2
   

Concatenation plus Space/Concatenate plus Space and Assign (@/@=)

Binary. Appends the right input string to the left input string with a space between them and returns the result. The "assign" version assigns the result to the left input (requires the left input to be a variable). The syntax for this operator is shown below:

   Input1 @ Input2
   Input1 @= Input2
   

Comparison Operators

Equality (==)

Binary. Performs a comparison of the right input to the left input and returns TRUE if they are the same and FALSE if not. If the two inputs are String values, this comparison is case-sensitive. The syntax for this operator is shown below:

   Input1 == Input2
   

Approximate Equality (~=)

Binary. If the two input are Float values, this performs a comparison of the right input to the left input and returns TRUE if the two values are within 0.0001 of one another and FALSE if not. If the two inputs are String values, this performs a case-insensitive comparison and returns TRUE if the two strings are the same and FALSE if not. The syntax for this operator is shown below:

   Input1 ~= Input2
   

Inequality (!=)

Binary. Performs a comparison of the right input to the left input and returns FALSE if they are the same and TRUE if not. If the two inputs are String values, this comparison is case-sensitive. The syntax for this operator is shown below:

   Input1 != Input2
   

Less Than (<)

Binary. Inputs can be Byte, Int, Float, or String values. Performs a comparison of the right input to the left input and returns TRUE if the value of the right input is less than the value of the left input. For String values, the comparison is alphabetical. The syntax for this operator is shown below:

   Input1 < Input2
   

Less Than or Equal (<=)

Binary. Inputs can be Byte, Int, Float, or String values. Performs a comparison of the right input to the left input and returns TRUE if the value of the right input is less than or equal to the value of the left input. For String values, the comparison is alphabetical. The syntax for this operator is shown below:

   Input1 <= Input2
   

Greater Than (>)

Binary. Inputs can be Byte, Int, Float, or String values. Performs a comparison of the right input to the left input and returns TRUE if the value of the right input is greater than the value of the left input. For String values, the comparison is alphabetical. The syntax for this operator is shown below:

   Input1 > Input2
   

Greater Than or Equal (>=)

Binary. Inputs can be Byte, Int, Float, or String values. Performs a comparison of the right input to the left input and returns TRUE if the value of the right input is greater than or equal to the value of the left input. For String values, the comparison is alphabetical. The syntax for this operator is shown below:

   Input1 >= Input2
   

Logical Operators

AND (&&)

Binary. Compares the values of the left and right inputs (which must evaluate to Bool values) and returns a value of TRUE if both inputs evaluate to TRUE. If the left input evaluates to FALSE, the right input is ignored and a value of FALSE is returned immediately since the comparison can never succeed. If the left input evaluates to TRUE, then the right input is evaluated as well. The syntax for this operator is shown below:

   Input1 && Input2
   

OR (||)

Binary. Compares the values of the left and right inputs (which must evaluate to Bool values) and returns a value of TRUE if either input evaluates to TRUE. If the left input evaluates to TRUE, the right input is ignored and a value of TRUE is returned immediately since the comparison will always succeed. If the left input evaluates to FALSE, then the right input is evaluated as well. The syntax for this operator is shown below:

   Input1 || Input2
   

XOR (^^)

Binary. Compares the values of the left and right inputs (which must evaluate to Bool values) and returns a value of TRUE if only one input evaluates to TRUE. Both inputs will always be evaluated. The syntax for this operator is shown below:

   Input1 ^^ Input2
   

Bitwise Operators

Negation (~)

Unary. Reverses each bit in the input value, i.e. 0's become 1's and 1's become 0's. The syntax for this operator is shown below:

   ~Input1
   

AND (&)

Binary. Compares the individual bits of the binary representation of the value of the inputs and sets the corresponding bit in the result to 1 when the bits of each input’s values are found to both be set to 1. If the bits are different or both set to 0, the corresponding bit in the result is set to 0. This operator only works on Int inputs and the result returned is an Int as well. The syntax for this operator is shown below:

   Input1 & Input2
   

OR (|)

Binary. Compares the individual bits of the binary representation of the value of the inputs and sets the corresponding bit in the result to 1 when the bits of either input’s values are set to 1. If the bits are both set to 0, the corresponding bit in the result is set to 0. This operator only works on Int inputs and the result returned is an Int as well. The syntax for this operator is shown below:

   Input1 | Input2
   

XOR (^)

Binary. Compares the individual bits of the binary representation of the value of the inputs and sets the corresponding bit in the result to 1 when the bits of only one input’s values are set to 1. If the bits are both set to 0 or 1, the corresponding bit in the result is set to 0. This operator only works on Int inputs and the result returned is an Int as well. The syntax for this operator is shown below:

   Input1 ^ Input2
   

Right Shift (>>)

Binary. Requires both inputs be Int values. Performs a bitwise shift to the right on the left input. The amount of bits that are shifted is determined by the right input. A right shift drops bits off the right side of the binary representation of the input’s value; essentially dividing by two each time a bit is shifted. Since it deals with Ints, when an odd number is divided by two, the result is truncated. The syntax for this operator is shown below:

   Input1 >> Input2
   

Left Shift (<<)

Binary. Requires both inputs be Int values. Performs a bitwise shift to the left on the left input. The amount of bits that are shifted is determined by the right input. A left shift adds bits to the right side of the binary representation of the input’s value; essentially multiplying by two each time a bit is shifted. The syntax for this operator is shown below:

   Input1 << Input2
   

Vector Operators

Cross Product (Cross)

Binary. Performs the cross product operation on the two input Vector values and outputs a Vector that is perpendicular to the two inputs. The syntax for this operator is shown below:

   Input1 Cross Input2
   

Dot Product (Dot)

Binary. Performs the dot product operation on the two input Vector values and outputs a Float value representing the scalar projection of the left input onto the right input. The result (assuming the two inputs are both unit vectors, e.g. each have a length of 1) can be anywhere from -1.0 to 1.0, with -1.0 representing the vectors pointing in perfectly opposite directions, 0.0 representing perpendicular vectors, and 1.0 representing parallel vectors pointing in the same direction. The syntax for this operator is shown below:

   Input1 Dot Input2
   

Reverse Rotation (>>)

Binary. The left input must be a Vector and the right input must be a Rotator. Performs a reverse rotation of the left input vector using the right input rotation which essentially means the vector is transformed from local space with the given rotation into world space. The syntax for this operator is shown below:

   Input1 >> Input2
   

Forward Rotation (<<)

Binary. The left input must be a Vector and the right input must be a Rotator. Performs a forward rotation of the left input vector using the right input rotation which essentially means the vector is transformed from world space into a local space with the given rotation. The syntax for this operator is shown below:

   Input1 << Input2
   

If you have a Vector facing 64 units ahead of a player, vect(64,0,0) is in local player-space. If you want it in world space, you have to transform it to world space using the player's rotation so you'd calculate it with the following:

myWorldSpaceVect = vect(64,0,0) >> playerPawn.rotation;

You'd want to use the forward rotation in cases when you have a world-space vector and you want it in local player space. As an example, you might want to convert a car actor's world-space velocity to local space so you can grab the X (forward velocity) to print it to a HUD.

Rotator Operators

ClockwiseFrom

Binary. The left and right inputs must be int values representing individual components (Pitch, Yaw, and Roll) of a Rotator. Returns a Bool value (TRUE or FALSE) specifying whether the left input is clockwise from the right input. The syntax for this operator is shown below:

   Input1 ClockwiseFrom Input2
   

Ternary operators

Conditional (? :)

Ternary. Returns the value of one of two (second or third) inputs based on the value of a first input. In essence, the first input is evaluated to either TRUE or FALSE. If the first input evaluates to TRUE, the value of second input is returned. If the value evaluates to FALSE, the value of the third input is returned. The syntax for this operator is shown below:

   Input1 ? Input2 : Input3
   

Operator precedence

The order in which operators are evealuated can completely alter the result of an expression. Each operator has a specific precendence value that determines which operators are evaluated first when a statement contains multiple operators. When you use a complex expression like 1 * 2 + 3 * 4, UnrealScript automatically groups the operators by precedence. Since multiplication has a higher precedence than addition, the expression is evaluated as (1 * 2) + (3 * 4).

The order of the built-in operators is shown in the table below (first to last) as well as the direction in which operators of the same precendence are evaluated (Associativity column):

New operators are added to the engine from time to time. For a complete list of operators, check the latest UnrealScript source - specifically the Object class.