save-schema-migration

Save schema migration

A shipped game inherits every save format it ever published. The first time you add a field to SaveData and re-export, every existing player loads a save with the old shape and gets either: silent data loss (missing field defaults to zero), a hard crash (null.method() on a missing sub-Resource), or a corrupt run.

This skill is the contract for evolving save data without breaking existing players. Pair it with setup-save-system, which already includes a version field and a _migrate() stub — this skill fills in the migration registry and the test that proves it works.

Rules

1. Every save Resource has a schema_version: int at the top level. Bump it whenever you add, remove, rename, or change the meaning of a field.
2. Migrations are sequential. A v1 save migrates to v2, then v2 to v3 — never v1 → v3 directly. This keeps each migration small and independently testable.
3. Migrations are pure functions of the loaded payload. They do not read the current scene, the autoloads, or anything else — same input → same output.
4. Migrations never delete data without an explicit decision. Renaming a field? Move the value. Removing? Either drop silently with a comment or stash under _legacy.<field_name> if there is any chance you'll want it back.
5. Every released version has a fixture save in test/fixtures/save/v<N>.tres. CI loads each fixture and asserts the migrated result matches the current schema's assert_valid() invariants.
6. Unknown future version = refuse to load. A v5 save loaded by a v3 build means the player rolled back. Do not guess — show "save from a newer version, please update".

File shape

resources/save_data.gd (extended from setup-save-system)

class_name SaveData
extends Resource
## Top-level save container. One file per slot.
##
## When `SCHEMA_VERSION` bumps, register the matching migration in
## SaveMigrations._migrations and ship a fixture under test/fixtures/save/.

const SCHEMA_VERSION := 3   # bump on every breaking change

@export var schema_version: int = SCHEMA_VERSION
@export var timestamp: int = 0
@export var play_time_seconds: float = 0.0
@export var current_scene: String = ""
@export var entries: Dictionary[NodePath, Variant] = {}

# v3 added: difficulty preset (was inferred from world flags before)
@export var difficulty: StringName = &"normal"

func assert_valid() -> void:
    assert(schema_version == SCHEMA_VERSION, "save not migrated to current schema")
    assert(timestamp > 0, "missing timestamp")
    assert(difficulty in [&"easy", &"normal", &"hard"], "invalid difficulty: %s" % difficulty)