Mutator

UT2003 :: Actor >> Info >> Mutator (Package: Engine)

An actor designed to modify smaller aspects of the game. For an overview of how the Mutator system works, see Mutator Topics.

See Mutator (UT) for the UT version of this class.

Note: In UT2003 many functions of UT's Mutator class are either no longer available or have been moved to the GameRules class.

Properties

Mutator NextMutator: The next mutator in the mutators linked list.
class<Weapon> DefaultWeapon
string DefaultWeaponName
bool bUserAdded: This mutator was added by the user either from the commandline when starting a server, in the "open" console command or via the mutator list.
bool bAddToServerPackages: if true, the package this mutator is in will be added to serverpackages at load time
string IconMaterialName
string ConfigMenuClassName: A GUI class that serves as this mutator's config window.
string GroupName: Only mutators from different groups are allowed in the mutator list. Use the same group name for mutators what will not work together, e.g. the Arena mutator and InstaGib/Zoom InstaGib use the group name "Arena".
string FriendlyName (localized): The display name of the mutator. Use this or the mutator won't show up in the selection list, even if you correctly create its INT File.
string Description (localized): This is the description displayed for the mutator. Use a pipe symbol "|" to create a line break.

Methods

Inherited From Actor

PreBeginPlay ( ): Checks whether the mutator is allowed (MutatorIsAllowed function) and destroys it if the check shows, that it isn't.
Destroyed ( ): Removes the mutator from the GameInfo's linked list of mutators.

BaseMutator Functions

These functions are only called for the first mutator in the list so if you override them they may not always be executed depending on the order any other mutators were added to the game by the user.

Mutator Chain Functions

These functions should call the same function of the next mutator in the linked list of mutators. This can usually be done by calling the superclass. For example:

function ModifyPlayer(Pawn Other)
{
  // do stuff here

  Super.ModifyPlayer(Other); // this will call the next mutator in the chain
}

Of course, since you have no control over the order of loaded mutators, you could just as easily call the Super function at the top of the function. It's traditional to put it at the bottom, but sometimes easier at the top.

For functions that return a value, you have to use your judgement on how to combine what you want to return with what other mutators might want to do.

function Mutate(string Command, PlayerController Sender): Called when a player enters "mutate <command>" at the game console.
function string RecommendCombo(string ComboName): This function can be used to recommend a combo (presumably to a bot) that works well with your mutator. This function will typically select a combo and then pass that selection on to the next mutator in the chain. The later the mutator is within the mutator chain the more likely that mutator's combo will be used. See the XGame.MutInstaGib class for an example.
function bool AlwaysKeep(Actor Other): If this function returns true then the game will keep the actor passed from being destroyed - even if other actors wish to remove it. It's best to force the game to keep as few actors as possible as this ensures mod compatibility, so only return true from this function if you really really mean it. This function is called from CheckRelevance(). The default return value for this function is false. If you wish to avoid duplicating the mutator chain-walk code then at the end of your overridden method simply add the following line: return bKeepActor | Super.AlwaysKeep(Other); where bKeepActor is a local variable that contains true or false depending on whether your mutator wants to keep this actor or not.
function bool IsRelevant(Actor Other, out byte bSuperRelevant)
function ModifyPlayer(Pawn Other): This function is called whenever a player spawns. It can be used to update the player's inventory, speed, and other attributes. This function should always call ModifyPlayer() on the next mutator in the chain (a call to the superclass method would do the trick).
function string GetInventoryClassOverride(string InventoryClassName): This function is much like checkreplacement, but is specific to items added to an actor's Inventory chain. The function is called with the proposed inventory actor's class as an argument. If the string returned differs from the argument (you return the name of a different class) an actor of the class whos name was returned will be added to the Inventory chain instead of the original proposed actor.\\Foxpaw: The above is mostly speculative and derived from the way a function posted on the Help Desk appears to operate. Some confirmation that that is actually what it is doing would be nice.
function ModifyLogin(out string Portal, out string Options ): modify player login parameters.

Poltomb: In some mutators, you may need to retrieve data from the Options string. The easiest way to do this is to use Level.Game.ParseOption(Options,OptionParameter) function ie:

PlayerName = Level.Game.ParseOption(Options,"Name");

Other Functions

function AddMutator(Mutator M): If a mutator has already been added to the game then this function may be used to add an additional mutator at the end of the mutator chain. Make sure that the Level.Game.BaseMutator reference actually points to a mutator before calling this function though.
function bool CheckReplacement(Actor Other, out byte bSuperRelevant): This function should return true if the actor passed to the function can be replaced within the game. It is very similar to the AlwaysKeep() function except that it doesn't walk the mutator chain. By default this function returns true. This function can also be used if you want to change the attributes of an Actor on the map - simply increasing the amount of ammunition in ammo packs for example. If used for this purpose the Actor passed in is never replaced and the function should always return true.

Discussion

Wormbo: I'm not sure, how exactly the functions should be grouped. This page should be a kind of starting point for people who want to learn more about mutator functions.

Trystan: How many functions are there, really? I guess what I'm saying is are there a large enough number of them of varying degrees of change to necessitate heavy categorization?

Wormbo: Well, we could cut it down to functions that are meant to be overridden and those that shouldn't be touched if that would be neccessary. There are 22 functions in Engine.Mutator, including the one already listed here. Stuff like CheckReplacement should be overridden, ModifyPlayer should both be overridden and call the next mutator's ModifyPlayer, ReplaceWith is a function that is only helpful, but can't actually be overridden and it seems like CheckRelevance is only called for the base mutator and shouldn't be touched at all. So we have at least these four notable categories.

Trystan: Mutator, Player, Weapon, Game?

EntropicLqd: Good sections. A quick discussion (or link) to how mutators and game rules differ would be nice. We may have one (I've not checked).

Category Class (UT2003)