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.
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!
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?
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.
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.
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
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.
Enjoy destroying things with your new, uber Enforcer+1s!