Creating your first mutator

What is a Mutator?
A mutator is a class in UnrealScript that changes certain aspects of a game. It can be anywhere from a set of new weapons, to changing hellbenders to scorpions, or adding new objects to the game. Mutators are easy to code, and easy to use. Once coded they appear in your mutators list, and can be added to any gametype!

How does it work?
Mutators work in many different ways. They can search for all actors on a map that match a certain type (like a sniper rifle) and then change them to a different object. Mutators can be used for many many many different purposes. Just have a look on websites for UT2004/3 mutators and you will see all the different functions they can do!

How do i make one?

We will be using what is called UnrealScript, the language that Unreal Tournament's classes are programmed in. For those of you who have never used a programming language before this may be a little alien to you. I will try and explain it as best as possible. All you need is a copy of UT2004 or UT2003, a computer (obviously ) and Notepad! Thats all that you need!

Now lets get started!

Now i will go step by step on how to make a mutator that will change all Bio Rifles to Sniper Rifles, it may sound simple, but we wan't to start out with the basics. Open up a new Notepad window.

In all UnrealScript classes we start with this:

Code:

class MyFirstMutator extends Mutator;

Now for some of you your probably wondering what does extends and class mean? A class is an object in UnrealScript. Objects can be Weapons, Karma Objects, Vehicles, or anything else in the Unreal world! Extend means it will "inherit" all items from its parent (the name after extends is its parent) or subclass it, essentially a child inheriting blue eyes from its mother as an example. That line is always at the top of every code. After that you will notice a ; which tells the program thats the end of this line or code. Dont put this after a function because that will cause errors. Now lets move on.

Code:

class MyFirstMutator extends Mutator;

function bool CheckReplacement( Actor Other, out byte bSuperRelevant )

in UnrealScript functions are lines of code that tell UT what to do. Bools are Booleans which are True or False questions for UT, and CheckReplacement is a certain kind of function, that just like its name, checks for Replacements of items. (Actor Other, out byte bSuperRelevant) tells UT that its looking for an Actor type, and out byte bSuperRelevant tells it Hey this is important! You should do this!
Now we will start writing some more code that will tell UT what to look for.

Code:

class MyFirstMutator extends Mutator;

function bool CheckReplacement( Actor Other, out byte bSuperRelevant )
{
    bSuperRelevant = 0;
    if ( xWeaponBase(Other) != None )
    {
      if ( xWeaponBase(Other).WeaponType == class'XWeapons.BioRifle' )
         xWeaponBase(Other).WeaponType = class'UTClassic.ClassicSniperRifle';
    }

now we are expanding a bit, we are telling the editor that if it finds an xWeaponBase which is the standard weapon spawn check and see if the weapontype that it is spawning is a BioRifle. You have probably noticed that there are these strange symbol { used in this at the beginning of the function. This tells UT that this is part of the function and not a different line of code. You will also notice that there is an != sign. This means that if the weapon base isn't nothing (yes its strange) then it equals true. In an If statement such as the ones you see above it asks UT if this is true do this. When it does equal true it will ask UT another question if the xWeaponBase's Weapon Type is a BioRifle. There is an double = sign there that means it HAS to be a BioRifle and is a lot stricter. For example if you put if( waffle = 1) waffle could be 1.54 since it only checks if it has a 1, if you put == it has to be 1 and not 1.54. That is why we use strict codes when using UnrealScript that could mess up if its not strict. Then you will see the line underneath if ( xWeaponBase(Other).WeaponType == class'XWeapons.BioRifle' ) is slightly to the right. You could do this

Code:

if ( xWeaponBase(Other).WeaponType == class'XWeapons.BioRifle' )
{
    xWeaponBase(Other).WeaponType = class'UTClassic.ClassicSniperRifle';
}

but it is unnecessary as its only a short line, and UT will understand that its part of the if question as it comes right after it. Now if you compiled this right now, it would only change weapon spawns and not ammo pickups or Weapon Lockers so lets add that in!

Code:

class MyFirstMutator extends Mutator;

function bool CheckReplacement( Actor Other, out byte bSuperRelevant )
{
  local int i;
  local WeaponLocker L;     
 
    bSuperRelevant = 0;
    if ( xWeaponBase(Other) != None )
    {
      if ( xWeaponBase(Other).WeaponType == class'XWeapons.BioRifle' )
         xWeaponBase(Other).WeaponType = class'UTClassic.ClassicSniperRifle';
    }
    else if ( BioRiflePickup(Other) != None )
      ReplaceWith( Other, "UTClassic.ClassicSniperRiflePickup");
  else if ( BioAmmoPickup(Other) != None )
      ReplaceWith( Other, "UTClassic.ClassicSniperAmmoPickup");
  else if ( WeaponLocker(Other) != None )
   {
      L = WeaponLocker(Other);
      for (i = 0; i < L.Weapons.Length; i++)
         if (L.Weapons[i].WeaponClass == class'BioRifle')
            L.Weapons[i].WeaponClass = class'ClassicSniperRifle';
      return true;
   }
   else
      return true;
   return false;
}

Phew thats quite a bit more code! Hopefully if you've been following along most of it should make sense as its almost the same as the first if function. An else if statement says that if the if statement is false, check for this, and if its true, do it. You can have as many else if statements as you wish in a class as it will just keep going down the list. Now the last part of the code may seem confusing. If you look at the top of that piece of code i added two new things called local values. Local values are numbers, strings, integers, or other variables that only apply to that certain function. I added an int or integer called i that will check for certain values on the weapon locker. The second is local WeaponLocker L; which says that when i say L im referring to the WeaponLocker. The i = 0; and i < L parts are just positioning on the Weapon Locker. Now if you'll also see this line called return true; that says that the if statement is done and it was true. On the last two parts with the else return true; simply says if none of the others are true, return, otherwise the whole function is false and UT shouldn't do anything. Now we have an almost complete working mutator! we will now add a line right at the bottom called defaultproperties. That defaultproperties is at the end of every class and as its name states, it says the objects default properties.

So now add this to your code:

Code:

defaultproperties
{
    GroupName="MyFirstMutator"
    FriendlyName="Bio Rifle Mutator"
    Description="Replace all bio rifles with sniper rifles."
}

The GroupName is what its name is in UScript, just give it the name MyFirstMutatort. The FriendlyName is a name you can give it such as MyFirstMutator that will appear in your mutator list. Feel free to call the GroupName, Description and FriendlyName whatever you wish as long as you keep the " marks on either side of it.


How do i get it to go into Unreal?
Time for the last step before enjoying your newly created friend. Save your notepad document if you haven't already and head over to your Unreal folder where you installed the game. Create a new folder called MyFirstMutator (it has to be this name as you called your class MyFirstMutator) and inside your new folder create another one called Classes. Then save your text file into there. Now we will have to change the file to a .uc Now on your window head to Tools -> Folder Options then hit the View tab and then go down to where it says Hide extensions for known file types. Turning this off will allow you to change the file types. Untick that box, and hit OK. Now rename your text file to MyFirstMutator.uc and it should ask you "If you change a file name extension...." hit yes, this will change it to a .uc file that the compiler can read. Ok now go into your UT folder and go to the System folder and find UT2004.ini (or Ut2003.ini depending on your game) and find where it says EditPackages=... and it should have quite a few of those. Add a new line just underneath those that says EditPackages=MyFirstMutator and save the file, but keep it open as we will erase that later.

Hit start -> Run and type command. A little box will open. Now hit cd (it means change directory) and type in where you put your UT2003/4 system folder (ex mine is C:\ut2004\system) then hit enter. It should change to your system folder of UT. Now type ucc make, and it should start going through a list of classes. Let it run and it should compile your class and create a brand new .u file in your system folder called MyFirstMutator.u This is your finished mutator! Hoorah! Coding isnt as easy as you thought was it? Don't let that put you off though. The more you practice the better and easier it gets.


It comes up with an error!
This is pretty common. Have a look at what is says, and navigate to that area of your code. Make sure you have the ; { and ( at the required spots. Its easy to miss them. Check your spelling too, those things are easily overlooked.

Now just remove that EditPackages line from your Ut2004.ini so it doesn't always load it, fire up UT2003/4 and check out your new mutator! If everything went well all your Bio Rifles should now be Sniper Rifles! Do a little dance if you got it working.

Hope you enjoyed this tutorial! Although it was rather long, i like to go into detail as it helps first time coders understand the programming world. If i made any mistakes feel free to correct me.

-Phoenix