game-save-and-persistence

Game Save and Persistence

Overview

A save file outlives the code that wrote it. Players carry saves across updates, crashes happen mid-write, and a lost 40-hour save is the bug players remember. Every save has a version, every older version has a tested migration, and a write never destroys the last good save.

Core principle: Versioned, migrated, written atomically, checked on load — and never deserialized with a format that can execute code.

The format

{
  "version": 3,
  "savedAtUtc": "2026-10-08T12:00:00Z",
  "player": { "levelId": "forest_02", "position": [12.5, 0, -4.0], "hp": 72 },
  "inventory": [{ "itemId": "sword_iron", "count": 1 }],
  "flags": ["met_blacksmith", "boss_forest_defeated"]
}

• A plain DTO, separate from engine objects: no GameObject, Node or AActor references, no array indices into data tables — stable IDs only (data-driven-gameplay-design).
• Settings (volume, bindings, accessibility) in a separate file from progress, so resetting one never touches the other.
• JSON is readable and diff-able; a compact binary format (MessagePack, protobuf, Godot's store_var without objects) is fine when size matters — the version field stays first.

Migrations

type Migration = (save: any) => any;
const migrations: Record<number, Migration> = {
  1: (s) => ({ ...s, version: 2, inventory: s.items.map((id: string) => ({ itemId: id, count: 1 })) }),
  2: (s) => ({ ...s, version: 3, flags: Object.keys(s.questState ?? {}).filter((k) => s.questState[k] === "done") }),
};

export function upgrade(raw: any): SaveV3 {
  if (typeof raw?.version !== "number") throw new SaveError("unversioned");
  if (raw.version > CURRENT) throw new SaveError("from a newer game version");  // refuse, never guess
  let s = raw;
  while (s.version < CURRENT) s = migrations[s.version](s);
  return SaveV3Schema.parse(s);
}

• One migration per version step, never edited after release; each tested with a fixture file captured from that version (tests/fixtures/saves/v1.json, v2.json).
• A save from a newer version is refused with a clear message, not loaded and overwritten.
• Changing a saved field's meaning without bumping the version is the bug this exists to prevent.