Version Number vs Schema Hash for Love2D Save Compatibility

Answer

Embed a plain integer formatVersion as the authoritative compatibility gate. Use a schema hash only as an optional same‑version drift check, and compute it on lightweight metadata (never the full payload) if you enable it.

Likely explanation

A version number gives a fast, deterministic refusal or migration path for breaking changes. A schema hash can catch field‑level changes inside the same version, but its value depends on canonical serialization and adds hashing overhead; it is not reliable as the sole load gate.

Confirmed facts

• Love2D’s love.filesystem stores opaque bytes; the save table must carry its own compatibility marker.
• Increment formatVersion only for breaking save‑format changes (field removal, rename, type change).
• On load, read the marker, compare it to the current version, and either refuse, run a migration function, or accept the save.
• If you enable schema hashing, hash a canonical schema descriptor (e.g., sorted list of required field names and types) rather than raw serialized bytes, and do this only on metadata or in dev builds.

Steps for this case

1. Add a marker to your save table: { formatVersion = CURRENT_VERSION, schemaHash = OPTIONAL_HASH, data = ... }.
2. When saving, set formatVersion to the current integer; compute schemaHash only if you want drift detection and store it.
3. When loading:
   1. Read the table via love.filesystem.read and deserialize.
   2. If formatVersion is missing or greater than CURRENT_VERSION, refuse or prompt for upgrade.
   3. If formatVersion is less than CURRENT_VERSION, run the migration function for that version.
   4. If you stored a schemaHash, compute the hash of the canonical schema descriptor and compare; on mismatch, log a warning or trigger a same‑version migration (only if you need drift detection).
4. Keep migrations defensive: treat missing fields as absent and supply defaults rather than indexing nil.

Missing diagnostic

Do you need to detect field‑level drift within the same version (e.g., for dev builds or early‑access testing)? If yes, keep the optional schema hash; if no, you can omit it entirely to save startup time.