U   n   r   e   a   l   S   c   r   i   p  t
by   Windex

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.

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.

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.

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.

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.

I n t e g e r

Keyword: int

An integer number value. For those of you not familiar with what an integer is, it's a whole number that can also be negative. In other words, anything without a decimal. 37 is an integer. 2 is an integer. -674 is an integer. 6.3432 is not an integer.      Integer Example var int myInt; myInt = 3; //Assign a value myInt++; //Increment myInt--; //Decrement   Note the special syntax you can use to add or subtract one from an integer. Saying "myInt++;" does the same thing as saying "myInt = myInt + 1;", and saying "myInt--;" does the same thing as saying "myInt = myInt - 1;".

F l o a t i n g   P o i n t

Keyword: float

A number value that, unlike an integer, can include decimals. 6.3432, 4534243.2, and -0.98 are all floating point numbers.      Floating Point Example var float myFloat; myFloat = 3.2453; //Assign a value   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:      Integers and Floats Don't Mix var int myInt; var float myFloat, Result; //Example 1 myInt = 5; myFloat = 0.5; Result = myFloat * myInt; //Example 2 myInt = 5; myFloat = 2.0; Result = myInt / myFloat;   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.

B o o l e a n   V a l u e

Keyword: bool

A value which is either "true" or "false". These have not always been around, since it's possible to simply use an integer, and set it to either 0 or 1. This would give the same effect. However, it's easier to see and understand the words true and false than it is to understand a 0 or 1, so the bool was introduced.      Boolean Example var bool bMyBool; bMyBool = true; //Assign a value   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.

B y t e

Keyword: byte

An integer value in the range of 0 to 255. The use of these may not be apparent at first glance. You're probably saying to yourself, Why not just use an integer? Well, I honestly can't answer that. I very rarely (if ever) use these, so I'm not extremely clear on their advantages. I can give you an example of one thing they are used for, though, and that is RGB color values, which fall in the range of 0 to 255.      Byte Example var byte bMyByte; bMyByte = 255; //Assign a value   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.

S t r i n g

Keyword: string

A string is simply a bunch of alpha-numeric characters. In other words... well, words. Strings of letters and numbers that make up words and sentences.      String Example var string[32] String1; //Declare string var string[32] String2; var string[32] Result; String1 = "Blah"; //Assign a value String2 = "Gah"; //Combine two strings Result = String1 $ String2; //Find left 2 characters of String1 Result = Left(String1, 2); //Find right 2 characters of String1 Result = Right(String1, 2); //Find the number of characters in String1 Result = Len(String1); //Return String1 in all caps Result = Caps(String1);   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.

N a m e

Keyword: name

Names are a tough one. They're hardly ever used, and understood by few. I'll do my best to explain them, though. The only application I can think of for them is in tags. If you've done any level design, you've probably used tags. They're used to associate one object with another in order to trigger certain events. Anyway, tags are simply name variables. It can be easy to confuse names with strings, but names are not strings. A string can be modified dynamically, but a name is simply a label for an object.      Name Example var name MyName; MyName = 'Windex'; //Assign a value

E n u m e r a t i o n

Keyword: enum

Enumerations are simply a way of defining a type of variable that can be one of a certain pre-defined set of values. Like bools, they're not absolutely necessary, since integers could be used to get the same effect. However, it's easier to see understand a set of descriptive words instead of a bunch of numbers.      Enumeration Example //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.

A c t o r   R e f e r e n c e

Keyword: n/a

Actor references are a special type of variable that references an actual object in the game. It will be difficult to fully grasp them at this point, but I'll give you the basics, at any rate. Later on, once I've introduced functions, I'll go into more detail about them.      Actor Reference Example //Declare a reference to any actor var Actor MyActor; //Declare a reference to a pawn var Pawn MyPawn; //Declare a reference to a weapon var Weapon MyWeapon;   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.

C l a s s   R e f e r e n c e

Keyword: class

Class references, like actor references, are a special type of variable. Also like actor references, they're difficult to explain at this point. I'll do my best, though. A class reference, unlike an actor reference, doesn't reference an actual object in the world. It references a class itself, or the mold. It references the thing that creates objects, instead of the objects themselves.      Class Reference Example //Declare a class reference var class<Actor> MyClass; //Assign a value MyClass = Class'Pawn';   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.

S t r u c t

Keyword: struct

A structure is a way of defining a new type of "super-variable" that is made up of individual components. A struct is actually similar to a class, although a very simple class that can only contain variables. Structs define a new type of variable that can be declared and used just as any other variable. Take this example:      Struct Example //Define a new struct struct Box { var float Length; var float Width; var float Height }; //Declare a couple variables of type Box var Box MyBox, YourBox; //Assign values to individual components YourBox.Length = 3.5; YourBox.Width = 5.43; YourBox.Height = 2.8; //Set MyBox equal to YourBox MyBox = YourBox;   The struct defines a new type of variable, called "Box", which has three sub-variables to it: length, width, and height. Once you define a variable of the new type, you can assign values to its individual components with the syntax "VarName.ComponentName". One very common struct in UnrealScript is the vector, which is made up of X, Y, and Z components. The techniques of working with vectors are somewhat complex, and you can learn more about them in the Vectors tutorial.

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

For loops are the type I use the most, since I've found that they usually fit my needs just as well or better than the other two types. The basic concept of a for loop is to execute a certain block of code over and over again, until a certain condition is met.      For Loop Example var int i; for ( i=0; i<5; i++ ) { Do stuff; }   The first statement in the parenthesis, "i=0", sets the initial value of i as the loop starts. The second statement, "i<5", is the condition that must be met for the loop to continue executing. As soon as i is greater than or equal to 5, the loop will terminate. The final statement, "i++", is what is done to i each time the loop executes. So, the first time this loop executes, i will equal 0. The next time, i will be incremented by one, making it equal 1. This is still less than 5, so the loop executes again. Next time, i will be 2, then 3, then 4, and finally 5. The loop will terminate once it gets to 5, since 5 is not less than 5.

D o   L o o p s

Do loops, unlike for loops, have no built-in expressions for incrementing counters or setting initial values. They simply execute over and over until a condition at the end of the loop is met. Because they have no built-in expression for incrementing a variable, you will have to include a line within the loop that somehow increments or changes your counter variable, so that the ending condition will eventually be met. Otherwise, you get an infinite loop. Not a good thing.      Do Loop Example var int i; do { Do stuff; i++; } until (i == 5);   You'll notice I included the line "i++;" within the loop. This will increment i each time the loop executes, so it will terminate when i gets to 5. The main distinction of the do loop is the fact that it executes until some condition is true. Both for and while loops execute while some condition is true.

W h i l e   L o o p s

While loops are basically do loops, except for the fact that they execute while their condition is true, whereas do loops execute until their condition is true. Again, you'll have to include a line in the loop to somehow increment your counter variable, since there is no built-in expression for this in the loop declaration.      While Loop Example var int i; while ( i < 5 ) { Do stuff; i++; }

S w i t c h   S t a t e m e n t s

A switch statement is basically like a complicated if statement. It allows you to execute different blocks of code depending on the value of a certain variable. Take a look at this example:      Switch Statement Example 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; }   Not too complicated. You just supply the variable you want to use for the switch in the first parameter, then write different "cases" depending on the different values of the variable. The final "default" label is optional, and will be executed if none of the other cases are true. Note the break statements marking the end of each case. Like I said before, switch statements are basically just complicated if statements. I rarely have use for them, since the same effects can be achieved simply by using an if/else if/else.

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.

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.

Good luck, and I hope to see some kick ass weapons from you :)