Custom Metadata

Crystal Save supports Custom Metadata for save slots, allowing you to tag each save with descriptive information such as playtime, difficulty, player name, or custom tags for conflict resolution and display in the UI.

This guide explains how to set, configure, and retrieve custom metadata.

🛠 Setting Up Custom Metadata

• Create a Save Slot Metadata Asset Go to:

Assets ▸ Create ▸ Crystal Save ▸ Settings ▸ Save Slot Metadata

This will create a SaveSlotMetadataSO asset which contains key/value pairs.

• Assign the Metadata Asset Open the Crystal Save Settings window:

Tools ▸ Crystal Save ▸ Settings ▸ Crystal Save Settings

In the Save Settings section, scroll to Custom Metadata and assign or edit your SaveSlotMetadataSO there.

• Add Entries Within the metadata asset:

  • Add new entries with a unique key and a value.

  • If Unity Localization is present, the value field becomes a LocalizedString.

  Examples:

  • Key: Difficulty → Value: Hard

  • Key: Region → Value: EU

  • Key: Version → Value: 2.0.1

• ✅ This metadata will automatically be injected into every save slot before serialization.

Retrieving Metadata

You can access metadata at runtime using the SaveManager.API:

🔸 Example: Get Metadata for a Slot

var metadata = SaveManager.API.GetSlotMetadata(slotNumber);
if (metadata.TryGetValue("Difficulty", out var difficulty))
{
    Debug.Log($"Slot {slotNumber} difficulty: {difficulty}");
}

🔸 Get All Keys and Values

foreach (var kvp in SaveManager.API.GetSlotMetadata(slotNumber))
{
    Debug.Log($"Key: {kvp.Key}  →  Value: {kvp.Value}");
}

Runtime Modification

You can also modify or add metadata programmatically before saving:

SaveManager.API.SetSlotMetadata(slotNumber, "PlayerName", "Arawn");
SaveManager.API.SetSlotMetadata(slotNumber, "Playtime", "2h 12m");

These changes persist only when made before the next save. If you want values to be remembered across sessions, ensure they're stored and reapplied before calling SaveManager.Save(slotNumber).

Metadata in Conflict Resolution

When Auto Conflict Resolution is set to Custom, metadata can be used to evaluate save slot quality:

1. In Save Settings, enable:

Auto Resolve Conflicts → Custom

1. Add Metadata Rules such as:

Rule 1: Key: Version Operator: GreaterThan Value: 2.0.0

You can combine two rules with AND logic. Crystal Save uses
these to determine the preferred save in a conflict.

Storage Details

• Metadata is stored as part of each save slot's metadata JSON.

• It is included in both local and cloud saves (Unity Cloud Save / Supabase / MySQL), depending on your configuration.

Debugging

Use the Save Settings window to preview and edit metadata directly. It is shown in the "Custom Metadata" section.

To verify runtime values:

Debug.Log(JsonUtility.ToJson(SaveManager.API.GetSlotMetadata(slotNumber)));