An atomic save/load system for Bevy Game Engine.

Overview

☢️ Bevy Atomic Save

An atomic save/load system for Bevy.

Features

  • Save and load a World into a RON file on disk
  • Control which entities should participate in save/load operations
  • Operations are synchronous, providing precise control over when save/load happens
  • Dump feature useful for inspecting worlds in text format without any boilerplate.

Overview

With the latest version of Bevy, it is possible to save the state of a world into a DynamicScene (see example). While this approach is useful for scene management and editting, it's not practical to use the same approach for saving and loading the game state.

In most typical cases, a game needs to save only a minimal subset of the world to be able to resume its state from disk. Visual and aesthetic elements of the game such as UI, models, sprites, cameras, or logic systems do not need to be serialized as they are usually initialized during game start.

This crate solves this problem by providing a framework for marking entities which need to be saved and loaded, along with functions to save/load these entities into and from disk.

Usage

Save

  1. Ensure SavePlugin is added to your App.
use bevy_atomic_save::SavePlugin;
...
app.add_plugin(SavePlugin);
  1. Mark any entities which should be saved using the Save component. This may either be a Bundle, or inserted like a regular component. Entities marked for save should have components which derive Reflect. Any component which does not derive Reflect is not saved.
use bevy::prelude::*;
use bevy_atomic_save::Save;

#[derive(Bundle)]
struct PlayerBundle {
    /* ... Serializable Player Data ... */
    save: Save,
}
  1. Save a world to disk using SaveWorld via a &mut World or &mut Commands.
use bevy::prelude::*;
use bevy_atomic_save::SaveWorld;

fn trigger_save(mut commands: Commands) {
    commands.save("world.ron");
}

Load

  1. Mark any entities which should be unloaded prior to load with Unload.
use bevy::prelude::*;
use bevy_atomic_save::Unload;

#[derive(Bundle)]
struct PlayerModelBundle {
    /* ... Player Transform, Mesh, Sprite, etc. ... */
    unload: Unload,
}
  1. Load a previously saved file using LoadWorld via a &mut World or &mut Commands.
    This starts a load process, which starts by deserializing the given file and then despawning (recursively) all entities marked with Save or Unload components. Finally, new entities are spawned and SaveStage::PostLoad begins.
use bevy::prelude::*;
use bevy_atomic_save::LoadWorld;

fn trigger_load(mut commands: Commands) {
    commands.load("world.ron");
}
  1. Update entity references during SaveStage::PostLoad.
    During load, there is no guarantee that the indices of saved entities are preserved. This is because there may already be entities in the current world with those indices, which cannot be despawned prior to load. Because of this, any components which reference entities should update their referenced entity during SaveStage::PostLoad.
    If your project does not reference entities in its save data, you can safely skip this step. Otherwise, see ./examples/pawn.rs for a complete example on how to do this.

Notes

Resources

Currently, a DynamicScene in Bevy does not save Resource items. To save/load resources, it is recommended to spawn your saved resources as entities with a Save component. This also gives you control over exactly which resources should be saved.

Bevy Components and Entity References

Some components in Bevy reference entities (e.g. Parent and Children), which would need to update their references during SaveStage::PostLoad. This crate does NOT provide this functionality. In most cases, you shouldn't need to save such components, as they typically belong to scene entities which may be spawned from loaded game data.

World Dump

During development, it may be useful to examine a world in raw text format, within a specific frame, for diagnostics purposes. This crate provides a simple function to do this which uses the underlying save system to dump the world state into a RON file. See SaveWorld::dump for details.

The only difference between a dump and a save request is that a dump saves all entities, as opposed to save which only saves entities with a Save component.

The result of a dump should not be loaded, as it can result in duplicate entities afterwards.

Future Plans

  • Provide asynchronous options
You might also like...
A light-weight Anchor-Offset based 2D sprite rendering system for the bevy engine.
A light-weight Anchor-Offset based 2D sprite rendering system for the bevy engine.

Bevy AoUI A light-weight anchor-offset based 2D sprite layout system for the bevy engine. Bevy AoUI provides a light-weight rectangular anchor-offset

Basic first-person fly camera for the Bevy game engine

bevy_flycam A basic first-person fly camera for Bevy 0.4 Controls WASD to move horizontally SPACE to ascend LSHIFT to descend ESC to grab/release curs

Inspector plugin for the bevy game engine
Inspector plugin for the bevy game engine

bevy-inspector-egui This crate provides the ability to annotate structs with a #[derive(Inspectable)], which opens a debug interface using egui where

Crossterm plugin for the bevy game engine
Crossterm plugin for the bevy game engine

What is bevy_crossterm? bevy_crossterm is a Bevy plugin that uses crossterm as a renderer. It provides custom components and events which allow users

Concise Reference Book for the Bevy Game Engine

Unofficial Bevy Cheat Book Click here to read the book! Concise reference to programming in the Bevy game engine. Covers useful syntax, features, prog

Proof-of-concept of getting OpenXR rendering support for Bevy game engine using gfx-rs abstractions
Proof-of-concept of getting OpenXR rendering support for Bevy game engine using gfx-rs abstractions

Introduction Proof-of-concept of getting OpenXR rendering support for Bevy game engine using gfx-rs abstractions. (hand interaction with boxes missing

A physics lib for the bevy game engine based on physme

physimple Physimple aims to be the simplest(and capable) physics engine(currently for bevy) WARNING Beware for breaking changes with each update for n

An immediate mode 2D drawing API for Bevy game engine

Bevy Canvas API prototype An unofficial immediate mode 2D drawing API for Bevy game engine. Check the documentation or the examples to know how to use

Simple RUST game with the Bevy Engine

Simple RUST Game using the Bevy Engine YouTube videos for this code base: Episode 1 - Rust Game Development tutorial from Scratch with Bevy Engine Epi

Owner
null
Minecraft-esque voxel engine prototype made with the bevy game engine. Pending bevy 0.6 release to undergo a full rewrite.

vx_bevy A voxel engine prototype made using the Bevy game engine. Goals and features Very basic worldgen Animated chunk loading (ala cube world) Optim

Lucas Arriesse 125 Dec 31, 2022
Bevy Simple Portals is a Bevy game engine plugin aimed to create portals.

Portals for Bevy Bevy Simple Portals is a Bevy game engine plugin aimed to create portals. Those portals are (for now) purely visual and can be used t

Sélène Amanita 11 May 28, 2023
Hanabi — a particle system plugin for the Bevy game engine.

Hanabi — a particle system plugin for the Bevy game engine

Jerome Humbert 256 Dec 30, 2022
🎆 CPU-driven, batch-rendered particle system for the Bevy game engine.

Bevy Firework ?? Bevy firework is a particle system plugin where particles are simulated on the CPU and use GPU batching for rendering. This allows ea

Manuel Brea Carreras 24 Mar 12, 2024
2d Endless Runner Game made with Bevy Game Engine

Cute-runner A 2d Endless Runner Game made with Bevy Game Engine. Table of contents Project Infos Usage Screenshots Disclaimer Project Infos Date: Sept

JoaoMarinho 2 Jul 15, 2022
A game of snake written in Rust using the Bevy game engine, targeting WebGL2

Snake using the Bevy Game Engine Prerequisites cargo install cargo-make Build and serve WASM version Set your local ip address in Makefile.toml (loca

Michael Dorst 0 Dec 26, 2021
A game made in one week for the Bevy engine's first game jam

¿Quien es el MechaBurro? An entry for the first Bevy game jam following the theme of "Unfair Advantage." It was made in one week using the wonderful B

mike 20 Dec 23, 2022
A Client/Server game networking plugin using QUIC, for the Bevy game engine.

Bevy Quinnet A Client/Server game networking plugin using QUIC, for the Bevy game engine. Bevy Quinnet QUIC as a game networking protocol Features Roa

Gilles Henaux 65 Feb 20, 2023
Bevy plugin for an AssetServer that can load embedded resources, or use other AssetServers based on the path.

Bevy-Embasset Embed your asset folder inside your binary. bevy-embasset adds support for loading assets embedded into the binary. Furthermore, it can

Johnny Tidemand Vestergaard 9 Aug 4, 2022
A Win32 GUI program which modifies save files from the game Freelancer (2003).

FL Save Convert A Win32 GUI program which modifies save files from the game Freelancer (2003). System Dependencies Your system will need the latest Mi

Devin Mutlu 3 Nov 15, 2022