Create a mutator. Features and Settings

To understand the following text well enough, it is important to have at least basic knowledge of OOP and the UnrealScript language in particular.

The mutator actor (class) provides several functions that allow you to notify about certain events. For example, when an actor appears or a player enters the current game, the mutator is allowed to change the behavior (variables) and attributes (methods) of other actors at the appropriate time. In addition, the mutator inherits all the functions of the actor (from which the mutator is derived), some of which are quite useful for writing even a simple mutator.

Basic functions

PostBeginPlay

Standard actor function, called after the mutator appears. Among other things, this function is useful for initializing variables, spawning necessary actors, and setting the initial value of a timer. At this stage, there is no guarantee that the player will exist, so the function does not depend on being able to access it.

function PostBeginPlay()
{
    // Initialization logic
}

Tick

Another standard actor function. Called after a certain game time cycle. At 60 fps, it will be called 60 times per second (or once every ~16 milliseconds). This function is often used by other actors, allowing them to continuously perform tasks (updating variables, etc.) on a frame-by-frame basis. The delta argument indicates how many seconds it took the last loop to complete the task (for example, at 2 fps the value of the argument should be ~0.5 since it will take half a second to take a frame.

function Tick(float Delta)
{
    // Per-frame mutator logic
}

Timer

Another important function of actors called by the script (script). The SetTimer() function declaration will schedule the call for the specified delay, which can optionally be repeated after some period of time.

function PostBeginPlay()
{
    SetTimer(0.5, False); // Once after 0.5s; False = do not repeat
}

function Timer()
{
    // Timer callback logic
}

Specific functions

ModifyPlayer

The function is called after the player has entered the game. It (the function) allows you to make changes to the player before he appears. For compatibility with other mutators, it is necessary to point to a superclass implementing this function, which will allow other mutators to process this request.

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

Mutate

This function is useful for both debugging and practical use. It is called when the player enters mutator <argument string> into the console. In a multiplayer game, it will be called regardless of whether the mutator is running on the client machine or not. As with the function above, you must send this call to other mutators in the chain (calling the superclass implementing this function will handle this for you).

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

CheckReplacement

The function is called whenever an actor spawns (this only applies to those whose bGameRelevant attribute is set to false - this function is not called for client-side actors, such as local effects). The function allows you to change/replace the actor. This is useful when you need to make changes to an actor after it has appeared so you don’t have to worry about making changes later. Unless you are an advanced user, always return with a call to the superclass implementing 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 a configuration specifier to declare non-local variables, you can change those variables from the mutator configuration window. Several functions are required to inform the game about the existence of these parameters, and also allow you to create a detailed description of each received parameter:

FillPlayInfo

This function is called when the game needs to get a list of required parameters. You must declare a superclass implementing this function before doing anything, as it will allow your customizations to be added 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 the settings as arguments. The variableName property must match the name of the variable needed to be designated. The settingDescription property allows you to provide a short description that is directly displayed next to the input field. The settingType property describes settings that can be displayed as text (string or numeric data), logical check (true/false), selection string (drop-down list box). When using the Text type, you can specify the length of the string and/or the range of accepted values as 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"); // max 3 chars; value clamped 100–200

When using selectType, you must specify the settingType of the argument in the following format: “Value1;Text1;Value2;Text2”. Example:

PlayInfo.AddSetting(
    default.RulesGroup,
    "StartWep",
    "Starting weapon",
    0,
    0,
    "select",
    "0;Deagle;1;Bullpup;2;LAR"); // dropdown: value;label pairs

GetDescriptionText

This function is called to obtain a description of specific settings (when the mouse cursor is hovered over the settings). You must declare a superclass implementing this function so that the settings can receive descriptions:

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

This article is a translation of an article by Benjamin, to whom many thanks are due.

Author: Kiyo