Save Games & Serialization

01A save is mutable state, not assets

Serialization is one toolbox, but a save and a cooked asset are opposite jobs for it. A cooked asset is authored once, immutable at runtime, shared by every player, and regenerable from the source art. A save is written at runtime, unique to one player, and has no source: lose it and it's gone. Unreal makes the split explicit with a base class for exactly this, USaveGame, "a base class for a save game object that can be used to save state about the game"^[1].

02The object-graph problem

Game objects point at each other: an AI's target, a projectile's owner, a node's parent. Those references are pointers in memory, and a pointer is just the address where an object happens to live this run, "pointer values usually change from run to run"^[2]. Write a raw pointer to disk and on the next load it points at garbage. The fix is to serialize a reference as something position-independent and re-resolve it on load.

Three ways to encode a reference, from worst to best for a save^[2]:

• Raw pointer. Unusable directly; needs a fix-up table converting offsets to addresses after load. The thing this section exists to avoid.
• Array index. Safe to save, but breaks when items move or are removed, and forces one big homogeneous array.
• Generational handle. A small value, typically {index, generation}, that uniquely names an object and stays valid across a save/load. The recommended encoding.

Save the graph, quit, reload. With ids, the references re-resolve through the handle table and reconnect. Flip on "store raw pointers" and the saved addresses point at nothing after reload, the dangling-reference crash this whole section exists to prevent:

struct Handle { uint32_t index; uint32_t generation; };   // position-independent reference

// SAVE: write the {index, generation}, never the raw pointer.
void writeRef(Writer& out, Handle h) { out.u32(h.index); out.u32(h.generation); }

// LOAD is TWO passes:
//   pass 1: instantiate every saved object, recording id -> new slot (so all targets exist)
//   pass 2: re-resolve each saved handle through the table (the fix-up)
Entity* resolveRef(const HandleTable& table, Handle h) {
    const Slot& slot = table.slots[h.index];
    if (slot.generation != h.generation) return nullptr;   // stale: slot reused -> invalid, NOT the wrong object
    return slot.entity;                                  // the live pointer, valid this run
}

#[derive(Clone, Copy, Serialize, Deserialize)]
struct Handle { index: u32, generation: u32 }   // position-independent reference (serde derives the bytes)

// LOAD pass 2: re-resolve a saved handle to a live entity through the table.
fn resolve_ref(table: &HandleTable, h: Handle) -> Option<&Entity> {
    let slot = table.slots.get(h.index as usize)?;
    if slot.generation != h.generation { return None; }   // stale handle -> None, never the wrong entity
    slot.entity.as_ref()                              // pass 1 already re-instantiated every object
}

Serialization libraries enforce this rule for you. cereal refuses raw pointers outright and dedups shared references, data behind a shared_ptr "is serialized only once, even if several shared_ptr... that point to the same data are serialized," and is re-linked on load^[4]. Unity's inline serializer goes the other way as a cautionary tale: it "does not support null or shared references, so any cycle in data can lead to unexpected results," which is exactly why ISerializationCallbackReceiver exists, to flatten a graph into parallel arrays of nodes plus parent indices by hand, the id-reference pattern applied manually^[5].

03Save vs recompute

Persist authoritative state; recompute derived state on load. Saving derived state bloats the file and creates a second source of truth that can drift out of sync with the authoritative fields it was computed from.

• Persist: positions, health, inventory, quest flags, the RNG seed and stream position, and the world-mutation deltas from §4.
• Recompute: the navmesh and spatial acceleration structures, render and physics proxies, cached paths, animation runtime state, and derived UI. They rebuild deterministically from the authoritative data.

04Full vs delta saves

The cooked level is already on disk, read-only and shared by every player. Re-storing all of it in each save is wasteful, so most level-based games persist only a delta over that baseline: the objects whose state changed from their authored default. Unreal's serializer has this built in, in its default mode "a property's value is not altered from its default... the property will not be serialized"^[7].

Bethesda's Creation Engine is the canonical shipped example. A save stores change forms, the deltas over the baked plugin data, and references are stable Form IDs (three bytes in the save, with index FF reserved for runtime-spawned objects unique to that save)^[8]. That same design is also why mods break saves: a reference baked against one load order resolves to the wrong plugin when the order changes, a real-world pointer-fix-up failure.

05Versioning & migration

This is the section that actually breaks in production. You will ship, then patch the save format, and players still have saves written by the old code. They must keep loading. The mechanism is a version tag plus migration: Casey Muratori frames it as "a version number in your struct and a function for migrating from an old version to a new version," explicitly like database migrations^[9].

Pick a save version and load it into the current (v3) game. Older saves migrate up: a missing field gets a default, a renamed field is mapped. New code reads every old save:

constexpr uint32_t SAVE_VERSION = 3;       // bump on every format change

PlayerState loadPlayer(Reader& in) {
    uint32_t version = in.u32();           // the version tag is the FIRST thing in the blob
    PlayerState p;
    p.health  = in.f32();                  // every version (stored as "hp" in v1/v2; same bytes)
    p.stamina = version >= 2 ? in.f32() : 100.0f;       // added in v2 -> default for older saves
    p.perks   = version >= 3 ? in.readPerks() : Perks{}; // added in v3 -> default for older saves
    return p;                              // new code reads ANY old save by defaulting missing fields
}

const SAVE_VERSION: u32 = 3;               // bump on every format change

fn load_player(r: &mut Reader) -> PlayerState {
    let version = r.u32();                 // version tag first
    PlayerState {
        health:  r.f32(),                   // every version
        stamina: if version >= 2 { r.f32() } else { 100.0 },        // added in v2
        perks:   if version >= 3 { r.read_perks() } else { Vec::new() }, // added in v3
    }
}

06Atomic writes

A save is overwritten in place at your peril. Crash, power-loss, or a killed process partway through the write and the file is half old data, half new, and unreadable, the worst outcome, because the previous good save is gone too. The fix is an atomic write: write a temp file in the same directory, force it to disk, then rename it over the real save.

Pick a strategy and crash mid-write. In-place corrupts the only save; temp-then-rename leaves the previous save fully intact, because the real file is never touched until the rename:

// Write a temp file in the SAME directory, flush to the platter, then atomically rename.
bool saveAtomic(const Path& dst, const Bytes& data) {
    Path tmp = dst.withSuffix(".tmp");     // same dir -> rename is atomic on the filesystem
    File f = openWrite(tmp);
    if (!f.writeAll(data)) return false;
    f.fsync();                              // force bytes to disk BEFORE the rename; flush() only hits the OS buffer
    f.close();
    return renameReplace(tmp, dst);          // POSIX rename(2) / Windows ReplaceFileW: the atomic swap
}

use std::io::Write;
// tempfile::persist() is the temp-then-rename; sync_all() is the fsync.
fn save_atomic(dst: &Path, data: &[u8]) -> std::io::Result<()> {
    let dir = dst.parent().unwrap();
    let mut tmp = tempfile::NamedTempFile::new_in(dir)?;  // same filesystem as dst
    tmp.write_all(data)?;
    tmp.as_file().sync_all()?;                        // fsync BEFORE the rename
    tmp.persist(dst)?;                                // atomic rename over the real save
    Ok(())
}

07Saving live

An autosave fires mid-play. The save must be a consistent snapshot taken at a tick boundary, not mid-update with half the systems stepped. Capture the state at the end of a frame, then write it off-thread so the I/O does not hitch the game. The hard case is streaming: some cells are streamed out, their live objects do not exist in memory, so the snapshot merges the live objects' current state with the last-known persisted delta for the streamed-out regions.

Wrong answers, and why: addresses cannot be pinned across runs and a bare index is fragile, so references are saved as generational handles and fixed up on load; an appended field needs a version branch or a tagged format, and refusing old saves discards progress; and a checksum detects torn-write corruption but only an atomic temp-rename prevents it.

08Pitfalls

09What's next

That completes the persistence pair with Open-World Streaming: the world stays resident around the player, and the changes they make to it survive a crash, a quit, and a patch that changed the format. The full Build a Game Engine path, foundations through the 3D capstone, is on the series hub.

1. WizardCell. "Unreal Engine Persistent Data Compendium." wizardcell.com. USaveGame as the base class for mutable game state, and the guidance not to persist rebuildable framework objects.
2. Noel Llopis. "Managing Data Relationships" (2010), Games from Within. gamesfromwithin.com. Pointer values change run to run; the raw-pointer / array-index / handle encoding taxonomy and why handles win for serialization.
3. "Automatic Serialization in C++ for Game Engines" (2022), IndieGameDev. indiegamedev.net. The two-pass load: instantiate all objects, then fix up references.
4. cereal documentation, "Pointers." uscilab.github.io/cereal. Raw pointers are refused; shared references behind a shared_ptr are serialized once and re-linked on load.
5. Unity Technologies. "ISerializationCallbackReceiver" and script serialization rules. docs.unity3d.com. Inline serialization does not support shared or cyclic references; flatten a graph to arrays of nodes plus parent indices (the id-reference pattern by hand).
6. sinbad/SPUD (Steve's Persistent Unreal Data). github.com/sinbad/SPUD. Runtime-spawned actors are re-spawned on load rather than serialized as live objects.
7. Christian Haase. "An Unreal Engine saving & loading system." medium.com. Delta serialization against the class default, only changed-from-default properties are written.
8. UESP. "Skyrim Mod:Save File Format" and "Skyrim:Form ID." en.uesp.net. Change forms (deltas over the baked plugin data), three-byte save Form IDs, and the FF index reserved for save-local runtime objects.
9. Casey Muratori, Handmade Hero, on serialization versioning (via Hacker News discussion). news.ycombinator.com. A version number in the struct plus a migration function, framed explicitly like database migrations.
10. Protocol Buffers. "Language Guide (proto3)." protobuf.dev. Unknown fields are ignored and missing fields defaulted; never reuse a field number and reserve deleted ones.
11. FlatBuffers. "Schema Evolution." flatbuffers.dev. New fields only at the end of a table; fields are deprecated, never deleted; changing a default rewrites the meaning of prior data.
12. Epic Games. "Versioning of Assets and Packages in Unreal Engine." dev.epicgames.com. GUID-based custom versions for independent format tracks; a removed field is ignored and a new field holds its default.
13. Elijah Lopez. "Avoid Data Corruption by Syncing to the Disk." blog.elijahlopez.ca. The write-temp, fsync, atomic-rename sequence, and why flush() is not enough without fsync. (POSIX rename(2) is atomic within a filesystem.)
14. SnapNet. "Netcode Architectures Part 1: Lockstep." snapnet.dev. Lockstep ships only inputs and requires bitwise-identical simulation; a state-snapshot save restores directly and needs no determinism.