Crates.io | moonshine-save |
lib.rs | moonshine-save |
version | 0.3.8 |
source | src |
created_at | 2023-03-08 05:48:46.269261 |
updated_at | 2024-07-05 00:14:24.295665 |
description | Save/Load framework for Bevy |
homepage | https://github.com/Zeenobit/moonshine_save |
repository | https://github.com/Zeenobit/moonshine_save |
max_upload_size | |
id | 804260 |
size | 175,588 |
A save/load framework for Bevy game engine.
In Bevy, it is possible to serialize and deserialize a World
using a DynamicScene
(see example for details). While this is useful for scene management and editing, it is problematic when used for saving/loading the game state.
The main issue is that in most common applications, the saved game data is a very minimal subset of the whole scene. Visual and aesthetic elements such as transforms, scene hierarchy, camera, or UI components are typically added to the scene during game start or entity initialization.
This crate aims to solve this issue by providing a framework and a collection of systems for selectively saving and loading a world.
use bevy::prelude::*;
use moonshine_save::prelude::*;
App::new()
.add_plugins(DefaultPlugins)
.add_plugins((SavePlugin, LoadPlugin))
.add_systems(PreUpdate, save_default().into_file("world.ron").run_if(should_save))
.add_systems(PreUpdate, load_from_file("world.ron").run_if(should_load));
fn should_save() -> bool {
todo!()
}
fn should_load() -> bool {
todo!()
}
The main design goal of this crate is to use concepts borrowed from MVC (Model-View-Controller) architecture to separate the aesthetic elements of the game (the game "view") from its logical and saved state (the game "model").
To use this crate as intended, you should design your game logic with this separation in mind:
✨ See Moonshine View for an automated, generic implementation of this pattern.
For example, suppose we want to represent a player character in a game.
Various components are used to store the logical state of the player, such as Health
, Inventory
, or Weapon
.
Each player is represented using a 2D SpriteBundle
, which presents the current visual state of the player.
Traditionally, we might have used a single entity (or a hierarchy) to reppresent the player. This entity would carry all the logical components, such as Health
, in addition to the SpriteBundle
:
use bevy::prelude::*;
#[derive(Bundle)]
struct PlayerBundle {
health: Health,
inventory: Inventory,
weapon: Weapon,
sprite: SpriteBundle,
}
#[derive(Component)]
struct Health;
#[derive(Component)]
struct Inventory;
#[derive(Component)]
struct Weapon;
An arguably better approach would be to store this data in a completely separate entity:
use bevy::prelude::*;
use moonshine_save::prelude::*;
#[derive(Bundle)]
struct PlayerBundle {
player: Player,
health: Health,
inventory: Inventory,
weapon: Weapon,
}
#[derive(Component)]
struct Player;
#[derive(Component)]
struct Health;
#[derive(Component)]
struct Inventory;
#[derive(Component)]
struct Weapon;
#[derive(Bundle)]
struct PlayerViewBundle {
view: PlayerView,
sprite: SpriteBundle,
}
#[derive(Component)]
struct PlayerView {
player: Entity
}
fn spawn_player_sprite(mut commands: Commands, query: Query<Entity, Added<Player>>) {
for player in query.iter() {
commands.spawn(PlayerViewBundle {
view: PlayerView { player },
sprite: todo!(),
});
}
}
This approach may seem verbose at first, but it has several advantages:
Ultimately, it is up to you to decide if the additional complexity of this separation is beneficial to your project or not.
This crate is not intended to be a general purpose save solution by default. However, another design goal of this crate is maximum customizability.
This crate provides some standard and commonly used save/load pipelines that should be sufficient for most applications based on the architecture outlined above. These pipelines are composed of smaller sub-systems.
These sub-systems may be used in any other desired configuration and combined with other systems to highly specialized pipelines.
In order to save game state, start by marking entities which must be saved using the Save
marker. This is a component which can be added to bundles or inserted into entities like any other component:
use bevy::prelude::*;
use moonshine_save::prelude::*;
#[derive(Component, Default, Reflect)]
#[reflect(Component)]
struct Player;
#[derive(Component, Default, Reflect)]
#[reflect(Component)]
struct Level(u32);
#[derive(Bundle)]
struct PlayerBundle {
player: Player,
level: Level,
name: Name,
save: Save,
}
⚠️ Saved components must implement
Reflect
and be registered types.
Add SavePlugin
and register your serialized components:
app.add_plugins(SavePlugin)
.register_type::<Player>()
.register_type::<Level>();
To invoke the save process, you must define a SavePipeline
. Each save pipeline is a collection of piped systems.
You may start a save pipeline using save_default
which saves all entities with a Save
component.
app.add_systems(PreUpdate, save_default().into_file("saved.ron"));
Alternative, you may also use save_all
to save all entities and save
to provide a custom QueryFilter
for your saved entities.
There is also save_all_with
and save_with
to be used with SaveFilter
.
When used on its own, a pipeline would save the world state on every application update cycle.
This is often undesirable because you typically want the save process to happen at specific times during runtime.
To do this, you can combine the save pipeline with .run_if
:
app.add_systems(PreUpdate, save_default().into_file("saved.ron").run_if(should_save));
fn should_save( /* ... */ ) -> bool {
todo!()
}
By default, resources are NOT included in the save data.
To include resources into the save pipeline, use .include_resource<R>
:
app.add_systems(PreUpdate, save_default().include_resource::<R>().into_file("saved.ron"));
By default, all serializable components on saved entities are included in the save data.
To exclude components from the save pipeline, use .exclude_component<T>
:
app.add_systems(PreUpdate, save_default().exclude_component::<T>().into_file("saved.ron"));
Before loading, mark your visual and aesthetic entities ("view" entities) with Unload
.
Similar to Save
, this is a marker which can be added to bundles or inserted into entities like a regular component.
Any entity marked with Unload
is despawned recursively before loading begins.
use bevy::prelude::*;
use moonshine_save::prelude::*;
#[derive(Bundle)]
struct PlayerSpriteBundle {
/* ... */
unload: Unload,
}
You should design your game logic to keep saved data separate from game visuals.
Any saved components which reference entities must implement MapEntities
:
use bevy::prelude::*;
use bevy::ecs::entity::{EntityMapper, MapEntities};
use moonshine_save::prelude::*;
#[derive(Component, Default, Reflect)]
#[reflect(Component, MapEntities)]
struct PlayerWeapon(Option<Entity>);
impl MapEntities for PlayerWeapon {
fn map_entities<M: EntityMapper>(&mut self, entity_mapper: &mut M) {
if let Some(weapon) = self.0.as_mut() {
*weapon = entity_mapper.map_entity(*weapon);
}
}
}
Make sure LoadPlugin
is added and your types are registered:
app.add_plugins(LoadPlugin)
.register_type::<Player>()
.register_type::<Level>();
To invoke the load process, you must add a load pipeline. The default load pipeline is load_from_file
:
app.add_systems(PreUpdate, load_from_file("saved.ron"));
Similar to the save pipeline, you typically want to use load_from_file
with .run_if
:
app.add_systems(PreUpdate, load_from_file("saved.ron").run_if(should_load));
fn should_load( /* ... */ ) -> bool {
todo!()
}
See examples/army.rs for a minimal application which demonstrates how to save/load game state in detail.
In the examples provided, the save file path is often static (i.e. known at compile time). However, in some applications, it may be necessary to save into a path selected at runtime.
You may use SaveIntoFileRequest
and LoadFromFileRequest
traits to achieve this.
Your save/load request may either be a Resource
or an Event
.
use std::path::{Path, PathBuf};
use bevy::prelude::*;
use moonshine_save::prelude::*;
// Save request with a dynamic path
#[derive(Resource)]
struct SaveRequest {
pub path: PathBuf,
}
impl FilePath for SaveRequest {
fn path(&self) -> &Path {
self.path.as_ref()
}
}
// Load request with a dynamic path
#[derive(Resource)]
struct LoadRequest {
pub path: PathBuf,
}
impl FilePath for LoadRequest {
fn path(&self) -> &Path {
self.path.as_ref()
}
}
You may use this in conjunction with .into_file_on_request
and load_from_file_on_request
.
app.add_systems(PreUpdate, save_default().into_file_on_request::<SaveRequest>());
app.add_systems(PreUpdate, load_from_file_on_request::<LoadRequest>());
Then you can invoke save/load by inserting the request as a resource:
fn trigger_save(mut commands: Commands) {
commands.insert_resource(SaveRequest { path: "saved.ron".into() });
}
fn trigger_load(mut commands: Commands) {
commands.insert_resource(LoadRequest { path: "saved.ron".into() });
}
Similarly, to use an event for save/load requests, you may use .into_file_on_event
and load_from_file_on_event
instead:
app.add_event(SaveRequest)
.add_event(LoadRequest)
.add_systems(PreUpdate, save_default().into_file_on_event::<SaveRequest>())
.add_systems(PreUpdate, load_from_file_on_event::<SaveRequest>());
Then you can invoke save/load by sending the request as an event:
fn trigger_save(mut events: EventWriter<SaveRequest>) {
events.send(SaveRequest { path: "saved.ron".into() });
}
fn trigger_load(mut events: EventWriter<SaveRequest>) {
events.send(LoadRequest { path: "saved.ron".into() });
}
Please post an issue for any bugs, questions, or suggestions.
You may also contact me on the official Bevy Discord server as @Zeenobit.