Learning UnrealScript Part 3 – Your First Class

Just as promised, in this installment I’m going to walk you through writing your first class, which will eventually become the base for a custom AI. Before we start I must let you know that although I have done a LOT of work with UnrealScript (custom weapons, custom menus, etc.), I have never worked with AI. And this is a good thing for you because I’m actually going to be learning the system as we go along, and I’ll offer insights into not only the “what” but the “why” and the “how”.

One of the reasons I’ve avoided messing with UDK’s AI is its size. Open up Windows Explorer and navigate to \Development\Src\UTGame\Classes\UTBot.uc — it’s a 164 KB file, one of the biggest in the entire game. That translates to over 6000 lines of code. For a programming newbie, the task of writing a custom AI based on such a class would be daunting.

But alright, suppose we wanted to do it anyway. Open your favorite programming IDE (mine is WOTGreal, available for download here: http://www.wotgreal.com/, but you could just as easily use Notepad) and open up UTBot.uc. The first non-commented line in the entire file is:

class UTBot extends UDKBot dependson(UTCharInfo);

Whenever you make a new .uc file, the first line of code must always be of this type. It may not include the extra “dependson”, but at the very least it should say class [your class name] extends [another class name]. And you should save your file as [your class name].uc. So, let’s open up a new file and save it as MyBot.uc in the folder \Development\Src\MyGame\Classes\. The first line of this file will be:

class MyBot extends UTBot;

We don’t need to rewrite the “dependson” because the parent class has already done that for us, but we DO need to specify the parent class (in this case UTBot). Now let’s go back to UTBot.uc and study its contents a bit more.

Under this first line of code there are a whole bunch of lines that say something like “var [blah blah blah]”. These are (you guessed it) variables global to this class. In UnrealScript, you can declare such global variables and allow them to be used by any of the functions in the class (as well as other classes, but we’ll get to that later) — the only requirement is that they are written at the start of the file, before all of the functions. The format is simple: var [type] [name]. For example, “var bool bHuntPlayer” is a variable called bHuntPlayer that is a boolean: it can only store either ‘true’ or ‘false’.

Then come the functions, which are of the type function [type] [function name] ([parameter 1], [parameter 2], etc.) {}. The only requirement is the function’s name. [type] is optional, and it declares what kind of variable this function returns. The parameters are also optional, and it declares the variables the function takes as inputs. So a function that just does something (no input/output) could be: “function DoStuff() {}”. You don’t need to write “void” or anything like that.

Inside functions you can declare local variables, which are only accessible by that function. They are of the form local [type] [name]. Like the global variables described earlier, they must come before anything else in the function, so always declare them first.

Now scroll all the way to the bottom of the file, and you’ll see a thing called defaultproperties {} with a bunch of stuff between the brackets. This is (as far as I know) a thing unique to UnrealScript: here is where you declare all the default values for global variables. When the class is first initialized in-game, the variables that have defaultproperties values will be given those values, and all others will be set to null.

Alright, let’s actually do something. One of the first things I noticed about UTBot.uc when I opened it up was the section of variables that looks like this:

var float BaseAlertness;
var float Accuracy;
var float BaseAggressiveness;
var float StrafingAbility;
var float CombatStyle;
var float Tactics;
var float ReactionTime;
var float Jumpiness;
var class<Weapon> FavoriteWeapon;
var float OldMessageTime;

Epic Games is practically giving you the keys to the AI kingdom right here; just flip a few of these values and suddenly you’ve got a totally different AI. Intrigued, I decided to research further by Ctrl+F’ing “CombatStyle”. On line 1500-something, I found this:

CombatStyle = FClamp(BotInfo.AIData.CombatStyle, -1, 1);

I noticed that “BotInfo” was just the input parameter to the function I was in:

function Initialize(float InSkill, const out CharacterInfo BotInfo) {}

Researching CharacterInfo took me to UTCharInfo.uc, which extends Object and, more importantly, has a config(CharInfo) modifier. This means that it saves and draws its data via the config files, more specifically the CharInfo config file. Hop on over to \UDKGame\Config\DefaultCharInfo.ini to see for yourself: all the bot characters that you play against in UDK, each with specific settings on Accuracy, Jumpiness, and more.

Of course, I had already seen this config file a billion times before, so why go through all this? The answer is because it’s a prime example of something you’re going to have to do all the time when you’re coding UnrealScript: jump from file to file, following the path that a variable or function takes through the system, to understand what it does. Even if I had never seen UDK before, using this strategy I could have figured out how UDK grabs the values for each bot from the config file and uses them in its AI code.

While you’re in the config files, notice also how not all of the bots have custom AIData values. In particular, most of them are lacking the Aggressiveness value. So head on back to your custom file, MyBot.uc, and add this:

defaultproperties
 {
 Aggressiveness=+00000.70000
 BaseAggressiveness=+00000.70000
 CombatStyle=+00000.80000
 }

Remember that the default values in UTBot were around 0.2-0.4; this is almost double. In other words, now you’re going to have insanely aggressive enemies fighting you, and according to their combat styles they will almost always rush you.

One last problem: how to actually get this in game? To do that, UDK is going to have to recognize this custom file. Open up a new file and call it MyGame.uc, then add:

class MyGame extends UTGame;
defaultproperties
{ 
BotClass=class'MyGame.MyBot'
}

Notice how the “.” operator discussed in the previous tutorial comes into play here. We are referencing the MyBot class that is in the folder \MyGame\Classes\, so our string becomes MyGame.MyBot.

Finally you’re going to need to have Frontend recognize that your new files exist, so open up the config file DefaultEngineUDK.ini and add the line +EditPackages=MyGame right under the line +EditPackages=UTGameContent (Ctrl+F it if you need to). Then, save a close DefaultEngineUDK.ini and delete UDKEngine.ini. That’s right, I said delete: UDK rewrites any missing .ini files with the default ones, and we want our changes to take effect.

With that done, open up UDK Frontend and recompile. Now you’re ready to try out your crazy new AI in a map of your choosing. Just open the map in the editor, go to View –> World Properties, change the “Game Type for PIE” to “MyGame” and play in the editor! Wow, custom AI without even a single function written!

Okay, so it’s not the best AI in the world…and not really suitable for a game, either. Next up we’ll begin improving on the AI by writing some functions. We’ll also begin to look more into the UDK class tree and see how different groups of classes interact.

Previous: The UDK Directory
Next: Building an AI Class