Struct SettingsPlugin 

pub struct SettingsPlugin {
    pub app_name: String,
}

Plugin to orchestrate loading and saving settings.

You are required to provide a unique application name, so that your settings don’t overwrite those of other apps. To ensure global uniqueness, it is recommended to use a reverse domain name, e.g. “com.example.myapp”. The plugin will create a directory with that name in the appropriate filesystem location (depending on platform) for app settings. For platforms without filesystems, other storage mechanisms will be used.

If you are do not have a domain name and cannot afford one, use a reverse domain based on the URL of your repo (GitHub, GitLab, Codeberg and so on).

Adding this plugin causes an immediate load of settings (from either the filesystem or browser local storage, depending on platform).

When using this plugin, care must be taken to ensure that plugins execute in the proper order. Loading settings causes registered settings to be inserted into the world as bevy resources. You cannot access these values before they are loaded, but you may want to use the loaded values when configuring other plugins. For this reason, it’s generally a good idea to initialize and load settings before other plugins. The settings plugin does not depend on any other plugins.

In many cases, you may want to introduce additional “glue” plugins that copy setting properties after they are loaded. For example, the WindowPlugin plugin knows nothing about settings, but if you want the window size and position to persist between runs you can add an additional plugin which copies the window settings from the resource to the actual window entity.

Saving of settings is not automatic; the recommended practice is to issue a SaveSettingsDeferred command after modifying a settings resource. This will wait for a short interval and then spawn an i/o task to write out the changed settings file. You can also issue a SaveSettingsSync::IfChanged command immediately before exiting the app. Note that on some platforms, depending on how the user exits (such as invoking Command-Q on MacOS) there may be no opportunity to intercept the app exit event, so the most reliable approach is to use both techniques: deferred save and save-on-exit.

Saving is crash-resistant: if the app crashes in the middle of a save, the settings file will not be corrupted (it writes to a temporary file first, then uses atomic operations to replace the previous file).

Fields

app_name: String

The unique name of the application.

Implementations

impl SettingsPlugin

pub fn new(app_name: &str) -> Self

Construct a new SettingsPlugin for the given application name.

Trait Implementations

impl Plugin for SettingsPlugin

fn build(&self, app: &mut App)

Configures the App to which this plugin is added.

fn ready(&self, _app: &App) -> bool

Has the plugin finished its setup? This can be useful for plugins that need something asynchronous to happen before they can finish their setup, like the initialization of a renderer. Once the plugin is ready, finish should be called.

fn finish(&self, _app: &mut App)

Finish adding this plugin to the App, once all plugins registered are ready. This can be useful for plugins that depends on another plugin asynchronous setup, like the renderer.

fn cleanup(&self, _app: &mut App)

Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.

fn name(&self) -> &str

Configures a name for the Plugin which is primarily used for checking plugin uniqueness and debugging.

fn is_unique(&self) -> bool

If the plugin can be meaningfully instantiated several times in an App, override this method to return false.