For the complete documentation index, see llms.txt. This page is also available as Markdown.

Mod Settings

How to create settings for your Redscript mods

Introduction

Mod Settings (NexusMod | GitHub) is a RED4ext plugin for modders who which to configure settings of their mods, using native UI of the game. It is mostly intended for players to allow them to tweak some parameters with a straightforward UX.

Example from NexusMods

You can use it when coding with redscript to declare a class, bind properties with annotations and listen for changes when player accepts them. That's it, everything else is handled by Mod Settings for you regarding UI and inputs.

Define a class

You can declare a new class which will hold the settings of your mod. You can choose to put all settings in the same class if you wish, even if you don't want to expose all of them.

It's recommended to register your class as a singleton, which ensures that only one instance of your class exists. With singletons, at any point in your code (assuming that game systems are available), you're able to get a reference to it and use it as you wish; which is a good use-case for settings.

To create a singleton, all you need to do is to have your class extend ScriptableSystem.

Different Types of Singletons

If you have Codeware installed, you can also register a singleton by using ScriptableService instead.

The main differences between these two is that ScriptableSystems are bounded to game sessions, they're only available when in a game session. ScriptableServices are independent of game sessions as they are created when the game starts, so they're always available.

In the context of settings, I would recommend ScriptableService as their use-case is perfect for settings.

Documentation:

Binding properties

Mod Settings uses the annotation @runtimeProperty(key: String, value: String) to bind metadata to a property. Using key value pairs (metadata), we can give Mod Settings information about what we want to show in the UI and how.

Whatever value you assign the property is treated as that property's default value.

For any annotations where you provide a string for the value, you can instead opt for a localization key.

Supported Types

These are the supported property types you can bind Mod Settings to, along with how they're shown in the UI.

  • Bool: A toggle-able on/off switch.

  • Int32: A slider with Int32 values for the user to choose from.

  • Float: A slider with Float values for the user to choose from.

  • Enum: A selector to choose from the specified enum's values.

  • EInputKey: A button where the user can input any key (supports both keyboard and controller).

Base Annotations

The following annotations is supported for all property types.

  • @runtimeProperty("ModSettings.mod", "String"): The unique name of your mod, this is how Mod Settings can differentiate settings for your mod from another mod. You must reuse the same value on other properties.

  • @runtimeProperty("ModSettings.displayName", "String"): The label for this property to show to the player in the UI.

  • @runtimeProperty("ModSettings.description", "String"): The hint for this property when the player hovers over the setting, which can be helpful if the label is not explicit for new players of your mod.

  • @runtimeProperty("ModSettings.category", "String"): The category to list a property under, Mod Settings will group all properties with the same category with each other, under a separator with the category's name.

  • @runtimeProperty("ModSettings.category.order", "Number"): The specific order placement for the category, use this if you want to manually specify how you want categories to be ordered in the UI.

  • @runtimeProperty("ModSettings.dependency", "String"): Use this annotation on a property if you want to show it only if another Boolean setting is enabled, String must be the name of the Boolean setting property.

Specific Annotations

The following annotations are only supported on properties with a specific type:

Int32

  • @runtimeProperty("ModSettings.min", "Int32"): The minimum allowed amount for the slider.

  • @runtimeProperty("ModSettings.max", "Int32"): The maximum allowed amount for the slider.

  • @runtimeProperty("ModSettings.step", "Int32"): The amount to add/decrease when the user changes the amount.

Float

  • @runtimeProperty("ModSettings.min", "Float"): The minimum allowed amount for the slider.

  • @runtimeProperty("ModSettings.max", "Float"): The maximum allowed amount for the slider.

  • @runtimeProperty("ModSettings.step", "Float"): The amount to add/decrease when the user changes the amount.

Enum

  • @runtimeProperty("ModSettings.displayValues.EnumValue", "String"): When displaying enums to the user, by default, Mod Settings will simply use the enum's values as the label displayed. If wanted, you can provide this annotation to specify the label for each value.

Listeners

In order to have the class' properties update during run-time when the player makes any changes (through the Accept button), you must register a listener to your class.

There are essentially two methods to tell Mod Settings you want to listen for changes:

Listening to Changes

Binding annotations to your class' properties isn't enough, as you also must register a listener to the class in order to have Mod Settings update the properties during run-time, whenever the player makes changes.

Listening to Modifications

If wanted, you can use the above methods on any class to make Mod Settings fire callbacks whenever a setting is changed in Mod Settings.

You must define any of the following methods to the class in order for Mod Settings to call it:

groupPath is equal to /mods/[ModName]/[ModClass], and varName is equal to the variable name.

You must exactly name the callback methods as you see it, you must also not forget to use the keyword cb either. Both conditions are required for the method to be called by Mod Settings.

Registering Listeners

We can update MySettings with Listen and Unlisten methods:

Now you can call Listen/Unlisten whenever your singleton is registered/unregistered in their respective lifecycle methods. Using MySettings from above, here is how you can register it for ScriptableSystems:

If you are using ScriptableService

Here's how it would look like instead:

Save changes dynamically

You can provide players with another entry-point to change your settings. For example using a popup or a choice hub, without Mod Settings menu. As-is, changes made to a setting won't be saved by Mod Settings in its configuration file.

You can get the ConfigVar of your settings, and then apply changes to be saved (dynamically) like if it was done through Mod Settings menu:

Full example

If you're having trouble implementing Mod Settings for your mod, feel free to ask for help in redscript-scripting channel on Discord.

Code

Here is a more in-depth example showcasing the various supported types and annotations:

If you are using ScriptableService instead

Preview

Things to note:

  • Note how the label for the "General" category was defined as Gameplay-RPG-Items-Categories-General, as Mod Settings supports localization keys for any string values.

  • You don't see the secondStyle setting in the UI at all, that's because it is dependent on the enabled property and won't show if enabled is false (i.e. it won't show if the mod is disabled).

  • The secret property of the class isn't known to Mod Settings at all because it has no annotations.

Practical Example

As an example, if you want to give the player X amount of money (where X equals to the threshold setting) whenever they jump, here's how you can do it:

You can also save a reference to MySettings instead of getting it every time you want to access it. You can add it as a field to PlayerPuppet (or the object you want to use it in) and get/remove the reference when the object is initialized and uninitialized.

For example:

Last updated