Settings
Overview
Settings are managed by the Settings Service (GameService.Settings
) and are saved to settings.json
. Settings are manged with the Settings.SettingEntry<T>
class and are contained within a Settings.SettingCollection
. SettingCollection
supports containing other SettingCollection
allowing you to better organize your settings.
All types are technically supported as long as they are serializable. The following types will, however, provide the best experience:
bool
float
int
string
- Any enum
Defining Settings
Settings can be defined at any time. Once defined, they are kept in settings.json
if their value is different from the defined default.
The best time to define module settings is in the DefineSettings
method. The settings
parameter is the root SettingCollection
associated with your module. You can add as many settings and collections as you would like within this collection.
DefineSettings(string entryKey, T defaultValue, string displayName = null, string description = null)
- entryKey is the unique name of the setting within the collection. Each setting within a
SettingCollection
must have a uniqueentryKey
. - defaultValue is the default or initial value of the setting.
- displayName is the friendly display name used when the setting is rendered within the UI.
- description is the setting description which is shown when the mouse hovers over a rendered setting within the UI.
tip
For internal settings managed manually by your module, you do not need to define displayName
or description
.
AddSubCollection(string collectionKey, bool renderInUi)
- collectionKey is the unique name of the new sub collection within the collection. No different than the
entryKey
when defining settings. - renderInUi if
true
, the subcollection will automatically render itself when a parent collection is rendered. Iffalse
, the subcollection will be ignored if the parent collection is rendered to the UI.
Compliant Settings
Some settings, in context, need to be limited in some way when displayed in the UI.
int
and float
setting entries can set the allowed range for the value using SetRange(minValue, maxValue)
. When the setting is rendered, the TrackBar control which allows changing the value will be limited to the range you've set with SetRange
.
Rendering Settings
Supported setting types (listed below) can be automatically rendered to a view. To do this, pass a SettingCollection
in the constructor of a SettingsView
.
'First Class' Types
Only some types support automatically generating controls to manage the setting. For instance, a bool setting can be automatically rendered to a checkbox control.