Settings Kit - Read settings

Read a setting

Read any setting through Settings<T>.Instance:

float volume = Settings<AudioDefaults>.Instance.MasterVolume;

A per-platform setting returns the values for the platform the game runs on:

string url = Settings<BackendConfig>.Instance.ApiUrl;

Don't cache Instance in a field of your own. Builds already cache it, and in the editor your copy would miss later edits, undos and test overrides.

Read before the first scene

In a build, settings are loaded before the first scene's Awake, so all scene code can read them. Code that runs earlier, in RuntimeInitializeLoadType.BeforeSceneLoad or before, checks Settings.Loaded first; while it is false, reads return defaults.

if (Settings.Loaded)
    Apply(Settings<AudioDefaults>.Instance);

Change a setting from code

Edits made in the settings window are saved for you. When your own editor code changes a setting, call Settings.Save() afterwards. It is safe to call from runtime code too, and does nothing in builds.

Warning: A change made from code behaves differently in the editor and in builds. In the editor, even in Play mode, it edits the stored settings, and the next save writes it to disk, whether you call Settings.Save() or another setting gets saved. In a build, it stays in memory and is lost when the app quits.

Open a page from your tools

Settings.OpenPage<TPage>() opens Project Settings or Preferences on your page. Use it in a menu item or a button in your own tools.

[MenuItem("Tools/My Game/Open Settings")]
static void Open() => Settings.OpenPage<GamePage>();

Test code that reads settings

In a unit test, Settings.OverrideForTests hands the code under test the values you choose. Until you dispose the returned handle, Settings<T>.Instance returns your test instance, and the saved settings are never touched.

[Test]
public void UsesConfiguredVolume()
{
    AudioDefaults stub = new() { /* set up a test instance */ };

    using (Settings.OverrideForTests(stub))
    {
        // code under test reads Settings<AudioDefaults>.Instance and sees the stub
    }
    // substitution is reverted here
}

Note: The override works in the editor and in players built by the Test Runner, and has no effect in any other build.

Build with settings

Builds need no setup. For what each kind of setting contributes to a build, refer to Choose a kind of setting. For what stops a build, refer to Validate values.