⚙️Custom Settings
You can add your own custom settings, too!
Last updated
You can add your own custom settings, too!
Last updated
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.
In your mod, you can register and unregister your custom settings using the following functions from the ConfigTools
class:
RegisterCustomSetting(BaseKernelConfig kernelConfig)
UnregisterCustomSetting(string setting)
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:
Before you continue, you must first understand the settings format and take a quick look at it here:
Settings FormatThe 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.
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:
After that, you must register your confguration class by just two lines somewhere in your mod initialization code:
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.
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.
You can also unregister your custom settings by putting the UnregisterCustomSetting()
function somewhere in your mod stop function like this:
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.
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.
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.
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.