Lesson 5 - UnrealScript: Variables

[Feralidragon]

This lesson covers the variables syntax of UnrealScript.
Just as mentioned earlier, variables are used to store data, and they can hold data permanently or temporarily.

Every single variable needs to be "declared", or in another words, you have to tell that the variable exists and what it's supposed to store in it.
The syntax is very simple:
var (variable type) (variable name)
or
local (variable type) (variable name)

Examples:

Code: Select all

var int SomeNumber;

local int SomeLocalNumber;

The main difference of declaring a variable with either var or local, is that the former is only used outside functions to store permanent data (which means that data stored in a var will be kept as long as the object or actor exists, which also means that variables declared as var are members of the class they are within).
On the other hand, variables declared as local are only used within functions, and are temporary and unaccessible from outside that function, hence once a function call finishes they simply disappear.


Variables are always declared before any code further is written. Unlike some other languages, you cannot declare variables in the middle of the code in UnrealScript.
Examples:

Code: Select all

class SomeClass extends Actor;

var int Var1;
var string Var2;
var bool Var3;

//Rest of the class code goes here

Code: Select all

function SomeFunction()
{
local int Var4;
local string Var5;
local bool Var6;

//Rest of the function code goes here
}

In UnrealScript every variable can hold a specific limited amount of data of a specific type, and they are divided into 4 main sets of types:
- primary
- enumeration
- reference
- structure


Primary types:
The primary types are the ones which store the most basic kind of data: numbers, text, etc, and in UnrealScript there are only 6 of them:

- bool: a boolean type, and its value can only be True or False.

- byte: an unsigned byte type, and as such its value can only range between 0 and 255.

- int: a signed 32bits integer type, as as such possible values can only range from -2147483648 to 2147483647.

- float: a float types, or in other words, any kind of real number with decimal places, like 1.25, 502.1235, etc. Keep in mind however due to the very nature of the float type ("float" stands for "floating point"), you may get precision errors the more decimal places you use or the higher the number itself becomes.

- name: a name is like a keyword, since it obbeys the same rules as the naming of variables and functions themselves (only letters, numbers and underscore, cannot start with numbers and cannot have spaces). They're represented within single quotes, as: 'Name_1', 'Name_2', 'Name_3'.
Don't use this type for normal text though, the name type is to be used as an identifier alone and cannot be concatenated.

- string: a normal text type, here you can use any characters you wish and it uses double quotes to enclose them, as: "This is some text".


Enumeration types:
The enumeration types are the ones which store "meaning" behind a set of numeric values. For example:

Code: Select all

enum EBtnPress
{
    BT_None,
    BT_PressUp,
    BT_PressDown
};

var EBtnPress ButtonPress;

In this example we declared a new enumeration type called EBtnPress, and then we created an actual variable using that type called ButtonPress.
Enumerations are nothing more than normal primary byte types, but with the catch that each value of the byte (0, 1, 2, ...) can be named to your liking and represent that value.
They are also good to restrict the range of that byte to the size of the enumeration.
Let's analyze the example above:
- BT_None represents the byte value 0;
- BT_PressUp represents the byte value 1;
- and so on, up to BT_PressDown in this case.

Therefore we can make friendly code like:

Code: Select all

if (ButtonPress == BT_PressUp)

instead of:

Code: Select all

if (ButtonPress == 1)

which is confusing.

And is also possible to make these:

Code: Select all

if (ButtonPress > BT_None)

Therefore, if you want to represent something through the values of a byte variable (0 means "this", 1 means "that"), enumerations are the correct way to go.
They are also used to be able to build list boxes when seeing an actor property in Unreal Editor for example.
The greatest and highest usage you will find on enumerations is when dealing with replication, but that will be explained later on in the replication lessons.


Reference types:
The reference types are the ones which store object or class references. They're generally also called "pointers".
Example:

Code: Select all

var Actor A;
var class<Effects> FXClass;

With variables storing a pointer to an actor, allows you to manipulate the actor itself and even retrieve its data, for example:

Code: Select all

var Actor A;
var float glow;

function PostBeginPlay()
{
    A.DrawScale = 2.0;
    A.PlayAnim('SomeAnim');
    glow = A.ScaleGlow;
}

where once the PostBeginPlay function is called, the DrawScale property from the actor referenced through A is changed to 2.0, and then PlayAnim is called from the same actor.
At the end, our object glow variable assumes the value of the ScaleGlow property of the actor A.
Being that A is just pointing at the actor, this means that if the actor changes in some way, A and all the variables pointing to this actor will see those changes as well.


Structure types:
The structure types are the ones which store other variables within them instead of actual data, therefore it's somewhat like creating our own variable types (in a way). For example:

Code: Select all

struct SomeStruct
{
    var int Var1;
    var string Var2;
    var Actor Var3;
};

var SomeStruct MyStructVar;

In short, MyStructVar is of the type structure called SomeStruct, which stores 3 variables of the types int, string and Actor respectively.
Then you can access them as:

Code: Select all

local int local_var1;
local string local_var2;
local Actor local_var3;

    local_var1 = MyStructVar.Var1;
    local_var2 = MyStructVar.Var2;
    local_var3 = MyStructVar.Var3;

And the biggest advantage of this is the ability of doing the following:

Code: Select all

local SomeStruct local_struct;

    local_struct = MyStructVar;

which basically means that you don't have to manually write that local_struct.Var1 = MyStructVar.Var1 and so on when reusing the same structure type.
This is useful when you want to represent a bunch of different data encapsulated into a single variable, and you can even create new structures with other structures within them, like:

Code: Select all

struct MegaStruct
{
    var string VarTxt;
    var SomeStruct VarStruct;
};

The engine already comes with some built-in structures like vector and rotator, whereas vector represents a 3D point in space (through X, Y and Z, declared as float variables) and a rotator represents rotation in 3D space (through Pitch, Yaw and Roll, declared as int variables).

________________________________________________________________________________________________________________________

< Previous lesson | Next lesson > (soon)

[Cronoloop]

I would have put this as one of the first lessons, btw you're great at explaining.
Waiting for more

[Feralidragon]

Thanks.
I know the standard order of things should be starting here, however I am doing this in a different order since through my whole life I never saw the "standard" way actually working with more than just a few people: people who were a bit into coding already.

Therefore, my idea in how this should get going is to first explain what coding essentially is (lesson 0), then go straight to some simple mods so people can have a sample and how it feels to make a mod all by themselves (lessons 1 and 2), and by doing so those people start to win confidence, motivation and a liking to learn more, as they start thinking "hey, this wasn't hard to do, I think I am starting to get the hang of it".
From that moment, the true lessons can finally begin (lesson 3 onwards) and by having done something small but somewhat "useful" already, they may be able to understand the rest with some ease.

What I often see is that by starting with theory on what a variable is, conditions, programming structure and the like, the whole thing looks so damn boring that the person will simply skip it, and then it's harder to go back and re-learn the basics first.

[Cronoloop]

Thanks.
What I often see is that by starting with theory on what a variable is, conditions, programming structure and the like, the whole thing looks so damn boring that the person will simply skip it, and then it's harder to go back and re-learn the basics first.

Lol yes, you made me remember myself years ago, when we were learning Pascal. I was bored about variables and things, so I told the teacher: "When we're going to make a space invaders game?!" lol
Thinking again, you did it well for the newcomers. GJ