bevy_atomic_save 0.2.2

An atomic save/load system for Bevy Game Engine.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use std::fs::File;
use std::io::prelude::*;
use std::path::PathBuf;

use bevy::ecs::schedule::ShouldRun;
use bevy::prelude::*;

mod load;
mod plugin;
mod save;

pub use load::*;
pub use plugin::*;
pub use save::*;

#[derive(StageLabel)]
pub enum SaveStage {
    /// The [`Stage`] after [`CoreStage::Last`] during which [`World`] is saved.
    Save,
    /// The [`Stage`] before [`CoreStage::First`] during which [`World`] is loaded.
    Load,
    /// The [`Stage`] after [`SaveStage::Load`].
    ///
    /// This stage is typically reserved for any systems which handle [`Loaded`] entities.
    PostLoad,
}

/// Trait used to save a [`World`] to a file.
pub trait SaveWorld {
    /// Inserts a new [`Request::Save`] with the given `path` into this [`World`].
    ///
    /// This request is processed during [`SaveStage::Save`]. During this stage, any [`Entity`]
    /// with a [`Save`] [`Component`] is serialized into a [`DynamicScene`] which is then written
    /// into a file located at given `path`.
    ///
    /// If the save request fails, an [`error`] message will be logged with cause of failure.
    fn save(self, path: impl Into<PathBuf>);

    /// Inserts a new [`Request::Save`] with the given `path` into this [`World`].
    ///
    /// This request is processed during [`SaveStage::Save`]. During this stage, all entities
    /// are serialized into a [`DynamicScene`] which is then written into a file located at given `path`.
    ///
    /// Unlike [`SaveWorld::save()`], this function saves *all* entities and their serializable components.
    /// The resulting file should not be used for loading, as it most likely has more data than required to
    /// actually load the game, which may result in duplicate or conflicting entities.
    ///
    /// As a result, this function should be used primarily for diagnostics, as it can be useful for inspecting
    /// worlds in a very simple, and somewhat readable text format.
    ///
    /// If the dump request fails, an [`error`] message will be logged with cause of failure.
    fn dump(self, path: impl Into<PathBuf>);
}

impl SaveWorld for &mut Commands<'_, '_> {
    fn save(self, path: impl Into<PathBuf>) {
        self.insert_resource(Request::Save {
            path: path.into(),
            mode: SaveMode::Filtered,
        })
    }

    fn dump(self, path: impl Into<PathBuf>) {
        self.insert_resource(Request::Save {
            path: path.into(),
            mode: SaveMode::Dump,
        })
    }
}

impl SaveWorld for &mut World {
    fn save(self, path: impl Into<PathBuf>) {
        self.insert_resource(Request::Save {
            path: path.into(),
            mode: SaveMode::Filtered,
        })
    }

    fn dump(self, path: impl Into<PathBuf>) {
        self.insert_resource(Request::Save {
            path: path.into(),
            mode: SaveMode::Dump,
        })
    }
}

/// Trait used to load a [`World`] from a file.
pub trait LoadWorld {
    /// Inserts a new [`Request::Load`] from the given `path` for this [`World`].
    ///
    /// This request is processed during [`SaveStage::Load`]. During this stage, any [`Entity`]
    /// with a [`Save`] or [`Unload`] [`Component`] is despawned recursively. Then, entities are deserialized
    /// from the given path (which should point to a previously saved file) and spawned in this [`World`]
    /// with a new [`Loaded`] [`Component`]. This component is removed after [`SaveStage::PostLoad`].
    ///
    /// If the load request fails, an [`error`] message will be logged with cause of failure.
    ///
    /// After a successful load, there is no guarantee that a loaded entity will have the same index with which
    /// it was saved. This is because there may already be an entity with that index in this world which is
    /// not marked for [`Save`] or [`Unload`]. This means any saved entity references are most likely invalid
    /// after load.
    ///
    /// To solve this, during [`SaveStage::PostLoad`], systems may use the [`Loaded`] component to update entity
    /// references as required. See examples for how this would be done.
    fn load(self, path: impl Into<PathBuf>);
}

impl LoadWorld for &mut Commands<'_, '_> {
    fn load(self, path: impl Into<PathBuf>) {
        self.insert_resource(Request::Load { path: path.into() })
    }
}

impl LoadWorld for &mut World {
    fn load(self, path: impl Into<PathBuf>) {
        self.insert_resource(Request::Load { path: path.into() })
    }
}

pub enum SaveMode {
    /// Save entities with a [`Save`] component.
    Filtered,
    /// Save all entities.
    Dump,
}

/// A [`Resource`] used to trigger a save or load request.
#[derive(Resource)]
pub enum Request {
    Save { path: PathBuf, mode: SaveMode },
    Load { path: PathBuf },
}

impl Request {
    fn should_save(&self) -> bool {
        matches!(self, Self::Save { .. })
    }

    fn should_load(&self) -> bool {
        matches!(self, Self::Load { .. })
    }
}