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.

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.
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.
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 withInt32values for the user to choose from.Float: A slider withFloatvalues 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,Stringmust 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:
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:
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
Code
Here is a more in-depth example showcasing the various supported types and annotations:
Preview

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