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

Settings Manager

The Settings Manager is a framework that lets you convert any serializable field into a setting, including a pre-built settings interface.

Installation

To install this package, follow the instructions in the Package Manager documentation.

This package provides a sample that demonstrates how to implement custom user settings. To install them, follow these instructions:

1. Make sure the Settings Manager package is installed in your Unity project.

2. In the Package Manager window, locate the Settings Manager package select it from the list.

   The Details view displays information about the Settings Manager package.

3. From the Details view, click the Import button under the Samples section.

Requirements

This version of the Settings Manager package is compatible with the following versions of the Unity Editor:

• 2018.4 and later

Using the Settings Manager

The Settings class is responsible for setting and retrieving serialized values from a settings repository.

Use settings repositories to save and load settings for a specific scope. This package provides two settings repositories:

• The UserSettingsRepository, backed by the EditorPrefs class, lets you save user preferences.
• The FileSettingsRepository saves a JSON file to the ProjectSettings directory in order to save project settings.

You can create and manage all settings from a singleton Settings instance. For example:

using UnityEditor.SettingsManagement;

namespace UnityEditor.SettingsManagement.Examples
{
    static class MySettingsManager
    {
        internal const string k_PackageName = "com.example.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;
            }
        }
    }
}

Getting and setting values

Your Settings instance should implement generic methods to set and retrieve values:

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

There are two arguments: key, and scope. The Settings class finds an appropriate ISettingsRepository for the scope, while key and T are used to find the value. Keys are unique among types: you can re-use keys as long as its 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, which makes it 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. You can also use UserSetting<T> fields with the [UserSettingAttribute] attribute, which lets the SettingsManagerProvider automatically add it to a settings inspector.

Settings Provider

To register your settings so they appear in the Project Settings window, you can either write your own SettingsProvider implementation, or use the UserSettingsProvider and let it automatically create your interface.

Making use of UserSettingsProvider 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 UserSettingsProvider, decorate it with [UserSettingAttribute(string displayCategory, string key)].

[!NOTE] The [UserSettingAttribute] decoration is only valid for static fields.

For more complex settings that require additional UI (or that don't have a built-in Editor), use UserSettingBlockAttribute to access the settings provider GUI. For more information, look at the sample source file SettingsExamples.cs under the Assets/Samples/Settings Manager/<version>/User Settings Example/PackageWithProjectAndUserSettings folder in your Unity project root.

[!TIP] If you don't see this path or file, follow the steps under the Installation section to import it.