U n r
e a l - m
a k e
I n t r o d u c t i o n
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.
T h e . u c F i l e
||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:
.uc Default Properties
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 export everything from UnrealEd into .uc files. I would advise
making a nice, easily accessible directory to keep all of these
classes in. I call mine "UC Archives".
U s i n g E x e c s
||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 t u r e I m p o r t i n g
TEXTURE IMPORT NAME=SomeTexture FILE=TEXTURES\SomeTexture.PCX
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.
OBJ LOAD FILE=TEXTURES\SomeUtx.utx PACKAGE=SomeGun.SomeGroup
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
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 :)
o u n d I m p o r t i n g
AUDIO IMPORT FILE="Sounds\44Magnum.WAV"
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.
P u t t i n g i t A l l T o g e t
h e r
||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=IpServer". Make a new line
just under this one, and type "EditPackages=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
Visitors Since December 26, 2000