bevy_settings/

lib.rs

//! Framework for saving and loading user settings files in Bevy
//! applications.
//!
//! The core of the framework is [`SettingsPlugin`], which
//! loads and synchronizes settings with the filesystem or browser
//! local storage, depending on platform.
//!
//! Settings are loaded into resources that implement [`SettingsGroup`](trait@SettingsGroup),
//! which is best implemented using the derive macro [`SettingsGroup`](derive@SettingsGroup).
//! In addition, the resource must have the `#[reflect(SettingsGroup, Default)]` annotation in
//! order to be saved and loaded by the plugin.
//!
//! Once all these conditions are met, and when [`SettingsPlugin`] is added, systems can query
//! for settings using [`Res`] and [`ResMut`] like any other resource.
//!
//! Refer to [`SettingsPlugin`] for detailed usage information.

use core::any::TypeId;
use core::time::Duration;
use serde::ser::SerializeMap;
use std::collections::HashMap;

use bevy_app::{App, Plugin, PostUpdate};
use bevy_ecs::{
    change_detection::Tick,
    reflect::{AppTypeRegistry, ReflectComponent, ReflectResource},
    resource::Resource,
    system::{Command, Commands, Res, ResMut},
    world::World,
};
pub use bevy_ecs_macros::SettingsGroup;
use bevy_log::warn;
use bevy_reflect::{
    enums::DynamicEnum,
    prelude::ReflectDefault,
    serde::{ReflectSerializerProcessor, TypedReflectDeserializer, TypedReflectSerializer},
    CreateTypeData, FromReflect, PartialReflect, Reflect, ReflectMut, TypeInfo, TypePath,
    TypeRegistration, TypeRegistry,
};

#[cfg(not(target_arch = "wasm32"))]
mod store_fs;

#[cfg(target_arch = "wasm32")]
mod store_wasm;

use bevy_time::{Real, Time, Timer, TimerMode};
use serde::de::DeserializeSeed;
#[cfg(not(target_arch = "wasm32"))]
use store_fs::SettingsStore;

#[cfg(target_arch = "wasm32")]
use store_wasm::SettingsStore;

/// Plugin to orchestrate loading and saving settings.
///
/// When added to an app, `SettingsPlugin` will load settings from storage (either the filesystem
/// or browser local storage) into resources that implement the [`SettingsGroup`](trait@SettingsGroup),
/// [`Default`], and [`Reflect`] traits, and, in
/// addition, are also annotated with `#[reflect(Default, SettingsGroup)]`. The plugin can also be used
/// to write these settings back to storage after they are changed by sending the [`SaveSettingsDeferred`]
/// or [`SaveSettingsSync`] commands.
///
/// 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](https://en.wikipedia.org/wiki/Reverse_domain_name_notation),
/// 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 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).
///
/// # Storage location and format
///
/// Settings are stored as **TOML** files. Each [`SettingsGroup`] type becomes a top-level section
/// in the file. The default filename is `settings`, which produces `settings.toml`.
///
/// On desktop platforms, files are written to `{preferences_dir()}/{app_name}/{filename}.toml`,
/// where [`preferences_dir()`](bevy_platform::dirs::preferences_dir) is provided by
/// [`bevy_platform::dirs::preferences_dir`]. With `app_name = "com.example.myapp"` and the default
/// filename, typical paths are:
///
/// - Linux: `~/.config/com.example.myapp/settings.toml` (or under `$XDG_CONFIG_HOME` when set)
/// - macOS: `~/Library/Preferences/com.example.myapp/settings.toml`
/// - Windows: `%LocalAppData%\com.example.myapp\settings.toml`
///
/// On `wasm32`, settings are stored in browser `localStorage` under the key
/// `{app_name}-{filename}` as a TOML string.
///
/// A file with one [`SettingsGroup`] named `counter` might look like:
///
/// ```toml
/// [counter]
/// count = 5
/// enabled = true
/// ```
///
/// Use `settings_group(file = "...")` on a [`SettingsGroup`] to write to a different file in the
/// same app directory (see [`SettingsGroup`] for details).
///
/// 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`](https://docs.rs/bevy/latest/bevy/prelude/struct.WindowPlugin.html) 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).
pub struct SettingsPlugin {
    /// The unique name of the application.
    pub app_name: String,
}

impl SettingsPlugin {
    /// Construct a new `SettingsPlugin` for the given application name.
    pub fn new(app_name: &str) -> Self {
        Self {
            app_name: app_name.to_string(),
        }
    }
}

impl Plugin for SettingsPlugin {
    fn build(&self, app: &mut App) {
        let app_name = self.app_name.clone();
        let world = app.world();
        let last_save = world.read_change_tick();

        // Get the type registry and clone the Arc so we don't have to worry about borrowing.
        let Some(app_types) = world.get_resource::<AppTypeRegistry>() else {
            return;
        };
        let app_types = app_types.clone();
        let types = app_types.read();

        let world = app.world_mut();
        let file_index = build_settings_registry(&app_name, &types, last_save);

        // Now load each of the toml files we discovered, and apply their properties to
        // the resources in the world.
        for (filename, manifest) in file_index.files.iter() {
            load_settings_file(world, &app_name, filename, manifest, &types);
        }

        // Cache the index so that we don't have to do it again when saving (and also makes
        // saving more deterministic).
        drop(types);
        world.insert_resource::<SettingsFileRegistry>(file_index);

        app.add_systems(PostUpdate, handle_delayed_save);
    }
}

/// Trait which identifies a type as corresponding to a section with a settings file.
///
/// In order for [`SettingsPlugin`] to do anything with types that implement this trait, the type must also
/// be annotated with `#[reflect(SettingsGroup, Default)]`.
///
/// You can override the name of the section with `settings_group(group = "<name>")`.
/// For enum `SettingGroup`s, you can also override the name of its key with `settings_group(key = "<name>")`
/// The name should be in ``snake_case`` to be consistent with TOML style.
/// If there is a collision between names (multiple resources have the same name) then
/// the resulting properties will be merged into a single section.
///
/// You can also control which file the type gets saved to via
/// `settings_group(file = "<filename>")`. This should be the base name of the file without the
/// extension. The default name is `settings`, which will cause the settings to be written out
/// to `settings.toml` in the app's settings directory.
///
/// Since these resources are loaded from storage, it is possible for them to be modified by hand by users,
/// so it's important to not rely on the validity of the data. In particular, it is important to ensure you do not
/// rely on any invariants of the input data to ensure safety elsewhere in your code.
pub trait SettingsGroup: Resource + Reflect + Default {
    /// The name of the logical section within the settings file.
    fn settings_group_name() -> &'static str;

    /// The key name within the settings file.
    /// For structs, this should be set to `None`; The struct’s field names will be used as keys.
    /// For enums, the `SettingsGroup` will use this key name within the settings file for its sole key-value pair.
    /// This is typically the same as the group name, but can be customized.
    fn settings_key_name() -> Option<&'static str>;

    /// The name of the configuration file that contains this settings group.
    // TODO: Eventually convert this into an enum which represents various configuration sources.
    fn settings_source() -> Option<&'static str>;
}

/// Reflected data from a [`SettingsGroup`].
#[derive(Clone)]
pub struct ReflectSettingsGroup {
    /// The name of the logical section within the settings file.
    settings_group_name: &'static str,
    /// The key name within the settings file. Should only be `Some` for enums.
    settings_key_name: Option<&'static str>,
    /// The name of the settings file, defaults to "settings".
    settings_source: Option<&'static str>,
}

impl ReflectSettingsGroup {
    /// Returns the groups's name.
    pub fn settings_group_name(&self) -> &'static str {
        self.settings_group_name
    }

    /// Returns the key name within the settings file of this group. Should only be `Some` for enums.
    pub fn settings_key_name(&self) -> Option<&'static str> {
        self.settings_key_name
    }

    /// Returns the name of this group's settings file.
    pub fn settings_source(&self) -> Option<&'static str> {
        self.settings_source
    }
}

impl<T: SettingsGroup + FromReflect + TypePath> CreateTypeData<T> for ReflectSettingsGroup {
    fn create_type_data(_input: ()) -> Self {
        ReflectSettingsGroup {
            settings_group_name: T::settings_group_name(),
            settings_key_name: T::settings_key_name(),
            settings_source: T::settings_source(),
        }
    }

    fn insert_dependencies(type_registration: &mut TypeRegistration) {
        type_registration.register_type_data::<ReflectResource, T>();
    }
}

/// List of resource types that will be associated with a specific settings file.
/// Also tracks when that file was last written or read.
#[derive(Default)]
struct SettingsFileManifest {
    last_save: Tick,
    resource_types: Vec<TypeId>,
}

/// Records the game tick when settings were last loaded or saved. This is used to determine
/// which settings files have changed and need to be saved. Also tracks which settings files
/// are associated with which resource types.
#[derive(Resource)]
struct SettingsFileRegistry {
    /// App name (from plugin)
    app_name: String,

    /// List of known settings files, determined by scanning reflection registry.
    files: HashMap<&'static str, SettingsFileManifest>,

    /// Timer used for batched saving.
    save_timer: Timer,
}

/// A Command which saves settings to disk. This blocks the command queue until saving
/// is complete.
#[derive(Default, PartialEq)]
pub enum SaveSettingsSync {
    /// Save settings only if they have changed since the most recent load or save.
    #[default]
    IfChanged,
    /// Save settings unconditionally.
    Always,
}

impl Command for SaveSettingsSync {
    type Out = ();

    fn apply(self, world: &mut World) {
        save_settings(world, false, self == SaveSettingsSync::Always);
    }
}

/// A [`Command`] which saves settings to disk. Actual file system operations happen in another thread.
#[derive(Default, PartialEq)]
pub enum SaveSettings {
    /// Save settings only if they have changed since the most recent load or save.
    #[default]
    IfChanged,
    /// Save settings unconditionally.
    Always,
}

impl Command for SaveSettings {
    type Out = ();

    fn apply(self, world: &mut World) {
        save_settings(world, true, self == SaveSettings::Always);
    }
}

/// A Command which saves changed settings after a delay. This is debounced: issuing this
/// command multiple times resets the delay timer each time. This is meant to be used for settings
/// which change at a high frequency, such as dragging a slider which controls the game's audio
/// volume. The default delay is 1.0 seconds.
pub struct SaveSettingsDeferred(pub Duration);

impl Default for SaveSettingsDeferred {
    fn default() -> Self {
        Self(Duration::from_secs(1))
    }
}

impl Command for SaveSettingsDeferred {
    type Out = ();

    fn apply(self, world: &mut World) {
        let Some(mut registry) = world.get_resource_mut::<SettingsFileRegistry>() else {
            return;
        };

        registry.save_timer.set_duration(self.0);
        registry.save_timer.reset();
        registry.save_timer.unpause();
    }
}

fn save_settings(world: &mut World, use_async: bool, force: bool) {
    let this_run = world.change_tick();
    let Some(registry) = world.get_resource::<SettingsFileRegistry>() else {
        warn!("Settings registry not found - did you forget to install the SettingsPlugin?");
        return;
    };
    let Some(app_types) = world.get_resource::<AppTypeRegistry>() else {
        return;
    };
    let app_types = app_types.clone();
    let types = app_types.read();

    for (filename, manifest) in registry.files.iter() {
        if force || has_settings_changed(world, manifest) {
            let table = resources_to_toml(world, &types, manifest);
            let store = SettingsStore::new(&registry.app_name);
            if use_async {
                store.save_async(filename, table);
            } else {
                store.save(filename, table);
            }
        }
    }

    // Update timestamps
    let mut registry = world.get_resource_mut::<SettingsFileRegistry>().unwrap();
    for manifest in registry.files.values_mut() {
        manifest.last_save = this_run;
    }
}

fn has_settings_changed(world: &World, manifest: &SettingsFileManifest) -> bool {
    let this_run = world.read_change_tick();
    manifest.resource_types.iter().any(|r| {
        let Some(component_id) = world.components().get_id(*r) else {
            return false;
        };
        if let Some(resource_change) = world.get_resource_change_ticks_by_id(component_id) {
            return resource_change.is_changed(manifest.last_save, this_run);
        }
        false
    })
}

struct SettingsSerializerProcessor;

impl ReflectSerializerProcessor for SettingsSerializerProcessor {
    fn try_serialize<S>(
        &self,
        value: &dyn PartialReflect,
        _registry: &TypeRegistry,
        serializer: S,
    ) -> Result<Result<S::Ok, S>, S::Error>
    where
        S: serde::Serializer,
    {
        let Some(type_info) = value.get_represented_type_info() else {
            return Ok(Err(serializer));
        };

        let is_option = type_info.type_path_table().module_path() == Some("core::option")
            && type_info.type_path_table().ident() == Some("Option");

        let is_none = is_option
            && value
                .reflect_ref()
                .as_enum()
                .is_ok_and(|enum_value| enum_value.variant_name() == "None");

        // If the value is None, serialize as an empty map
        if is_none {
            let map = serializer.serialize_map(Some(0))?;
            return Ok(Ok(SerializeMap::end(map)?));
        }

        Ok(Err(serializer))
    }
}

fn resources_to_toml(
    world: &World,
    types: &TypeRegistry,
    manifest: &SettingsFileManifest,
) -> toml::map::Map<String, toml::Value> {
    let mut table = toml::Table::new();

    for tid in manifest.resource_types.iter() {
        let ty = types.get(*tid).unwrap();

        let Some(cmp) = ty.data::<ReflectComponent>() else {
            continue;
        };

        let Some(reflect_settings_group) = ty.data::<ReflectSettingsGroup>() else {
            continue;
        };

        let settings_group = reflect_settings_group.settings_group_name;
        let settings_key = reflect_settings_group.settings_key_name;

        let Some(component_id) = world.components().get_id(*tid) else {
            continue;
        };

        let Some(res_entity) = world.resource_entities().get(component_id) else {
            continue;
        };
        let res_entity_ref = world.entity(res_entity);
        let Some(reflect) = cmp.reflect(res_entity_ref) else {
            continue;
        };

        let serializer = TypedReflectSerializer::with_processor(
            reflect.as_partial_reflect(),
            types,
            &SettingsSerializerProcessor,
        );

        let toml_value = if let Some(settings_key) = settings_key {
            // convert toml value into a key value pair if settings_key is set. settings_key is only set for enums
            toml::Value::Table(toml::Table::from_iter([(
                settings_key.to_string(),
                toml::Value::try_from(serializer).unwrap(),
            )]))
        } else {
            // Otherwise, the whole struct is serialized into toml
            toml::Value::try_from(serializer).unwrap()
        };

        match (
            toml_value.as_table(),
            table
                .get_mut(settings_group)
                .and_then(|value| value.as_table_mut()),
        ) {
            (Some(from), Some(to)) => {
                // Merge the tables
                for (key, value) in from.iter() {
                    to.insert(key.clone(), value.clone());
                }
            }
            _ => {
                table.insert(settings_group.to_string(), toml_value);
            }
        };
    }

    table
}

/// Builds the settings file registry by scanning the type registry for settings resources.
/// This is separated from loading to enable testing without file I/O.
///
/// Returns the [`SettingsFileRegistry`] that tracks which resources are associated with
/// which settings files.
fn build_settings_registry(
    app_name: &str,
    types: &TypeRegistry,
    last_save: Tick,
) -> SettingsFileRegistry {
    // Build an index that remembers all of the resource types that are to be saved to
    // each individual settings file.
    let mut file_index = SettingsFileRegistry {
        app_name: app_name.to_string(),
        files: HashMap::new(),
        save_timer: Timer::new(Duration::from_secs(1), TimerMode::Once),
    };
    file_index.save_timer.pause(); // Ensure timer is initially paused

    let mut errors = Vec::new();
    // Scan through types looking for resources that have the necessary traits and
    // annotations.
    for ty in types.iter() {
        // All types that are relevant
        let Some(reflect_group) = ty.data::<ReflectSettingsGroup>() else {
            continue;
        };

        if !ty.contains::<ReflectDefault>() {
            // Collect all the errors into a single list so that a user can see all of them at once rather than chasing them
            // down one by one as they fix the errors.
            errors.push(format!(
                "Type {} has #[reflect(SettingsGroup)], which requires #[reflect(Default)] in order to save or load.",
                ty.type_info().type_path()
            ));
            continue;
        };

        // If no filename is specified, use "settings"
        let filename = reflect_group.settings_source.unwrap_or("settings");
        let pending_file = file_index
            .files
            .entry(filename)
            .or_insert(SettingsFileManifest {
                last_save,
                resource_types: Vec::new(),
            });
        pending_file.last_save = last_save;
        pending_file.resource_types.push(ty.type_id());
    }
    if !errors.is_empty() {
        panic!("{}", errors.join("\n"));
    }

    file_index
}

/// Loads a single settings file and applies its values to the world's resources.
fn load_settings_file(
    world: &mut World,
    app_name: &str,
    filename: &str,
    manifest: &SettingsFileManifest,
    types: &TypeRegistry,
) {
    // Load the TOML file
    let store = SettingsStore::new(app_name);
    let toml = store.load(filename);
    if toml.is_none() {
        warn!("Filename {filename}.toml not found");
    }

    apply_settings_to_world(world, toml.as_ref(), manifest, types);
}

/// Applies settings from a TOML table to the world's resources.
/// This is separated from file loading to enable testing without filesystem access.
///
/// For each resource type in the manifest, this function either:
/// - Updates an existing resource with values from the TOML, or
/// - Creates a new resource with default values merged with TOML values
fn apply_settings_to_world(
    world: &mut World,
    toml: Option<&toml::Table>,
    manifest: &SettingsFileManifest,
    types: &TypeRegistry,
) {
    for tid in manifest.resource_types.iter() {
        let ty = types.get(*tid).unwrap();
        let Some(reflect_settings_group) = ty.data::<ReflectSettingsGroup>() else {
            continue;
        };

        let settings_group = reflect_settings_group.settings_group_name;
        let settings_key = reflect_settings_group.settings_key_name;

        let reflect_component = ty.data::<ReflectComponent>().unwrap();
        let component_id = world.components().get_id(*tid);
        let res_entity = component_id.and_then(|cid| world.resource_entities().get(cid));

        if let Some(res_entity) = res_entity {
            // Resource already exists, so apply toml properties to it.
            let res_entity_mut = world.entity_mut(res_entity);
            let Some(mut reflect) = reflect_component.reflect_mut(res_entity_mut) else {
                continue;
            };

            if let Some(toml) = toml
                && let Some(value) = toml.get(settings_group)
            {
                let value = if let Some(settings_key) = settings_key {
                    // If there is a settings key, then we need to look one level deeper in the TOML
                    // to find the actual properties to apply to the resource.
                    value.get(settings_key).unwrap_or(value)
                } else {
                    // No settings key, so we can apply the whole section to the resource
                    value
                };

                load_properties(value, &mut *reflect, types);
            }
        } else {
            // The resource does not exist, so create a default.
            let reflect_default = ty.data::<ReflectDefault>().unwrap();
            let mut default_value = reflect_default.default();
            let mut res_entity = world.spawn_empty();

            if let Some(toml) = toml
                && let Some(value) = toml.get(settings_group)
            {
                let value = if let Some(settings_key) = settings_key {
                    // If there is a settings key, then we need to look one level deeper in the TOML
                    // to find the actual properties to apply to the resource.
                    value.get(settings_key).unwrap_or(value)
                } else {
                    // No settings key, so we can apply the whole section to the resource
                    value
                };

                load_properties(value, &mut *default_value, types);
            }

            // Now add the new resource to the world.
            reflect_component.insert(&mut res_entity, default_value.as_partial_reflect(), types);
        }
    }
}

fn is_option_type(type_info: &TypeInfo) -> bool {
    type_info.type_path_table().module_path() == Some("core::option")
        && type_info.type_path_table().ident() == Some("Option")
}

fn load_properties(value: &toml::Value, resource: &mut dyn PartialReflect, types: &TypeRegistry) {
    let Some(tinfo) = resource.get_represented_type_info() else {
        return;
    };

    match tinfo {
        TypeInfo::Struct(stinfo) => {
            if let Some(table) = value.as_table()
                && let ReflectMut::Struct(st_reflect) = resource.reflect_mut()
            {
                // Deserialize matching field names, ignore ones that don't match.
                for (idx, field) in stinfo.field_names().iter().enumerate() {
                    if let Some(toml_field_value) = table.get(*field)
                        && let Some(field_info) = stinfo.field_at(idx)
                        && let Some(field_type) = types.get(field_info.type_id())
                    {
                        let field = st_reflect.field_at_mut(idx).unwrap();
                        if is_option_type(field_type.type_info())
                            && toml_field_value
                                .as_table()
                                .is_some_and(toml::Table::is_empty)
                        {
                            let mut none = DynamicEnum::new_with_index(0, "None", ());
                            none.set_represented_type(Some(field_type.type_info()));
                            field.apply(none.as_partial_reflect());
                        } else {
                            let deserializer = TypedReflectDeserializer::new(field_type, types);
                            if let Ok(field_value) =
                                deserializer.deserialize(toml_field_value.clone())
                            {
                                field.apply(&*field_value);
                            }
                        }
                    }
                }
            }
        }
        TypeInfo::TupleStruct(tstinfo) => {
            if let ReflectMut::TupleStruct(tst_reflect) = resource.reflect_mut() {
                // tuple structs with length > 1 are always serialized as arrays
                if tst_reflect.field_len() > 1
                    && let Some(array) = value.as_array()
                {
                    for (idx, toml_field_value) in array.iter().enumerate() {
                        if let Some(field_info) = tstinfo.field_at(idx)
                            && let Some(field_type) = types.get(field_info.type_id())
                        {
                            let deserializer = TypedReflectDeserializer::new(field_type, types);
                            if let Ok(field_value) =
                                deserializer.deserialize(toml_field_value.clone())
                            {
                                // Should be safe to unwrap here since we know the field exists (above).
                                tst_reflect.field_mut(idx).unwrap().apply(&*field_value);
                            }
                        }
                    }
                } else if tst_reflect.field_len() == 1
                    && let Some(field_info) = tstinfo.field_at(0)
                    && let Some(field_type) = types.get(field_info.type_id())
                {
                    let deserializer = TypedReflectDeserializer::new(field_type, types);
                    if let Ok(field_value) = deserializer.deserialize(value.clone()) {
                        // Should be safe to unwrap here since we know the field exists (above).
                        tst_reflect.field_mut(0).unwrap().apply(&*field_value);
                    }
                }
            }
        }
        TypeInfo::Enum(einfo) => {
            if let ReflectMut::Enum(en_reflect) = resource.reflect_mut()
                && let Some(variant_type) = types.get(einfo.type_id())
            {
                let deserializer = TypedReflectDeserializer::new(variant_type, types);

                if let Ok(variant_value) = deserializer.deserialize(value.clone()) {
                    en_reflect.apply(&*variant_value);
                }
            }
        }
        _ => {}
    }
}

fn handle_delayed_save(
    mut settings: ResMut<SettingsFileRegistry>,
    time: Res<Time<Real>>,
    mut commands: Commands,
) {
    settings.save_timer.tick(time.delta());
    if settings.save_timer.just_finished() {
        commands.queue(SaveSettings::IfChanged);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use bevy_ecs::{change_detection::Tick, schedule::Schedule};
    use bevy_reflect::Reflect;
    use bevy_time::Virtual;
    // Required to make proc macros work in bevy itself.
    extern crate self as bevy_settings;

    /// Test resource that uses default settings group name (derived from type name)
    #[derive(Resource, SettingsGroup, Reflect, Default)]
    #[reflect(Resource, SettingsGroup, Default)]
    struct CounterSettings {
        count: i32,
    }

    /// Test resource that shares the same settings group name as another resource
    #[derive(Resource, SettingsGroup, Reflect, Default)]
    #[reflect(Resource, SettingsGroup, Default)]
    #[settings_group(group = "counter_settings")]
    struct ExtraCounterSettings {
        enabled: bool,
    }

    #[derive(Resource, SettingsGroup, Reflect, Debug, Default, PartialEq)]
    #[reflect(Resource, SettingsGroup, Default)]
    #[settings_group(group = "counter_settings", key = "refresh_rate")]
    enum CounterRefreshRateSettings {
        #[default]
        Slow,
        Fast,
    }

    /// Test resource that uses a different settings file
    #[derive(Resource, SettingsGroup, Reflect, Default)]
    #[reflect(Resource, SettingsGroup, Default)]
    #[settings_group(file = "audio")]
    struct AudioSettings {
        volume: f32,
    }

    #[derive(Resource, SettingsGroup, Reflect, Default)]
    #[reflect(Resource, SettingsGroup, Default)]
    struct OptionalSettings {
        value: Option<u32>,
    }

    #[test]
    fn test_build_registry_single_struct_resource() {
        let mut types = TypeRegistry::default();
        types.register::<CounterSettings>();

        let registry = build_settings_registry("test_app", &types, Tick::new(0));

        assert_eq!(registry.app_name, "test_app");
        assert_eq!(registry.files.len(), 1);
        assert!(registry.files.contains_key("settings"));

        let manifest = registry.files.get("settings").unwrap();
        assert_eq!(manifest.resource_types.len(), 1);
    }

    #[test]
    fn test_build_registry_single_enum_resource() {
        let mut types = TypeRegistry::default();
        types.register::<CounterRefreshRateSettings>();

        let registry = build_settings_registry("test_app", &types, Tick::new(0));

        assert_eq!(registry.app_name, "test_app");
        assert_eq!(registry.files.len(), 1);
        assert!(registry.files.contains_key("settings"));

        let manifest = registry.files.get("settings").unwrap();
        assert_eq!(manifest.resource_types.len(), 1);
    }

    #[test]
    fn test_build_registry_merged_groups() {
        let mut types = TypeRegistry::default();
        types.register::<CounterSettings>();
        types.register::<ExtraCounterSettings>();

        let registry = build_settings_registry("test_app", &types, Tick::new(0));

        // Both resources should be in the same file
        assert_eq!(registry.files.len(), 1);
        assert!(registry.files.contains_key("settings"));

        let manifest = registry.files.get("settings").unwrap();
        // Both resources should be tracked
        assert_eq!(manifest.resource_types.len(), 2);
    }

    #[test]
    fn test_build_registry_separate_files() {
        let mut types = TypeRegistry::default();
        types.register::<CounterSettings>();
        types.register::<AudioSettings>();

        let registry = build_settings_registry("test_app", &types, Tick::new(0));

        // Resources should be in different files
        assert_eq!(registry.files.len(), 2);
        assert!(registry.files.contains_key("settings"));
        assert!(registry.files.contains_key("audio"));

        let settings_manifest = registry.files.get("settings").unwrap();
        assert_eq!(settings_manifest.resource_types.len(), 1);

        let audio_manifest = registry.files.get("audio").unwrap();
        assert_eq!(audio_manifest.resource_types.len(), 1);
    }

    #[test]
    fn test_resources_to_toml_merges_same_group() {
        let mut world = World::new();
        let mut types = TypeRegistry::default();
        types.register::<CounterSettings>();
        types.register::<ExtraCounterSettings>();
        types.register::<CounterRefreshRateSettings>();

        // Insert both resources
        world.insert_resource(CounterSettings { count: 42 });
        world.insert_resource(ExtraCounterSettings { enabled: true });
        world.insert_resource(CounterRefreshRateSettings::Fast);

        // Build a manifest with both resource types
        let manifest = SettingsFileManifest {
            last_save: Tick::new(0),
            resource_types: vec![
                TypeId::of::<CounterSettings>(),
                TypeId::of::<ExtraCounterSettings>(),
                TypeId::of::<CounterRefreshRateSettings>(),
            ],
        };

        let table = resources_to_toml(&world, &types, &manifest);

        // Both resources should be merged into the same "counter_settings" section
        assert!(table.contains_key("counter_settings"));
        let counter_section = table.get("counter_settings").unwrap().as_table().unwrap();

        // Check that fields are present in the merged section
        assert_eq!(
            counter_section.get("count").unwrap().as_integer().unwrap(),
            42
        );
        assert!(counter_section.get("enabled").unwrap().as_bool().unwrap());
        assert_eq!(
            counter_section
                .get("refresh_rate")
                .unwrap()
                .as_str()
                .unwrap(),
            "Fast"
        );
    }

    #[test]
    fn test_round_trip_serialization() {
        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug, Default)]
        #[reflect(Resource, SettingsGroup, Default)]
        struct SingleFieldTupleStruct(u8);

        #[derive(Reflect, PartialEq, Debug, Default)]
        #[reflect(Default)]
        struct NestedStruct {
            a: u8,
            b: u16,
        }

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug, Default)]
        #[reflect(Resource, SettingsGroup, Default)]
        struct MultiFieldTupleStruct(u8, NestedStruct);

        #[derive(Resource, SettingsGroup, Reflect, Default)]
        #[reflect(Resource, SettingsGroup, Default)]
        struct NewTypeSingleTupleStruct(SingleFieldTupleStruct);

        #[derive(Resource, SettingsGroup, Reflect, Default)]
        #[reflect(Resource, SettingsGroup, Default)]
        struct NewTypeMultiTupleStruct(SingleFieldTupleStruct, MultiFieldTupleStruct);

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug, Default)]
        #[reflect(Resource, SettingsGroup, Default)]
        enum EnumUnitVariant {
            #[default]
            A,
        }

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug)]
        #[reflect(Resource, SettingsGroup, Default)]
        enum EnumSingleTupleVariant {
            A(u8),
        }

        impl Default for EnumSingleTupleVariant {
            fn default() -> Self {
                EnumSingleTupleVariant::A(0)
            }
        }

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug)]
        #[reflect(Resource, SettingsGroup, Default)]
        enum EnumMultiTupleVariant {
            A(u16, u32),
        }

        impl Default for EnumMultiTupleVariant {
            fn default() -> Self {
                EnumMultiTupleVariant::A(0, 0)
            }
        }

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug)]
        #[reflect(Resource, SettingsGroup, Default)]
        enum EnumStructVariant {
            A { x: u8, y: u16 },
        }

        impl Default for EnumStructVariant {
            fn default() -> Self {
                EnumStructVariant::A { x: 0, y: 0 }
            }
        }

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug)]
        #[reflect(Resource, SettingsGroup, Default)]
        enum EnumSingleNewTypeVariant {
            A(SingleFieldTupleStruct),
        }

        impl Default for EnumSingleNewTypeVariant {
            fn default() -> Self {
                EnumSingleNewTypeVariant::A(SingleFieldTupleStruct(0))
            }
        }

        #[derive(Resource, SettingsGroup, Reflect, PartialEq, Debug)]
        #[reflect(Resource, SettingsGroup, Default)]
        enum EnumMultiNewTypeVariant {
            A(SingleFieldTupleStruct, MultiFieldTupleStruct),
        }

        impl Default for EnumMultiNewTypeVariant {
            fn default() -> Self {
                EnumMultiNewTypeVariant::A(
                    SingleFieldTupleStruct(0),
                    MultiFieldTupleStruct(0, NestedStruct { a: 0, b: 0 }),
                )
            }
        }

        let mut world = World::new();
        let mut types = TypeRegistry::default();

        types.register::<CounterSettings>();
        types.register::<ExtraCounterSettings>();
        types.register::<CounterRefreshRateSettings>();
        types.register::<SingleFieldTupleStruct>();
        types.register::<MultiFieldTupleStruct>();
        types.register::<NewTypeSingleTupleStruct>();
        types.register::<NewTypeMultiTupleStruct>();
        types.register::<EnumUnitVariant>();
        types.register::<EnumSingleTupleVariant>();
        types.register::<EnumMultiTupleVariant>();
        types.register::<EnumStructVariant>();
        types.register::<EnumSingleNewTypeVariant>();
        types.register::<EnumMultiNewTypeVariant>();

        // Insert resources with specific values
        world.insert_resource(CounterSettings { count: 123 });
        world.insert_resource(ExtraCounterSettings { enabled: false });
        world.insert_resource(CounterRefreshRateSettings::Fast);
        world.insert_resource(SingleFieldTupleStruct(1));
        world.insert_resource(MultiFieldTupleStruct(2, NestedStruct { a: 1, b: 2 }));
        world.insert_resource(NewTypeSingleTupleStruct(SingleFieldTupleStruct(1)));
        world.insert_resource(NewTypeMultiTupleStruct(
            SingleFieldTupleStruct(1),
            MultiFieldTupleStruct(2, NestedStruct { a: 1, b: 2 }),
        ));
        world.insert_resource(EnumUnitVariant::A);
        world.insert_resource(EnumSingleTupleVariant::A(1));
        world.insert_resource(EnumMultiTupleVariant::A(1, 2));
        world.insert_resource(EnumStructVariant::A { x: 1, y: 2 });
        world.insert_resource(EnumSingleNewTypeVariant::A(SingleFieldTupleStruct(1)));
        world.insert_resource(EnumMultiNewTypeVariant::A(
            SingleFieldTupleStruct(1),
            MultiFieldTupleStruct(2, NestedStruct { a: 1, b: 2 }),
        ));

        // Build a manifest with both resource types
        let manifest = SettingsFileManifest {
            last_save: Tick::new(0),
            resource_types: vec![
                TypeId::of::<CounterSettings>(),
                TypeId::of::<ExtraCounterSettings>(),
                TypeId::of::<CounterRefreshRateSettings>(),
                TypeId::of::<SingleFieldTupleStruct>(),
                TypeId::of::<MultiFieldTupleStruct>(),
                TypeId::of::<NewTypeSingleTupleStruct>(),
                TypeId::of::<NewTypeMultiTupleStruct>(),
                TypeId::of::<EnumUnitVariant>(),
                TypeId::of::<EnumSingleTupleVariant>(),
                TypeId::of::<EnumMultiTupleVariant>(),
                TypeId::of::<EnumStructVariant>(),
                TypeId::of::<EnumSingleNewTypeVariant>(),
                TypeId::of::<EnumMultiNewTypeVariant>(),
            ],
        };

        // Serialize to TOML
        let table = resources_to_toml(&world, &types, &manifest);

        // Create a new world and apply the TOML
        let mut new_world = World::new();
        apply_settings_to_world(&mut new_world, Some(&table), &manifest, &types);

        // Verify resources were created with correct values
        let counter = new_world.get_resource::<CounterSettings>().unwrap();
        assert_eq!(counter.count, 123);

        let extra = new_world.get_resource::<ExtraCounterSettings>().unwrap();
        assert!(!extra.enabled);

        let refresh_rate = new_world
            .get_resource::<CounterRefreshRateSettings>()
            .unwrap();
        assert_eq!(*refresh_rate, CounterRefreshRateSettings::Fast);

        let single_field_tuple_struct = new_world.get_resource::<SingleFieldTupleStruct>().unwrap();
        assert_eq!(single_field_tuple_struct.0, 1);

        let multi_field_tuple_struct = new_world.get_resource::<MultiFieldTupleStruct>().unwrap();
        assert_eq!(multi_field_tuple_struct.0, 2);
        assert_eq!(multi_field_tuple_struct.1.a, 1);
        assert_eq!(multi_field_tuple_struct.1.b, 2);

        let new_type_single_tuple_struct = new_world
            .get_resource::<NewTypeSingleTupleStruct>()
            .unwrap();
        assert_eq!(new_type_single_tuple_struct.0 .0, 1);

        let new_type_multi_tuple_struct =
            new_world.get_resource::<NewTypeMultiTupleStruct>().unwrap();
        assert_eq!(new_type_multi_tuple_struct.0 .0, 1);
        assert_eq!(new_type_multi_tuple_struct.1 .0, 2);
        assert_eq!(new_type_multi_tuple_struct.1 .1.a, 1);
        assert_eq!(new_type_multi_tuple_struct.1 .1.b, 2);

        let enum_unit_variant = new_world.get_resource::<EnumUnitVariant>().unwrap();
        assert_eq!(*enum_unit_variant, EnumUnitVariant::A);

        let enum_single_tuple_variant = new_world.get_resource::<EnumSingleTupleVariant>().unwrap();
        assert_eq!(*enum_single_tuple_variant, EnumSingleTupleVariant::A(1));

        let enum_multi_tuple_variant = new_world.get_resource::<EnumMultiTupleVariant>().unwrap();
        assert_eq!(*enum_multi_tuple_variant, EnumMultiTupleVariant::A(1, 2));

        let enum_struct_variant = new_world.get_resource::<EnumStructVariant>().unwrap();
        assert_eq!(*enum_struct_variant, EnumStructVariant::A { x: 1, y: 2 });

        let enum_single_new_type_variant = new_world
            .get_resource::<EnumSingleNewTypeVariant>()
            .unwrap();
        assert_eq!(
            *enum_single_new_type_variant,
            EnumSingleNewTypeVariant::A(SingleFieldTupleStruct(1))
        );

        let enum_multi_new_type_variant =
            new_world.get_resource::<EnumMultiNewTypeVariant>().unwrap();
        assert_eq!(
            *enum_multi_new_type_variant,
            EnumMultiNewTypeVariant::A(
                SingleFieldTupleStruct(1),
                MultiFieldTupleStruct(2, NestedStruct { a: 1, b: 2 })
            )
        );
    }

    #[test]
    fn test_round_trip_with_existing_resources() {
        let mut world = World::new();
        let mut types = TypeRegistry::default();
        types.register::<CounterSettings>();
        types.register::<CounterRefreshRateSettings>();

        // Insert resource with initial values
        world.insert_resource(CounterSettings { count: 100 });
        world.insert_resource(CounterRefreshRateSettings::Fast);

        let manifest = SettingsFileManifest {
            last_save: Tick::new(0),
            resource_types: vec![
                TypeId::of::<CounterSettings>(),
                TypeId::of::<CounterRefreshRateSettings>(),
            ],
        };

        // Serialize
        let table = resources_to_toml(&world, &types, &manifest);

        // Modify the resource
        world.resource_mut::<CounterSettings>().count = 999;
        *world.resource_mut::<CounterRefreshRateSettings>() = CounterRefreshRateSettings::Slow;

        // Apply TOML (should restore the original value)
        apply_settings_to_world(&mut world, Some(&table), &manifest, &types);

        let counter = world.get_resource::<CounterSettings>().unwrap();
        assert_eq!(counter.count, 100);
        let refresh_rate = world.get_resource::<CounterRefreshRateSettings>().unwrap();
        assert_eq!(*refresh_rate, CounterRefreshRateSettings::Fast);
    }

    #[test]
    fn test_partial_toml_preserves_missing_fields() {
        let mut world = World::new();
        let mut types = TypeRegistry::default();
        types.register::<CounterSettings>();
        types.register::<ExtraCounterSettings>();
        types.register::<CounterRefreshRateSettings>();

        // Insert resources with specific values
        world.insert_resource(CounterSettings { count: 50 });
        world.insert_resource(ExtraCounterSettings { enabled: true });
        world.insert_resource(CounterRefreshRateSettings::Fast);

        // Create a TOML table that only contains one field from one resource
        let mut table = toml::Table::new();
        let mut counter_section = toml::Table::new();
        counter_section.insert("count".to_string(), toml::Value::Integer(999));
        table.insert(
            "counter_settings".to_string(),
            toml::Value::Table(counter_section),
        );
        // Note: "enabled" field is missing from the TOML

        let manifest = SettingsFileManifest {
            last_save: Tick::new(0),
            resource_types: vec![
                TypeId::of::<CounterSettings>(),
                TypeId::of::<ExtraCounterSettings>(),
                TypeId::of::<CounterRefreshRateSettings>(),
            ],
        };

        // Apply the partial TOML
        apply_settings_to_world(&mut world, Some(&table), &manifest, &types);

        // Verify count was updated
        let counter = world.get_resource::<CounterSettings>().unwrap();
        assert_eq!(counter.count, 999);

        // Verify enabled was preserved (not overwritten with default false)
        let extra = world.get_resource::<ExtraCounterSettings>().unwrap();
        assert!(extra.enabled);

        // Verify refresh_rate was preserved
        let refresh_rate = world.get_resource::<CounterRefreshRateSettings>().unwrap();
        assert_eq!(*refresh_rate, CounterRefreshRateSettings::Fast);
    }

    #[test]
    fn test_handle_delayed_save_ticks_with_real_time_while_paused() {
        let mut world = World::new();
        world.insert_resource(Time::<Real>::default());
        world.insert_resource(Time::<Virtual>::default());
        // Virtual time is paused, so the delayed save timer must use real time.
        world.resource_mut::<Time<Virtual>>().pause();

        // SettingsFileRegistry with a delayed save timer
        world.insert_resource(SettingsFileRegistry {
            app_name: "test_app".to_string(),
            files: HashMap::new(),
            save_timer: {
                let mut timer = Timer::new(Duration::from_millis(500), TimerMode::Once);
                timer.unpause();
                timer
            },
        });

        // Simulate real time advancing
        world
            .resource_mut::<Time<Real>>()
            .advance_by(Duration::from_millis(600));

        let mut schedule = Schedule::default();
        schedule.add_systems(handle_delayed_save);
        schedule.run(&mut world);

        let registry = world.resource::<SettingsFileRegistry>();
        assert!(registry.save_timer.just_finished());
    }

    #[test]
    fn test_none_value_apply_settings() {
        let mut world = World::new();
        let mut other_world = World::new();
        let mut types = TypeRegistry::default();

        types.register::<OptionalSettings>();

        let manifest = SettingsFileManifest {
            last_save: Tick::new(0),
            resource_types: vec![TypeId::of::<OptionalSettings>()],
        };

        world.insert_resource(OptionalSettings { value: None });
        let table = resources_to_toml(&world, &types, &manifest);

        other_world.insert_resource(OptionalSettings { value: Some(12) });
        apply_settings_to_world(&mut other_world, Some(&table), &manifest, &types);

        let settings = other_world.get_resource::<OptionalSettings>().unwrap();
        assert_eq!(settings.value, None);
    }
}