Crate bevy_simple_preferences

About

Bevy Preferences Simple Abstraction

Provides a simple Preferences API for Bevy that allows different crates to relay in a simple preferences abstraction giving the final app crate full control on how and where to store the preferences.

This crate is heavily based on the Bevy Preferences API proposal.

Examples

You first need to define a struct / enum that represents your preferences.

#[derive(Reflect, Default)]
struct ExampleSettings {
    field_u32: u32,
    some_str: String,
    some_option: Option<String>,
}

And in your code, you just need to add the PreferencesPlugin and call RegisterPreferencesExt::register_preferences

App::new()
    .add_plugins(PreferencesPlugin::persisted_with_app_name("YourAppName"))
    .register_preferences::<ExampleSettings>();

If you are implementing a library, you don’t need to add PreferencesPlugin, since it’s up the final user to add it themselves. But you can rely on the Preferences param to read and write preferences, even if the final user does not add the plugin.

If the final user does not add the PreferencesPlugin, the effect is that preferences are simply not stored.

impl Plugin for MyCratePlugin {
    fn build(&self, app: &mut App) {
        app.register_preferences::<MyCratePreferences>()
            .add_systems(Update, |my_preferences: Preferences<MyCratePreferences>| {
                // Do stuff with your preferences
                assert!(my_preferences.some_field >= 0);
            });
        ;
    }
}

Supported Bevy Versions

Bevy	bevy_simple_preferences
0.14	0.1

Details

PreferencesPlugin is responsible to define where the preferences are stored, but sensible defaults are chosen for the user, like the storage path and format.

Storage path

By default, the following paths are used to store the preferences

Platform	Value	Example
Native	dirs::preference_dir/{app_name}/preferences.toml	/home/alice/.config/MyApp/preferences.toml
Wasm	LocalStorage:{app_name}_preferences	LocalStorage:MyApp_preferences

Final user can personalize this paths by using PreferencesPlugin::with_storage_type and use any convinient value of PreferencesStorageType.

Storage format

By default, the following formats are used:

Platform	Format	Example
Native	toml	[MyPluginPreferences]\nvalue = 3
Wasm	json	{ "MyPluginPreferences": { "value": 3 } }

A different format (only for native) can be configured by implementing crate::storage::fs::FileStorageFormat;

Go to the crate::storage::fs::FileStorageFormat documentation for more information on how to do it.

Modules

serializable_map

Contains PreferencesSerializableMap that allows preferences to be serialize and deserialize using reflection.

storage

Contains everything related to store and load preferences. Two main submodules are present, depending on the platform.

Structs

Preferences

System param that allows to read and write preferences of a type T.

PreferencesPlugin

Preferences Plugin that configures how preferences are stored. It should be only added by final applications, not libraries, since it’s not their responsibility.

PreferencesResource

Stores the specific values of a preferences of type T. Is preferable to use Preferences system param, but if you need fine-grained control over the change detection, you might need to use the Resource directly

ReflectPreferences

Represents the type data registration of a PreferencesType type. It doesn’t contain any data, so it only serves as a marker type to make sure a type has been registered as Preferences.

Enums

PreferencesError

Possible errors that could happen during either loading or saving preferences

PreferencesSet

System Set used by PreferencesPlugin

PreferencesStorageType

Type of storage that will be used. Most use cases are covered by PreferencesStorageType::DefaultStorage and PreferencesStorageType::NoStorage

Traits

PreferencesType

Marker trait to indicate that the type can work as Preferences. Is automatically implemented for anything that implements FromReflect and TypePath .

RegisterPreferencesExt

Extension for App to allow registering preference types.