Migrations & Versioning

Why do you need Migrations?

When you update your game (v1.0.0 → v1.1.0, for example ), save file structure may change:

• Renamed fields

• New features

• Removed old data

Migrations automatically convert old saves to the new format.

For example, imagine that in Version 1.0.0 your player’s health was stored under the key "playerHealth", but in the next version it was renamed to "playerHealthValue". Without a migration, OmniSave would still attempt to load "playerHealth". Since that key no longer exists, the health value wouldn’t load at all.

Migration solves this by informing OmniSave that player health is no longer stored as "playerHealth", and that it should instead look for "playerHealthValue". This ensures that no data is lost between versions.

Creating a Migrator ( No-Code )

1

Open OmniSave Hub

Press Alt+O to open the OmniSave Hub, then Navigate to "Migration"

2

Select Migration Asset

3

Add Version

1. Click on "Add Version", a New Version with 0 Operations will appear.

2. Set From to the Previous version ( Migrated From )

3. Set To to the Next Version ( Migrated To ) ( 1.0.0 to 1.1.0 = From to To )

4. (Optional) Add a Description to identify key changes in the Migrations

4

Add Required Operations

There are 3 type of Operations:

• Rename: A Field was renamed ( playerHealth > playerHealthValue )

• Addition: A Field was added

• Removal: A Field was removed

When all Operations are properly configured, you´ll see "Ready to Generate" at the bottom right corner.

If any operation info is missing, or something is miss-configured, it will trigger a Validation Error. Ensure all Validation errors are solved before proceeding with the next Step.

5

Generate Code

This process avoids coding for easier set-up. However, we are forced to generate some code for our operations to be effective. Luckily, this process is completely automated: Press on "Generate Code". Notice that Code Generation settings can be viewed/tweaked in "Settings"

Chain Migrations

Chain migrations automatically:

v1.0 > v1.1 > v1.2 > v2.0

OmniSave runs them in order.

---