Mutator (UT)

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

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

See Linked List/Existing Lists in Unreal Tournament for a thorough description of the different mutator types (including how to make a working HUD mutator).

See Mutator for the UT2003 version of this class.

Properties

Mutator NextMutator: The next mutator in the mutators linked list.
Mutator NextDamageMutator: The next registered damage mutator. These mutators receive MutatorTakeDamage calls from Pawn (UT)s.
Mutator NextMessageMutator: The next registered message mutator. Message mutators receive MutatorTeamMessage, MutatorBroadcastMessage and MutatorBroadcastLocalizedMessage calls.
Mutator NextHUDMutator: The next registered HUD mutator. Mutators can only be registered to one HUD (UT). However HUDs work client-side, so a HUD mutator can be registered to one HUD on the first client or the server and to another HUD on another client.
bool bHUDMutator: If this variable is true the mutator was successfully registered as HUD mutator on this client/server.
class<Weapon (UT)> DefaultWeapon: A weapon class that should replace the default weapon (usually the impact hammer).

Functions

Most mutator functions (except ReplaceWith, RegisterHUDMutator, CheckReplacement and MyDefaultWeapon) call the corresponding function of the next mutator in the list.

PostRender (Canvas (UT) Canvas) [simulated]: Called by the HUD (UT) when this mutator is registered as HUD mutator. Always call NextHUDMutator.PostRender(Canvas) to allow the next HUD mutator to draw on the canvas.
ModifyPlayer (Pawn (UT) Other): Called by the GameInfo (UT)'s AddDefaultInventory function which is called by RestartPlayer and AcceptInventory.
bool HandleRestartGame ( ): This function is never called anywhere in script. Nowhere. It is serving no other purpose than to add a couple of bytes to the Engine.U package. Completely useless...
bool HandleEndGame ( ): This is called when the GameInfo wants to end the game. If the mutator returns True, the Game will not attempt to Set the end cams. If it does return true, the code should either execute its own implementation of the gameinfo.SendEndCams() function or set bOverTime to true to force the game into overtime...
bool HandlePickupQuery (Pawn (UT) Other, Inventory (UT) item, out byte bAllowPickup): This is similar to the Inventory (UT)'s HandlePickupQuery function. Return true handle the pickup query from this function or deny pickup.
bool PreventDeath (Pawn (UT) Killed, Pawn (UT) Killer, name damageType, vector HitLocation): Called by the killed pawn's Died function. If the function returns True it should set the pawn's health to a value greater than 0.
ModifyLogin (out class<PlayerPawn> SpawnClass, out string Portal, out string Options): Called from the GameInfo's LogIn function. The mutator can change any options before the LogIn function processes them.
ScoreKill (Pawn (UT) Killer, Pawn (UT) Other): Called by the GameInfo's ScoreKill function.
Class<Weapon (UT)> MutatedDefaultWeapon ( ): Returns which weapon should be used as default weapon. You shouldn't modify this function. Use the DefaultWeapon property instead.
Class<Weapon (UT)> MyDefaultWeapon ( ): Use by the MutatedDefaultWeapon function. Returns the DefaultWeapon property of this mutator or (if DefaultWeapon is None) the DefaultWeapon of the GameInfo.
AddMutator (Mutator M): Adds another mutator to the list of mutators. If NextMutator is None it is set to M, otherwise NextMutator.AddMutator(M) is called.
bool ReplaceWith (Actor (UT) Other, string aClassName): Intended to use in CheckReplacement. ReplaceWith replaces an actor Other with a new one of the class specified in aClassName.
bool AlwaysKeep (Actor (UT) Other): Called by the GameInfo (UT)'s IsRelevant function. If it returns true neither the GameInfo nor any mutator will try to remove the actor. In this case no mutator receives a CheckReplacement call for this actor.
bool IsRelevant (Actor (UT) Other, out byte bSuperRelevant): Also called by the GameInfo (UT)'s IsRelevant function. It calles the CheckReplacement function, so you don't need to modify IsRelevant.
If bSuperRelevant is set to 1 the GameInfo (UT) will not modify the actor (generally running filter tests). If IsRelevant returns false the actor will be destroyed.
bool CheckReplacement (Actor (UT) Other, out byte bSuperRelevant): Called by IsRelevant() to determine whether the actor should be available within the game or not. If this function returns true for every mutator within the mutator chain then the actor will be kept within the game. If any of the mutators within the mutator chain return false then the actor will be removed. You can replace actors by using ReplaceWith() and then return false.
Mutate (string MutateString, PlayerPawn Sender): With this function mutators are able to handle console commands. (e.g. "mutate tossrelic", MutateString then is "tossrelic")
MutatorTakeDamage(out int ActualDamage, Pawn (UT) Victim, Pawn (UT) InstigatedBy, out Vector HitLocation, out Vector Momentum, name DamageType): Called by the victim's take damage function if the mutator is a registered damage mutator. (Done via GameInfo (UT).RegisterDamageMutator(Self); from within the mutator.)
This is called after the GameInfo (UT) and the victim's Inventory (UT) items had the chance to reduce the damage.
bool MutatorTeamMessage (Actor (UT) Sender, Pawn (UT) Receiver, PlayerReplicationInfo PRI, coerce string S, name Type, optional bool bBeep): Called by the Say and TeamSay functions of PlayerPawn (= Sender). The message will be sent eventually if all message mutators return True.
bool MutatorBroadcastMessage (Actor (UT) Sender, Pawn (UT) Receiver, out coerce string Msg, optional bool bBeep, out optional name Type): Called by the BroadcastMessage function of the sending actor. The message mutator can change the string and the message type. Only if all message mutators return true the message will be sent to Receiver.
bool MutatorBroadcastLocalizedMessage (Actor (UT) Sender, Pawn (UT) Receiver, out class<LocalMessage (UT)> Message, out optional int Switch, out optional PlayerReplicationInfo (UT) RelatedPRI_1, out optional PlayerReplicationInfo (UT) RelatedPRI_2, out optional Object OptionalObject): Called by the BroadcastLocalizedMessage function of the sending actor. The message mutator can change all aspects of the message. Only if all message mutators return true the message will be sent to Receiver.
RegisterHUDMutator ( ) [simulated]: Registers this mutator as a HUD mutator if the local PlayerPawn (the PlayerPawn with a HUD) exists. bHUDMutator is set to True after successfully registering the HUD mutator. See Useful Mutator Functions for details.

Known Subclasses

Relic
HUDMutator (used as base class for the relic HUD mutator) – Don't use this! Prefer breaking compatibility with the relic HUD mutator instead of breaking compatibility with any other HUD mutator. See Relics Patch for restoring compatibility without using this subclass.
EnhancedMutator (EnhancedItems)

Tarquin: probably a dumb question... is it possible to embed a mutator in a map so that it is included automatically when the map is played?

Wormbo: Should be possible with this code:

function PreBeginPlay()
{
    Level.Game.BaseMutator.AddMutator(Self);
}

It might not be able to replace map actors, but I wouldn't consider that being a problem in this particular case.

Mychaeel: Alright... you were faster. (Damn. ;-) )

Dawn: I have developed a robust, generic Embedded Mutator and written a tutorial to accompany it. Go here to check it out: Writing and Using an Embedded Mutator. Hope someone finds it useful!

Category Class (UT)