> For the complete documentation index, see [llms.txt](https://aptivi.gitbook.io/aptivi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aptivi.gitbook.io/aptivi/nitrocid-ks-v0.2.1-rolling-manual/advanced-and-power-users/inner-workings/kernel-settings/custom-settings.md).
# Custom Settings
You can add your own custom settings, too!
Customized settings give you an ability to leverage the built-in settings application provided by the Nitrocid base system to customize your mod's behavior. These settings are saved to your kernel configuration directory as JSON files under the class names for easy recognition.
***
## Defining custom settings
Before you continue, you must first understand the settings format and take a quick look at it here:
{% content-ref url="/pages/3bVMS1ds8AL0BIR0zw0c" %}
[Settings Format](/aptivi/nitrocid-ks-v0.2.1-rolling-manual/advanced-and-power-users/inner-workings/kernel-settings/settings-format.md)
{% endcontent-ref %}
Here's how you can define the custom settings.
{% stepper %}
{% step %}
### Make a custom settings class
The first thing that your custom kernel settings requires is that you need to have a class (for example, let's assume that your custom settings class name is `OxygenSettings`) that is derived from both the `BaseKernelConfig` class and the `IKernelConfig` interface.
{% code title="OxygenSettings.cs" lineNumbers="true" %}
```csharp
internal class OxygenSettings : BaseKernelConfig, IKernelConfig
{
// Your custom settings here
}
```
{% endcode %}
{% endstep %}
{% step %}
### Override the settings entries property
This class **must** override the `SettingsEntries` property from the base class so that it can understand your custom settings entries and how they're defined.
The easiest way to override it is to just let this property return an array from `SettingsEntries` using the `GetSettingsEntries` function, pointing it at your variable containing your JSON representation of the settings entries, as demonstrated in the below example:
internal class OxygenSettings : BaseKernelConfig, IKernelConfig
{
// Your JSON representation about your settings entries
private readonly string _entriesJson =
"""
[
{
"Name": "CustomSection",
"Desc": "This is the custom section.",
"DisplayAs": "Custom section",
"Keys": [
{
"Name": "Custom switch",
"Type": "SBoolean",
"Variable": "CustomSwitch",
"Description": "Specifies the custom switch."
},
{
"Name": "Custom character",
"Type": "SChar",
"Variable": "CustomChar",
"Description": "Specifies the custom character."
},
{
"Name": "Custom color",
"Type": "SColor",
"Variable": "CustomColor",
"Description": "Specifies the custom color."
},
{
"Name": "Custom double",
"Type": "SDouble",
"Variable": "CustomDouble",
"Description": "Specifies the custom double."
},
{
"Name": "Custom figlet font",
"Type": "SFiglet",
"Variable": "CustomFigletFont",
"Description": "Specifies the custom figlet font."
},
{
"Name": "Custom integer",
"Type": "SInt",
"Variable": "CustomInt",
"Description": "Specifies the custom integer."
},
{
"Name": "Custom integer slider",
"Type": "SIntSlider",
"Variable": "CustomIntSlider",
"Description": "Specifies the custom integer slider.",
"MinimumValue": 0,
"MaximumValue": 255
},
{
"Name": "Custom list",
"Type": "SList",
"Variable": "CustomList",
"SelectionFunctionName": "GetPathList",
"SelectionFunctionType": "Filesystem",
"DelimiterVariable": "PathLookupDelimiter",
"IsValuePath": true,
"IsPathCurrentPath": true,
"Description": "Specifies the custom list."
},
{
"Name": "Custom preset",
"Type": "SPreset",
"Variable": "CustomPreset",
"ShellType": "Shell",
"Description": "Specifies the custom preset."
},
{
"Name": "Custom selection",
"Type": "SSelection",
"Variable": "CustomSelection",
"IsEnumeration": false,
"SelectionFunctionName": "ListAllLanguages",
"SelectionFunctionType": "LanguageManager",
"IsSelectionFunctionDict": true,
"SelectionFallback": [ "en-US" ],
"Description": "Specifies the custom selection."
},
{
"Name": "Custom string",
"Type": "SString",
"Variable": "CustomString",
"Description": "Specifies the custom string."
}
]
}
]
""";
// You must override this
public override SettingsEntry[] SettingsEntries =>
ConfigTools.GetSettingsEntries(_entriesJson);
// Your variables. Your JSON representation of the entries must contain information about these
public char CustomChar { get; set; } = 'A';
public string CustomColor { get; set; } = Color.Empty.PlainSequence;
public double CustomDouble { get; set; } = 0.5d;
public bool CustomSwitch { get; set; } = true;
public string CustomFigletFont { get; set; } = "small";
public int CustomInt { get; set; } = 1;
public int CustomIntSlider { get; set; } = 4;
public string CustomList { get; set; } = "";
public string CustomPreset { get; set; } = "Default";
public string CustomString { get; set; } = "Default";
public string CustomSelection { get; set; } = "en-US";
}
{% hint style="info" %}
Beware that your base kernel configuration class must contain valid entries in your list of entries under the JSON representation.
You can use the below function to convert your JSON settings entries to their usable ones:
```csharp
public static SettingsEntry[] GetSettingsEntries(string entriesText) { }
```
You can also embed your settings JSON content if it became too big using the Resources feature, which you can learn more about how to add a file to your project resources and use it [here](https://learn.microsoft.com/en-us/dotnet/core/extensions/create-resource-files).
You don't have to save a copy of your `customSettings` variable, since it gets added to the custom settings list that the kernel configuration tool supervises.
{% endhint %}
{% endstep %}
{% step %}
### Register your configuration class
After that, you must register your configuration class by just two lines somewhere in your mod initialization code:
{% code title="MyModInit.cs" lineNumbers="true" %}
```csharp
var customSettings = new OxygenSettings();
ConfigTools.RegisterCustomSetting(customSettings);
```
{% endcode %}
{% endstep %}
{% endstepper %}
{% hint style="danger" %}
Once your mod registers a settings instance, it can never be unloaded due to a current limitation affecting serialization and deserialization of JSON files.
{% endhint %}
***
## Additional tools
After you register your own custom settings, you can now use the following tools:
Using your own custom settings
To use your own custom settings, you'll have to get a settings instance from `GetKernelConfig()` before being able to get the updated settings instance containing your configured settings, even if you have a new instance of your custom settings.
You can easily wrap it to a property like this:
{% code title="Mod.cs" lineNumbers="true" %}
```csharp
internal static BaseKernelConfig Configuration =>
Config.GetKernelConfig(nameof(OxygenSettings));
```
{% endcode %}
You can then get a value from your desired settings key.
For example, if you want to get a value of a string configuration defined earlier, called `CustomString`, you can get the value of this key like this:
{% code title="Mod.cs" lineNumbers="true" %}
```csharp
var key = ConfigTools.GetSettingsKey(Configuration, nameof(OxygenSettings.CustomString));
string value = (string)ConfigTools.GetValueFromEntry(key, Configuration);
```
{% endcode %}
{% hint style="warning" %}
If you used this method against your newly-created instance of your custom settings (the `customSettings` variable) instead of the above property, calls to `GetValueFromEntry()` would not return the configured results changed by the settings command.
{% endhint %}
Testing your own custom settings
To test your own custom settings to check to see if it works or not, make sure that you've registered your custom settings upon starting your mod. Invoking the help usage of the `settings` command (`help settings`) is enough to list all of your kernel settings (built-in and custom).
Use the `settings` command to specify your kernel settings type with the `-type` switch, pointing it to your custom kernel settings name, which is usually your settings class name, for example, `settings -type=OxygenSettings`.
If everything goes well, you should be able to change your settings there.
{% hint style="info" %}
When registering custom settings, the kernel runs a validation test to ensure that your custom settings are formed well before adding it to the list. If it fails, the kernel will give you a list of the configuration entries that you'll have to fix before being able to use them.
{% endhint %}
{% hint style="warning" %}
If **any** of the kernel configuration entries is invalid, the configuration tools will report a failure. Make sure that all of the entries are valid and that you've specified the variable names correctly. Use `nameof` to help you assign them.
**The variable names are case-sensitive.**
{% endhint %}
Fallback configuration
You can generate a configuration instance that contains all fallback values that are determined by the constructor of all settings properties. You can provide either a configuration class as a generic type argument, or a config type name, using the `GetFallbackKernelConfig()` function.
To demonstrate that, you can use either of the following:
* F8: Reset all configuration entries
* SHIFT + R: Reset selected configuration entry
{% hint style="warning" %}
Some of the kernel settings may store the current settings, even if the fallback instances are generated. Settings for your mods should not rely on external variables when possible.
{% endhint %}
Unregistering your own custom settings
You can unregister your custom settings by putting the `UnregisterCustomSetting()` function somewhere in your mod stop function like this:
{% code title="MyModStop.cs" lineNumbers="true" %}
```csharp
ConfigTools.UnregisterCustomSetting(nameof(OxygenSettings));
```
{% endcode %}
{% hint style="info" %}
You don't have to do all the guesswork to figure out how to get your custom configuration name. All you have to do is to point the above function to the name of your configuration class using the `nameof` function.
{% endhint %}
