bevy_pkv

When interacting with LocalStorageStore (which is aliased as InnerStore), operations can fail with specific error types. Understanding these errors is necessary for robust error handling in Wasm environments.

GetError

Returned by get operations:

• NotFound: No value was found for the provided key.
• Json: Failed to deserialize the stored JSON string into the requested type.
• GetItem: A JavaScript error occurred during the getItem call.

SetError

Returned by set or clear operations:

• SetItem: A JavaScript error occurred during the setItem call.
• Json: Failed to serialize the value into a JSON string.
• Clear: A JavaScript error occurred during the clear operation.

RemoveError

Returned by remove or remove_and_get operations:

• NotFound: No value was found for the given key.
• Json: Failed to deserialize the JSON string.
• GetItem: A JavaScript error occurred during the getItem call.
• Clear: A JavaScript error occurred during the remove_item or clear call.

The PersistentResourcePlugin<T> automatically handles loading and saving a Bevy resource using a PkvStore.

How it works:

1. Startup: It attempts to load the resource from storage using the type's full name as the key. If not found, it uses a default value provided by the plugin.
2. Runtime: It monitors the resource for changes. Whenever the resource is modified, the plugin automatically saves it to the PkvStore during the PostUpdate stage.

Requirements:

• The resource T must implement Resource, Serialize, and DeserializeOwned.
• You must first insert a PkvStore resource into your App before adding the plugin.

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

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

App::new()
    .insert_resource(PkvStore::new("ExampleOrg", "ExampleApp"))
    .add_plugins(PersistentResourcePlugin::<GameSettings>::new())
    .run();

The PkvStore uses serde for serialization. You can store any type that implements Serialize and retrieve any type that implements DeserializeOwned.

Key Methods:

• set<T: Serialize>(&mut self, key: impl AsRef<str>, value: &T): Serializes and stores a value.
• set_string(&mut self, key: impl AsRef<str>, value: &str): A convenience method for storing raw strings.
• get<T: DeserializeOwned>(&self, key: impl AsRef<str>) -> Result<T, GetError>: Retrieves and deserializes a value. Returns Err(GetError::NotFound) if the key does not exist.
• remove(&mut self, key: impl AsRef<str>) -> Result<(), RemoveError>: Deletes a key.
• remove_and_get<T: DeserializeOwned>(&mut self, key: impl AsRef<str>) -> Result<Option<T>, RemoveError>: Deletes the key and returns the value that was stored there.
• clear(&mut self) -> Result<(), SetError>: Wipes all data from the store.

use bevy_pkv::PkvStore;
use serde::{Serialize, Deserialize};

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

let mut store = PkvStore::new("MyOrg", "MyGame");

// Storing a custom type
let user = User { name: "Alice".into(), age: 30 };
store.set("current_user", &user).unwrap();

// Retrieving a custom type
let retrieved_user: User = store.get("current_user").unwrap();
assert_eq!(user, retrieved_user);

// Storing a string
store.set_string("session_id", "abc-123").unwrap();

// Removing a key
store.remove("session_id").unwrap();

// Clearing everything
store.clear().unwrap();

Use PkvStore to create a persistent key-value store. You can initialize it using platform-default locations (which use the organization and application names to determine the path) or by specifying a custom directory.

Note on Backends:

• On Native platforms, you must enable exactly one of the rocksdb, redb, or sled features.
• On Wasm, it uses localStorage automatically.
• Custom directory methods (new_in_dir, new_in_dir_with_filename) are only available when using rocksdb, redb, or sled backends.

use bevy_pkv::PkvStore;

// Use platform default locations
let mut store = PkvStore::new("MyOrg", "MyGame");

// Use platform default with a qualifier (e.g., "com")
let mut store = PkvStore::new_with_qualifier("com", "MyOrg", "MyGame");

// Use a custom directory (requires rocksdb, redb, or sled features)
let mut store = PkvStore::new_in_dir("./my_data_dir");

// Use a custom directory with a specific filename (requires rocksdb, redb, or sled features)
let mut store = PkvStore::new_in_dir_with_filename("./my_data_dir", "settings.db");