Skip to content

Game.Modding.ModSetting

Assembly: Assembly-CSharp
Namespace: Game.Modding

Type: abstract class

Base: Game.Settings.Setting

Summary:
ModSetting is an abstract base class used by mods to expose settings and to integrate mod-specific input bindings with the game's InputManager and Settings UI. It provides automatic discovery of ProxyBinding properties via reflection, creation and registration of ProxyAction/ProxyComposite/ProxyBinding data with the InputManager, helpers to produce localization keys for options, and facilities for applying, resetting, and mirroring key bindings. Instances are tracked in a static dictionary keyed by a generated id for the mod.

Fields

  • private PropertyInfo[] m_keyBindingProperties
    {{ Backing cache for computed keyBindingProperties. This is lazily populated by reflecting the instance's public instance properties of type ProxyBinding. }}

  • internal static Dictionary<string, ModSetting> instances { get; }
    {{ Static registry map of all ModSetting instances, keyed by the setting id (generated from the mod's assembly/namespace/type). Used to look up settings by id. }}

  • internal IMod mod { get; }
    {{ The mod instance that owns this settings object (internal). Provided via constructor. }}

  • protected internal sealed override bool builtIn => false
    {{ Overrides the base Setting.builtIn to mark mod settings as non-built-in (i.e. user/mod provided). }}

  • [SettingsUIHidden] public string id { get; }
    {{ Unique id for this ModSetting instance; generated in the constructor as "AssemblyName.Namespace.TypeName". Used as the input action map id and as the settings section id. Hidden from the Settings UI (SettingsUIHidden attribute). }}

  • [SettingsUIHidden] public string name { get; }
    {{ A name for the settings object (defaults to the type name). Hidden from the Settings UI. }}

  • [SettingsUIHidden] public bool keyBindingRegistered { get; private set; }
    {{ Tracks whether the mod's key bindings have been registered with the InputManager. Readable publicly, writable only by this class. }}

  • private PropertyInfo[] keyBindingProperties
    {{ Lazy property that returns the collection of public instance properties on the concrete ModSetting type which are of type ProxyBinding and are readable/writable. Cached into m_keyBindingProperties. }}

Properties

  • public string id { get; }
    {{ Read-only unique id generated from the mod type. Used as the Input action map id and settings section id. }}

  • public string name { get; }
    {{ Read-only name of the settings object (defaults to the class name). }}

  • public bool keyBindingRegistered { get; private set; }
    {{ Indicates whether key bindings have been registered. Registration is performed by calling RegisterKeyBindings(). }}

  • internal IMod mod { get; }
    {{ The owning mod instance provided at construction. Internal visibility. }}

  • internal static Dictionary<string, ModSetting> instances { get; }
    {{ Global registry of ModSetting instances keyed by id. }}

  • protected internal sealed override bool builtIn
    {{ Returns false, marking these settings as non-built-in. }}

Constructors

  • public ModSetting(IMod mod)
    {{ Constructor. Generates the settings id from the mod's type (assembly name + namespace + type name), sets the settings name, stores the mod reference, registers this settings instance in the static instances dictionary, and calls InitializeKeyBindings() to create ProxyBinding objects for any ProxyBinding properties found on the derived type. }}

Methods

  • public void RegisterInOptionsUI()
    {{ Convenience for registering this settings section in the game's Options UI. Calls Setting.RegisterInOptionsUI(id, addPrefix: true). }}

  • public void UnregisterInOptionsUI()
    {{ Unregisters the settings section from the Options UI (calls Setting.UnregisterInOptionsUI(id)). }}

  • private void InitializeKeyBindings()
    {{ Reflects the ProxyBinding properties (keyBindingProperties) and assigns each property a generated ProxyBinding using GenerateBinding. This prepares ProxyBinding objects so they exist before the bindings are registered with InputManager. }}

  • private ProxyBinding GenerateBinding(PropertyInfo property)
    {{ For a given ProxyBinding property, inspects custom attributes (SettingsUIKeyboardBindingAttribute, SettingsUIGamepadBindingAttribute, SettingsUIMouseBindingAttribute) to determine action name, device, action type, action component, default control path, and modifiers. If a SettingsUIBindingMimicAttribute is present and points to a built-in action/composite, the binding will be created to mimic that source binding via CreateMimicBinding; otherwise CreateBinding is used. Returns the configured ProxyBinding instance. }}

  • private bool TryGetSourceBindingForMimic(PropertyInfo property, InputManager.DeviceType device, ActionComponent component, out ProxyBinding sourceBinding)
    {{ Attempts to find a built-in action specified by a SettingsUIBindingMimicAttribute on the property. If the referenced action and composite exist and contain a binding for the requested device/component, returns that binding via out parameter. Used to create mimic bindings. Returns true on success. }}

  • public void RegisterKeyBindings()
    {{ Main routine to register the mod's key bindings with InputManager. If already registered, returns early. Gathers ProxyBinding properties and groups them into ProxyAction/ProxyComposite structures, creates CompositeInstance for each composite (honoring SettingsUIInputActionAttribute metadata on the settings type), constructs ProxyAction.Info structures and calls InputManager.instance.AddActions(actionsToAdd). After adding actions it attaches watchers to each ProxyBinding so property values are kept in sync when changed in the UI or by code. Also attaches a watcher to source bindings when mimicking so changes to the source update the mimic. Marks keyBindingRegistered = true at the end. }}

  • private ProxyBinding CreateBinding(InputManager.DeviceType device, string actionName, ActionType type, ActionComponent component, string control, IEnumerable<string> modifierControls)
    {{ Helper to create a new ProxyBinding using composite/component metadata from InputManager.TryGetCompositeData. Fills device, path, originalPath, modifiers and originalModifiers. Used when there is no mimic target. }}

  • private ProxyBinding CreateMimicBinding(InputManager.DeviceType device, string actionName, ActionType type, ActionComponent component, ProxyBinding sourceBinding)
    {{ Helper to create a ProxyBinding that copies path and modifier data from an existing source binding. Used when a property is marked with SettingsUIBindingMimicAttribute and a built-in source exists. }}

  • [AfterDecode] protected internal void ApplyKeyBindings()
    {{ Called after settings are decoded (deserialized). If key bindings were registered, it collects the current ProxyBinding property values and calls InputManager.instance.SetBindings to apply them. Ensures saved bindings are pushed into the InputManager on load. }}

  • protected void ResetKeyBindings()
    {{ Resets this ModSetting's key bindings to their default generated values by calling GenerateBinding for each ProxyBinding property, applying them via InputManager.instance.SetBindings, and then calling ApplyAndSave() (inherited) to save the reset values. Only operates if keyBindingRegistered == true. }}

  • public ProxyAction GetAction(string name)
    {{ Returns the ProxyAction for the given action name in this ModSetting's action map, using InputManager.instance.FindAction(id, name). }}

  • public IEnumerable<ProxyAction> GetActions()
    {{ Returns all ProxyAction instances defined for this ModSetting's action map, or an empty array if the action map is not found. }}

  • public string GetSettingsLocaleID()
    {{ Returns the localization key for the settings section: "Options.SECTION[]". }}

  • public string GetOptionLabelLocaleID(string optionName)
    {{ Returns the localization key for an option label: "Options.OPTION[..]". }}

  • public string GetOptionDescLocaleID(string optionName)
    {{ Returns the localization key for an option description: "Options.OPTION_DESCRIPTION[..]". }}

  • public string GetOptionWarningLocaleID(string optionName)
    {{ Returns the localization key for an option warning: "Options.WARNING[..]". }}

  • public string GetOptionTabLocaleID(string tabName)
    {{ Returns the localization key for an option tab: "Options.TAB[..]". }}

  • public string GetOptionGroupLocaleID(string groupName)
    {{ Returns the localization key for an option group: "Options.GROUP[..]". }}

  • public string GetEnumValueLocaleID<T>(T value) where T : Enum
    {{ Returns a localization key for an enum value: $"Options.{id}.{typeof(T).Name.ToUpper()}[{value}]". Useful for enum option labels. }}

  • public string GetOptionFormatLocaleID(string optionName)
    {{ Returns a localization key for option format strings: "Options.FORMAT[..]". }}

  • public string GetBindingKeyLocaleID(string actionName)
    {{ Shortcut to get binding key locale id for an action using the default press component name. Calls GetBindingKeyLocaleID(actionName, InputManager.GetBindingName(ActionComponent.Press)). }}

  • public string GetBindingKeyLocaleID(string actionName, AxisComponent component)
    {{ Returns binding key locale id for an AxisComponent by converting to ActionComponent and delegating to the string overload. }}

  • public string GetBindingKeyLocaleID(string actionName, Vector2Component component)
    {{ Returns binding key locale id for a Vector2Component by converting to ActionComponent and delegating to the string overload. }}

  • private string GetBindingKeyLocaleID(string actionName, string componentName)
    {{ Constructs the binding key locale id: "Options.OPTION[//]". Used by the public GetBindingKeyLocaleID overloads. }}

  • public string GetBindingKeyHintLocaleID(string actionName)
    {{ Returns a hint localization key for a binding: "Common.ACTION[/]". }}

  • public string GetBindingMapLocaleID()
    {{ Returns the localization key for the binding map: "Options.INPUT_MAP[]". }}

Usage Example

// Example: a mod settings class that exposes a keyboard binding and registers with the options/input system.
public class MyModSettings : ModSetting
{
    // A ProxyBinding property will be discovered automatically and initialized.
    // You can decorate it with SettingsUIKeyboardBindingAttribute / SettingsUIGamepadBindingAttribute / SettingsUIMouseBindingAttribute
    // to control defaults.
    [SettingsUIKeyboardBinding(actionName: "ToggleFeature")]
    public ProxyBinding ToggleFeature { get; set; }

    public MyModSettings(IMod mod) : base(mod)
    {
        // base constructor already calls InitializeKeyBindings().
        // Optionally register this section in the Options UI and register key bindings:
        RegisterInOptionsUI();
        // Call RegisterKeyBindings when appropriate (e.g., when the mod is enabled / when InputManager is ready)
        RegisterKeyBindings();
    }

    // To reset bindings to defaults programmatically:
    public void ResetMyBindings()
    {
        ResetKeyBindings();
    }
}

{{ YOUR_INFO }}
- Typical lifecycle notes: create and store an instance of your concrete ModSetting when your mod initializes, call RegisterInOptionsUI() if you want the settings section to appear in the game's options, and call RegisterKeyBindings() once the InputManager is ready so your ProxyAction/ProxyComposite/ProxyBinding entries are added. Use ApplyKeyBindings (triggered automatically after decode/load) and ResetKeyBindings to manage persisted binding state. - Attribute hooks: SettingsUI* attributes on ProxyBinding properties drive default device/action/component/control and modifier values. SettingsUIBindingMimicAttribute allows a mod binding to mirror a built-in game binding so the mod action follows changes to the referenced built-in binding.