Developer & Publisher

Since early 2002, Shee Labs has been a group of individuals working to produce free game and media downloads. With ever-fluctuate staffing, Shee Labs continues working behind the scenes on various exciting projects for a bewildering array of areas. Shee Labs ceased to exist in September 2009.

A brief tutorial outlining how to write a simple mutator for Unreal Tournament 3. This is a relatively in depth and detailed tutorial, ideal for any budding Unreal Programmer who really wants to know how to get started.

So, you have your nice shiny new copy of Unreal Tournament 3. You've played through the entire singleplayer campaign, and had your fill of rocket-jockeying the internet. It's time for something new. But wait! Surely this game has some life in it yet?

Unreal Tournament 3 has a very flexible system that renders it an ideal platform to mod with. There are a few different types of mod for Unreal Tournament 3, the humble Mutator, the custom Game Mode, the almighty Total Conversion and the ever-popular custom Content.

This is where you come in, and today we will be focusing on the Mutator, a short snippet of code that can be run as a set of 'new rules' in any game type, either on a server or by yourself in Instant Action.

Mutators only ever make small changes to the game - and should only ever make small changes. Because they do this, many mutators may be used at the same time in combinations for all manner of wierd and wonderful effects - this is the benefit and the flexibility of the mutator.

Preparation

Before we get started, we need to know a bit about how Unreal Tournament 3 is set up - if we don't learn this, we'll never be able to work out anything!

Unreal Tournament 3 stores everything in packages - that includes everything from 3d models, sounds and in our case, unrealscript. Packages are collections of game resources, and generally have the extension .upk. Code packages however tend to have the extension .u, but this does not mean they necessarily contain only code. They can also contain things such as sounds and textures that the code depends on. Keeping these all in one package keeps things organised and easy to manage.

Unrealscript itself is an object-orientated scripting language, which means that whenever we want to make changes or additions, instead of writing a lot of new code, or changing old code, we can instead over ride or extend existing code to suit our needs. In fact, you should never modify the stock Unreal Tournament 3 script files - doing so will prevent you from playing online.

You will want to extract the files found in the 'exported scripts' folder to the correct directory - by default this is C:\Documents and Settings\My Documents\My Games\Unreal Tournament 3\UTGame\Src.

You may need to create this directory if it does not exist. Don't forget to supplant with your own windows user name. You will now create a folder to house your script code, to seperate it from the existing UT code - add a folder in Src called 'FirstMutator', and a second folder under that called 'Classes'.

You'll probably want a decent text editor to get working - you can use standard Notepad if you wish, however I strongly recommend Notepad++ as the weapon of choice. Later tutorials will discuss the differences and benefits of Notepad++ and dedicated Unreal IDE (Integrated Development Environments) for development in Unreal Tournament 3.

The Classes folder is where we will be keeping all our unrealscript that we're about to write - and we're just about ready to get started, but before we do we need to make sure that the game knows where to find our new code - so we need to find UTEditor.ini in our Unreal Tournament 3 directory (use the system search to find it - this is a very useful tool for finding files in Unreal Tournament 3, so get used to using it!) and once in the file, find the section marked [ModPackages].

Right at the end of this section, add ModPackages=FirstMutator - this tells the unrealscript compiler where to find your code. Hold on! Where is the unrealscript compiler?

If you look in the start menu, you'll notice that you have shortcuts to both the editor and the game. Look at their properties, and you'll notice something cunning - both shortcuts point to the same program. The editor is accessed by adding the editor command switch to the end of the target entry. We can access the unrealscript compiler the same way - copy the shotcut for UnrealEd and replace the editor command switch with make - the command used to tell the game to build the script. Name the shortcut something useful, and put it somewhere handy. I keep mine in the same directory as the script I'm working on.

Now we're ready to get scripting!

Writing the Mutator

We need to create our first script file. Create a new text file, and call it FirstMutator.uc. The .uc file extension is how the compiler recognised an unrealscript text file. This means you can keep code snippets and old code in your working directory by changing the file extension, and the compiler will ignore it. I like to use .OLD and .SNIP to keep things organised, but the choice is yours.

Open this text file, and it's time to write out first lines of code. Things are finally getting somewhere, huh?

uscript code:

class FirstMutator extends UTMutator;

DefaultProperties{}

Okay, this code doesn't do much - but it's important! class FirstMutator is the new unrealscript class you are writing. Always remember to give your class the same name as your text file - otherwise the compiler will tell you you have a class / filename mismatch and refuse to compile. The default properties are where you store the default values for any variable you might create for the mutator - it is not necessary to include this if you don't intend to include any (a rarity) - but it's just good programming practice.

Now we need to tell our mutator to do something. The mutator class that we are extending contains a lot of useful functions that allow us to change the way the game plays - find the file and open it - take a look at it, and you'll see a lot of code. If you've programmed before, take a read through it and get familiar with it. If you haven't programmed before, then you're probably going to find this a bit too difficult to understand right now, so don't worry about it.

In this mutator, we're going to make the Enforcers do more damage. Enforcers+1!

The first thing we're going to do, is stop the player from spawning with a normal Enforcer, and instead make them spawn with an Enforcer+1. A player will start with a defaultinventory - this is dictated by the class UTGame. You can have a look at that file if you're interested.

We create a function to over ride the InitMutator() function in the Mutator class - this means that this new function is used instead of the one in Mutator. Because we also want it to do everything that it does in Mutator, we add Super.InitMutator() at the end - the super keyword tells the unrealscript compiler to look at the class we extended and call the function after the keyword - nifty!

If you looked in UTGame, you'll have spotted that the player is gifted with two weapons in their defaultinventory - the Enforcer and the ImpactHammer. By changing the first element in the defaultinventory array, we change what they get - in this case we swap UTWeap_Enforcer for our shiny new UTWeap_EnforcerPlusOne.

But there is no EnforcerPlusOne! Don't worry, we haven't gotten to that yet, but we'll cover it in good time, so keep going!

This is great - the player will now start with the Enforcer+1 instead of the normal Enforcer. Ideally, this is really enough and will work - but suppose someone makes a map (because none of the default maps have it) that has Enforcer pickups in it? Then the player would be able to have both weapons - and we don't want that. This is where the CheckReplacement function comes in, and is probably the function you'll be using the most when writing mutators in future.

CheckReplacement literally goes through every single Actor object in the game (which is effectively every game object) - we can over ride this function to check what that actor is, and if it's something we don't like, we can get rid of it or replace it.

What happened there? We checked to see if our object was an Enforcer, but not an EnforcerPlusOne because our EnforcerPlusOne is going to extend the Enforcer class. If we did not check that we're not an EnforcerPlusOne, the CheckReplacement function would keep finding out first EnforcerPlusOne (which is still an Enforcer!), and replace it over and over again, leading the game to crash every time we try to run the mutator. Bad!

We then called the ReplaceWith function, replacing the Enforcer actors with our new ones. You could look up this function in the mutator class to see how it works if you are interested.

We're nearly done! All we need to do now is create an EnforcerPlusOne to replace all the Enforcers.

Create another new text file in your Classes directory, and call itUTWeap_EnforcerPlusOne.uc. Why not Plus1? Well, there's no technical reason not to, but the script compiler thinks that ending class names with numbers is a naughty thing to do and bad programming style. The code will compile perfectly fine, but you'll get a little yellow warning come up telling you not to do it again.

In that text file, we're going to write some simple code. Now would be a great time to look at the UTWeap_Enforcer class to see what's in it. Since we're extending it and only want it to do more damage, we don't need any fancy new functions, just a few changes to those default variables.

uscript code:

class UTWeap_EnforcerPlusOne extends UTWeap_Enforcer;

DefaultProperties{
InstantHitDamage(0)=50
InstantHitDamage(1)=50}

That's really all it is, two variable swaps. Note that InstantHitDamage(0) is the first fire mode and InstantHitDamage(1) is the second. You could also find other variables in UTWeap_Enforcer to customise - for example if you only want it to burst fire, you could change both FiringStatesArrays to WeaponBursting.

One last thing to do now, and that's compile it, and check it out.

Compiling the Code

Remember that little short cut we created to access the make switch command? Now is the time to use it. All you should need to do is simply run that, and the code should compile nicely without any errors or warnings. If you do get errors or warnings, you might want to step back and take a look at what they're telling you. Chances are you've made a small mistake, and it's easily rectified. If you really get stuck, try asking in the BeyondUnreal forums, or if heading to other sites isn't your cup of tea, the forums here on ModDB.

When you compile the code, the script compiler will automatically generate a package file with your compiled code in it and a configuration ini file if necessary. You'll find your package file in your Unreal tournament 3 directory, which by default is C:\Documents and Settings\My Documents\My Games\Unreal Tournament 3\UTGame\Unpublished\CookedPC\Script\FirstMutator.u

So what's left?

Only one last little thing remains before this mutator is really ready. You can already theoretically jump into the game, select FirstMutator from the menu and play with it. But it doesn't have a name, or a description that's any use, and you'll have to run the game with another command switch (the '-useunpublished' switch) in order for it to show up.

This is where that configuration ini file comes in. Use windows search to find the configuration file (hint, look for FirstMutator). Open it, and find the section [FirstMutator UIDataProvider_Mutator] - under that you should add (or alter if it is already there);

This section of the ini file controls how your mutator will show up in the mutator menu.

Next, we need to look at the [UTWeap_EnforcerPlusOne UTUIDataProvider_Weapon] section, as there are some things in here that will deal with how it will appear in the weapon browser. Once again, add or alter your entry to look like so;

Now the weapon browser has a mesh reference, and knows to correctly display the Enforcer mesh, as well as some other details - but we still only know that we have an Enforcer in the normal game - how do we tell we have an Enforcer+1?

We also need to find the localisation file - which by default should have be found in; C:\Documents and Settings\My Documents\My Games\Unreal Tournament 3\UTGame\Unpublished\CookedPC\Localization\
We'll have to create that folder if we don't already have it.

Let's add a new file called FirstMutator.int, and we should find add the following lines to it:

Now we will be told that we have an Enforcer+1 or have picked up an Enforcer+1 in the game, excellent.

Now we're ready to rumble! We can run the game by creating a new shortcut the same way we accessed the unrealscript compiler - by adding the command switch ' -useunpublished' - but this is no good if we want to give our mutators to someone.

Last thing we need to do, is move all our finished files - this is nice and easy. All of your files are currently in the Unpublished directory; just copy them all over (remembering to keep the same directory structure!) into the published directory, and you're done.

Thanks for the comments - ideally this is the 'Hello World' of the mutators, it's not so much designed to teach the language, as show what mutating is about and how it is achieved, but still keep it relatively simple; so I went for a quick object replacement showing how to up the damage on the Enforcer rather than anything else, because it's good to have visible results in your first code. I intend to go into a bit more depth with the language in later tutorials.

Actually, I did try (three times) to get the tutorial tabbed out, but it would appear that the auto-formatting of the article keeps removing them.

I'm having problems with the INT file, it's not being created for me, I'm not sure why not but I cannot find it not even when i search '*.int' in the 'My Games' folder, care to help me out please? Thanks

Just updated to include that you'll probably have to create your int file manually.

As an additional - this won't affect weapons that need to be picked up. Weapons that need to be picked up need to have their pickup bases and weapon locker entries changed, because those will spawn normal sniper rifles. You should find that the weapon replacement mutator knows about your new sniper though, and you could add it to the default inventory, and it would work.

(1)For the part that talks about FirstMutator.int
(a) Create a folder named "Localization" in C:\Documents and Settings\My Documents\My Games\Unreal Tournament 3\UTGame\Unpublished\CookedPC
(b) Create a new text file in that folder called "FirstMutator.int" and put in it the lines:
[UTWeap_EnforcerPlusOne]
ItemName="Enforcer+1"
PickupMessage="Enforcer+1"

(2) To go from unpublished to published you must:
(a) Create a new folder titled "Published" in C:\Documents and Settings\My Documents\My Games\Unreal Tournament 3\UTGame
(b) copy the CookedPC folder from Unpublished to Published

1) This part was covered in the tutorial;
"We also need to find the localisation file - which by default should have be found in; C:\Documents and Settings\My Documents\My Games\Unreal Tournament 3\UTGame\Unpublished\CookedPC\Localization\ We'll have to create that folder if we don't already have it.

Let's add a new file called FirstMutator.int, and we should find add the following lines to it:

Now we will be told that we have an Enforcer+1 or have picked up an Enforcer+1 in the game, excellent."

2) That is entirely correct. This tutorial did not cover publishing content, so instead I included instructions for creating a shortcut to the -useunpublished command switch.

The -useunpublished command switch is for development, so you can keep compiling code and testing it as need be. When it comes to publishing, you'd then cook your packages if need be, and then move them to publishing, ready for distribution. I'll be covering distribution in a later stage of the tutorial series.

Maybe I'm just stupid, but you completely lost me at "Writing the Mutator". You don't mention what files we're editing (you just say "find the file and open it. What file?) and where we're putting the new lines of code. Perhaps clearing that up a little would help?

Any files that you need to modify are quite explicit - and for this example we only deal with files we've created, so I should hope you can find those.

For the others that are mentioned that you might want to look at, learn to use the windows search functions. There are thousands of source files, divided into various subfolders - there's now way of remember where everything is, so searching is your only option (for example, if you want 'UTGame' you'd search for that, or if you want 'Mutator' you'd search for that; every class is in a file of the same name, so it can always be found that way.

I'm a bit late to the cake, but anyway. The above poster is right, you write:
"Now we need to tell our mutator to do something. The mutator class that we are extending contains a lot of useful functions that allow us to change the way the game plays - find the file and open it - take a look at it, and you'll see a lot of code."
But we do not know which file. I really wanna check this "file" out, but you don't give the name out. I really doubt we will "see a lot of code" in the file we just created with 3 lines of code. Any hints appreciated.

You're welcome. Unfortunately, between working full-time (as an unreal programmer), writing tutorials for UT3 and working on my own UT3 projects, I don't tend to get a lot of free time, and can get a bit sick of Unreal!

I might give it a shot once it's out there mind, just to see what you've done with it.

just wondering if you could clear something up for me (im a bit confused) where you said:

"We create a function to over ride the InitMutator() function in the Mutator class - this means that this new function is used instead of the one in Mutator. Because we also want it to do everything that it does in Mutator, we add Super.InitMutator() at the end - the super keyword tells the unrealscript compiler to look at the class we extended and call the function after the keyword - nifty!"

The Class FirstMutator extends UTMutator and the Class UTMutator extends Mutator right? You said the super keyword tells the unrealscript compiler to look at the class we extended (e.g. UTMutator) and call the function InitMutator(). But UTMutator doesn't contain the function InitMutator() - the Mutator class does.

So really what i would like to know is; does 'super' automatically traverse up the class tree until it finds the function InitFunction()?

Hi Cybran - that is exactly correct, it will traverse up the tree (in a manner of speaking) until it finds the correct function - actually, in reality a subclass will inherit all of the properties of the parent,and any properties that parent may also have inherited... so we're in fact over-writing the original function, but telling it to also do the parent's function with the super keyword :)

As a potentially helpful tidbit, although I expect you'll probably never use it - if you have a function that you don't want inherited by the children, you can declare the function with the final keyword. (final function x(Y).

I looked at the files I created, named FirstMutator.uc and I clicked on propertiies. Windows Vista decided that the .uc is part of the name and left it as a text file for type. FirstMutator.uc.txt is what was actually in my Classes folder.

So it's a Vista problem I ran into. Thanks for your help. I'll figure out how to change a file type in Vista.