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 avalue
.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:
In Save Settings, enable:
Auto Resolve Conflicts → Custom
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)));
Last updated