Save-game schema migration and recoverable writes

A save is a long-lived interface

A save file can outlive the code that produced it. Renaming a field, changing units, or splitting an inventory structure changes that interface even when parsing still succeeds. Design persistence around a documented data model, a schema version, and a recovery path rather than serializing arbitrary live objects.

Format is not compatibility

Godot's saving guide illustrates explicit game-state serialization and the limitations of JSON types. [1] Protocol Buffers documents compatibility rules, including preserving field-number identity and reserving removed numbers. [2] A serialization format helps represent data; game-specific meaning, defaults, migrations, and supported version ranges remain design responsibilities.

Worked example

An illustrative version 1 save contains coins: 125. Version 2 replaces that field with wallet: {gold: 125}. Version 3 adds difficulty, using normal only when migrating an older save that lacks the field.

Implement 1 → 2 and 2 → 3 transformations over decoded data. After the first step, verify that currency remains 125; after the second, verify the default and preserve all unrelated progress. Advance the recorded version only after each transformation succeeds. A version 3 save must not receive an extra grant merely because it is loaded again.

If a version 5 save is newer than this loader supports, preserve it and report incompatibility. Guessing its meaning and overwriting it with version 3 would turn a temporary compatibility problem into data loss.

Migration and restore workflow

Keep immutable fixtures for every supported historical schema, including missing optional fields and boundary values. Validate data types, ranges, stable object identifiers, required assets, and cross-references before replacing the live world. Construct the restored state in isolation where practical, then activate it after validation.

Separate schema migration from content remapping: an item removed from the game needs a documented replacement or compensation policy, not merely a renamed field. Make errors actionable and retain the previous usable save until the replacement is verified.

Commit and failure boundaries

For SQLite-backed saves, commit data and schema version in one transaction; its atomic-commit documentation explains both the mechanism and storage assumptions. [3] For file saves, stage a complete replacement and use the platform's supported atomic replacement and durability operations. Rename alone is not a universal power-loss guarantee.

Test interrupted writes, full storage, corrupt input, and migration failure. A checksum can detect accidental corruption but does not establish valid game semantics. Define backup selection and recovery explicitly, and never report success before the chosen persistence operation has completed successfully.

Sources

[1] Saving games — Godot Engine documentation.

[2] Proto3 language guide — Protocol Buffers documentation.

[3] Atomic commit — SQLite developers.