Public API

Namespace SettingsKit, assembly SettingsKit.

Declaring settings

SettingsPage

abstract class

Declares a settings page. It appears in Project Settings, Preferences, or both, depending on the settings attached to it. Title and order come from SettingsDisplayAttribute. Explained in Declare settings.

abstract string Path { get; }Where the page appears; / nests (for example "My Game/Networking"). Must be constant.
virtual string Description { get; }Help box at the top of the page. Optional.
virtual string HelpUrl { get; }Documentation link, shown as a "?" button. Optional.

BuildSettingsEntry<TPage>

abstract class

Base for a build setting: shown in Project Settings, committed, and readable in builds. The class must be [System.Serializable] with a parameterless constructor; field initializers are the defaults. Explained in Declare settings.

PlatformSettingsEntry<TPage>

abstract class

Base for a per-platform build setting: like BuildSettingsEntry<TPage>, with different values per build target. Reads return the values for the current platform. Explained in Declare settings.

EditorSettingsEntry<TPage>

abstract class

Base for an editor setting: shown in Project Settings and committed, but not included in builds (reads in a build return defaults). Explained in Declare settings.

UserSettingsEntry<TPage>

abstract class

Base for a user setting: shown in Preferences, per developer, not included in builds (reads in a build return defaults). Explained in Declare settings.

SettingsDisplayAttribute

Attribute

Optional title, tooltip and order for a page or a settings class. Without it, a page uses the last segment of its path and a settings class its type name (AudioDefaults shows as "Audio Defaults"). Explained in Customize the window.

SettingsDisplayAttribute()Keeps the default title.
SettingsDisplayAttribute(string title)Sets the title.
string Title { get; set; }The title shown in the settings window.
string Tooltip { get; set; }Tooltip for the title.
int Order { get; set; }Order among siblings, lowest first.

Reading settings

Settings

static class

Load state, saving, page navigation and test overrides. Read values through Settings<T>.Instance. Explained in Read settings.

static bool Loaded { get; }Whether saved settings are loaded. Always true in the editor; in a build, true by the first scene's Awake, but possibly false in RuntimeInitializeLoadType.BeforeSceneLoad or earlier. While false, reads return defaults.
static void Save()Saves changes made from editor code. Safe to call from runtime code; does nothing in builds.
static void OpenPage<TPage>() where TPage : SettingsPage, new()Opens the page in Project Settings or Preferences. Safe to call from runtime code; does nothing in builds.
static IDisposable OverrideForTests<T>(T value) where T : SettingsEntry, new()Makes Settings<T>.Instance return value until the handle is disposed. Saved settings are untouched. Works in the editor and in players built by the Test Runner; has no effect in any other build, development builds included.
Throws ArgumentNullException when value is null.

Settings<T>

static class

Reads one settings class. Don't cache Instance: builds already cache it, and in the editor your copy would miss later edits, undos and test overrides. Safe to read from any thread once settings are loaded. Explained in Read settings.

static T Instance { get; }The configured values of T, or defaults if never configured. In the editor, changes made through it edit the stored settings, and Settings.Save writes them to disk. In a build, changes stay in memory and are lost when the app quits.

Validation and migration

IValidatedSettings

interface

Implement it on a settings class to check its values: Validate returns false with a message when they are invalid. The message shows under the section in the settings window, and an invalid build setting also stops the build. Explained in Customize the window.

bool Validate(out string error)Returns false with an error message when invalid.

IVersionedSettings

interface

Implement it on a settings class whose saved values need converting when its data changes: raise Version, and convert the old values in Migrate. Runs in the editor when settings load. Explained in Update your settings.

int Version { get; }The current version; raise it when the data changes.
void Migrate(int fromVersion)Converts values saved at fromVersion. Runs once per upgrade, and again on the next load if it throws, so running it twice must be harmless.

SettingsMigratorAttribute

Attribute

Put [SettingsMigrator] on a static method to recover the saved values of a settings class you deleted: the method receives the old data, and you copy it into your current settings. Runs in the editor when settings load, before the old data is deleted. Explained in Update your settings.

static void AnyName(MissingSettings missing)Called once for each saved setting whose class no longer exists. Check the names to recognize your old class, read it with TryRead, copy the values into current settings, and call Settings.Save. Any access level works.
A method with any other signature is ignored, with an error in the console as soon as Unity compiles it.

MissingSettings

readonly struct

Saved data whose settings class no longer exists, passed to every [SettingsMigrator] method. Explained in Update your settings.

string ClassName { get; }The class name of the deleted type.
string Namespace { get; }The namespace of the deleted type, or empty.
string AssemblyName { get; }The name of the assembly the deleted type belonged to.
bool TryRead<TOld>(out TOld value)Copies the saved fields into TOld, a [System.Serializable] type you declare with the fields you want back. Returns false when the data cannot be read.
Settings Kit v1.0.0  ·  For full signatures and remarks, see the XML doc comments in the source.