[Tutorial] Mutator Essentials

[Benjamin]

Prerequisites: Creating a basic mutator

Mutator Essentials

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 "mutator <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);
}

[rickyhorror]

YAY
thanks!

[Prodigy]

nice.
very helpful

your two guides should be stickied!

[RuneHarle]

Noob question.... can I use the same function more than once at differant variables? For instance I'm working with your original posts mutator to regenerate health, I also want to add in that the specimens will regenerate at a different variable in time and I can't figure how to rewrite the if statement for specimen instead of player and if its possible to write it all in one function with separate time frames or do I have to split it into two separate functions and if that's even possible >.<.

I have never coded in this way, all my coding experience was with Ragnarok Online and that was about 6 years ago before they switched to MySQL. Therefore I have no experience with the unreal engine code and I'm basically starting from scratch again. Any help would be appreciated as I did love writing npc's and the like.

EDIT: Meant to post this in Basic Mutator thread but I have several tabs open and misposted

[Dest]

ModifyPlayer executes after I spawn, is there a way to get it executed before clientrestart?

I want to change something in the inventory, but it should happen before the player respawns. When I change any settings in ClientRestart function, it only changes server side, not client side. That's why I wanted to use modifyplayer, which works for client sides, but it executes too late.

Or are there perhaps other functions within gametype or playercontroller similair to modifyplayer from mutator that change properties client side only?

ScriptLog: ---> This is State DEAD <---

**** Here are executions inside clientrestart, which only work on server side ****

ScriptLog: ---> This is ClientRestart <---

**** And here is Modify Player, just before I'm dead again ****

ScriptLog: ---> This is State DEAD <---

[FluX]

Originally Posted by Dest

ModifyPlayer executes after I spawn, is there a way to get it executed before clientrestart?

I want to change something in the inventory, but it should happen before the player respawns. When I change any settings in ClientRestart function, it only changes server side, not client side. That's why I wanted to use modifyplayer, which works for client sides, but it executes too late.

Or are there perhaps other functions within gametype or playercontroller similair to modifyplayer from mutator that change properties client side only?

ScriptLog: ---> This is State DEAD <---
 
**** Here are executions inside clientrestart, which only work on server side ****
 
ScriptLog: ---> This is ClientRestart <---
 
**** And here is Modify Player, just before I'm dead again ****
 
ScriptLog: ---> This is State DEAD <---

Shouldn't you try to modifyplayer AS the player spawns instead of BEFORE the player spawns due to before they have no inventory technically?

[Dest]

Originally Posted by FluX

Shouldn't you try to modifyplayer AS the player spawns instead of BEFORE the player spawns due to before they have no inventory technically?

There is a class list with specific inventory. I want to alter this inventory before they spawn. It works when I do it in function clientrestart, but then it'll only works for the host, not on clients.

I got it working on clients with modifyplayer, but then it gets changed a spawn later, instead of the initial spawn.

Some people say that modifyplayer works on the initial spawn, but in my case it doesn't..

Edit: Got it working, replicated the chosen number.

[kyoji]

How do you access settings that you have added using PlayInfo.AddSetting()?