Library/PackageCache/com.unity.settings-manager@1.0.3/Documentation~/settings-manager.md

# Settings Manager

A framework for making any serializable field a setting, complete with a pre-built settings interface.

## Quick Start

Settings are stored and managed by a `Settings` instance. This class is responsible for setting and retrieving serialized values from the appropriate repository.

Settings repositories are used to save and load settingsfor a settings scope. Two are provided with this package: one for saving User preferences (`UserSettingsRepository`, backed by the `EditorPrefs` class) and one for Project settings (`ProjecSettingsRepository`, which saves a JSON file to the `ProjectSettings` directory).

Usually you will want to create and manage a singleton `Settings` instance. Ex:

```
using UnityEditor.SettingsManagement;

namespace UnityEditor.SettingsManagement.Examples
{
    static class MySettingsManager
    {
        internal const string k_PackageName = "com.unity.my-settings-example";

        static Settings s_Instance;

        internal static Settings instance
        {
            get
            {
                if (s_Instance == null)
                    s_Instance = new Settings(k_PackageName);

                return s_Instance;
            }
        }
    }
}
```

Values are set and retrieved using generic methods on on your `Settings` instance:

```
MySettingsManager.instance.Get<float>("myFloatValue", SettingsScope.Project);
```

There are two arguments: key, and scope. The `Settings` class will handle finding an appropriate `ISettingsRepository` for the scope, while `key` and `T` are used to find the value. Setting keys are unique among types, meaning you may re-use keys as long as the setting type is different.

Alternatively, you can use the `UserSetting<T>` class to manage settings. This is a wrapper class around the `Settings` get/set properties, and makes it very easy to make any field a saved setting.

```
// UserSetting<T>(Settings instance, string key, T defaultValue, SettingsScope scope = SettingsScope.Project)
Setting<int> myIntValue = new Setting<int>(MySettingsManager.instance, "int.key", 42, SettingsScope.User);
```

`UserSetting<T>` caches the current value, and keeps a copy of the default value so that it may be reset. `UserSetting<T>` fields are also eligible for use with the `[UserSettingAttribute]` attribute, which lets the `SettingsManagerProvider` automatically add it to a settings inspector.

## Settings Provider

To register your settings in the `Settings Window` you can either write your own `SettingsProvider` implementation, or use the provided `SettingsManagerProvider` and let it automatically create your interface.

Making use of `SettingsManagerProvider` comes with many benefits, including a uniform look for your settings UI, support for search, and per-field or mass reset support.

```
using UnityEngine;

namespace UnityEditor.SettingsManagement.Examples
{
	static class MySettingsProvider
	{
		const string k_PreferencesPath = "Preferences/My Settings";

		[SettingsProvider]
		static SettingsProvider CreateSettingsProvider()
		{
			// The last parameter tells the provider where to search for settings.
			var provider = new SettingsManagerProvider(k_PreferencesPath,
				MySettingsManager.instance,
				new [] { typeof(MySettingsProvider).Assembly });

			return provider;
		}
	}
}
```

To register a field with the `SettingsManagerProvider`, simply decorate it with `[UserSettingAttribute(string displayCategory, string key)]`. `[UserSettingAttribute]` is only valid for static fields.

For more complex settings that require additional UI (or simply don't have a built-in editor), you can use `UserSettingBlockAttribute`. This provides access to the settings provider GUI. See `SettingsExamples.cs` for more on this.