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.
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.

function string 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 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).

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)