Unreal -make
by Windex

If you're reading this tutorial for the first time, then I'm betting you write UScript within the UnrealEd environment. If you use Unreal -make, then I would advise you to stop reading right now, because you're most likely already familiar with everything I'm about to explain. In any case, this is a tutorial on the Unreal directory structure, and how to use Unreal -make to compile packages.

As I said in the Beginner's Guide to UnrealScript, there are two ways to write and compile UnrealScript. First, there's UnrealEd, which you should already be familiar with. UnrealEd is probably the simpler to use when you're first starting out, but as you become a more experienced coder, you'll most likely begin to become annoyed with it. UnrealEd is a great tool for level editing, but it can really leave a little something to be desired when writing code. For one, it's slow, and has ungodly loading times (It's not nearly as bad with the most recent patches, but it's still not exactly speedy). Besides the loading times, though, what do you do if you want to import a model? It's not possible to import a model from within UnrealEd; it has to be done using Unreal -make. So, to get a new model into a package, you've got to export all your classes, arrange them in directories properly, and recompile everything to include your new model. Kind of a hassle. Wouldn't it be simpler to just do away with UnrealEd altogether, and compile all your code using Unreal -make?

If you're shaking your head "no", then I'm not going to try to convince you to give up UEd. Unreal -make isn't for everyone, but it's generally just a natural occurrence that people eventually make the switch. Anyway, if you're to the point where you're just plain annoyed with UnrealEd, and want an alternative... this is for you.

T h e   D i r e c t o r y   S t r u c t u r e

So, what's the deal with all this "Directory Structure" talk, anyway? Well, when you're compiling a package with Unreal -make, it expects a very specific directory structure for everything to be in. First comes a project directory with the same name as your package. Within this project directory come various sub-directories for all the different types of files that can be put into a package. For instance, all code files go in a directory called "Classes". All model files go in a directory called "Models", textures go in "Textures", and sounds go in "Sounds". For instance, take a look at this example project directory:

The project directory, "SomeGun", is branched off of the root Unreal directory. Within this are three sub-directories: Classes, Models, and Sounds. Classes contains all the code for the package, Models contains a single model and a skin for that model, and Sounds contains a couple of .wav files which will be used as weapon sound effects.

The .uc file is the basic format for writing UnrealScript outside of UnrealEd. It's simply a plain text file that can be edited with Notepad, Wordpad, MS Word, or just about anything else. A single .uc file contains a single UnrealScript class. Not too complicated, is it? In fact, I've found to be even simpler than working with UnrealEd.

So, to write your code, you simply open up your favorite text editor, write your class just as you would in UnrealEd, and save it with a .uc extension in the Classes sub-directory of your project directory. There are just a couple things that should be noted. First of all, you must remember to write the class declaration. If you're used to writing code in UnrealEd, then you've probably never worried about class declarations, since UEd generates them for you. Notepad, however, doesn't.

Second, there's the matter of default properties. In UnrealEd, a classes' default properties take the form of a nice little graphical window. In a .uc, though, the default properties are written in a special section at the end of the file, like this:

defaultproperties
{
     FireSound=Sound'SomeGun.FireSound'
     AltFireSound=Sound'SomeGun.FireSound'
     Mesh=Mesh'SomeGun.SomeGun'
}
 

Only the default properties that are added or changed from a classes' parent class are included in a particular .uc file. There are also no "groups", as there are in UnrealEd. At first, this will probably be the most confusing part of writing code outside of UnrealEd. Once you get used to it, though, you'll probably come to like it. In any case, if you're still a bit confused on what exactly your .uc files should look like, then I'd advise you to go into UnrealEd, and "Export All" the classes. This will save all the existing Unreal classes as .uc files in their own project directories.

In fact, you'll probably want to do this anyway. The only major drawback to writing code outside of UnrealEd is the lack of a nice, organized class tree to use as a reference. If you've had much experience at all writing UnrealScript, then you'll know that being successful is extremely dependant on how well you know the existing Unreal classes. Knowing which classes to inherit from, and which functions to override is absolutely essential. And, therefore, so is having easy access to the existing UnrealScript classes. What all this boils down to, is that you're going to need to accessible directory to keep all of these classes in. I call mine "UC Archives".

If you've never written code outside UnrealEd, then you've probably never imported anything using #exec commands. This is because #exec commands are executed only when they're compiled with Unreal -make. They're ignored when you simply compile within UnrealEd. So, I suppose you're going to need a crash course on them, aren't you?

#exec commands are used to import things. Models. Textures. Sounds. They're essential for telling Unreal how you want all these different files in your project directory to be mushed together into a single package. There are quite a few different types of #exec commands, all of them used for importing different things. When you import a model using 3ds2unr (see the importing a Model tutorial for more details on how to do this), the #execs are automatically generated for you, so you don't have to worry about them too much. But what if you just want to import a texture or sound? It's not too difficult... you just have to know the right #exec command. So what are the right #exec commands? Read on.

E x e c    C o m m a n d
#exec TEXTURE IMPORT NAME=SomeTexture FILE=TEXTURES\SomeTexture.PCX GROUP=SomeGroup

Not too complicated. There's just a few pieces of information that you need to supply. The "NAME" part is what the texture will be known as in UnrealScript. This is the name you'll use to reference it in your actual code. The "FILE" part is, obviously, the filename of your actual image file. Note that your image files don't have to be in your Textures sub-directory. In fact, I very rarely ever use a Textures directory. I usually put all my textures, whether they're model skins or not, into my Models directory. Also, just in case you were wondering, it is possible to import a BMP file as a texture instead of a PCX. There's no major difference. You just have to replace the "PCX" in the exec with "BMP". Finally, the "GROUP" part is the texture group that this texture will be stored under. If you're into level design, then I'm sure you're familiar with texture groups. They're simply a way of organizing things within a package. They also serve to add a little more difficulty in referencing a texture from UnrealScript. For instance, if the texture in this #exec were being imported to a package called "SomeGun", you'd have to use "SomeGun.SomeGroup.SomeTexture" to reference it.

This is a nifty little trick that I haven't seen documented anywhere before. If you have a .utx texture package, and you want to moosh it in with a .u file, you can use this #exec. Simply put the .utx file in your Textures or Models sub-directory like you would any other image file. Then, put this #exec in one of your classes to import it. The "FILE" part is used to tell Unreal where the .utx you want to import is, and the "PACKAGE" part tells unreal the .u package name (probably the one you're writing the #exec in) and texture group to import the .utx into.

You may be asking why you would need to import a .utx file, since it would be pointless to import your textures into a .utx in UnrealEd when you could just import them directly into your .u using a texture import #exec. Why add the middleman? The answer is: Fire Textures. You see, Unreal has a built-in system for generating special algorithmic textures that dynamically animate themselves. They're used for creating almost any type of fire, electric, or energy effect you see in the game. There's one thing about them, though: they can't exactly be saved as a plain old .pcx file. When you generate them in UnrealEd, they're saved in a .utx file. So, there's your reason for needing this #exec.

In any case, this could very well work the same way for .uax files, too. I've never tried it myself, but I don't see why it should be much different. Experiment a little :)

S o u n d   I m p o r t i n g
#exec AUDIO IMPORT FILE="Sounds\44Magnum.WAV" NAME="SGBlast" GROUP="Shotgun"

Nothing shockingly new here. Pretty much the same as the texture import #exec, only with the word "AUDIO" instead of "TEXTURE". Just supply a source filename, name, and group, and you'll be set.

So, you've got this nice organized project directory, with all your classes, textures, and sounds. How in the hell do you compile all that into a useable .u file? With Unreal -make. Once you've got everything ready to go, the first thing you have to do is make a little modification to your Unreal.ini file. You see, when you run Unreal -make, it searches your Unreal.ini file for a certain set of lines that tell it what project directories to compile. For it to recognize and compile your precious project directory, you have to make an entry for it in Unreal.ini.

So, open up Unreal.ini, and search for a set of lines that begin with "EditPackages". The last line in the set should be "EditPackages[7]=IpServer". Make a new line just under this one, and type "EditPackages[8]=PackageName". PackageName being the name of your project directory, of course. Save and close Unreal.ini, and get ready to rock. The process of compiling your project directory into a .u file is a simple one, really, as you can see by this diagram:

Not too difficult, is it? Once you've edited Unreal.ini, all you have to do is run Unreal.exe with the -make parameter, and watch the magic happen. When it's finished (barring any code errors, which you'll have to fix), you'll have a nice, new, shining .u file waiting for you in your Unreal\System directory.