Unreal Tournament 3 marks the return of the world's première first-person shooter. It unleashes the full power of Unreal Engine 3, taking graphics, gameplay, and challenge to a whole new level. Players engage in intense battles with other human players online, or against Unreal artificial intelligence that sets the industry standard. With the most powerful futuristic weapons and vehicles available, this is FPS action at its best!

Report article RSS Feed Unreal Learning #1: My First Unreal Tournament 3 Mutator

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.

Posted by ambershee on Nov 20th, 2007
Basic Server Side Coding.

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.

If you haven't done so already, you can conveniently download the script files here.

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!

uscript code:
class FirstMutator extends UTMutator;

function InitMutator(string Options, out string ErrorMessage)
{
if (UTGame(WorldInfo.Game) != None)
{
UTGame(WorldInfo.Game).DefaultInventory[0] = class'UTWeap_EnforcerPlusOne';
}

Super.InitMutator(Options, ErrorMessage);
}

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.

uscript code:
class FirstMutator extends UTMutator;

function InitMutator(string Options, out string ErrorMessage)
{
if (UTGame(WorldInfo.Game) != None)
{
UTGame(WorldInfo.Game).DefaultInventory[0] = class'FirstMutator.UTWeap_EnforcerPlusOne';
}

Super.InitMutator(Options, ErrorMessage);
}

function bool CheckReplacement(Actor Other)
{
if (Other.IsA('UTWeap_Enforcer') && !Other.IsA('UTWeap_EnforcerPlusOne'))
{
ReplaceWith(Other, "UTWeap_EnforcerPlusOne");
}

return true;
}

DefaultProperties
{
}

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);

uscript code:
ClassName=FirstMutator.FirstMutator
FriendlyName=First Mutator
Description=My First Mutator!
GroupNames=
UIConfigScene=
bStandaloneOnly=False
bRemoveOn360=False
bRemoveOnPC=False
bRemoveOnPS3=False

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;

uscript code:
ClassName=FirstMutator.UTWeap_EnforcerPlusOne
AmmoClassPath=UTGame.UTAmmo_Enforcer
Flags=
FriendlyName=EnforcerPlusOne
Description=The Enforcer+1 is just plain better than the Enforcer.
MeshReference=UI_Weapons.Mesh.SK_UI_Weapons_Enforcer_3P
bRemoveOn360=False
bRemoveOnPC=False
bRemoveOnPS3=False

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:

uscript code:
[UTWeap_EnforcerPlusOne]
ItemName="Enforcer+1"
PickupMessage="Enforcer+1"

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.

Enjoy destroying things with your new, uber Enforcer+1s!

Post comment Comments  (100 - 118 of 118)
c0ldZ
c0ldZ Oct 14 2008, 4:07am replied:

Aah .. I wish, really, but no =( Please take a look, i'm lost =(

My "Src" folder contains "Classes" and "FirstMutator" as said in the tutorial. Inside "FirstMutator" I have my two .uc files (FirstMutator.uc & UTWeap_EnforcerPlusOne.uc). Inside the "Classes" folder , I have more folders of all the different script files.

And, my lines inside UTEditor.ini

ModPackagesInPath=..\UTGame\Src
ModOutputDir=..\UTGame\Unpublished\CookedPC\ Script
ModPackages=FirstMutator

(Nothing wrong too, just a space here because i can't have words longer than 50 characters >_<)

Well I can't believe it.. I always get "No scripts need recompiling" Have you maybe a solution ? Is there maybe a program compiling the scripts than using the editor ?

+1 vote     reply to comment
c0ldZ
c0ldZ Oct 14 2008, 4:33am replied:

Sorry ! It works now =D ! I created the folder "Classes" in "FirstMutator" and i put my two .uc files there ^^

+1 vote     reply to comment
belzaran
belzaran Oct 28 2008, 11:42am says:

Thank ! It's very detailed. A perfect first tutorial to modding UT3 !

+1 vote     reply to comment
Ghost.X
Ghost.X Feb 15 2009, 9:14am says:

One little problem. I can't find the FirstMutator.ini for modifying the description and what not. You say search for it but it doesn't show up! I tested it with -useunpublished and it works but I just can't find the .ini file. Where is it located?

+1 vote     reply to comment
Ghost.X
Ghost.X Feb 18 2009, 4:30am says:

Nvm I figured it out.

+1 vote     reply to comment
Tyc_00n
Tyc_00n Mar 18 2009, 10:50pm says:

Awesome tutorial!

I have it working, but I want to know how to make it replace all other weapons on the map without using UT_Arena(which does work)

the original code you used is:

function bool CheckReplacement(Actor Other)
{
if (Other.IsA('UTWeap_Enforcer') && !Other.IsA('UTWeap_EnforcerPlusOne'))
{
ReplaceWith(Other, "UTWeap_EnforcerPlusOne");
}

I tried using:

function bool CheckReplacement(Actor Other)
{
if (!Other.IsA('UTWeap_EnforcerPlusOne'))
{
ReplaceWith(Other, "UTWeap_EnforcerPlusOne");
}

and it compiled fine(as expected) and it replaced the enforcer on spawn(as expected) but nothing else. All of the other weapons are still there. Any help?

**NOTE**: I changed other values in the weapon code [EnforcerPlusOne.uc] (firerate, burst, etc.) and they work fine. In the other file [FirstMutator.uc], I only made the changes as shown above. I hope this does not make a difference.

Thanks for the help,

~``Tyc_00n

+1 vote     reply to comment
westsidazrhidaz
westsidazrhidaz May 14 2009, 6:23pm says:

wow it took me a while but I successfully completed it!

thx
Yan

+1 vote     reply to comment
Rothschild
Rothschild Jun 5 2009, 6:17am says:

hi thx for your tutorial.
it was ver helpfull, although i never scripted before everything worked right away.

i have only 2 questions,

-why do you actually need two files?
(Firstmutator and UTWeap_EnforcerPlusOne)?
could you merge them in 1 file?

-could i use "CheckReplacement" for my beer-can mutator
to replace all health vials?

+1 vote     reply to comment
wes773105333
wes773105333 Sep 30 2009, 4:16pm says:

Hello, I have used the compiler but it does not create a package and configuration ini file for it. It says that it compiled right and I've been through the tutorial three times and keep getting stuck at this point. Please help.

+1 vote     reply to comment
biggest_kid
biggest_kid Oct 3 2009, 3:08am says:

Yes i also have the same problem as wes. I use the compiler, and it does not report any errors, only a warning. The warning says "Cant find files matching C:/..."

It also doesnt create a UI file for me in the Config folder. How can this be fixed?

+1 vote     reply to comment
Mr.Rodi
Mr.Rodi May 2 2010, 12:15pm says:

Ok, so where do I place the source code if I dont have the game??

I downloaded just the unreal 3 engine so I dont own the game.

+1 vote     reply to comment
mascot
mascot Oct 19 2010, 7:08pm says:

I realize that I'm a little behind here, but I just recently got UT3 from steam and am yet to get the compiler to open... if someone could give me a little more detail on how it could be opened, that would be nice, because no one else seems to be having this problem. I think it is because I am thinking like a n00b, and the fault is mine.

+1 vote     reply to comment
bluesombre
bluesombre Oct 22 2010, 10:53pm says:

I keep getting the error message
"error, bad, or missing expression after '&' : 'amp'
I literally copy pasted the text from the tutorial and have looked over it and cant work out what its problem is...any ideas?

+1 vote     reply to comment
mascot
mascot Oct 24 2010, 11:20pm says:

I am sorry about that previous comment
I think I was stoned when I wrote it even though I don't drink, because I don't remember writing it, nor would I need to. Maybe my account was hacked or someone I live with wrote it... idk.

+1 vote     reply to comment
aker
aker Sep 4 2011, 7:37am says:

UPDATE (UDK August 2011 Beta)

After spending an incredible ammount of hours to get this mutator to work, I found that you don't need to add "ModPackages=FirstMutator" under [ModPackages] in UDKEditor.ini anymore. This will complie the mutator perfectly fine, but even if you use the -useunpublished flagor move the .u file to the published folder, the game will give a warning like this:

"Warning: Warning, Failed to load 'Class FirstMutator.FirstMutator': Failed to find object 'Class FirstMutator.FirstMutator'"

Instead, you must add "ModEditPackages=FirstMutator" under [UnrealEd.EditorEngine] in UDKEngine.ini. This will compile the mutator just as fine and move it to the UDKGame/Script folder, where the game finds it every time.

+1 vote     reply to comment
aker
aker Sep 4 2011, 7:56am replied:

Also, if you're too lazy to download the UT3 sources, you can still modify the Shock Rifle (UTGame.UTWeap_ShockRifle), which comes with the UDK bundle.

+1 vote     reply to comment
fAvorable
fAvorable Nov 5 2011, 10:49am says:

any ideas,

Error, Superclass UTWeap_Enforcer of class UTWeap_EnforcerPlusOne not found.

UTWeap_Enforcer exists and is in my Src folder with all the other scripts downloaded from the link at the top. also I am using the UDK game version in the UDK bundle is that possible?

+1 vote     reply to comment
Guest
Guest Jul 4 2013, 10:19am says:

This comment is currently awaiting admin approval, join now to view.

Post a Comment
click to sign in

You are not logged in, your comment will be anonymous unless you join the community today (totally free - or sign in with your social account on the right) which we encourage all contributors to do.

2000 characters limit; HTML formatting and smileys are not supported - text only

Icon
Unreal Tournament 3
Platforms
Windows, PS3, X360
Developer
Epic Games
Publisher
Midway Games
Contact
Send Message
Official Page
Unrealtournament3.com
Release Date
Released Nov 18, 2007
Game Watch
Track this game
Tutorial
Browse
Tutorials
Report Abuse
Report article
Related Games
Unreal Tournament 3
Unreal Tournament 3 Single & Multiplayer First Person Shooter
Related Engines
Unreal Engine 3
Unreal Engine 3 Commercial Released Aug 31, 2007
Related Groups
Epic Games
Epic Games Developer & Publisher
Shee Labs Game Development
Shee Labs Game Development Developer & Publisher with 14 members
Unreal Tournament 3 Mod Developers
Unreal Tournament 3 Mod Developers Fans & Clans group with 232 members