Başar BallıözProduct Engineer
← All posts

Save file versioning: loading every save from v1 to v18

A player who installs an update should find their pet exactly where they left it, whether their save is from last week or from the very first version. Tibblo's save format is on its eighteenth version. Here is how a save from any of them still loads.

By Başar Ballıöz · · 4 min read

Why saves deserve this much care

In a web app the server holds the truth; a bad deploy can be rolled back. In an offline game, the truth is a file on the player's phone. If an update cannot read it, there is no rollback: the pet a child has looked after for months is simply gone. So the save file gets the same care as a database schema.

Separate files for separate jobs

Tibblo writes three JSON files, each with its own owner:

  • The pet save: pets, home, coins, inventory, progress. This is what changes between versions.
  • The account file: real-money purchases and owned products. Starting the game over never touches it, so a player never loses something they paid for.
  • Settings: sound, text size, language. Also kept apart, so starting over does not reset them.

Every save carries a version number. That single field is what makes everything below possible.

Writing: never leave a half-written file

A phone can lose power or kill the app at any moment, including in the middle of a save. Writes go through one function that guarantees there is always at least one complete, valid file:

  1. Write the new data to save.tmp, close it, then read it back and parse it. If that fails, stop; the old save is untouched.
  2. Rotate: the current save becomes save.bak, and the temporary file becomes the save.
  3. If the last rename fails, put the backup back.

Loading: recover, and keep the evidence

Loading tries the main file first, then the backup. If the main file exists but cannot be read, it is copied to save.corrupt-<time>.json before anything can overwrite it, so a broken save can still be looked at later.

The loader reports one of four outcomes: a new game, a normal load, restored from backup, or reset because both were unreadable. The last two show the player a short message instead of failing silently.

Migrations: two eras

For the first eighteen versions, the loader read old saves through version gates: if version >= 7, read health and experience; otherwise give sensible defaults. That works, but every new version adds another branch to the loader, and the branches pile up.

From version 18 on, new versions go through step functions instead. A table maps each version to a function that turns a save of version N into version N+1:

  • Each step gets a deep copy and returns the new shape. It never edits the original and never fails.
  • An old save is raised one step at a time until it reaches the current version, then read by the normal loader.
  • If a step is missing, the save comes back unchanged and is rejected by its version, rather than loading half-migrated.

Adding a version is now a three-step routine: raise the version number, write that one step function, and freeze a real save of the previous version as a test fixture.

The rules each migration follows

A few rules have held since version one:

  • Missing fields get defaults, and nothing is ever demoted. A new field never takes something away from an old save.
  • New features start from the player's real history. When species arrived, every older save loaded as an adopted pet with its name, needs and coins untouched, so existing players never saw the adoption screen. When health and experience arrived, older pets got full health (less if they were sick at the time) and experience based on the care they had already given.
  • When one pet became several, the old single pet became the first slot.
  • Only valid data gets in. Unknown item ids are dropped, and an outfit can only be worn if the player owns it.

A frozen save for every version

This is the part I would copy into any project with saved data. For each of the eighteen versions there is a real save file, frozen in the test folder. One test suite loads every one of them and checks three things:

  1. It loads.
  2. It keeps what that version knew: the name, coins, items and progress that existed at the time.
  3. It survives a round trip: save it again, load it again, and nothing changes.

The same suite fails if the version number goes up without a fixture or without a migration step. A version bump simply cannot ship on its own.

Tests also never touch real data: every test run writes into its own sandbox folder, so running the suite on a development phone or computer can never overwrite real progress.

What I would tell anyone starting a game

  1. Put a version number in the very first save you write.
  2. Write atomically, keep one backup, and keep corrupt files instead of deleting them.
  3. Keep purchases in their own file, away from anything a reset can touch.
  4. Prefer small step-by-step migrations over a loader full of version checks.
  5. Freeze a real save for every version and test it on every change.

None of this is visible to players, which is exactly the point. For more on how the game is built, see Godot 4 for web developers.

More posts

Godot on iOS: from an uneven 60 fps to 120 Hz with MetalA Godot 4 game stuck near 60 fps on an iPhone 14 Pro with a main thread busy only 4 ms a frame. How a phone bench and Instruments found the cause, and how switching iOS to Metal gave 119 fps. Quest pacing: measuring where a 150-level game goes flatHow I measured the story pacing of Tibblo's 763-day road from level 1 to 150, found where it went flat after level 40, and fixed it with three-step arcs, a daily limit and a 'Last time…' card.