Skip to content

Step 11: Save Versions & Migration

Jump to bottom
BavGames edited this page Jul 11, 2026 · 2 revisions

Ship an update without breaking your players' old saves.

What does NOT need migration

Serialization is name-based, so most day-to-day changes are absorbed automatically:

  • Adding a SaveGame variable: old saves load fine, the new variable gets its default.
  • Removing a variable: the old value in the save is skipped by name.
  • Adding/removing components: unknown component records are skipped, new ones start fresh.

If that is all you changed, ship it - no migration, no version bump needed.

What DOES need migration

  • You renamed or moved a class (old records point at a class path that no longer exists).
  • You deleted an actor type and want its records cleaned out of old saves.
  • You need a wholesale data transform (split one actor into two, convert units, etc.).
  • You renamed a variable: the old value is lost by default. Either keep the old variable for one version and copy it over in On Loaded, or write a custom C++ step.

How it works

Project Settings holds your Game Version and a list of Migration Steps. Every save records the version it was written with. On load, if the save's version is older, the runner chains the steps in order until the data reaches the current version:

save v1 -> [Step v1->v2] -> [Step v2->v3] -> current (v3)

The chain is validated in the editor - a gap or overlap logs a warning immediately.

Walkthrough: renamed a Blueprint class

Say v1 saves contain BP_Barrel and you renamed it to BP_ExplosiveBarrel:

  1. Project Settings > Ultimate Save System > Versioning
  2. Add a Migration: Class Remap entry to Migration Steps
  3. Set From Version = 1, To Version = 2
  4. Set From Class = old path, To Class = BP_ExplosiveBarrel
  5. Bump Game Version to 2

Old saves now remap on load; new saves are written as v2.

Built-in steps

Step Use
Migration: Class Remap Actor class renamed or moved to another folder/module.
Migration: Drop Class Actor type removed from the game; purge its records.

Custom steps

Create a Blueprint (or C++ class) child of USS Migration Step, set From/To Version and override Apply - it receives the whole world save data and edits it in place. Blueprint steps can add/remove/filter actor records; blob-level property surgery is C++ territory.

Notes

  • Migration runs once per load, before the world is touched. A migrated save is written back at the new version the next time the player saves.
  • A save NEWER than the game refuses to load with a clean error (player downgraded the game).
  • Very large saves: a load that needs migration falls back to a whole-world load for that one time (streaming resumes on the next, already-migrated save).

Next: FAQ

Clone this wiki locally