# 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:

```csharp
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

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

#### 🔸 Get All Keys and Values

```csharp
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:

```csharp
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:

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