Save Data Versioning

Crystal Save provides three complementary approaches to handle save data evolution as your game grows:

Approach	Use Case	Complexity
Schema Evolution	Adding/removing fields in SaveData classes	Low
LegacyTypesInitializer	Renaming classes or changing namespaces	Medium
MigrationManager	Transforming data values between versions	High

---

Schema Evolution with MemoryPack

MemoryPack provides two serialization modes for handling schema changes. Choose the one that fits your needs:

Mode	Add Fields	Delete Fields	Requires [MemoryPackOrder]	Performance
Default (GenerateType.Object)	✅ Yes	❌ No	❌ No	Fastest
VersionTolerant (GenerateType.VersionTolerant)	✅ Yes	✅ Yes	✅ Yes	Slightly slower

Recommendation: Use GenerateType.VersionTolerant for SaveData classes in games under active development. The small performance cost is worth the flexibility to both add AND remove fields.

---

Default Mode (Add-Only)

The default [MemoryPackable] attribute supports adding new fields at the end, but you cannot delete fields.

Rules for Default Mode

• ✅ Can add new members (append only)

• ❌ Cannot delete members

• ✅ Can rename members

• ❌ Cannot change member order

• ❌ Cannot change member type

// Version 1.0
[MemoryPackable]
public partial class PlayerSaveData
{
    public int health { get; set; }
    public int mana { get; set; }
}

// Version 1.1 - Adding stamina at the END is OK
[MemoryPackable]
public partial class PlayerSaveData
{
    public int health { get; set; }
    public int mana { get; set; }
    public int stamina { get; set; }  // ✅ Added at end - OK
}

// ❌ WRONG - Cannot delete fields in default mode
[MemoryPackable]
public partial class PlayerSaveData
{
    // public int health { get; set; }  // ❌ Deleted - BREAKS OLD SAVES
    public int mana { get; set; }
    public int stamina { get; set; }
}

---

VersionTolerant Mode (Add & Delete)

Use GenerateType.VersionTolerant when you need the flexibility to both add and delete fields.

The Problem with Default Mode

If you delete a field in default mode, old saves will break because MemoryPack uses positional serialization:

// Default mode - if you delete a field, positions shift and old saves break

The Solution

Use GenerateType.VersionTolerant with [MemoryPackOrder] attributes:

[MemoryPackable(GenerateType.VersionTolerant)]
public partial class ItemSaveData
{
    [MemoryPackOrder(0)] public string myID { get; set; }
    [MemoryPackOrder(1)] public string myName { get; set; }
    [MemoryPackOrder(2)] public int level { get; set; }
    
    // ========== NEW FIELDS GO BELOW THIS LINE ==========
    // Always add new fields at the end with the next available order number.
    [MemoryPackOrder(3)] public int mySlotNumber { get; set; }
}

Rules for VersionTolerant Mode

• ✅ Can add members (with new order numbers)

• ✅ Can delete members (but cannot reuse their order numbers)

• ✅ Can rename members

• ❌ Cannot change member order

• ❌ Cannot change member type

• ⚠️ All members must have explicit [MemoryPackOrder]

How It Works

• MemoryPack serializes by order number instead of position

• Old saves missing new fields → fields get default values

• New saves with deleted fields → missing orders are skipped during deserialization

Example: Adding and Deleting Fields

// Version 1.0
[MemoryPackable(GenerateType.VersionTolerant)]
public partial class PlayerSaveData
{
    [MemoryPackOrder(0)] public int health { get; set; }
    [MemoryPackOrder(1)] public int mana { get; set; }
    [MemoryPackOrder(2)] public int oldUnusedField { get; set; }
}

// Version 1.1 - Delete oldUnusedField, add stamina
[MemoryPackable(GenerateType.VersionTolerant)]
public partial class PlayerSaveData
{
    [MemoryPackOrder(0)] public int health { get; set; }
    [MemoryPackOrder(1)] public int mana { get; set; }
    // [MemoryPackOrder(2)] DELETED - do NOT reuse order 2
    
    // NEW in v1.1 - use next available order (3)
    [MemoryPackOrder(3)] public int stamina { get; set; }
}

When loading a v1.0 save in v1.1:

• health (order 0) and mana (order 1) load normally

• oldUnusedField (order 2) is ignored (field no longer exists)

• stamina (order 3) gets its default value (0)

Critical Rules

Critical Rules for VersionTolerant:

1. Never change existing order numbers

2. Never reuse a deleted order number

3. Always add new fields with the next available order number

4. All members must have [MemoryPackOrder] - no exceptions

---

LegacyTypesInitializer

Use this when you need to rename a class or move it to a different namespace.

The Problem

Save files store the full type name (including namespace). If you rename a class:

// Before: MyGame.PlayerData
// After:  MyGame.Save.PlayerSaveData

Old saves reference MyGame.PlayerData which no longer exists → deserialization fails.

The Solution

Register the legacy type mapping in LegacyTypesInitializer.cs:

public static class LegacyTypesInitializer
{
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    private static void InitializeSerializer()
    {
        RegisterLegacyTypes();
    }

    private static void RegisterLegacyTypes()
    {
        var serializer = SaveDataSerializer.Instance;

        // Map old type name to new type
        serializer.RegisterLegacyTypes(
            typeof(PlayerSaveData),           // Current type
            typeof(LegacyPlayerData)          // Legacy type(s)
        );
        
        // You can register multiple legacy versions
        serializer.RegisterLegacyTypes(
            typeof(ItemSaveData),
            typeof(LegacyItemDataV1),
            typeof(LegacyItemDataV2)
        );
    }
}

Creating a Legacy Type Stub

You need to keep a minimal stub of the old type for the registry to reference:

// Keep this for backward compatibility
namespace MyGame
{
    [MemoryPackable]
    public partial class LegacyPlayerData { }
}

The legacy type stub doesn't need any properties—it's only used for type name resolution.

When to Use

Scenario	Use LegacyTypesInitializer?
Renamed class (PlayerData → PlayerSaveData)	✅ Yes
Moved namespace (MyGame → MyGame.Save)	✅ Yes
Added/removed fields	❌ No (use VersionTolerant)
Changed field types	❌ No (use MigrationManager)

---

MigrationManager

Use this when you need to transform data values between versions, such as converting field types or restructuring data.

Overview

The MigrationManager is a ScriptableObject that holds a list of migration steps, each targeting a specific version.

Setup

1. Create the MigrationManager asset:

   • Right-click in Project → Create → Crystal Save → Settings → Create Migration Manager

   • Place it in a Resources folder

2. Create MigrationAction scripts for your data transformations

3. Configure migration steps in the MigrationManager inspector

Creating a MigrationAction

using UnityEngine;
using Arawn.CrystalSave.Runtime;

[CreateAssetMenu(fileName = "MigrateHealthToFloat", 
                 menuName = "Crystal Save/Migrations/Migrate Health To Float")]
public class MigrateHealthToFloat : MigrationAction
{
    public override void ApplyMigration(SaveData data)
    {
        // Access and transform your save data here
        foreach (var scene in data.scenes)
        {
            foreach (var go in scene.savedGameObjects)
            {
                foreach (var component in go.savedComponents)
                {
                    if (component.typeId == "PlayerSaveData")
                    {
                        // Transform the data as needed
                        // This runs before deserialization
                    }
                }
            }
        }
        
        Debug.Log("Migration: Converted health from int to float");
    }
}

Configuring Migration Steps

In the MigrationManager inspector:

Field	Description
Target Version	The version this migration upgrades TO
Description	Human-readable description of the migration
Migration Actions	List of MigrationAction assets to execute

How It Works

1. Save file is loaded with version 1.0.0

2. Current game version is 1.2.0

3. MigrationManager finds all steps between 1.0.0 and 1.2.0

4. Each step's MigrationActions are executed in order

5. Save data version is updated after each step

6. Migrated data is then deserialized normally

Version Configuration

Set your current version in SaveSettings:

1. Select your SaveSettings asset

2. Set the Version field (Major.Minor.Patch)

The VersionManager compares save file versions against this setting.

---

Choosing the Right Approach

┌─────────────────────────────────────────────────────────────┐
│                    What changed?                             │
└─────────────────────────────────────────────────────────────┘
                           │
       ┌───────────────────┼───────────────────┐
       ▼                   ▼                   ▼
┌─────────────┐     ┌───────────┐      ┌─────────────────┐
│ Added fields│     │ Renamed   │      │ Changed data    │
│ (append)    │     │ class     │      │ format/values   │
└─────────────┘     └───────────┘      └─────────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐     ┌───────────┐      ┌─────────────────┐
│ Default or  │     │ Legacy    │      │ Migration       │
│ Version-    │     │ Types     │      │ Manager         │
│ Tolerant    │     │ Initial-  │      │                 │
└─────────────┘     │ izer      │      │                 │
                    └───────────┘      └─────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│              Need to DELETE fields too?                      │
└─────────────────────────────────────────────────────────────┘
       │                           │
       ▼                           ▼
    ┌─────┐                    ┌─────┐
    │ Yes │                    │ No  │
    └─────┘                    └─────┘
       │                           │
       ▼                           ▼
┌─────────────────┐        ┌─────────────────┐
│ VersionTolerant │        │ Default mode    │
│ + MemoryPack    │        │ (no attributes) │
│ Order           │        │                 │
└─────────────────┘        └─────────────────┘

Combined Example

A major refactor might require all three:

// 1. VersionTolerant for new fields
[MemoryPackable(GenerateType.VersionTolerant)]
public partial class CharacterSaveData  // Renamed from PlayerSaveData
{
    [MemoryPackOrder(0)] public float health { get; set; }  // Changed from int
    [MemoryPackOrder(1)] public float mana { get; set; }
    [MemoryPackOrder(2)] public float stamina { get; set; }  // New field
}

// 2. LegacyTypesInitializer for the rename
serializer.RegisterLegacyTypes(
    typeof(CharacterSaveData),
    typeof(LegacyPlayerSaveData)
);

// 3. MigrationAction for the int→float conversion
public class MigrateHealthToFloat : MigrationAction
{
    public override void ApplyMigration(SaveData data)
    {
        // Convert int health values to float
    }
}

---

Best Practices

Recommendations:

1. Use VersionTolerant on SaveData classes if you anticipate needing to delete fields later

2. Use Default mode if you only ever add fields (simpler, slightly faster)

3. Add order numbers sequentially, never skip numbers

4. Document each order number's purpose in comments

5. Test migrations with actual save files before release

6. Keep legacy type stubs even after several versions—some players may have very old saves

Avoid:

• Changing existing [MemoryPackOrder] numbers

• Reusing order numbers from deleted fields

• Deleting fields when using default mode (use VersionTolerant instead)

• Removing legacy type registrations too early

• Deploying without testing migration paths

---

Quick Reference

I want to...	Use
Add a new field to my SaveData	Default mode (append) or VersionTolerant
Remove/delete an old field	VersionTolerant mode only
Rename a SaveData class	LegacyTypesInitializer
Move a class to a different namespace	LegacyTypesInitializer
Change a field's type (int → float)	MigrationManager
Transform data values	MigrationManager