CH3Z/Developer Journal

UnrealScript For Non-Programmers

(new page candidate for "Category Tutorial" ?)

Please note: Unreal Wiki is not a site that intends to teach programming, nor is its primary audience intended to be that of beginners to programming. This guide exists within Unreal Wiki merely as an attempt to give you some of the knowledge that you will most definitely need in order to do anything with the information that this site provides. With that, please understand that the concept of programming offered here is geared toward OOP and is sometimes specific to UnrealScript as the intention of this guide is to explain more clearly what it is that you are changing when you modify a game.

Overview

Why This Tutorial Exists: I don't see anywhere else on Unreal Wiki for would-be-scriptors to start if they have no programming experience whatsoever. So I'll start an introduction to programming here. "Programming" as it is discussed here will be OOP as that is the type of programming that is done when using UnrealScript.
Do I Have Be Able To Write A Whole Program?!?!: To modify Unreal Engine games you will not write a program. The program is already written. You will however need to understand what that program is and how it is structured in order to add to it. Even if you want to take away from the program you will be adding something to it that takes part of it away.
About Reading This Tutorial: Throughout this guide you will see certain keywords or phrases in italics. This formatting will either mean that the word will be discussed more later, or that the word has already been discussed and I want you to note its usage in that sentence. It may also be to bring your attention to an important phrase. Also, note that the links provided within this tutorial are usually placed for you in case you want to take a quick look and then come back here to finish your reading. If you click on one of them and then click a link from that page you may end up sidetracked or temporarily lost. Remember how you found this tutorial; it is currently located at Category Journal on the sub page /CH3Z.
Where This Tutorial Will Take You: Jumping right into it, we will need to have an overview of what an OOP program is and what it does followed by an explanation of how it all fits together. Then we can examine the more involved inner workings of what makes things actually happen in a program: the code.

Taking it in that order lets see if we can define it and define what it does.

What an OOP Program is and What it Does

First of all a program is a file (data) that changes other data. Your operating system (perhaps DOS) is a program. An example of the data that it might change would be the data that the computer is sending to your monitor. Your program might change that data from being no data sent to the monitor (resulting in blank screen) to data being sent to the monitor telling it to light up certain pixels on the screen in a pattern resembling letters that spell out "Hello World". An image file is data but it is not a program. While its data is a pattern of pixels to light up on the monitor, which will resemble a picture of something, that data alone changes nothing, therefore the image file is not a program. A program would change the data sent to the monitor to be the data that the image file contains. In an OOP program, subclasses of class objects change (override) data in their parent class and act as extensions of the program itself. This will become clearer as you read on.

Programs execute one line of code at a time in a linear fashion. Starting from the first line of code the program will continue to the second line of code and then the third, unless one of those lines of code instruct the program to jump to another line and execute it. If perhaps the fourth line of code instructs the program to execute the 27th line of code the program will do so and then resume execution of its code from line five. Line 27 of the program's code may be the beginning of a block of code that consists of 5 or 6 lines of code. All 5 or 6 lines would be executed before the program returns to line 5 to continue from there. One of those 5 or 6 lines of code may instruct the program to jump back up to line 14. The program will then execute line 14 and all lines that follow within the block that begins at line 14 and then return to the next line of the block that began at 27 and finish that block before returning to line 5.

Rather than bounce around up and down a list of instructions an Object Oriented Program will jump a lot of the time to code within a separate modular piece of the program. This modular piece of the program, perhaps a class file, is compiled and embedded into the program and becomes kind of a file inside of a file. An Exe file that appears to be one file that is the program may actually be made up of individual modules and compiled into one file. Just as the program would jump to line 27 of its code, a line of code in an OOP program may call (tell the program to jump to) code within another module. That module is kind of like one of the blocks of code mentioned earlier. Now when you look at the code you can see the core of the program in one module, and specialized sections of code contained in separate modules that might be extended even further other modules that hold even more specific code related to the module that they are extending.

Use your imagination. Depending on the type of program you are writing, you might imagine the modules representing different "real life" objects. For example, if you are writing a business program you may imagine different modules being different departments within the same office, each having specific duties where all departments work on modulated aspects of the office's one project. If you were writing a game some of the modules would be items and some would be players. Still yet some other modules in a game would be physics of world the game takes place in and some would be smaller components of one module that is an item in the game (like a bullets for a gun or guns for a player). If all of the code in the program was one long list of code to be executed in linear fashion it would be very hard to keep track of while you were writing it and almost impossible to fix or change the code later. That's how it used to be done, but we know better now. Another reason for programs being OOP is that you can actually use these modules in other programs that you write and save a whole lot of time for yourself.

An OOP program might have an object named "DoDraw" built into it that specifies pixels to light up which creates an image with a black border and an effect applied to the image. That object may have another object named "DrawDogs" linked to it that extends "DoDraw" and specifies an alternate border color or alternate image or alternate or alternate effect. This OOP "Program" is "Oriented" to evaluate a hierarchy of "Objects". When it is time for this program to "DrawDogs" it will see that "DrawDogs" extends (is a branch of) "DoDraw" and will execute all the commands in "DoDraw" with the data in "DrawDogs" overriding some of the data in "DoDraw". You see here that "DrawDogs" has extended "DoDraw" to do a more specific task.

Who Begat Who? Further down, the branch of the hierarchy that starts with "DoDraw" and branches off to "DrawDogs" may be even further extended by an object named "DogsPoodle" which overrides data in "DrawDogs" to draw a specific class of dog like a poodle, thus extending "DrawDog to do a more specific task. There may even be subclasses extending "DogsPoodle" such as "PoodleFrench". In effect, when it is time for the program to draw a french poodle, "PoodleFrench" will inherit all the code from "DogsPoodle" which inherits all the code from "DrawDogs" which inherits all the code from "DoDraw" therefore allowing "PoodleFrench" to draw a specific picture with specific borders and effects. In OOP when an object is a subclass of another object and therefor has access to all of its parents code, this is called inheritance.

This quote is part the definition of the word "modify" according to Webster:

...a : to make minor changes in b : to make basic or fundamental changes in often to give a new orientation to or to serve a new end <the wing of a bird is an arm modified for flying...

So, a "wing" is a subclass of the object "arm".

(By permission. From Merriam-Webster's Online Dictionary at [www.Merriam-Webster.com] by Merriam-Webster, Incorporated)</wiki>

So, What's In It For Me? If you were to write a mod for this program it might be to add a new class of dog, perhaps "DogsBull" or maybe you want to add a new class of animal to "DoDraw", perhaps "DrawCats". Can you imagine a subclass that would extend "DrawCats"? How about a subclass that extends "DogsBull"? For that matter, can you imagine another subclass extending "DoDraw"?

Consider how the hierarchy of this program would look.

 Object
    +-SomeSubClass
    +-AnotherSubClass
    |     +-SubClass of AnotherSubClass
    |
    +-DoDraw
    |     +-DrawCats
    |     +-DrawDogs
    |     |     +-DogsBull
    |     |     +-DogsPoodle
    |     |         +-PoodleFrench

If you can imagine these modifications then you can imagine a new subclass to extend "Weapon" which extends "Inventory" which extends "Actor". It would be a specific type of weapon that the actor has available to add to its inventory.

One such subclass is "FlakCannon". What subclass does "FlakCannon" extend? See if you can answer that question before reading on. If you said Weapon, you are correct. So the first line of code that makes the FlakCannon exist in UT is simply:

class FlakCannon extends Weapon;

Just as a poodle has inherited characteristics from its parent that make the poodle what it is, part of an OOP program can inherit characteristics from its parent class. Just as the poodle may have a different personality than its parent, a part of an OOP program may override some of the characteristics that it has inherited. Just as a poodle is a class of dog, a dog is a class of animal, an animal is a class of life form, a life form is a class of "thing", makes a poodle a specific "thing", a class object in an OOP program is a subclass of an object higher in the hierarchy of objects within the OOP program.

How all of These Things Are Put Together to Make an OOP Program

Here, you will gain understanding of the structure of an OOP program. The section after this one will introduce you to all the things that it consists of so you will see how thy all interact with each other to carry out the objective that the program is written for.

With the knowledge you now have its time for you take a look at the Class Tree of the Unreal Engine. See if you can find where FlakCannon fits hierarchy and see if that make sense to you. Then come back here.

Now go back to the Class Tree and/or click on Weapon so you can see all the code that FlakCannon inherits from its parent class. The actual class, FlakCannon, has overridden some of that code to make it still a weapon but a unique and specific weapon. Try to pick out some of the things you would suspect that FlakCannon overrides to make itself unique. Then return here.

Now you should read Unreal Object Oriented Programming for a nice introduction to how OOP is used in the UnrealScript and how it is important to you if you are interested in modifying an Unreal Engine based game. Then take a look at OOP Overview for another example of OOP and a peak at some coding conventions used. Then come back here and continue reading the next section to understand more about the code.

What an OOP Program Consists of

Objects: defined on Terminology as: "abstraction that typically is assigned clearly specified characteristics; in other words, a chunk of data with a certain class associated to it; the class describes the data structure and contains the code that deals with objects of that class".
Classes: defined on Terminology as: "type of an object, an object's class defines how an object is implemented; derived from or instantiated by an object, from which it inherits clearly defined attributes. A class can contain: static data members, objects of another class, pointers and references to types and objects of the same or another class, declarations of another class, member functions, and friend classes. All Classes are listed in the Actor browser".
Functions: defined on Terminology as: "piece of code with a defined entry point and one or more exit points".

Basically, a section of code within an object that is declared (created and defined) and does nothing until it is called from somewhere else. I assume that the "defined entry point" would be the point at which another function calls that function. At that point the program will begin to execute the code in that function in the order that the function dictates. Within the function will be at least one "exit point" which tells the program that there is no more code to execute from that function.

That exit point may be reached upon completion of every line of code in the function or as the result of a test within that function that indicates in the event of a negative result the program should skip all the rest of the code in the function and exit.

When the program exits that function it resumes executing code in the function that called it, and continues this until reaching an exit point in that function.

Variables: defined on Terminology as: "memory location with a symbolic name where a program can store information for future retrieval".

When a variable is declared (created and defined) in a program it becomes the symbolic name of a location in memory and your program can save data to that location. The data in that variable (its "value") can be read and can be changed by the program. You can declare variables in your program and name them whatever you want to name them as long as the name is not recognized anywhere else in the program as something other than a variable or as another variable (still yet, that depends on the "scope" in which that variable exists – more on scope shortly).

A variable is created as soon as it is declared, and it is initialized (set to a specific value) with its data type's empty value. I would suggest that you initialize your variables as soon as you have declared them to keep a more organized frame of mind about them. Otherwise, if you try to retrieve the value of your variable later you may get a value like "Null" or something instead of the value you could have initialized it to such as "0" or "" (a text value with no text yet) or anything else that might make more sense to you than whatever UnrealScript might put there depending on the data type you declared the variable as. An example of initializing a variable will follow later in this tutorial and you will see how that initial value can make more sense.

Scope has to do with depths of a program and at what depths a variable exists. For example if you declared a variable as "local" then its scope is only within that function or class that is created in unless it is passed to another function or class as a parameter. Therefore, if a function outside of that variable's scope was to try to look at that variable to change it or retrieve the value of it, your program would error because the variable doesn't exist to that function. If you declared the variable as "public" then you had better make sure that its name is quite unique and keep track of where all it is being changed from because it can be called from anywhere in the program, from any function in any class. If you loose track of that then your program is out of control and functions might be working on corrupted data that doesn't add up later on because the variable's value gets changed by one function while another function is working with its previous value, unaware of the change.

Just take the general idea for now. You will understand more when you start to use variables. They will become clearer also as you start to see them in the examples you will be studying here.

Continue reading here. After this next section, a look back at OOP Overview will show you how much you are learning by your being able to follow the code samples offered there.

A Deeper Look Into Program Construction

Here we will examine other parts of the code that makes up a program such as Tests and Loops. This section intends to prepare you to further understand these concepts by examining the UnrealScript Language Reference/Program Structure and then I think you have earned your white-belt and can consider yourself a no0b.

Tests

Conditional Statements such as the tests we will discuss here are how your program is directed as to what it should do next. Keep in mind that if you are writing a program, it only does what you tell it to. Even if it does something that is not what you intended to be the outcome. It is still doing what you told it to do, and the error therefore is yours.

Your program is no smarter than you are. If this program can only do what you tell it do when you write it then you are going to have to give it a way to do more than simply going down a linear list of commands. Try to consider what a program could possibly accomplish with that kind of structure. It could maybe stuff a few variables with numeric values and perform some math functions on them dumping the result into another variable and print that variable's value to the screen. Weeeeeee! But can it check to see if the answer is correct?

You have to help your program act non-linearly. If you know how to make your program perform tests and take particular action(s) depending on the results of those tests then it becomes much more dimensional and capable of much more. For instance, Picture an egg on a fence. It's going to fall one way or the other way. On one side of the fence is a cement sidewalk, hard and unforgiving. On the other side of fence is a water trough full of soft, impact-absorbing water. We can use a conditional statement for our to program to perform specified tasks depending on the outcome.

We know what the outcome of the egg falling one way would be over it falling the other. Let's assume that there is already a function written in our class to assign a random number to our variable we have created to represent the state of the egg. With that variable's value set to be a random number from one to two, we want our program to draw a broken egg at the point that it lands on the sidewalk if our program finds the current value of that variable to be "1". And we want to run an animation of water splashing if it falls into the trough because the variable intEggState has a value of "2".

With intEggState already declared elsewhere and a function that keeps it set to a value that indicates the current state of the egg, how do we tell the program to execute one task depending on one outcome? Here is where a test of intEggState's value will let our program know what it should do next. Our program is an OOP program and we are writing code in a subclass that inherits code from its parent (i.e. a function named "Draw()" ). So all we have to do here is call on the functions that already exist. We will tell our program to do what we want it to do in the case of intEggState by writing an if statement.

"if", "else", and "else if":

(Two forward slashes (//) tells the program that anything else on the rest of this line is only a comment to future readers of the code and to skip everything on this line after the slashes.)

// If the egg lands on the sidewalk, it breaks.
if( intEggState == 1 )
    Draw( BrokenEgg );

What was that all about? When the program sees the keyword "if", it will test the condition set within the following parenthesis. Upon finding that the condition is true, it will execute the code that follows on the next line. When finding that the condition is not true the program will exit the whole if statement doing nothing and proceed linearly to the next piece of code. But what if the egg didn't land on the sidewalk but instead in the trough? The test above does not account for that. It would do nothing, but we wanted it to draw a splash animation if it landed in the water. How about this code:

else

// If the egg lands on the sidewalk, it breaks
// but if the egg lands in the trough, it splashes.
if( intEggState == 1 )
    Draw( BrokenEgg );
else
    Draw( SplashAnimation );

When the program finds the condition following the keyword "if" to be true, it will execute the code that follows and then exit the if statement ignoring the "else" keyword as well as the code following. We are satisfied with this because there was only one outcome and therefore we only wanted one thing to happen.

When the program finds the condition of if to be false, it will skip the next code and begin to work from the keyword "else" and will execute the code following and the egg will splash into the trough. Again we would be satisfied with the single action performed in reaction to the single outcome. But what if the egg hadn't fallen yet?

We will have to assume here that when the variable intEggState was declared that it was also initialized to have a value of "0".

(like this)

var int intEggState; //Declared the variable
intEggState=0; //Initialized the variable to a value other than 1 or 2

Now, until the egg falls one way or the other, it remains on the fence and therefore intEggState's value remains "0".

else if

// If the egg lands on the sidewalk, it breaks
// but if the egg lands in the trough, it splashes.
// If it hasn't fallen yet, it does nothing.
if( intEggState == 1 )
    Draw( BrokenEgg );
else if( intEggState == 2 )
    Draw( SplashAnimation );

When the program finds the condition of if to be false, it will skip the next code and begin to work from the keyword "else". Here it finds another if keyword. When it finds the condition of "else if" to be true it will execute the code following the condition and the egg will splash into the trough. But we already know the egg hasn't fallen yet so in this case, the program would find the condition of if to be false and test the condition of else if, finding it false, and exit the whole if statement doing nothing. This would satisfy us, as we don't want anything to happen until the egg falls.

Case Tests: (In Progress... Might use Case to evaluate the eggs "State".)

Loops

The For Loop: (In Progress)
The Do Loops: (In Progress)

That's the jist of it. Go get more acquainted with the concepts you have learned here at:

You have completed the Introduction To Programming Tutorial for beginners at Unreal Wiki. Please, comment in the "Discussion" area at the bottom of this page if you feel that this tutorial needs more development in a particular area or comment on anything that would make this tutorial of greater benefit to its audience. Having used this tutorial from the status of complete beginner with no prior programming experience, YOU are best judge of its intuitiveness and effectiveness.

Happy Modding And Best Wishes For Success!

 
 (This whole tutorial is a work in progress.)

Where You Might Go From Here

Having completed this tutorial, you may find any of the next steps to be practical furtherance of your studies.

UnrealScript Lessons

Category Journal