ModelProject/Library/PackageCache/com.unity.settings-manager@1.0.2/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.