Crate bevy_pkv 

bevy_pkv

bevy_pkv is a cross-platform persistent key value store for rust apps.

Use it for storing things like settings, save games etc.

Currently, the Bevy dependency is optional, so it may be used in other games/apps as well.

Usage with Bevy

Add a store resource to your app

use bevy::prelude::*;
use bevy_pkv::PkvStore;

fn main() {
App::new()
    .add_plugins(DefaultPlugins)
    .insert_resource(PkvStore::new("FooCompany", "BarGame"))
    // ...insert systems etc.
    .run();
}

This will create or load a store in the appropriate location for your system, and make it available to bevy systems:

fn setup(mut pkv: ResMut<PkvStore>) {
    if let Ok(username) = pkv.get::<String>("username") {
        info!("Welcome back {username}");
    } else {
        pkv.set_string("username", "alice")
            .expect("failed to store username");

        // alternatively, using the slightly less efficient generic api:
        pkv.set("username", &"alice".to_string())
            .expect("failed to store username");
    }
}

Using Custom Types

You can also store and retrieve your own types that implement serde::Serialize and Deserialize:

#[derive(Serialize, Deserialize)]
struct User {
    name: String,
}

fn setup(mut pkv: ResMut<PkvStore>) {
    if let Ok(user) = pkv.get::<User>("user") {
        info!("Welcome back {}", user.name);
    } else {
        let user = User {
            name: "bob".to_string(),
        };
        pkv.set("user", &user).expect("failed to store user");
    }
}

Persistent Resources

For resources that should automatically persist when they change, use the convenient init_persistent_resource API:

use bevy::prelude::*;
use bevy_pkv::prelude::*;
use serde::{Serialize, Deserialize};

#[derive(Resource, Serialize, Deserialize, Default)]
struct GameSettings {
    volume: f32,
    difficulty: u8,
}

App::new()
    .add_plugins(DefaultPlugins)
    .insert_resource(PkvStore::new("FooCompany", "BarGame"))
    .init_persistent_resource::<GameSettings>()
    .run();

This automatically loads the resource from storage on startup and saves it whenever it changes!

See the examples for further usage

Usage without Bevy

Disable the default features when adding the dependency:

bevy_pkv = {version = "0.9", default-features = false}

Implementation details

Native

redb and rmp_serde (MessagePack) is used for storage. It’s creating a bevy_pkv.redb db in the appropriate application data directory for your system.

Alternatively, disable default-features and enable the rocksdb feature to use a RocksDB-based implementation or sled feature to use sled db.

Wasm

Window.localStorage and serde_json is used for storage. Perhaps IndexedDb and something else would have been a better choice, but its API is complicated, and I wanted a simple implementation and a simple synchronous API.

Bevy version support

The main branch targets the latest bevy release.

bevy	bevy_pkv
0.17	0.14, main
0.16	0.13
0.15	0.12
0.14	0.11
0.13	0.10
0.12	0.9
0.11	0.8
0.10	0.7
0.9	0.6
0.8	0.5
0.7	0.2, 0.3, 0.4
0.6	0.1

License

MIT or Apache-2.0

Modules

prelude

Convenient re-exports for common bevy_pkv functionality

Structs

PersistentResourcePlugin

A plugin that automatically persists a resource when it changes using a PkvStore

PkvStore

Main resource for setting/getting values

Enums

GetError

Errors that can occur during PkvStore::get

RemoveError

Errors that can occur during PkvStore::

SetError

Errors that can occur during PkvStore::set

Traits

PersistentResourceAppExtensions

Extension trait for App to provide convenient methods for initializing persistent resources