Modding:Options

This page is about modding. See the modding overview for an abstract on modding.

This page is about modding. See the modding overview for an abstract on modding.

For best results, it's recommended to have read the following topics before this one:

• Modding:C Sharp Scripting

Adding new options

In some cases it may be desirable to add tunable settings to your mod, to allow players to pick options to their liking. In these cases, you can piggyback off of Qud's built in Options menu by merging your own settings into Options.xml.

Here's an example of a custom Options.xml:

<?xml version="1.0" encoding="utf-8" ?>
<options>
  <option ID="Option_MyName_MyMod_EnableFoo" DisplayText="Enable Foo"
    Category="Mods: MyMod" Type="Checkbox" Default="Yes"></option>
  <option ID="Option_MyName_MyMod_FooSelector" DisplayText="Foo, Bar, or Baz?"
    Category="Mods: MyMod" Type="Combo" Default="Foo"></option>
</options>

This produces a new section in the options menu, which appears as follows:

The <option>...</option> XML tag defines a new setting in Options.xml. This tag can have the following attributes:

Tag	Meaning
ID	A unique ID corresponding to the option. This ID is referred to in the code when retrieving the value of the configured setting.
DisplayText	The text that should be displayed alongside the option in the settings menu.
Category	The area under which the option appears in the settings menu. In general, all of your options should go under a single custom category for your mod.
Type	Affects the widget that is rendered for the option, and the values that it can take on. There are multiple types available, including Checkbox, Slider, Button, Combo, and BigCombo. Each of these types has custom attributes that are specific to them; refer to the base game's Options.xml for a reference.
Default	The default value that the option should be set to, before any user configuration.
SearchKeywords	Additional keywords that players can use to find an option in the settings menu.

Using configured options in code

Once you've added your own custom options, you can retrieve them in code using the XRL.UI.Options.GetOption method. This method always returns a string, but you may want to convert them into a different type before using them in your code. One way of doing so is to create a thin wrapper around XRL.UI.Options that calls GetOption under the hood, for instance:

using System;

namespace MyName.MyMod {
    public class Options {
        private static string GetOption(string ID, string Default = "") {
            return XRL.UI.Options.GetOption(ID, Default);
        }

        public static bool EnableFoo => GetOption("Option_MyName_MyMod_EnableFoo").EqualsNoCase("Yes");
        public static int FooAmount => Convert.ToInt32(GetOption("Option_MyName_MyMod_FooAmount"));
    }
}