中国翻译
한국어
Interested in the Unreal Engine?
Visit the Unreal Technology site.
Looking for jobs and company info?
Check out the Epic games site.
Questions about support via UDN?
Contact the UDN Staff
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 like123
. If the string doesn't represent a value, the result is0
. - 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"
toTrue
andFalse
; converts any non-zero value toTrue
; everything else isFalse
. - Bool to String: Result is either
"True"
or"False"
. - Byte, Int, Float, Vector, Rotator to Bool: Converts nonzero values to
True
; zero values toFalse
. - Bool to Byte, Int, Float: Converts
True
to1
;False
to0
. - 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 isNone
;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^{2} 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 performx *= 4
, the value ofx
will be 8 afterward. The multiplication is performed first and then the result is assigned to the left input, in this casex
. 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 andFALSE
if not. If the two inputs areString
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 returnsTRUE
if the two values are within0.0001
of one another andFALSE
if not. If the two inputs areString
values, this performs a case-insensitive comparison and returnsTRUE
if the two strings are the same andFALSE
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 andTRUE
if not. If the two inputs areString
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
, orString
values. Performs a comparison of the right input to the left input and returnsTRUE
if the value of the right input is less than the value of the left input. ForString
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
, orString
values. Performs a comparison of the right input to the left input and returnsTRUE
if the value of the right input is less than or equal to the value of the left input. ForString
values, the comparison is alphabetical. The syntax for this operator is shown below:Input1 <= Input2
- Greater Than (>)
- Binary. Inputs can be
Byte
,Int
,Float
, orString
values. Performs a comparison of the right input to the left input and returnsTRUE
if the value of the right input is greater than the value of the left input. ForString
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
, orString
values. Performs a comparison of the right input to the left input and returnsTRUE
if the value of the right input is greater than or equal to the value of the left input. ForString
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 ofTRUE
if both inputs evaluate toTRUE
. If the left input evaluates toFALSE
, the right input is ignored and a value ofFALSE
is returned immediately since the comparison can never succeed. If the left input evaluates toTRUE
, 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 ofTRUE
if either input evaluates toTRUE
. If the left input evaluates toTRUE
, the right input is ignored and a value ofTRUE
is returned immediately since the comparison will always succeed. If the left input evaluates toFALSE
, 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 ofTRUE
if only one input evaluates toTRUE
. 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 anInt
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 anInt
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 anInt
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 withInts
, 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 aVector
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 aFloat
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 aRotator
. 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 aRotator
. 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
, andRoll
) of aRotator
. Returns aBool
value (TRUE
orFALSE
) 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
orFALSE
. If the first input evaluates toTRUE
, the value of second input is returned. If the value evaluates toFALSE
, 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):
Operator | Associativity |
---|---|
( ) | Left to Right |
!, ++, --, -, ~ | Right to Left |
Dot, Cross, ClockwiseFrom | Left to Right |
*, /, % | Left to Right |
+, - | Left to Right |
<<, >> | Left to Right |
<, >, <=, >= | Left to Right |
=, ! , ~= | Left to Right |
& | Left to Right |
^ | Left to Right |
| | Left to Right |
&& | Left to Right |
|| | Left to Right |
^^ | Left to Right |
@, $ | Left to Right |
, + , -=, *=, /=, @=, $= | Right to Left |
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.