Metadata Import (Beta)

Crystal Save can import save-slot metadata created by another title that also uses Crystal Save. This is a lightweight, cross-game bridge: you bring in slot name, scene, timestamp, and any custom metadata fields, then decide how the receiving game reacts (unlock rewards, branch dialogue, seed a profile, etc.).

This feature is Beta. APIs and workflows may change before final release.

Why use metadata import?

• Cross-game continuity: keep a persistent identity across separate releases.

• Marketing hooks: reward players for prior games or events.

• Easier spin-offs: prototype new genres while honoring progress.

• Event distribution: share promo metadata blobs via web, email, or physical cards.

Prerequisites

• The receiving project must include Crystal Save and have SaveManager initialized before import.

• If the payload is encrypted, the receiving project must use the same encryption setup (master secret + user context) as the source game.

What gets imported

Metadata import produces a SaveSlot instance with:

• SlotNumber

• SlotName

• LastSaved

• ScreenshotFileName

• LastActiveScene

• CustomMetadata (dictionary of string key/value pairs)

The importer does not load the actual save payload or screenshots. You decide how to apply the imported metadata in your game.

Supported formats

Crystal Save supports three input shapes:

1. Binary MemoryPack bytes for SaveSlot (optionally CSAV-encrypted).

2. Base64 of the MemoryPack bytes.

3. JSON with the minimal schema below.

JSON schema

JSON import supports a minimal DTO only. Custom metadata is not included in JSON.

{
  "SlotNumber": 1,
  "SlotName": "Slot 1",
  "ScreenshotFileName": "slot1.png",
  "LastActiveScene": "Town",
  "LastSavedTicks": 638683882000000000
}

Unity component: SaveMetadataImportSource

SaveMetadataImportSource is a simple MonoBehaviour wrapper around the importer.

Inspector fields

Field	Description
binarySource	TextAsset containing the metadata blob (MemoryPack bytes, optionally CSAV-encrypted, or JSON).
base64OrJson	String input for base64 payload or raw JSON text.
onImported	UnityEvent<SaveSlot> fired when metadata is parsed successfully.
onFailed	UnityEvent fired when parsing fails.

Triggering an import

1. Add Crystal Save → Import → Save Metadata Import Source to a GameObject.

2. Provide either binarySource or base64OrJson.

3. Wire up onImported / onFailed listeners.

4. Use Import Now (context menu) or call ImportNow() in code.

Example (component)

using Arawn.CrystalSave.Modules.Unity.Import;
using UnityEngine;

public class SaveImportExample : MonoBehaviour
{
    [SerializeField] private SaveMetadataImportSource importer;

    private void Start()
    {
        importer.onImported.AddListener(slot =>
        {
            Debug.Log($"Imported slot {slot.SlotNumber} from {slot.LastActiveScene}");
            // Apply rewards / branch logic here.
        });

        importer.onFailed.AddListener(() =>
        {
            Debug.LogWarning("Metadata import failed.");
        });

        importer.base64OrJson = LoadTextFromClipboard();
        importer.ImportNow();
    }
}

Manual usage (API)

using Arawn.CrystalSave.Runtime;

byte[] bytes = File.ReadAllBytes(pathToMetadata);
if (SaveMetadataImporter.TryParse(bytes, out var slot, SaveManager.Instance.EncryptionService))
{
    // Decide how to use the imported metadata.
}

Exporting metadata in the source game

MemoryPack (recommended)

Use MemoryPack if you want to preserve CustomMetadata.

using Arawn.CrystalSave.Runtime;
using System;

var slot = await SaveManager.Instance.GetSlotMetadataAsync(slotNumber);
slot.CustomMetadata["origin"] = "MyGame1";
slot.CustomMetadata["ending"] = "Neutral";

byte[] bytes = SaveDataSerializer.Instance.Serialize(slot);

// Optional encryption (CSAV header).
var enc = SaveManager.Instance.EncryptionService;
if (enc != null && enc.UseEncryption)
    bytes = enc.MaybeEncrypt(bytes);

string base64 = Convert.ToBase64String(bytes);

JSON (minimal)

Use JSON when you only need built-in fields.

var json = JsonUtility.ToJson(new
{
    SlotNumber = slot.SlotNumber,
    SlotName = slot.SlotName,
    ScreenshotFileName = slot.ScreenshotFileName,
    LastActiveScene = slot.LastActiveScene,
    LastSavedTicks = slot.LastSaved.ToUniversalTime().Ticks
});

Applying imported metadata

Importing metadata does not automatically create or replace a local save. Common patterns:

• Rewards / flags: read CustomMetadata to unlock content.

• Story branching: set a global flag based on an ending.

• UI continuity: persist the imported slot as a display-only entry.

To persist metadata into the local system, you can save it via the save system:

await SaveManager.Instance.SaveSystem.SaveSlotMetadataAsync(slot);

You may also want to map the incoming SlotNumber to a local slot instead of using it directly.

Encryption notes

• The importer detects encrypted payloads by the CSAV header.

• Decryption only works if the receiving game has the same master secret and same encryption context (user id) as the source game.

• If encryption is enabled and the key is missing, import fails.

What is doable

• Import metadata across Crystal Save titles to unlock quests, cosmetics, or endings.

• Use CustomMetadata for cross-game decisions, player flags, or achievements.

• Distribute event rewards as base64 strings or JSON payloads.

What is not doable

• Importing the full save state or world data.

• Importing screenshots or binary save files.

• Importing metadata from non–Crystal Save formats.

• Preserving CustomMetadata via JSON (use MemoryPack for that).

Games with similar features

Well-known examples of cross-game continuity include:

• Baldur's Gate → Baldur's Gate II (character import)

• The Witcher 2 → The Witcher 3 (choice import)

• Mass Effect 1 → 2 → 3 (save transfer)

• Dragon Age: Origins → Dragon Age II (world state carryover)

• Pillars of Eternity → Deadfire (save import)

Troubleshooting

• Import fails immediately: check that MEMORYPACK and ARAWN_REMEMBERME are defined.

• Encrypted payload fails: verify the same master secret and user context.

• JSON parses but custom fields are missing: JSON does not carry CustomMetadata.

• Nothing happens after import: ensure you handle onImported and apply the metadata.