Package

A package is a package is a package. It just differs in what you put into it.

Updated to reflect UT2003 paradigm.

The Basics

When I first began getting into editing for Unreal Tournament, there were many things that confused me. When reading tutorials, I found that there were a lot of ideas that weren't explained, as they were so obviously basic knowledge, that most tutorial authors assumed that you would already know them. But to someone like me, with no previous programming experience, those were the very ideas I needed to learn the most to get started.

This document attempts to address some of those basic concepts. There are 4 basic areas to creating content for Unreal Tournament:

Scripting - writing the code to describe how objects in UT behave
Mapping - creating the maps and applying textures to those maps
Modelling - creating new object models to be used in UT
Texturing - creating the textures and meshes that will used in maps and models

This tutorial only focuses on the first of those four.

Classes vs. Packages

The first hurdle for me was to understand the difference and relationship between the UT Classes and the UT files. I think was made this the most difficult, was that sometimes, when referencing a class, the name of the file is used, and sometimes, it isn't. Also, a class representation, such as "Pawn.PlayerReplicationInfo" looks exactly like a variable reference, such as "PlayerReplicationInfo.PlayerName". In addition, classes have an entirely different heirarchy than the files, and it's for the most part, completely unrelated. Hey, while we're at it, what exactly is a class file anyway, and where do I find it? Add that all together, and you have a potentially very confusing situation for a wet-behind-the-ears scripter like myself.

Confused? Don't worry, I'll explain it all right here

What Are Packages?

Many times you will see references to something called a package. Well, what exactly IS a package? A package refers to ANY of the Unreal file formats - such as: .u, .ut2, .utx, .uax, .umx, .uz2, .uxx, .usx (can also be a combination of any of these files! ). Each of these extensions represents a file containing a different type of Unreal content. .u files contain unrealscript classes, .utx packages contain textures, .uax packages contain sounds, .ut2 packages contain maps, and so on.

The engine does not actually care about the extensions at all - the engine sees all packages equally, but it suuure makes life easier for us humans . It would be perfectly valid to create a .utx file which contains nothing but classes (though it *would* be pretty tricky to coax the compiler into doing this). I mention this only for completeness (and to satisfy the header that is not a header ), as that is more of an advanced topic. At this point, it is best to think of each extension as representing a container file which holds a different type of content. Let's now begin to focus on the type of package we're interested in - a .u package!

Unreal .u files are essentially containers for the class scripts. It's much like a zip file, in fact, since you can put any type of class, regardless of what it does, into a package....but what's a class?

What Are Classes?

TODO Insert links to pages that

have more comprehensive introductions to class objects
outline the difference between classes and objects

The whole idea behind UnrealScript is a programming concept called Object Oriented Programming. Basically, this means that we're going to create the entire program using individual little pieces, called objects, which define their own behaviors and parameters. Those objects interact with each other inside the realm of the Unreal engine, with scripting to tell them how to interact with each other. It's important to remember, here, that there is no external influence telling these objects how to behave (for the most part). They are fully self-contained objects which control their own behavior and how they'll react when another object comes into their sphere of influence. That's your basic (extremely basic) overview of OOP (Object Oriented Programming)...let's move on to UnrealScript's implementation of this.

A .u package file may contain many classes. A few examples: GameInfo, Mutator, UTServerAdmin, Inventory. Each of these classes tells the Unreal Engine about an object in the Unreal universe. In UnrealScript, each class that we create becomes an object in the Unreal engine. This means that for every "piece" of a mutator, mod, or whatever, we must write a seperate class file for it. For instance, in the case of writing a new weapon, you must write one class (class = object) for the weapon, and another class for the ammo that goes into the weapon. You must write yet another class for the projectiles that the weapon fires, and yet another class for the shell casing (for example) that are produced when you fire a weapon. Another class must be written for the muzzle flash, yet another for the explosion your weapon causes when it hits something, etc. etc. So, you will write several classes for a simple weapon, each class describing a different object that the engine must know about in order for your weapon to be successfully loaded and used in the game. The number of "pieces", or classes you use is, for the most part, entirely up to you, subject only to the laws of practicality.

For now, remember that .u files contain classes, which each define a single object in the Unreal engine. These classes tell the engine all about how that object interacts with the rest of the objects in the engine, and together, they create a mutator, mod, or what-have-you.

Components of .U Files

Now a little about how an Unreal .u is put together.

If you unsure of exactly how to create a class script, how to setup the folders, and how to compile those .uc files into a .u file, you should first read over the following pages:

http://unreal.epicgames.com/UTMods.html

Setting Up UnrealScript

When you write a script, you use text, such as

class Mutator extends Info;

var PlayerPawn P;

function ModifyPlayer(Pawn Other);

defaultproperties { }

It would take an extremely long time, however, for the computer to parse these text statements during the game, so you must first compile the script. Compiling is the process of converting all of the text you've written into computer optimized code, commonly referred to as 'binary'. After the compilation process has completed, you should see a new .u package in your System directory, with the same name as the directory you created. If you look at compiled script (a .u package) in a text editor, it will look like gibberish:

 ×£<]$)\²=Pe6
 õJ¯'ÁžP×²!À°
 L¢bBƒ€mcìkÁ€
 mcì[Á€mcìKÁ€
 ½Ë¹'Aümcî;Á¤
 mcî3Á¥mcî3Á¦
 mcî3Á§hcxBƒ€
 mcî3Á¬$×£<]<
 [×£$$)\£%<[=

Once the script has been compiled into a package this way, you can no longer modify the package. In order to make changes, you must delete the compiled package, make the changes to the original script text, and recompile it.

For further information on the process of creating and compiling your scripts, check out Compiling with UCC.

ClassName/PackageName Notation

Suppose you had written a class called 'MyWeaponClass', and named the folder for all your script 'MyWeaponMod'. Your compiled package name would be 'MyWeaponMod.u'. There are two distinct heirarchies, or "trees", which can be used to refer to the MyWeaponClass class which now resides inside the MyWeaponMod.u package. These two trees are commonly referred to the as the Package Tree, and the Class Tree. The Unreal engine uses a dotted notation system to access different branches of these trees, and the notation used for both systems is exactly the same, so this can be a little confusing at first.

Which tree you should use in order to reference a class depends on the situation.

The Package Tree looks very much like the directory structure of your Unreal directory. Within each folder, there are a number of .uc files. Each .uc file contains the script for one class. Each .u package contains one class for each .uc file that was in the respective folder. To reference a class using the package tree, the syntax is

PackageName.ClassName

Note that the extension is omitted. Why? As I said above, the extensions are only to help humans keep everything straight - the engine saves and loads all packages exactly the same.

The Class Tree works quite differently. As you probably know by now, the Object class is the base class for all of the Unreal classes. If you take a look at Object.uc, inside the Core\Classes\ folder, you'll see that it is the only class that does not 'extend' or 'expand' another class. In the class tree, this is similar to the root directory of the game. All classes which directly subclass Object would be like the first level of folders in your Unreal installation, with the classes that subclass those classes being like the second level of subfolders, and so on. Referencing a class in the class tree is done directly - no package name is necessary.

InstaGibDM? (UT2003/4: MutInstaGib?) is the name of the class that defines the InstaGib? mutator, and this class file is located in the "container" BotPack?.u (UT2003/4: XGame?.u) package, which is in the System directory. The .u packages also contains many other classes which work together to define a number of behaviors for the game. In some cases, such as Engine.u, the classes contained by the package do not necessarily relate to each, while in other cases, such as IpDrv.u, all of the classes contained in the package are focused on a particular area of the game. To reference a class using the class tree, you do not specify the package at all.

 class'ClassName'

That's it!

TODO: Just as a packages contain classes, so do classes contain variables and functions. To access variables and function within a class, you must sometimes use a combination of package notation and class notation.

Here is an example of starting a dedicated server from the command line. Notice that the class names (CTFGame, XMapsControl, SuperInstaGib) are preceeded by package names using a dotted notation system:

  ucc server CTF-Face.unr?game=Botpack.CTFGame?mutator=XMaps.XMapsControl,SuperInstaGib3.SuperInstaGib

  or, for UT2003/4

  ucc server CTF-Gaul.ut2?Game=XGame.xCTFGame?Mutator=XGame.MutInstaGib

Look at the part that begins with

?game=Botpack.CTFGame

The first of Botpack.CTFGame is Botpack. This tells the computer which package file we're using. If you look in your System directory, sure enough, you'll see a file called Botpack.u. Inside of the Botpack.u package, there is a class called CTFGame. This class tells the engine all about a particular object that exists in the game, and in this case, the object represents a gametype called CaptureTheFlag.

On to the next part: ?mutator=XMaps.XMapsControl. This says that we're using a package called XMaps, and that the mutator class that should be spawned by the engine upon starting up is a class named XMapsControl. The next parameter reads exactly the same: in a package named SuperInstaGib3, spawn a mutator class named SuperInstaGib (which is responsible for controlling the spawning and initialization of the rest of the classes in the package). So in essence, the UnrealTournament heirarchy is much like any other dotted notation system. If you are familiar with OOP concepts, then this is nothing new.

If you aren't, then not to worry. If you understand how website addresses work, you'll have no problem learning how to interpret the dotted notation to correctly map class names to package files.

How Unreal Engine Maps Package Names To Class Names

Here I'll explain a little more in depth the role of the package as opposed to the role of the class to the Unreal engine. The way it works is very similar to the way a webserver works. Let's say I'm hosting a website on my computer - www.scriptnewbie.com. On my computer, I have designated a particular folder, "C:\WebServer\", as the default directory that will contain all my webpages, such as home.htm, links.htm, etc...

Let's say I have some pictures I on my website, and these pictures are located on my harddrive in the

C:\Pictures

directory. However, when I set up my webserver, I set up a "virtual" directory that points to that C:\Pictures directory. The details of this are unimportant, but here's my point:

When you access my website, you will do so by typing http://www.scriptnewbie.com into your browser. You will then actually be accessing my "C:\WebServer" directory, but to you, it appears as though you are accessing the root directory of www.scriptnewbie.com . If you want to access my pictures, you would then type into your browser http://www.scriptnewbie.com/pics/ to access my C:\Pictures directory, but again, to you, it appears as though you're accessing the "pics" subdirectory of the website.

In similar fashion, the packages of the engine are like the actual directories on my harddrive: C:\WebServer, and C:\Pictures, whereas the classes are like the virtual folders you type into your browser. You could not type into your browser:

C:\www.scriptnewbie.com\Pics

and expect to arrive at my website nor would you type:

C:\Website\

on your computer and expect to arrive at that directory on my computer.

My content's physical location is C:\WebServer, but my WebServer software mediates between you (the user) and the physical location. Same thing goes for UT. In both cases, content may be in any arbitrary physical location. It does not matter to the web visitor, because the server software handles the mapping.

When you are writing the script text, importing textures, referencing sounds, etc., you will be working with the file heirarchy in detail. It's important to know which classes reside in which .u files, which textures reside in which .utx file, which sounds reside in which .uax file, etc. This is like looking at my webserver from my computer. It's important I know which actual directory my pictures are located in, so that I can place the resources in the correct place, and configure my webserver to pull the resources from the correct location when you attempt to access the /pics/ directory.

In Unreal, as the script is being executed, it's unimportant (for the most part**) which particular .u file a class is in, because we're now working with a completely different heirarchy. We are now inside the "Engine" of Unreanl, and will be accessing those textures, classes, sounds, etc. from the standpoint of an object (every aspect of Unreal is an object) inside the engine, much like the visitor to my website accesses my pictures using the "/pics/" directory. The actual .u file an object belongs to doesn't really matter inside the game, because I'm using the Unreal server to access the information I need. The actual folder that the content resides in on my computer doesn't really matter to my website visitor, because he is using my webserver to access that information.

** Protocol and intention is that no two objects can have the same name, such as Botpack.BlueFlag and MyMod.BlueFlag. However, there is nothing to prevent you from doing this, as it is syntactically correct. UnrealScript is designed to be much more pliant than other programming languages with regards to duplicate files and null references (this is intentional). As a result, you must be very careful if you choose to give a class the same name as a class in another package. It will be allowed by the compiler (unless it is in the same package) but you may get very unreliable results while playing.

Package Flags

Normally clients connecting to a game server will download all packages that are currently in use by the server. If you don't want that because it's unnecessary, you can set certain package flags to specify how the server should handle this package.

Setting package flags for an existing package

Use the ucc packageflag commandlet to set flags for existing packages.

Setting package flags during compilation

If you are compiling your own .u packages, you can set up a small text file called MyPackage.upkg (where "MyPackage" is the name of your package) in your package's Classes directory. It can contain the following settings:

  [Flags]
  AllowDownload=False
  ClientOptional=False
  ServerSideOnly=False

UT Package Tree

See Package Extension Catalog.

Files
- .U
  - Classes
    - Functions
    - Variables
  - Textures
  - Sounds
  - Meshes
- .UTX
  - Textures
- .UAX
  - Sounds
- .UMX
  - Music
- .UNR
  - Maps
  - Scripts
  - Textures
  - Brushes
- .UZ - Compressed For Download
  - U
  - UMX
  - UNR
  - UAX
  - UTX
- UXX - Cached for Decompression after Download
  - Cache