Crate bevy_save

Bevy_save

A framework for saving and loading game state in Bevy.

Features

Serialization and Deserialization

While Bevy’s DynamicScene only allows you to save entities and components, bevy_save enables you to save everything, including resources.

• World::serialize<S>() and World::deserialize<D>() allow you to serialize and deserialize game state with your own serializer / deserializer.

Save file management

bevy_save automatically uses your app’s workspace name to create a unique, permanent save directory in the correct place for whatever platform it is running on.

Supports Windows, Linux, and MacOS. WASM support is in progress.

• World::save() and World::load() uses your app’s save directory to save and load your game state to disk, handling all serialization and deserialization for you.
• This uses a predefined binary format, if you want to use your own serializer see "examples/json.rs".

Snapshots and Rollback

bevy_save is not just about save files, it is about total control over game state.

This crate introduces three different snapshot types which may be used directly:

• Snapshot is a serializable snapshot of all saveable resources, entities, and components.
• Rollback is a serializable snapshot of all saveable resources, entities, and components that are included in rollbacks.
• SaveableScene is a serializable snapshot of all saveable entities and components.

Or via the World extension methods:

• World::snapshot() captures a snapshot of the current game state, including resources. (equivalent to Snapshot::from_world())
• World::checkpoint() captures a snapshot for later rollback / rollforward.
• World::rollback() rolls the game state backwards or forwards through any checkpoints you have created.

The Rollbacks resource also gives you fine-tuned control of the currently stored rollbacks.

Type registration

bevy_save adds methods to Bevy’s App for registering types that should be saved. As long as the type implements Reflect, it can be registered and used with bevy_save. Types that are not explicitly registered in the SaveableRegistry are not included in save/load.

• App.register_saveable::<T>() registers a type as saveable, allowing it to be included in saves and rollbacks.
• App.ignore_rollback::<T>() excludes a type from rollback.
• App.allow_rollback::<T>() allows you to re-include a type in rollback after it has already been set to ignore rollback.

Type filtering

While types that are not registered with SaveableRegistry are automatically filtered out for you, bevy_save also allows you to explicitly filter types when creating a snapshot.

• Snapshot::from_world_with_filter()
• Rollback::from_world_with_filter()
• SaveableScene::from_world_with_filter()

Entity mapping

As Entity ids are not intended to be used as unique identifiers, bevy_save supports mapping Entity ids:

• World::deserialize_with_map() allows you to apply an EntityMap while manually deserializing a snapshot.
• World::load_with_map() allows you to apply an EntityMap while loading from a named save.
• World::rollback_with_map() allows you to apply an EntityMap while rolling back / forward.

This is also available directly on the snapshot types:

• Snapshot::apply_with_map()
• Rollback::apply_with_map()
• SaveableScene::apply_with_map()

If you use the methods that do not accept an EntityMap (deserialize, load, rollback, apply), the entities are assumed to have a one-to-one mapping with the currently spawned entities (1->1, 2->2, 3->3).

Any entities that do not have a mapping are automatically assigned a new id.

MapEntities

bevy_save also supports MapEntities via reflection to allow you to update entity ids within components and resources.

See Bevy’s Parent Component for a simple example.

License

bevy_save is dual-licensed under MIT and Apache-2.0.

Compatibility

NOTE: We do not track Bevy main.

Bevy Version	Crate Version
0.10	0.4, 0.5
0.9	0.1, 0.2, 0.3

Modules

• prelude
  Prelude: convenient import for all the user-facing APIs provided by the crate

Structs

• EntitySerializer
  A serializer for SaveableEntity that uses reflection.
• Rollback
  A rollback snapshot of the game state.
• RollbackDeserializer
  A deserializer for Rollback that uses reflection.
• RollbackSerializer
  A serializer for Rollback that uses reflection.
• Rollbacks
  The global registry of snapshots used for rollback / rollforward.
• RollbacksDeserializer
  A deserializer for Rollbacks that uses reflection.
• RollbacksSerializer
  A serializer for Rollbacks that uses reflection.
• SAVE_DIR
  The platform-specific save directory for the app.
• SavePlugin
  bevy_save core functionality plugin.
• SavePlugins
  Default plugins for bevy_save.
• SaveableEntity
  A reflection-powered serializable representation of an entity and its components.
• SaveableRegistry
  The global registry of types that should be tracked by bevy_save. Only types that are registered in here and [AppTypeRegistry] are included in save/load and rollback.
• SaveableScene
  A collection of serializable dynamic entities, each with its own run-time defined set of components.
• SaveablesPlugin
  Saveable registrations for common types.
• SceneDeserializer
  A deserializer for SaveableScene that uses reflection.
• SceneSerializer
  A serializer for SaveableScene that uses reflection.
• Snapshot
  A complete snapshot of the game state.
• SnapshotDeserializer
  A deserializer for Snapshot that uses reflection.
• SnapshotSerializer
  A serializer for Snapshot that uses reflection.

Enums

• SaveableError
  An error that may occur when loading saves or rollbacks.

Constants

• WORKSPACE
  The name of the project’s workspace.

Traits

• CloneReflect
  Clone-like trait for duplicating [Reflect]-related types.
• SaveableAppExt
  Extension trait that adds save-related methods to Bevy’s [App].
• WorldSaveableExt
  Extension trait that adds save-related methods to Bevy’s [World].

Functions

• get_save_file
  Returns the absolute path to a save file given its name.