bevy-save-load

Bevy 0.19 — save and load

When to use this skill

• Gameplay state must remain loadable across ECS/content/code refactors.
• Large worlds need base snapshots, sparse deltas, compaction, and recovery.
• Native and browser builds need one asynchronous save-service contract.
• Reflected world serialization is being considered as a durable save format.

A save file is a long-lived product API. Serialize an explicit, versioned data model and convert it to/from the live ECS. Runtime Entity values, dense palette indices, query order, Rust enum discriminants, and reflected component layout are not stable persistence identities.

Canonical pattern

use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(transparent)]
struct SaveId(String);

#[derive(Debug, Deserialize, Serialize)]
struct SaveV3 {
    world_seed: u64,
    player: SaveId,
    actors: Vec<ActorV3>,
}

#[derive(Debug, Deserialize, Serialize)]
struct ActorV3 {
    id: SaveId,
    archetype: String,
    position: [f32; 3],
}

live Bevy World
  -> validate/capture one logical revision
  -> current Save DTO with stable IDs
  -> encode + checksum envelope
  -> platform storage transaction

platform bytes
  -> size/magic/checksum validation
  -> decode declared old DTO
  -> migrate one version at a time
  -> validate current DTO
  -> allocate entities, then resolve stable-ID references
  -> rebuild derived/runtime-only state

Never partially mutate the active world while bytes are still being decoded or migrated. Load into staging, validate, then commit or replace the gameplay world.

Version the envelope and payload

Wrap encoded payload bytes with magic, format version, schema/content version, payload length, codec/compression identifiers, and checksum. A checksum detects accidental corruption; it does not prevent malicious tampering. Use authentication or a signature when trust is part of the requirement.

Keep migrations as explicit V1 -> V2 -> V3 pure functions. Test golden fixtures from every supported version, including corrupt, truncated, duplicated-ID, unknown-ID, and future-version files. Never deserialize an old version directly into today's struct and hope Serde defaults reproduce old semantics.