Mutator Essentials

From Tripwire Interactive Wiki
Jump to: navigation, search

This is a general guide on essential mutator information. It is taken from the tutorial of the same name, written for the official Tripwire Interactive forums by Benjamin.

The mutator actor provides some functions that allow notification of certain events, such as when an actor spawns or a player logs in, allowing the mutator to alter behaviour and attributes of other actors at an appropriate time. Additionally, it inherits all the regular actor functions, some of which are highly useful to take advantage of when writing even the simplest mutator.

Essential Functions

PostBeginPlay

A standard actor function, this is called after the mutator has been spawned. It's useful for (among other thing) initializing variables, spawning necessary actors, and setting an initial timer value. At this point there is no guarantee that a local player exists, so do not depend on being able to access it.

function PostBeginPlay()
{
	// Handle initialization here
}

Tick

Another standard actor function, this is called every tick (game loop). At 60fps it'll get called 60 times per second, or once every ~16 milliseconds. It's used frequently by other actors since it allows the actor to constantly perform tasks each frame, allowing updating of variables and such. The argument delta indicates how many seconds the last tick took to execute (for example at 2fps the value should be roughly 0.5 since it takes half a second to render a frame).

function Tick(float delta)
{
	// Handle updating of mutator logic here
}

Timer

Another important actor function, this is scheduled to be called by the script. A call to SetTimer() will schedule a call at the delay specified, and can optionally be made to repeat at set intervals.

function PostBeginPlay()
{
	SetTimer(0.5, false); // Call timer in half a second, do not repeat (=false)
}

function Timer()
{
	// Handle timer-related stuff here
}

Mutator-specific functions

ModifyPlayer

Called when a player enters the game, this function allows you to make modifications to the player before it spawns. In order to be compatible with other mutators you must call the superclass implementation of this function, which allows other mutators to handle this call.

function ModifyPlayer(Pawn Other)
{
	Other.GiveWeapon("KFMOD.SCARMK17AssaultRifle");
	Super.ModifyPlayer(Other);
}

Mutate

Useful for debugging and practical use, this function is called when a player enters "mutate <argument string>" in the console. In a multiplayer game it will be called regardless of whether the mutator runs on the client machine or not. As with the above, for compatibility with other mutators you must pass this call on to other mutators in the chain (calling the superclass implementation of this function handles this for you).

function Mutate(string MutateString, PlayerController Sender)
{
	if (Caps(MutateString) == "HYPER")
		Sender.Pawn.Health = 999;
	
	Super.Mutate(MutateString, Sender);
}

CheckReplacement

Called whenever an actor is spawned (only applies to those who have their bGameRelevant attribute set to false - this function isn't called for client-side actors such as local effects). Allows you to modify or replace an actor. Useful since you can make changes to an actor just as it is spawning, and not have to worry about it later. Unless you are an advanced user always return with a call to the superclass implementation of this function.

function bool CheckReplacement(Actor Other, out byte bSuperRelevant)
{
	if (KFMonster(Other) != None)
	{
		KFMonster(Other).Health = 1;
	}

	return Super.CheckReplacement(Other, bSuperRelevant);
}

Adding mutator settings

If you use the config specifier when declaring instance (non-local) variables, you can modify these variables from the mutator configuration window. A couple of functions are required to inform the game that these settings exist, as well as allowing a detailed description for each setting to be obtained.

FillPlayInfo

Called when the game wants to retrieve the list of available settings. You must call the superclass implementation of this function before you do anything else, since it allows us to add our settings to the game.

static function FillPlayInfo(PlayInfo PlayInfo)
{
	Super.FillPlayInfo(PlayInfo);
	PlayInfo.AddSetting(default.RulesGroup, "variableName", "settingDescription", 0, 0, "settingType");
}

As you can see above to add a setting to the game you must call PlayInfo.AddSetting() and pass in arguments describing the setting. The variableName property must match the name of the instance variable. The settingDescription property allows you to provide a brief description which is displayed directly next to the input field. The settingType property describes what kind of setting it is, which can be either text (string or numeric data), check (boolean), or select (drop-down select box).

When using the string type you can specify a string length and/or a value range in an additional argument after settingType. Some examples:

PlayInfo.AddSetting(default.RulesGroup, "bEnabled", "Enabled?", 0, 0, "check");
PlayInfo.AddSetting(default.RulesGroup, "HealthMax", "Maximum Health", 0, 0, "text");
PlayInfo.AddSetting(default.RulesGroup, "HealthMax", "Maximum Health", 0, 0, "text", "3;100:200"); // 3 characters maximum, value in the range of 100-200

When using the select type you must provide an argument after the settingType property in the format of "Value1;Text1;Value2;Text2", for example:

PlayInfo.AddSetting(default.RulesGroup, "StartWep", "Starting weapon", 0, 0, "select", "0;Deagle;1;Bullpup;2;LAR"); // Gives us a list of weapons with values associated

GetDescriptionText

This function is called to retrieve a detailed description of a particular setting (when you hover the mouse over the setting). You must call the superclass implementation of this function in order to allow other settings to have their descriptions received.

static function string GetDescriptionText(string SettingName)
{
	switch (SettingName)
	{
		case "ExampleVar":
			return "This is the 'long' description for the setting.";
	}
	
	return Super.GetDescriptionText(SettingName);
}

See also