bevy_gltf_save_load (deprecated in favor of Blenvy)

bevy_gltf_save_load has been deprecated in favor of its successor Blenvy, part of the Blenvy project. No further development or maintenance will be done for Bevy bevy_gltf_save_load. See #194 for background.

Built upon bevy_gltf_blueprints this crate adds the ability to easilly save and load your game worlds for Bevy .

• leverages blueprints & seperation between
  • dynamic entities : entities that can change during the lifetime of your app/game
  • static entities : entities that do NOT change (typically, a part of your levels/ environements)
• and allows allow for :
  • a simple save/load workflow thanks to the above
  • ability to specify which entities to save or to exclude
  • ability to specify which components to save or to exclude
  • ability to specify which resources to save or to exclude
  • small(er) save files (only a portion of the entities is saved)

Particularly useful when using Blender as an editor for the Bevy game engine, combined with the Blender plugin that does a lot of the work for you (including spliting generating seperate gltf files for your static vs dynamic assets)

A bit of heads up:

• very opinionated !
• still in the early stages & not 100% feature complete
• fun fact: as the static level structure is stored seperatly, you can change your level layout & still reload an existing save file

Usage

Here's a minimal usage example:

# Cargo.toml
[dependencies]
bevy="0.14"
bevy_gltf_save_load = "0.5"
bevy_gltf_blueprints = "0.11" // also needed

use bevy::prelude::*;
use bevy_gltf_save_load::*;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            SaveLoadPlugin::default()
        ))
        .run();
}



// add a system to trigger saving
pub fn request_save(
    mut save_requests: EventWriter<SaveRequest>,
    keycode: Res<Input<KeyCode>>,
)
{
    if keycode.just_pressed(KeyCode::S) {
        save_requests.send(SaveRequest {
            path: "save.scn.ron".into(),
        })
    }
}

// add a system to trigger loading
pub fn request_load(
    mut load_requests: EventWriter<LoadRequest>,
    keycode: Res<Input<KeyCode>>,
)
{
    if keycode.just_pressed(KeyCode::L) {
        save_requests.send(LoadRequest {
            path: "save.scn.ron".into(),
        })
    }
}

// setting up your world
// on initial setup, the static entities & the dynamic entities are kept seperate for clarity & loaded as blueprints from 2 seperate files
pub fn setup_game(
    mut commands: Commands,
    mut next_game_state: ResMut<NextState<GameState>>,
) {
    info!("setting up game world");
    // here we actually spawn our game world/level
    let world_root = commands
        .spawn((
            Name::from("world"),
            GameWorldTag,
            InAppRunning,
            TransformBundle::default(),
            InheritedVisibility::default(),
        ))
        .id();

    // and we fill it with static entities
    let static_data = commands
        .spawn((
            Name::from("static"),
            BluePrintBundle {
                blueprint: BlueprintName("World".to_string()),
                ..Default::default()
            },
            StaticEntitiesRoot,
            Library("models".into())
        ))
        .id();

    // and we fill it with dynamic entities
    let dynamic_data = commands
        .spawn((
            Name::from("dynamic"),
            BluePrintBundle {
                blueprint: BlueprintName("World_dynamic".to_string()),
                ..Default::default()
            },
            DynamicEntitiesRoot,
            NoInBlueprint,
            Library("models".into())
        ))
        .id();
    commands.entity(world_root).add_child(static_data);
    commands.entity(world_root).add_child(dynamic_data);

    next_game_state.set(GameState::InGame)
}

take a look at the example for more clarity

Installation

Add the following to your [dependencies] section in Cargo.toml:

bevy_gltf_save_load = "0.3"
bevy_gltf_blueprints = "0.10" // also needed, as bevy_gltf_save_load does not re-export it at this time

Or use cargo add:

cargo add bevy_gltf_save_load

Setup

use bevy::prelude::*;
use bevy_gltf_save_load::*;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins
            SaveLoadPlugin::default()
        ))
        .run();
}

you likely need to configure your settings (otherwise, not much will be saved)

use bevy::prelude::*;
use bevy_gltf_save_load::*;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            SaveLoadPlugin {
                save_path: "scenes".into(), // where do we save files to (under assets for now) defaults to "scenes"
                component_filter: SceneFilter::Allowlist(HashSet::from([ // this is using Bevy's build in SceneFilter, you can compose what components you want to allow/deny
                    TypeId::of::<Name>(),
                    TypeId::of::<Transform>(),
                    TypeId::of::<Velocity>(),
                    // and any other commponent you want to include/exclude
                ])),
                resource_filter: SceneFilter::deny_all(), // same logic as above, but for resources : also be careful & remember to register your resources !
                ..Default::default()
            },
            // you need to configure the blueprints plugin as well (might be pre_configured in the future, but for now you need to do it manually)
            BlueprintsPlugin {
                library_folder: "models/library".into(),
                format: GltfFormat::GLB,
                aabbs: true,
                ..Default::default()
            },
        ))
        .run();
}

How to make sure your entites will be saved

• only entites that have a Dynamic component will be saved ! (the component is provided as part of the crate)
• you can either add that component at runtime or have it baked-in in the Blueprint

Component Filter:

• by default only the following components are going to be saved

  • Parent
  • Children
  • BlueprintName : part of bevy_gltf_blueprints, used under the hood
  • SpawnHere :part of bevy_gltf_blueprints, used under the hood
  • Dynamic : included in this crate, allows you to tag components as dynamic aka saveable ! Use this to make sure your entities are saved !

• you CANNOT remove these as they are part of the boilerplate

• you CAN add however many other components you want, allow them all etc as you see fit

• you can find more information about the SceneFilter object here and here

Events

• to trigger saving use the SaveRequest event

// add a system to trigger saving
pub fn request_save(
    mut save_requests: EventWriter<SaveRequest>,
    keycode: Res<Input<KeyCode>>,
)
{
    if keycode.just_pressed(KeyCode::S) {
        save_requests.send(SaveRequest {
            path: "save.scn.ron".into(),
        })
    }
}

• to trigger loading use the LoadRequest event

// add a system to trigger saving
pub fn request_load(
    mut load_requests: EventWriter<LoadRequest>,
    keycode: Res<Input<KeyCode>>,
)
{
    if keycode.just_pressed(KeyCode::L) {
        save_requests.send(LoadRequest {
            path: "save.scn.ron".into(),
        })
    }
}

• you also notified when saving / loading is done
  • SavingFinished for saving
  • LoadingFinished for loading

Note: I highly recomend you change states when you start/finish saving & loading, otherwise things will get unpredictable Please see the example for this.

Additional notes

• the name + path of the static level blueprint/gltf file will be saved as part of the save file, and reused to dynamically load the correct static assets, which is necessary when you have multiple levels, and thus all required information to reload a save is contained within the save

SystemSet

For convenience bevy_gltf_save_load provides two SystemSets

• LoadingSet
• SavingSet

Examples

Highly advised to get a better understanding of how things work ! To get started I recomend looking at

• world setup
• various events & co

All examples are here:

• https://github.com/kaosat-dev/Blender_bevy_components_workflow/tree/main/examples/bevy_gltf_save_load/basic

Compatible Bevy versions

The main branch is compatible with the latest Bevy release, while the branch bevy_main tries to track the main branch of Bevy (PRs updating the tracked commit are welcome).

Compatibility of bevy_gltf_save_load versions:

License

This crate, all its code, contents & assets is Dual-licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)