Data Migrations

When you rename or restructure data across game versions, register migration steps and Vault upgrades old saves automatically on load.

Registering Steps

// Register before any Vault.Load — typically in Awake() or RuntimeInitializeOnLoad
VaultMigrations.Register(1, 2, ctx =>
{
    ctx.RenameKey("PlayerStats.health", "PlayerStats.hitPoints");
});

VaultMigrations.Register(2, 3, ctx =>
{
    ctx.DeleteKey("legacy_flag");
    ctx.RenamePrefix("OldClass.", "NewClass.");
});

// Only apply to specific drawers
VaultMigrations.Register(3, 4, ctx =>
{
    ctx.SetValue("newSetting", "\"default\"");
}, drawer => drawer.StartsWith("save_slot_"));

Migration Context API

Method	Description
`ctx.RenameKey(old, new)`	Rename a single key.
`ctx.RenamePrefix(old, new)`	Rename all keys starting with a prefix.
`ctx.DeleteKey(key)`	Remove a key.
`ctx.SetValue(key, rawJson)`	Write a raw JSON value.
`ctx.GetValue(key)`	Read a raw JSON string.
`ctx.FromVersion`	The version being migrated from.

Stamp Fresh Saves

// Stamp fresh saves to skip all migrations on new games
Vault.SetDataVersion(VaultMigrations.LatestVersion);

Never modify or delete a registered migration — only add new ones. Players may skip multiple versions in one session.