What is the write-then-rename pattern for save files?

Write-then-rename (also called atomic save) means writing the new save data to a temporary file first (e.g. saveslot1.tmp), then renaming it over the real save file (saveslot1.sav) in a single OS operation. Rename is atomic on all major platforms — it either completes fully or doesn't happen at all. This prevents partial writes from corrupting a save if the game crashes or is killed mid-write.

How should I handle a save file from a newer game version?

When loading a save, check the save_version field. If it's higher than the current game version, you have three options: refuse to load and show a clear error message, attempt to load while ignoring unknown fields (forward compatibility), or prompt the player to update the game. The worst option is to silently load and discard unknown fields without warning, because the player may not realize their progress was truncated. Always communicate clearly what happened to their data.

How do I test save compatibility across versions?

Maintain a set of reference save files for each major version in your test suite. When you release a new version, run an automated test that loads every reference save and verifies the game reaches a playable state without errors. For complex save formats, also test the reverse: create a save in the new version and verify the previous version either loads it gracefully or rejects it with a clear error rather than crashing.

Should I use JSON or a binary format for save files?

JSON is easier to debug (you can read the file in a text editor), easier to version with schema evolution tools, and more tolerant of adding new fields. Binary formats (Protocol Buffers, FlatBuffers, MessagePack) are smaller and faster to parse, which matters for large save files or mobile. For most indie games, JSON is the right default — save file size is rarely a bottleneck, and the debuggability advantage is significant when investigating corruption reports.

What save data should I include in crash reports?

Include the save schema version, the current scene or area name, the save slot number, and the timestamp of the last successful save. Do NOT include the full save file content in crash reports — it may contain player-created names, story choices, or other data they consider private, and save files can be large enough to bloat your crash report storage.

Debugging Save File Corruption Across Game Versions

Quick answer: Version your save schema from day one, write explicit migration functions for each version bump, use the write-then-rename pattern to prevent partial writes, back up saves before migrating, test every old save format against the current game build, and treat save corruption crashes as the highest-priority category of bug report you can receive.

Nothing destroys player trust faster than corrupted save data. Losing 40 hours of progress to a bad patch is the kind of experience players write about in reviews, forum posts, and Reddit threads for years. Save file corruption spans an enormous range of severity — from a missing inventory item to a completely unloadable save — and it disproportionately affects your most dedicated players, the ones who played long enough to hit a versioning edge case. Debugging it systematically requires understanding the three categories of corruption and building your save system to survive them.

Three Categories of Save File Corruption

Not all save corruption is the same. Categorizing the bug before debugging it saves significant time:

Data loss: valid data is missing from the save. The file loads but the player is missing items, quests, or progress they definitely had. Usually caused by a migration that discards fields it doesn’t recognize, a partial write that was interrupted before the full save completed, or a serialization bug that silently skips certain fields.
Invalid state: the save loads but the game reaches an inconsistent or unplayable state. Quest flags are set without the associated items. The player is in a scene that requires a key they don’t have. NPCs are in states that shouldn’t coexist. These are logic bugs in migration or in the save/load code itself.
Incompatible schema: the save file cannot be parsed at all. The game crashes or shows an error on load. Typically caused by a breaking schema change without a migration path, a binary format change, or a truncated write (the file is incomplete).

Category 3 produces crash reports. Categories 1 and 2 produce forum posts. Your crash reporter will surface category 3 automatically; categories 1 and 2 require player-submitted bug reports or in-game validation checks.

Save Schema Versioning

The single most important architectural decision for save compatibility is embedding a schema version number in every save file from day one. If you ship without it, adding one later requires inferring the old version from save contents — possible but painful.

// JSON save file format with explicit schema version
{
  "save_version": 3,
  "created_with_game_version": "1.4.2",
  "saved_at": "2026-03-04T22:14:07Z",
  "player": {
    "name": "Adventurer",
    "level": 17,
    "current_scene": "forest_village"
  },
  "inventory": [],
  "quests": []
}

The save_version field is the schema version — it changes when the save format changes. The created_with_game_version field is the game’s release version — useful for debugging but not for migration logic. Keep these separate; a single game release might not change the save schema at all.

Writing Migration Functions

Every schema version bump requires a migration function: a piece of code that takes a save at version N and produces a valid save at version N+1. Chain these migrations so you can always upgrade any old save to the current schema, regardless of how many versions behind it is.

func MigrateSave(data map[string]interface{}) (map[string]interface{}, error) {
    version, _ := data["save_version"].(float64)
    currentVersion := 3

    for int(version) < currentVersion {
        switch int(version) {
        case 1:
            data = migrateV1toV2(data)
        case 2:
            data = migrateV2toV3(data)
        default:
            return nil, fmt.Errorf("unknown save version: %d", int(version))
        }
        version++
        data["save_version"] = version
    }
    return data, nil
}

// V1 to V2: added stamina system, default all existing players to max stamina
func migrateV1toV2(data map[string]interface{}) map[string]interface{} {
    player := data["player"].(map[string]interface{})
    if _, ok := player["stamina"]; !ok {
        player["stamina"] = 100 // default for saves that predate stamina
    }
    return data
}

Write and test migrations before shipping the version that changes the schema. A migration that fails in production corrupts data it was meant to preserve.

The Write-Then-Rename Pattern for Atomic Saves

The most common cause of category-3 corruption is a partial write. The game is in the middle of writing a save file when the process is killed — by the OS, by the player Alt+F4-ing, by a crash in an unrelated subsystem, or by a laptop battery dying. The result is a truncated file that cannot be parsed.

The fix is the write-then-rename pattern:

// WRONG: direct write can produce a partial file if interrupted
WriteFile("saveslot1.sav", saveData)

// CORRECT: write to temp, then atomically rename
WriteFile("saveslot1.tmp", saveData) // write to temp path
os.Rename("saveslot1.tmp", "saveslot1.sav") // atomic on POSIX; use MoveFileEx on Windows

On POSIX systems (Linux, macOS), rename() is guaranteed atomic when source and destination are on the same filesystem. On Windows, use MoveFileEx with the MOVEFILE_REPLACE_EXISTING flag, which provides the same guarantee on NTFS. The temp file and the real save file must be on the same volume for this to work — don’t write the temp file to a different drive.

The pattern means that a crash during the write leaves the old save file intact and the temp file incomplete. On next launch, detect and delete orphaned .tmp files before loading saves.

Backing Up Saves Before Migration

Every time you load a save and determine it needs migration, back it up before running the migration. The backup is your rollback if the migration has a bug:

func LoadSave(path string) (*SaveData, error) {
    raw, err := os.ReadFile(path)
    if err != nil {
        return nil, err
    }

    data := map[string]interface{}{}
    json.Unmarshal(raw, &data)

    version := int(data["save_version"].(float64))
    if version < CurrentSaveVersion {
        // Back up before migrating
        backupPath := fmt.Sprintf("%s.v%d.bak", path, version)
        os.WriteFile(backupPath, raw, 0644)

        data, err = MigrateSave(data)
        if err != nil {
            return nil, fmt.Errorf("migration failed, backup at %s: %w", backupPath, err)
        }
    }
    // ... parse and return
}

Show the player where the backup is in any migration error message. They may not know how to use it, but having the path visible means a developer or a knowledgeable community member can help them recover.

Testing Save Compatibility with a Version Matrix

The most valuable test you can write for a save system is a compatibility matrix: a table of old save files crossed with new game versions, with a pass/fail column for each combination. Automate it.

Keep a testdata/saves/ directory in your repository with reference save files for every schema version you’ve shipped:

testdata/saves/
  savefile_v1_early_game.sav
  savefile_v1_endgame.sav
  savefile_v2_early_game.sav
  savefile_v2_mid_game_quest_active.sav
  savefile_v3_all_features.sav

In your test suite, run every reference save through the current load path and assert that loading completes without error and that key fields have expected values. When a migration test fails, it will tell you exactly which old save and which migration step broke.

“The player who lost 40 hours of progress to your migration bug is not coming back, even if you fix it in the next patch. Build save compatibility right the first time.”

Using Crash Reports to Identify Save-Corruption Crashes

Save-corruption crashes have a distinctive fingerprint in your crash reporter. They tend to occur immediately after launch (during the load-save flow), they’re often fatal (the game can’t recover), and they cluster around game version transitions — you see a spike in crashes shortly after a patch ships.

Configure your crash reporter to capture save-load context as custom fields:

Save schema version detected in the file header
Save slot number being loaded
Last successful save timestamp
Current scene at the time of save
Migration path taken (e.g. “v1 → v2 → v3”)

In Bugnet, add these as custom properties on the crash event before throwing the exception. When a cluster of crashes all show save_version: 2 and a migration path of "v2 → v3", you immediately know the v2-to-v3 migration has a bug and can reproduce it using any of the reference save files from your test suite.

Communicating Save Issues to Players

When save corruption affects players, communicate honestly and immediately. Don’t minimize the issue or bury it in patch notes. Players who discover corruption from your announcement are less angry than players who discover it mid-session.

A good player communication for a save issue includes:

What happened (which versions are affected, which save conditions trigger it).
What to do right now (don’t launch the game until patch X is available, or load from save slot Y instead of Z).
Whether a save recovery is possible (if you built the backup system above, the answer is often yes).
When a fix will ship and how to get it.

If you have a recovery guide, publish it on your support site and link to it from Steam announcements, Discord, and any review responses. Players who recover their saves with your help often become advocates. Players who lose their saves without any communication become your loudest critics.

Every save file is a player’s time. Treat migration bugs with the same urgency as a payment processing failure.