If you've never written a line of code in your life, though, don't give up. Everyone has to start somewhere, and UnrealScript is as good a place as any. I've tried to make this tutorial as simple and basic as possible, so it can be understood by just about anyone. Like anything else, UnrealScript takes practice to become good at, but that doesn't mean it can't be fun along the way.

Alright. It's time to start your career in UnrealScript. Open up UnrealEd, and take a look around. The first thing you'll probably notice are the grided viewports in the center. These are meant for level design and you won't be using them for writing UnrealScript. Now take a look on the right. This is the browser window. By default, it displays textures for level design, but this isn't what you want. Click on the "Browse" pull-down menu, and select "Classes". This will bring up the class tree.

A popular analogy is to think of a class as a mold that is used to create objects in the game. You might have more than one skaarj in a game at the same time, but that doesn't mean that these skaarj are identical. One of them could be patrolling peacefully at its post, and the other might be fighting for its life against a blood-crazed player with an attitude and a big gun. They are both created from the same class, or "mold", but they are controlled separately.

In case you're new to 3D game development, there's something I should probably explain at this point. I've said an object is something in the game that can (usually) be seen and interacted with. What you "see" however is not dictated by the code you write for it. What you see is a 3D model which is created in a separate program entirely, such as 3D Studio Max or Lightwave. The code you write controls what the object does. A model without code will just sit there and do nothing in the game. Code makes your eightball fire when you click the mouse button, makes the rocket appear in front of you, and makes it speed off to explode between your enemy's eyes.

The idea behind having the classes arranged in a hierarchy is that each class will inherit code from the classes above it. Code that will be used for every class in the game is put in the top-most class, so it will be inherited by all the classes below it. This is very useful, since it means that you don't have to re-invent the wheel for each new class you create. If you want to create a new weapon, for instance, you can simply expand upon the existing Unreal weapon class, and add only the functionality that is specific to your weapon, instead of unnecessarily re-writing code that is already written in the base weapon class.

Now, click on the little minus sign by the word "Inventory" to display its child classes. After that, expand "Weapon", and look at what appears. All the Unreal weapons are child classes of Weapon, which is a child class of Inventory, which is a child class of Actor. There is quite a bit of code in Inventory and Weapon which controls the basics of how a weapon should act, but the specific code that controls how each individual weapon works is contained in that weapon's class. To get your first look at UnrealScript in all its glory, double-click on the FlakCannon class. A window with a dark blue background will appear, containing all the code for the FlakCannon. If you've written C++ or JavaScript before, you'll probably recognize quite a bit of the syntax. If you're new to programming, though, don't panic. Code may look complicated at first, but once you break it down, it's really very simple.

Code in UnealEd is color coded, as you've probably noticed already. Comments (text which is ignored by the compiler, and used to explain and document your code) are bright green, keywords are aqua blue, labels are yellow, exec commands are gray, and everything else is white. The first line of aqua blue and white when you first open the class is called the class declaration. Under this are the gray exec commands. These are used to import the models, sounds, and textures used by the class, and can be ignored for now. Scroll down till you get to some more colorful code. This code contains the variables, functions, and states of the class, and is what actually controls what the FlakCannon does.

Not too difficult, is it? All it consists of is the word "class", followed by the name of the class, then the word "expands" followed by the name of the parent class and a semicolon. The semicolon is just a way of telling the compiler that the statement is finished. Just about everything you write in UnrealScript will need a semicolon at the end, so get used to it.

Now, when writing code in UnrealEd, you won't have to worry about the class declaration much, since UnrealEd will automatically generate this line of code when you create a new class. However, if you write code in text-based .uc files outside of UnrealEd, you will need to write the class declaration manually.

Technically speaking, a variable is a location in your computer's memory that stores a piece of information. This information can be of many different types, such as numbers or words. Variables come in handy all the time while writing code. For example, let's say you're making a new weapon, and you want it to charge up in alt-fire. To accomplish this, you could use a variable. When the player presses alt-fire, have Unreal add to this variable. Then, when the player presses fire, have Unreal fire a projectile that does a varying amount of damage according to the value that was stored in your charge variable.

Damn, I didn't do a very good job explaining that, did I? Well, hopefully you're able to grasp the concept of variables without much help from me. I've found that most people don't have much trouble with it. It's just one of those things that naturally makes sense.

Pretty straight-forward. First comes the keyword "var", then the type of variable you are declaring, and finally the name of the variable. Variables must be declared at the beginning of a class, after the class declaration and exec commands, but before any functions. There are many different types of variables, ranging from numbers, to letters and words, to "true" or "false" values. The types available in UnrealScript are as follows:

You cannot increment and decrement a float using the same syntax as an int. To add one to a float, you would have to say "myFloat = myFloat + 1;", not "myFloat++;". It's also important to keep in mind one other thing when working with integers and floats. Take a look at these examples:

In example one, Result will not equal 2.5. Because you are multiplying an integer by a float, you will always get an integer back. If you wanted to get 2.5 back, you would have to declare myInt as a float, not an int. The same is true for example two. Even though you are dividing 5 by 2, and assigning the result to a float, you will not get 2.5 back, because the 5 is an integer. Also, note the way I've declared the two floats in this example. You can declare multiple variables in the same statement by simply separating the different variable names with commas.

Keyword: bool

Note that the prefix "b" is often used in boolean variable names. This is just a naming convention, though, and it's not a required.

Keyword: byte

Again, note the prefix "b". For some reason, Epic chose to use the same naming convention for both bytes and bools. So, be careful not to confuse the two when looking through existing scripts.

Note that strings are declared in a special way. The number in the square brackets after the word "string" is the maximum number of characters the string can be. In this example, the maximum length of String1, String2, or Result would be 32. There are also many special operations which can be performed on strings, such as "concantations" (or combining two strings into one), finding left or right characters, or finding the length of the string.

Keyword: name

Keyword: enum

//Declare a new enumeration
enum EColor;
{
	CO_Red,
	CO_Blue,
	CO_Green
};

//Declare variable of type EColor
var EColor MyColor;

//Assign a value
MyColor = CO_Blue;

Note that the "CO_" preceding each of the color values is simply a naming convention, and is not required. You can name your enumeration values anything you want.

Keyword: n/a

You'll notice I didn't include any examples explaining how you assign a value to an actor reference. This is because you can only set an actor reference equal to another actor reference, or to a newly spawned actor using the Spawn() function. As I said, actor references are difficult to explain at this point, but I'll go into more detail later, once you've learned a bit more.

Keyword: class

The word "Actor" in angle brackets after the word "class" in the declaration means that Actor is the upper limit of this variable. What this means is that MyClass cannot be set equal to anything higher than Actor in the class tree. Class references are assigned values by using the keyword Class, followed by the name of a class in single quotes.

Keyword: struct

if ([expression1] [operator] [expression2])
{
	Do some stuff here;
}
else if ([expression1] [operator] [expression2])
{
	Do more stuff here;
}
else
{
	Hey, look, more stuff;
}

First, Unreal checks to see if the first condition is true by comparing expression1 to expression2 using the operator. If that condition checks out, then the first set of commands are executed, and the conditional is finished. If the first condition isn't true, though, Unreal will check the second condition, and if it's true, it'll execute the second set of commands. If it goes through all the conditions, and none of them are true, it will execute the "else" set of commands. When writing a conditional, you don't have to have else if's and else's. They're just available should you need to be more specific with what you want Unreal to do. All you have to have when writing a conditional is the first "if" statement. There are many different operators that can be used in conditionals, as you can see in this table:

Not every operator will work with every variable type. For instance, you can't really say that one actor reference is "greater than" another actor reference, so the four greater than/less than operators aren't applicable to actor references. Just use common sense to determine what will work with what, and you should be just fine.

var bool bSomeBool, bSomeOtherBool;
var int SomeInt, SomeOtherInt;

if (SomeInt > 3)
{
	SomeInt is greater than 3, so do 
	something;
}
else if (SomeOtherInt <= SomeInt)
{
	SomeInt is not greater than 3, 
	but SomeOtherInt is less than or 
	equal to SomeInt, so do something 
	else;
}
else
{
	All the conditionals failed, so 
	do this;
}

if (bSomeBool)
{
	bSomeBool is true, so do this;
}
else if (!bSomeOtherBool)
{
	The first conditional failed, but 
	bSomeOtherBool is false, so do this 
	instead;
}

Note the way I used the bools in the second conditional. Because bools can only be one of two values (true or false), they don't need to be compared using two expressions. Saying "if (bSomeBool)" is the same as saying "if (bSomeBool == true)", and saying "if (!bSomeOtherBool)" is the same as saying "if (bSomeOtherBool == false)". Now, moving on, what if you wanted to do something only if two conditions were true? Or what if you wanted to do something if only one of two different conditions were true? That's where these operators come in:

These are used to link conditions together in the same statement. Take a look at this example:

var bool bSomeBool;
var int SomeInt, SomeOtherInt;

if (SomeInt > 3 && SomeOtherInt < 3)
{
	SomeInt is greater than three, 
	and SomeOtherInt is less than 
	three, so do something;
}
else if (SomeOtherInt == SomeInt || !bSomeBool)
{
	The first condition failed, but 
	either SomeOtherInt equals SomeInt, 
	or bSomeBool is false, so do this 
	instead;
}

In the first one, && links the two statements together, so the condition is only true if both statements are true. In the else if, || links the two expressions together, so the condition will be true if either of the statements is true.

F o r   L o o p s

var int i;

for ( i=0; i<5; i++ )
{
	Do stuff;
}

var int i;

do
{
	Do stuff;
	i++;
} until (i == 5);

var int i;

while ( i < 5 )
{
	Do stuff;
	i++;
}

var string[32] Developer;

switch ( Developer )
{
	case "Tim":
		Hey, it's Tim. Do something;
		break;
 
	case "Cliff":
		Look, there's Cliffy.  
		Do something else;
		break;

	case "Myscha":
		Where'd Myscha come from?  
		Better do something else;
		break;

	default:
		No one here;
		break;
}

So, what's a function, you ask? A function is just a block of code that performs some action. Once they're defined, they can be called in other parts of the code, to do whatever it is they're supposed to do. They can be given, or passed, variables when they're called, and they can return values. I know this all probably sounds very complicated (assuming you've never done any programming before), but it's really fairly simple once you understand it. Take a look at this example:

var int SomeInt, Result;

//Take an integer, and return its square
function int Sqr( int Num )
{
	return Num * Num;
}

//Test the Sqr() function
function PostBeginPlay()
{
	SomeInt = 3;
	Result = Sqr(SomeInt);
}

There are two functions here, Sqr(), and PostBeginPlay(). Sqr() takes a number, Num, multiplies it by itself, and returns it. You'll notice that I didn't declare Num up with SomeInt and Result. This is because it is "declared" as a parameter to a function. When I call Sqr() down in the PostBeginPlay() function, I supply SomeInt as the value in parenthesis, or the parameter. The call to Sqr() causes the code contained in the Sqr() function to be executed, with SomeInt plugged in for Num. You'll also notice that I put the call to Sqr() after "Result =". This is because I am assigning the value which is returned by Sqr() to Result. When all this code is done executing, Result will be equal to 9: the square of 3. You may also have noticed the keyword "int" before the function name in Sqr()'s definition. This "int" means that Sqr() returns an integer value.

Anyway, you may be wondering by now, Where is PostBeginPlay() being called from? The answer is, the engine. There are a wide variety of functions in UnrealScript which are called by the engine in certain places and under certain circumstances. The PostBeginPlay() function is called when an object is first created, so it makes a good place to put code that you want to be executed before any other code. For a list of common functions which are called by the engine (as well as other useful functions which aren't called by the engine), refer to the Function Reference at the side of this page.

So, are you thoroughly confused yet? If not, then you're doing good. I know I was scratching my head quite a bit when I first learned this stuff. Well, keep reading, it gets better (or worse, depending on your viewpoint). You know the way I've been declaring variables all along? At the beginning of a class, using the syntax "var [vartype] [varname]"? Well, that's not the only way you can declare a variable. That type of variable, declared outside of any functions, is called a global variable. Global variables can be accessed anywhere in a class, and even outside of a class (as we'll see a little later). But, there are also local variables. Local variables are declared at the beginning of a function, and can only be accessed within that function. They're useful for doing short-term operations that won't need to be "seen" outside of a particular function. You see, one of the key elements of a function, and of object-oriented program as a whole, is the fact that a class or function can share useful data and important information with other classes and functions, but hide how they got that useful data and information. They show only the result, but not how they found the result. In any case, where was I going with this? Oh, yes. Local variables. Local variables are declared just like global variables, only they use the local keyword instead of the var keyword.

function PostBeginPlay()
{
	//Declare a local integer
	local int SomeInt;

	//Assign a value
	SomeInt = 3;
}

So, that's a local variable. Not too complicated, is it? Just like a global variable, except for the fact that it can only be accessed inside a particular function.

Any new code you write in a class is simply added on to the code inherited from parent classes. But what if you wanted to change a certain inherited function? Well, you can. It's called overriding a function. All you have to do is copy the function definition into the new class (the name, parameters, and return value type), and write new code for it. The ability to do this is extremely useful in UScript, since it allows you to add or change functionality in things without having to copy over all the code. For instance, say you wanted to make an ASMD that launched grenades in alt-fire instead of the little blue energy ball thingy. All you would have to do is copy the one function that controls what happens when the player presses alt-fire, and make a few little changes. Nothing to it.

state Idle
{
	function AnimEnd()
	{
		PlayIdleAnim();
	}

	function bool PutDown()
	{
		GotoState('DownWeapon');
		return True;
	}

Begin:
	bPointing=False;
	if ( (AmmoType != None) 
	    && (AmmoType.AmmoAmount<=0) ) 
		Pawn(Owner).SwitchToBestWeapon();
	if ( Pawn(Owner).bFire!=0 ) Fire(0.0);
	if ( Pawn(Owner).bAltFire!=0 ) AltFire(0.0);	
	Disable('AnimEnd');
	PlayIdleAnim();
}

Code in states can be written either within functions, or under labels. Begin is by far the most common label, and any code written under it is executed as soon as the class enters that state. Another cool thing about states is that you can use them to override functions within a particular class. For instance, say you had a Timer() function defined outside of a state. If you defined another Timer() function within a state, then that Timer() function would override the global one if the class was in that state.

Another useful thing you can do with a state is to stop certain functions from executing while the class is in that state. For example, if you wanted to make it so the player couldn't fire while his gun was reloading (usually a good idea), you could add this line just after the definition of your reload state:

ignores Fire, AltFire;

This makes it so neither the Fire() or AltFire() function can be executed while the class is in this state. To make an object enter a state, use the syntax: "GoToState('State');".

var([defaultgroup]) [vartype] [varname];

The part in the parenthesis, defaultgroup, tells Unreal what section of the default properties you want the variable to be displayed in. If you don't supply anything for this parameter, it will be displayed in a section with the same name as the class. You can look at and change the default properties of a class by selecting it in the class browser, and clicking the "Defaults" button.

To start off, I suppose I should explain a little something about the way Unreal is organized. All classes, sounds, textures, and models are stored in special files called packages. Most of the code and models, and some of the textures and sounds for Unreal are stored in two files: unreali.u, and unrealshare.u (as of 220, anyway). These files are found in your Unreal\System directory, as are all .u files. When you create a new class in UnrealScript, you store that class in a new .u file. It's not a good idea to store a new class in an existing .u file, since you would then have to pass around the entire file if you wanted to distribute your class.

With that out of the way, let's get ready to rumble. Open up UnrealEd (if you don't already have it open), and get to the class browser. Open up the Inventory and Weapon threads, and select the FlakCannon class. Now, hit the "New..." button, which can be found down below the browser. You'll get a window asking you to enter a class name, and a package name. Enter "MultiCannon" in both fields, and press the "Create this actor class" button. You'll see that your MultiCannon class will appear under FlakCannon in the class tree, and an editor window will appear, complete with the class declaration.

The next thing to do is copy the AltFire() function from the FlakCannon class, since we want to modify what the weapon shoots in alt-fire. AltFire() is simply a function which is called by the engine when the player presses the alt-fire button. It's used to control what happens when a weapon alt-fires. The same goes for the Fire() function, but we're not modifying primary fire here, so we don't need Fire(). Anyway, double-click on FlakCannon in the class browser to open it up. Scroll through the code until you find the AltFire() function, and copy it into your MultiCannon class. You'll notice that the new code appears as all green when you first copy it. This is because UnrealEd doesn't apply the proper coloring to code until you compile it. So, let's compile it. Compiling in UnrealEd couldn't be easier. Simply hit the F7 key to compile all modified classes.

Now, add the following local variable declarations to your new AltFire() function:

local projectile p;
local class<projectile> Proj;
local float Selection;

Next, find the line "Spawn(class'FlakShell',,, Start,AdjustedAim);", and replace it with the following lines:

Selection = FRand ();
if ( Selection < 0.4 )
	Proj = Class'FlakShell';
else if ( Selection < 0.7 )
	Proj = Class'Grenade';
else
	Proj = Class'TazerProj';
p = Spawn(Proj,,, Start,AdjustedAim);
if ( Proj == Class'Grenade' )
	p.DrawScale *= 1.5;

That's it. Those are all the modifications that need to be made. Hit F7 again to compile the changes, and you're set. So, what does all this code do, you ask? Well, it's simple, really. Selection is set equal to FRand(), which returns a random number between 0.0 and 1.0. Then, an if/else if/else is used to set Proj to either FlakShell, Grenade, or TazerProj, depending on the value of Selection. Whatever Proj is set to is then spawned (Spawn() is a function that brings a class into existence in the Unreal world), and at the same time, p is set equal to this new projectile.

Now, here's something I haven't explained quite yet. The line "p.DrawScale *= 1.5;" is used to reference a variable called "DrawScale" in p, and assign it as itself times 1.5. This is useful notation. If you want to reference a variable or function in another class, all you have to do is specify which class it's in by putting the name of the class, followed by a dot and the name of the variable or function.

So, that's it. Your first new UnrealScript class. Before the MultiCannon package will actually be written to your hard disk for use in-game, though, you'll have to save it. Hit the "Save" button at the bottom of the class browser, and select "MultiCannon" in the pull down menu of the window that appears. You'll need to do this every time you make any changes to one of your classes. Now, to try out your work in a game, start up Unreal, go to the console, and type "summon multicannon.multicannon"

Written by Windex