Metadata Import (Beta)

Crystal Save now lets you import save-slot metadata generated by another game that also uses Crystal Save. By transferring the slot’s name, scene, timestamp and any custom fields, you can continue a story across different titles or genres—similar to how The Witcher 3 can read saves from The Witcher 2. This feature is currently Beta; APIs and workflows may change before it is finalized.

Limitations

• Metadata only – The importer loads slot metadata, not the full save payload. You must decide how the receiving game reacts (e.g., unlocking a quest or populating an avatar).

• Encryption – Encrypted metadata can only be parsed if the receiving project has the matching encryption key configured in its SaveManager. Without the key, the import fails.

• Format parity – Both games must serialize SaveSlot metadata in a compatible way (MemoryPack or the JSON schema Crystal Save expects). Non‑Crystal Save formats are not supported.

Unity component: SaveMetadataImportSource

SaveMetadataImportSource is a MonoBehaviour that wraps the importer in a reusable component.

Inspector fields

Field	Description
binarySource	TextAsset containing the metadata blob (MemoryPack bytes, optionally CSAV‑encrypted, or raw JSON).
base64OrJson	Text area for a base64 string or plain JSON. Handy for copy/paste flows or cloud responses.
onImported	UnityEvent<SaveSlot> fired when metadata is parsed successfully.
onFailed	UnityEvent fired when parsing fails for all inputs.

Triggering an import

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

2. Provide either binarySource or base64OrJson.

3. Wire up onImported or onFailed listeners.

4. Call Import Now from the context menu or invoke ImportNow() in code.

Example

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}");
            // React to imported metadata here…
        });

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

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

If the metadata is encrypted, ensure the receiving project’s SaveManager is initialized with the same encryption settings before calling ImportNow().

Manual usage

For custom workflows, use SaveMetadataImporter directly:

byte[] bytes = File.ReadAllBytes(pathToMetadata);
if (SaveMetadataImporter.TryParse(bytes, out var slot, SaveManager.Instance.EncryptionService))
{
    // Handle imported slot
}

Suggested workflows

• Cross‑genre narratives – Import a player’s final state from a story‑driven RPG into a strategy spin‑off to unlock unique scenarios or bonuses.

• Event rewards – Distribute a small JSON payload during a limited‑time event; players paste it into your game to receive the reward associated with that slot.

Beta notice

This importer is still in Beta. Report issues and expect minor breaking changes as feedback is integrated.