Local Player Settings

The Kanda SDK provides a LocalLocalPlayerSettingsService to persist various runtime data between application sessions. This service is designed to store and retrieve user preferences, system configurations, and other values that need to be maintained across different runs of the application.

Overview

The LocalPlayerSettingsService is implemented using Unity's PlayerPrefs system, with additional functionality for saving complex objects and encrypting sensitive data. It provides a convenient interface for storing and retrieving various types of data, including primitives, strings, and serializable objects.

Key Features

• Persistence of data between application sessions
• Support for primitive types (int, float, string)
• JSON serialization for complex objects
• Encryption for sensitive data

Accessing the LocalPlayerSettingsService

You can access the LocalPlayerSettingsService using the AppServiceLocator:

using Kanda.Foundation.DependencyInjection;
using Kanda.Foundation.Settings.User;
 
ILocalPlayerSettingsService localPlayerSettings = AppServiceLocator.Get<ILocalPlayerSettingsService>();

Basic Usage

Checking if a Key Exists

bool hasKey = localPlayerSettings.HasKey("myKey");

Setting Values

localPlayerSettings.SetInt("myIntKey", 42);
localPlayerSettings.SetFloat("myFloatKey", 3.14f);
localPlayerSettings.SetString("myStringKey", "Hello, World!");

Subscribing to Changes

You can subscribe to changes of a specific Key, this will provide a callback to the Action provided whenever that specific key is changed using the Set methods.

localPlayerSettings.Subscribe("myIntKey", OnMyKeyChanged);
    
void OnMyKeyChanged()
{
    // Do something   
}

To unsubscribe use the Unsubscribe method.

localPlayerSettings.Unsubscribe("myIntKey", OnMyKeyChanged);

Getting Values

int myInt = localPlayerSettings.GetInt("myIntKey");
float myFloat = localPlayerSettings.GetFloat("myFloatKey");
string myString = localPlayerSettings.GetString("myStringKey");

Deleting a Key

localPlayerSettings.DeleteKey("myKey");

Forcing a Save

This will typically happen automatically when quitting the application, but if a setting value is particularly important, forcing a save will commit it to disk immediately in case of a crash.

localPlayerSettings.ForceSave();

Working with Complex Objects

The LocalPlayerSettingsService can serialize and deserialize complex objects using JSON:

// Saving an object
var myObject = new MyClass { Property1 = "Value1", Property2 = 42 };
localPlayerSettings.SetObject("myObjectKey", myObject);
 
// Retrieving an object
MyClass retrievedObject = localPlayerSettings.GetObject<MyClass>("myObjectKey");

Encrypting Sensitive Data

For sensitive information, you can use the encryption methods:

// Saving encrypted string
localPlayerSettings.SetStringWithEncryption("sensitiveKey", "sensitive data");
 
// Retrieving encrypted string
string decryptedString = localPlayerSettings.GetEncryptedString("sensitiveKey");
 
// Saving encrypted object
var sensitiveObject = new SensitiveData { UserToken = "secret_token" };
localPlayerSettings.SetObjectWithEncryption("sensitiveObjectKey", sensitiveObject);
 
// Retrieving encrypted object
SensitiveData retrievedSensitiveObject = localPlayerSettings.GetEncryptedObject<SensitiveData>("sensitiveObjectKey");

Best Practices

1. Use constants for keys: To avoid typos and ensure consistency, define constants for your setting keys.

   public static class PlayerSettingsKeys
   {
       public const string InputSensitivity = "InputSensitivity";
       public const string SelectedTheme = "SelectedTheme";
       public const string LastLoginDate = "LastLoginDate";
   }

2. Handle missing keys: When retrieving values, be prepared to handle cases where the key doesn't exist.

   float sensitivity = localPlayerSettings.HasKey(PlayerSettingsKeys.InputSensitivity) 
       ? localPlayerSettings.GetFloat(PlayerSettingsKeys.InputSensitivity) 
       : 1.0f; // Default value

3. Use encryption for sensitive data: Always use the encryption methods when storing sensitive information like authentication tokens or personal data.
4. Avoid storing large amounts of data: The PlayerPrefs system is not designed for storing large datasets. Consider alternative storage solutions for substantial amounts of data.
5. Be mindful of performance: While generally fast, reading and writing settings can impact performance if done frequently. Consider caching values in memory if they're accessed often.

Example: Theme Manager

Here's an example of how you might use the LocalPlayerSettingsService in a theme manager:

public class ThemeManager : MonoBehaviour
{
    private ILocalPlayerSettingsService _localPlayerSettings;
    
    private void Awake()
    {
        _localPlayerSettings = AppServiceLocator.Get<ILocalPlayerSettingsService>();
        LoadTheme();
    }
 
    private void LoadTheme()
    {
        string themeName = _localPlayerSettings.HasKey(PlayerSettingsKeys.SelectedTheme)
            ? _localPlayerSettings.GetString(PlayerSettingsKeys.SelectedTheme)
            : "Default";
        
        ApplyTheme(themeName);
    }
 
    public void SetTheme(string themeName)
    {
        _localPlayerSettings.SetString(PlayerSettingsKeys.SelectedTheme, themeName);
        ApplyTheme(themeName);
    }
 
    private void ApplyTheme(string themeName)
    {
        // Logic to apply the theme
    }
}

By leveraging the LocalPlayerSettingsService, you can easily create persistent, user-specific configurations that enhance the user experience and maintain state across application sessions.