Modding:Options: Difference between revisions

← Older edit

Modding:Options (view source)

Revision as of 02:54, 23 April 2024

2,079 bytes added , 23 April

m

Fix typo

Kernelmethod

Bureaucrats, Interface administrators, Administrators

718

edits

@@ Line 1: / Line 1: @@
-[[Category:Modding]]{{Modding Info}}
+[[Category:Script Modding]]
+{{Modding Info}}{{Modding Topic Prerequisites | Modding:C Sharp Scripting}}
 ==Adding new options==
@@ Line 16: / Line 17: @@
 </options>
 </syntaxhighlight>
+This produces a new section in the options menu, which appears as follows:
+[[Image:Modding-Options example.png|center|600px|alt=Example of custom settings added to the Options menu by a mod. This settings menu includes three new options: a checkbox for "Enable Foo", a combo selector for "Foo, Bar, or Baz?", and a slider labeled "Amount of foo to use".]]
 The <code><option>...</option></code> XML tag defines a new setting in <code>Options.xml</code>. This tag can have the following attributes:
-* <code>ID</code>: a unique ID corresponding to the option. This ID is referred to in the code when retrieving the value of the configured setting.
+{| class="wikitable" style="min-width: 50%;"
-* <code>DisplayText</code>: the text that should be displayed alongside the option in the settings menu.
+! Tag
-* <code>Category</code>: 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.
+! Meaning
-* <code>Type</code>: affects the widget that is rendered for the option, and the values that it can take on. There are multiple types available, including <code>Checkbox</code>, <code>Slider</code>, <code>Button</code>, <code>Combo</code>, and <code>BigCombo</code>. Each of these types has custom attributes that are specific to them; refer to the base game's <code>Options.xml</code> for a reference.
+|-
-* <code>Default</code>: the default value that the option should be set to, before any user configuration.
+| <code>ID</code>
-* <code>SearchKeywords</code>: additional keywords that players can use to find an option in the settings menu.
+| A unique ID corresponding to the option. This ID is referred to in the code when retrieving the value of the configured setting.
+|-
+| <code>DisplayText</code>
+| The text that should be displayed alongside the option in the settings menu.
+|-
+| <code>Category</code>
+| 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.
+|-
+| <code>Type</code>
+| Affects the widget that is rendered for the option, and the values that it can take on. The following widget types are currently supported:
+* <code>Checkbox</code>
+* <code>Slider</code>
+* <code>Button</code>
+* <code>Combo</code>
+* <code>BigCombo</code>
+Each of these types has custom attributes that are specific to them; refer to the base game's <code>Options.xml</code> for a reference.
+|-
+| <code>Default</code>
+| The default value that the option should be set to, before any user configuration.
+|-
+| <code>Requires</code>
+| Hides an option unless a precondition is met. For instance, adding <code>Requires="MyName_MyMod_EnableFoo==Yes"</code> to an option will hide that option unless the checkbox for the "Enable Foo" option is selected.
+|-
+| <code>SearchKeywords</code>
+| 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 <code>XRL.UI.Options.GetOption</code> 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 <code>XRL.UI.Options</code> that calls <code>GetOption</code> under the hood, for instance:
+<syntaxhighlight lang="csharp">
+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"));
+    }
+}
+</syntaxhighlight>
+=== Enabling and disabling XML ===
+Options are not natively supported by the game for conditionally enabling or disabling behavior in XML. For example, there isn't a way to configure the game only to merge into an object's blueprint if a given option is enabled. For one possible solution to this problem, check out the [https://github.com/kernelmethod/QudMods/tree/main/SubmoduleManagement submodule-management] mod.
+{{Modding Navbox}}