Literals

Literals in general are notations that represent a value. This article describes the types of literals available in UnrealScript.

Numbers

In UnrealScript, all numeric literals start with a digit. Numeric literals can either stand for an integer or a floating point value and may be prefixed with a minus sign.

Integer numbers

The UnrealScript compiler knows two types of integer literals: decimal and hexadecimal. Decimal literals only consist of the decimal digits 0 to 9, while hexadecimal literals start with 0x, directly followed by the hexadecimal digits 0 to 9 and A to F. Upper- and lowercase letters can be mixed freely in hexadecimal literals.

Examples:

123

0xC0FFEE

010

The first example is a typical decimal literal that can represent a byte or int value, while the second example is a hexadecimal literal that exceeds the byte range and definitely stands for a value of type int. The third example is not octal, but just a decimal literal with a leading zero representing the value ten.

Float numbers

Floating point literals always start with one or more digits, followed by a decimal dot. After the dot, there may be zero or more decimal digits.

Examples:

1.0

123.456

987.

Note that you can't use the comma as decimal separator, even if that's the standard way to display decimal fractions on your system.

Other ways to specify numbers

The compiler recognizes any "glob" consisting of digits, the letters A to F, the letter X and the decimal dot as a number, as long as it starts with a digit. If it contains an X then it's treated as hexadecimal integer literal, if it contains a dot it's treated as floating point literal, otherwise it's a decimal integer literal.

This loose interpretation allows two additional number notations: octal integer literals and scientific floating point literals, the latter only with unsigned exponent, though. An octal integer literal starts with 0, followed by any combination of the octal digits 0 to 7. It also needs to include the letter X, otherwise it will be treated as decimal integer literal.

Examples:

0123456789ax

123456789ax

The first example is interpreted as the value 1234567_oct, which is the same as 342391_dec. The character 8 is no valid octal digit and thus terminates the value. The compiler takes the entire number glob, sees the X in it and passes it to the generic number parser. That one sees the leading zero, not followed by an X and treats the literal as octal. The second example contains an X, but does not start with a 0, so it is actually treated as decimal literal and stands for the value 123456789_dec. It contains the letter A, but it doesn't start with 0x, so it's not a hexadecimal literal and the number parser stops when it arrives at the A.

A scientific floating point literal starts like a normal floating point literal, but after the decimal dot and optional decimal places there's the letter D or E, followed by one or more digits.

Examples:

1.5e2

1.5d2

1.5e+2

1.5e-2

1.f

Only the first two examples actually are actually a single literal. The next two examples really represent the expressions 1.5 +/- 2.0 respectively. The last example can be found quite often in the UT2004 script code and is nothing else than the value 1.0 expressed in a way C++ and Java programmers immediately recognize as a float value. You could, in fact, also write 1.a and it would mean the exact same thing in UnrealScript.

Boolean values

Boolean literals are quick to explain. There are only two of them, True and False. Both are case-insensitive, like any other identifiers in UnrealScript, so "true" and "tRuE" are the same thing to the compiler.

Strings

String literals start and end with double quotes. Between these there may be any number of characters, except line breaks. To include a double quote or backslash character in the string, it must be "escaped" by a(nother) backslash character. Starting with Unreal Engine 3, strings can also contain other escape sequences, such as \n for a newline character. In Unreal Engine 1 and 2 escaped letters only stand for themselves, i.e. the string "\n" is absolutely equal to the string "n" there.

Examples:

"abc"

"This is an \"example\"."

""

Names

Name literals are similar to strings. They are enclosed in single quotes and may only contain letters, digits and the underscore character. Name literals can't contain escape sequences.

Examples:

'RedBase'

'SniperNest2'

''

The last example is an empty name, which is often used to spawn actors without a Tag or to switch to the null state. It is actually the same as the name literal 'None', but sometimes the empty name makes more sense.

Enums

An enum literal can only be used when specifying a value of an enum type. For example the parameter of the SetPhysics function can be any of the EPhysics values, like PHYS_Falling or PHYS_Projectile.

Examples:

PHYS_Walking

ROLE_SimulatedProxy

DP_UpperRight

Request_GET

Objects

Generally, an object literal starts with the unqualified name of an object class, followed by a qualified or unqualified name of an object instance, enclosed in single quotes. These single quotes work slightly different from those of name literals in that there may be whitespace around them. The same goes for the dots between the parts of qualified object names.

Examples:

class'Actor'

Texture 'Engine.WhiteTexture'

Sound ' Announcer . monsterkill '

The first example is an unqualified literal of type Class representing the Actor class. The compiler will automatically find out the package containing the class, if it is already loaded. If the package isn't loaded, the lookup will fail. In this case the compiler issues a warning or an error. The second example is a qualified literal of type Texture representing the WhiteTexture object in the Engine package. Note that WhiteTexture doesn't actually need to be a Texture, but could also be any subclass of Texture, such as FireTexture. The object literal only specifies the base class and name of the object. The third example represents the monsterkill sound in the Announcer package. Again, this doesn't need to be a Sound object, but could for example be a SoundGroup object.

There are also two special object literals. The literal None stands for no object. The literal Self can only be used in states and non-static functions and stands for the object instance executing that piece of code.

Structs

There are no general struct literals, but the compiler recognizes literals for vector and rotator constants.

Vectors

A vector literal looks like a function call, but actually represents a constant value. It starts with the keyword Vect, followed by number literals for each of the three components in the order X, Y, Z. The component values are separated by commas and enclosed in round parentheses. You can't use variables or return values of functions here!

Example:

vect(0,0,0)

vect (1.2, 3.4 , 5.6)

The first example is the null vector, i.e. a vector of length zero with an unspecified direction.

Rotators

Rotator literals are similar to vector literals. They start with the keyword Rot, followed by the Pitch, Yaw and Roll components. Like vector components, these are separated by commas and enclosed in round parentheses. Variables and functions are not allowed in rotator literals.

Example:

rot(0,0,0)

rot (1234, 5678 , 9012)

Range

In various engine builds the compiler also accepts literals for the Object.Range type in the form rng(A, B). Most builds don't implement the UnrealScript byte code for this literal though, which causes the compiler to crash.

Functions

Function literals are only used in delegate assignments. They consist only of the function name without any special symbols or the keyword None if no function is to be assigned.