supreme_hook_config/

mods_state.rs

//! On-disk I/O for the mods directory's single state file: [`ModsState`]
//! (persisted as `mods.json`), which replaces the older
//! `enabled_mods.json` + `mod_configuration.json` pair. Consolidating them
//! fixes a specific bug in that older layout: with two files, a mod's
//! *display* position was reconstructed at load time from which bucket it
//! happened to be in (enabled vs. not), so toggling a mod would visibly
//! reshuffle the whole list.
//!
//! [`ModsPreset`] is the one shape used both for the live, currently-applied
//! configuration ([`ModsState::active`]) and for every saved, not-currently
//! -active preset in [`ModsState::presets`], deliberately the same type,
//! not two structs that happen to share field names. Each carries its own
//! full `order` (display position, doubling as DLL merge-priority order,
//! see [`ModsPreset::priority_order`]) alongside `enabled` (membership) and
//! `configuration` (per-mod overrides). `order` is never touched by
//! enabling/disabling a mod, only by an explicit reorder or by
//! [`ModsState::sync_active_order`] reconciling it against what's actually
//! installed on disk.
//!
//! Applying a saved preset ([`ModsState::apply_preset`]) is a plain
//! `active = preset.clone`, the preset's `order` becomes the new display
//! order outright, dropping any locally-installed mod the preset doesn't
//! mention. Those dropped mods aren't lost: the next
//! [`ModsState::sync_active_order`] call (part of every `discover_mods`
//! scan) re-appends every installed mod not already in `active.order`, so
//! the launcher's list still shows every installed mod after switching
//! presets, just with the preset's chosen mods first, in the preset's
//! order, and everything else appended after.

use crate::error::HookConfigError;
use std::collections::HashMap;
use std::path::Path;

/// Every mod's current parameter *overrides*, values a person has
/// actually set via the launcher, keyed by mod directory name, then by
/// [`crate::mod_config::ModParameter::id`], layered on top of that mod's
/// own [`crate::mod_config::ModConfig::configuration`] defaults at
/// resolution time (see
/// [`crate::mod_config::ModConfig::effective_configuration`]).
pub type ModConfigurations = HashMap<String, HashMap<String, serde_json::Value>>;

/// The on-disk mods directory, relative to the game's root directory.
/// Layout:
/// - `<mods_dir>/mods.json`, the single state file described by
///   [`ModsState`].
/// - `<mods_dir>/<mod_name>/mod.json`, that mod's own metadata, rules,
///   parameters, and default values for them, see
///   [`crate::mod_config::ModConfig`]. This is the author's distributable
///   definition: reinstalling or updating a mod means replacing this whole
///   file (and the mod's other assets), which is exactly why per-user
///   *overrides* live in [`ModsState`] instead, an update can safely
///   replace even a mod's defaults without touching what a person has
///   personally changed.
pub const DEFAULT_MODS_DIR_NAME: &str = ".supreme/mods";
/// File name, within [`DEFAULT_MODS_DIR_NAME`], holding [`ModsState`].
pub const MODS_STATE_FILE_NAME: &str = "mods.json";
/// File name, within each mod's own subdirectory, holding that mod's
/// metadata, rules and parameters.
pub const MOD_FILE_NAME: &str = "mod.json";

/// A full mod configuration: every known mod's display order, which of
/// them are enabled, and their settings. Used both as the live,
/// currently-applied configuration ([`ModsState::active`]) and as a named,
/// saved shortcut ([`ModsState::presets`]), the same shape either way, so
/// "the active configuration" and "a saved preset" can never structurally
/// drift apart.
#[derive(serde::Serialize, serde::Deserialize, Debug, Clone, Default, PartialEq)]
pub struct ModsPreset {
    /// Every mod's directory name this configuration knows about, in
    /// display order, including disabled ones. For the *active*
    /// configuration this also doubles as DLL merge-priority order (see
    /// [`ModsPreset::priority_order`]): dragging a mod in the launcher's
    /// list both moves it on screen and changes where it merges relative
    /// to other enabled mods, deliberately, since those are the same
    /// action. For a saved-but-inactive preset, `order` is simply frozen
    /// at save time until the preset is applied.
    #[serde(default)]
    pub order: Vec<String>,
    /// Which mods (by directory name) are enabled, membership only,
    /// order is meaningless here. This configuration's actual priority
    /// order is always `order` filtered to this set, computed on demand
    /// by [`ModsPreset::priority_order`], never stored separately, so it
    /// can never drift from what `order` shows.
    #[serde(default)]
    pub enabled: Vec<String>,
    /// Every enabled mod's current parameter overrides, keyed by mod
    /// directory name. A mod with no entry here simply has no overrides,
    /// every parameter falls back to that mod's own
    /// [`crate::mod_config::ModConfig::configuration`] default, or fully
    /// unset if it doesn't have one either.
    #[serde(default)]
    pub configuration: ModConfigurations,
}

impl ModsPreset {
    /// This configuration's effective merge-priority order: every name in
    /// [`Self::order`] that's also in [`Self::enabled`], in `order`'s
    /// order. Deliberately computed rather than stored, display order
    /// *is* priority order, with no second copy that could disagree with
    /// what the launcher's list shows.
    pub fn priority_order(&self) -> Vec<&str> {
        let enabled_set: std::collections::HashSet<&str> =
            self.enabled.iter().map(String::as_str).collect();
        self.order
            .iter()
            .map(String::as_str)
            .filter(|name| enabled_set.contains(name))
            .collect()
    }

    /// Reconciles [`Self::order`] against `discovered`, the mod
    /// directory names actually found under `mods_dir` right now. Mods
    /// present in `discovered` but not yet in `order` are appended at the
    /// end, in `discovered`'s order (stable but otherwise arbitrary among
    /// newly-seen mods, typically already alphabetical, since callers
    /// usually pass a sorted directory listing). Mods in `order` but no
    /// longer in `discovered` are dropped. Existing entries keep their
    /// relative position.
    ///
    /// This never touches [`Self::enabled`], membership isn't affected
    /// by a mod folder simply appearing or disappearing on disk, only by
    /// an explicit enable/disable.
    pub fn sync_order<I, S>(&mut self, discovered: I)
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        let discovered: Vec<String> = discovered.into_iter().map(Into::into).collect();
        let discovered_set: std::collections::HashSet<&str> =
            discovered.iter().map(String::as_str).collect();

        self.order
            .retain(|name| discovered_set.contains(name.as_str()));

        let known: std::collections::HashSet<String> = self.order.iter().cloned().collect();
        for name in discovered {
            if !known.contains(&name) {
                self.order.push(name);
            }
        }
    }

    /// Sets which mods are enabled to exactly `enabled_names`,
    /// membership only; their relative priority is still whatever `order`
    /// says (see [`Self::priority_order`]), unaffected by the order
    /// `enabled_names` happens to be given in. Call this after a checkbox
    /// toggle. Does not touch `order`, dragging to reorder is a
    /// separate, direct assignment to that field.
    pub fn set_enabled<'a>(&mut self, enabled_names: impl IntoIterator<Item = &'a str>) {
        self.enabled = enabled_names.into_iter().map(str::to_string).collect();
    }
}

/// The full persisted state of a game's mods directory: the currently-
/// active configuration, and any named presets saved for later.
///
/// No launcher UI surfaces `presets` yet, the field exists so the format
/// doesn't need to change again once that lands.
#[derive(serde::Serialize, serde::Deserialize, Debug, Clone, Default, PartialEq)]
pub struct ModsState {
    /// The live, currently-applied configuration, what the game actually
    /// uses, and what the launcher's Mods page displays and edits
    /// directly. See [`ModsPreset`] for its shape.
    #[serde(default)]
    pub active: ModsPreset,
    /// Named presets a person has saved, keyed by preset name. Applying
    /// one ([`ModsState::apply_preset`]) replaces `active` wholesale.
    #[serde(default)]
    pub presets: HashMap<String, ModsPreset>,
}

impl ModsState {
    /// Reconciles [`ModsState::active`]'s order against `discovered`, see
    /// [`ModsPreset::sync_order`]. A thin forward to the active
    /// configuration specifically; a saved-but-inactive preset in
    /// `presets` is never touched by this, since its `order` should stay
    /// frozen exactly as saved until it's applied.
    pub fn sync_active_order<I, S>(&mut self, discovered: I)
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.active.sync_order(discovered);
    }

    /// Applies a saved preset as the new active configuration: `active`
    /// becomes an exact copy of `preset`, same `order`, `enabled`, and
    /// `configuration`. This can drop locally-installed mods the preset
    /// doesn't mention from `active.order` entirely; they aren't lost,
    /// they're just no longer part of this configuration until the next
    /// [`ModsState::sync_active_order`] call (part of every
    /// `discover_mods` scan) re-appends every installed mod not already
    /// present, so the launcher's list still shows every installed mod,
    /// the preset's own mods first, in the preset's order, then everything
    /// else appended after.
    ///
    /// `presets` itself is untouched, applying a preset doesn't consume
    /// or modify it, so it can be applied again later.
    pub fn apply_preset(&mut self, preset: &ModsPreset) {
        self.active = preset.clone();
    }
}

/// Reads [`ModsState`] from `<mods_dir>/mods.json`. A missing file
/// reads as a fresh, empty state rather than an error, the common state
/// before `.supreme/mods/` has ever been created, e.g. right after a fresh
/// install.
///
/// # Errors
///
/// Returns an error if the file exists but isn't valid JSON.
pub fn load_mods_state(mods_dir: &Path) -> Result<ModsState, HookConfigError> {
    let path = mods_dir.join(MODS_STATE_FILE_NAME);
    match std::fs::read(&path) {
        Ok(bytes) => Ok(serde_json::from_slice(&bytes)?),
        Err(source) if source.kind() == std::io::ErrorKind::NotFound => Ok(ModsState::default()),
        Err(source) => Err(HookConfigError::Read { path, source }),
    }
}

/// Writes `state` to `<mods_dir>/mods.json`, creating `mods_dir` if
/// it doesn't exist yet.
///
/// # Errors
///
/// Returns an error if `mods_dir` can't be created or the file can't be
/// written.
pub fn save_mods_state(mods_dir: &Path, state: &ModsState) -> Result<(), HookConfigError> {
    std::fs::create_dir_all(mods_dir).map_err(|source| HookConfigError::Write {
        path: mods_dir.to_path_buf(),
        source,
    })?;
    let path = mods_dir.join(MODS_STATE_FILE_NAME);
    let json = serde_json::to_vec_pretty(state)?;
    std::fs::write(&path, json).map_err(|source| HookConfigError::Write { path, source })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn missing_file_reads_as_default_state() {
        let dir = tempfile::tempdir().unwrap();
        assert_eq!(load_mods_state(dir.path()).unwrap(), ModsState::default());
    }

    #[test]
    fn invalid_json_is_an_error() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join(MODS_STATE_FILE_NAME), b"not json").unwrap();
        assert!(load_mods_state(dir.path()).is_err());
    }

    #[test]
    fn round_trips_through_disk() {
        let dir = tempfile::tempdir().unwrap();
        let mods_dir = dir.path().join(".supreme/mods");

        let mut state = ModsState::default();
        state.active.order = vec!["a_mod".to_string(), "b_mod".to_string()];
        state.active.enabled = vec!["b_mod".to_string()];
        state.active.configuration.insert(
            "b_mod".to_string(),
            HashMap::from([("Flag".to_string(), serde_json::json!(true))]),
        );
        state.presets.insert(
            "My Preset".to_string(),
            ModsPreset {
                order: vec!["a_mod".to_string()],
                enabled: vec!["a_mod".to_string()],
                configuration: ModConfigurations::new(),
            },
        );

        save_mods_state(&mods_dir, &state).unwrap();
        assert_eq!(load_mods_state(&mods_dir).unwrap(), state);
    }

    #[test]
    fn sync_active_order_appends_new_and_drops_missing_preserving_relative_order() {
        let mut state = ModsState::default();
        state.active.order = vec![
            "zebra_mod".to_string(),
            "alpha_mod".to_string(),
            "removed_mod".to_string(),
        ];

        // "removed_mod" is gone; "new_mod" just appeared. Discovery order
        // here is alphabetical, as a sorted dir listing would produce.
        state.sync_active_order(["alpha_mod", "new_mod", "zebra_mod"]);

        assert_eq!(
            state.active.order,
            vec![
                "zebra_mod".to_string(),
                "alpha_mod".to_string(),
                "new_mod".to_string(),
            ]
        );
    }

    #[test]
    fn sync_active_order_is_idempotent_when_nothing_changed() {
        let mut state = ModsState::default();
        state.active.order = vec!["b_mod".to_string(), "a_mod".to_string()];
        let before = state.active.order.clone();

        state.sync_active_order(["a_mod", "b_mod"]);

        assert_eq!(state.active.order, before);
    }

    #[test]
    fn sync_active_order_never_touches_saved_presets() {
        let mut state = ModsState::default();
        state.active.order = vec!["alpha_mod".to_string()];
        state.presets.insert(
            "Racing".to_string(),
            ModsPreset {
                order: vec!["ghost_mod".to_string()],
                enabled: vec!["ghost_mod".to_string()],
                configuration: ModConfigurations::new(),
            },
        );

        // "ghost_mod" isn't discovered on disk at all, only the active
        // configuration should be reconciled against that; the saved
        // preset's frozen order must stay exactly as saved.
        state.sync_active_order(["alpha_mod"]);

        assert_eq!(
            state.presets.get("Racing").unwrap().order,
            vec!["ghost_mod".to_string()]
        );
    }

    #[test]
    fn toggling_enabled_never_reorders_active_order() {
        // The regression this whole module exists to fix: disabling then
        // re-enabling a mod must not move it in the display list.
        let mut state = ModsState::default();
        state.active.order = vec![
            "alpha_mod".to_string(),
            "beta_mod".to_string(),
            "gamma_mod".to_string(),
        ];
        state
            .active
            .set_enabled(["alpha_mod", "beta_mod", "gamma_mod"]);
        let order_before = state.active.order.clone();

        // Disable beta_mod (simulating a UI toggle: membership shrinks,
        // order is untouched).
        state.active.set_enabled(["alpha_mod", "gamma_mod"]);
        assert_eq!(state.active.order, order_before);
        assert_eq!(
            state.active.priority_order(),
            vec!["alpha_mod", "gamma_mod"]
        );

        // Re-enable it, priority order follows order's original relative
        // position, not the order re-enabling happened in.
        state
            .active
            .set_enabled(["gamma_mod", "alpha_mod", "beta_mod"]);
        assert_eq!(state.active.order, order_before);
        assert_eq!(
            state.active.priority_order(),
            vec!["alpha_mod", "beta_mod", "gamma_mod"]
        );
    }

    #[test]
    fn priority_order_follows_order_not_enabled_order() {
        let mut state = ModsState::default();
        state.active.order = vec![
            "c_mod".to_string(),
            "a_mod".to_string(),
            "b_mod".to_string(),
        ];

        // Deliberately a different order than active.order, priority
        // must still follow active.order, since that's the one true order
        // for the active configuration.
        state.active.set_enabled(["a_mod", "c_mod"]);

        assert_eq!(state.active.priority_order(), vec!["c_mod", "a_mod"]);
    }

    #[test]
    fn dragging_to_reorder_changes_priority_because_it_changes_order() {
        // The whole point: for the active configuration there is no
        // separate priority list to keep in sync, reordering the display
        // list directly *is* reordering priority.
        let mut state = ModsState::default();
        state.active.order = vec!["alpha_mod".to_string(), "beta_mod".to_string()];
        state.active.set_enabled(["alpha_mod", "beta_mod"]);
        assert_eq!(state.active.priority_order(), vec!["alpha_mod", "beta_mod"]);

        // Drag beta_mod above alpha_mod in the launcher's list.
        state.active.order = vec!["beta_mod".to_string(), "alpha_mod".to_string()];

        assert_eq!(state.active.priority_order(), vec!["beta_mod", "alpha_mod"]);
    }

    #[test]
    fn apply_preset_replaces_active_wholesale() {
        let mut state = ModsState {
            active: ModsPreset {
                order: vec!["alpha_mod".to_string(), "beta_mod".to_string()],
                enabled: vec!["alpha_mod".to_string()],
                configuration: ModConfigurations::new(),
            },
            ..Default::default()
        };

        let preset = ModsPreset {
            order: vec!["gamma_mod".to_string(), "delta_mod".to_string()],
            enabled: vec!["gamma_mod".to_string(), "delta_mod".to_string()],
            configuration: HashMap::from([(
                "gamma_mod".to_string(),
                HashMap::from([("Speed".to_string(), serde_json::json!(9.0))]),
            )]),
        };
        state.apply_preset(&preset);

        assert_eq!(state.active, preset);
    }

    #[test]
    fn apply_preset_drops_locally_installed_mods_the_preset_does_not_mention() {
        // A preset is a complete description of a configuration,
        // applying it means exactly what it says, not merging with
        // whatever was active before. Any locally-installed mod it
        // doesn't mention is the launcher's (sync_active_order's) job to
        // re-surface, not apply_preset's.
        let mut state = ModsState::default();
        state.active.order = vec![
            "alpha_mod".to_string(),
            "beta_mod".to_string(),
            "gamma_mod".to_string(),
        ];
        state.active.set_enabled(["alpha_mod"]);

        let preset = ModsPreset {
            order: vec!["gamma_mod".to_string()],
            enabled: vec!["gamma_mod".to_string()],
            configuration: ModConfigurations::new(),
        };
        state.apply_preset(&preset);

        assert_eq!(state.active.order, vec!["gamma_mod".to_string()]);
        assert_eq!(state.active.enabled, vec!["gamma_mod".to_string()]);
    }

    #[test]
    fn apply_preset_then_sync_active_order_re_appends_dropped_local_mods() {
        // The full flow the launcher relies on: apply_preset narrows
        // active.order down to just the preset's mods, then the next
        // discover_mods scan's sync_active_order call re-appends every
        // other installed mod at the end, so the list still shows
        // everything, preset mods first in the preset's order, then
        // everything else.
        let mut state = ModsState::default();
        state.active.order = vec![
            "alpha_mod".to_string(),
            "beta_mod".to_string(),
            "gamma_mod".to_string(),
        ];

        let preset = ModsPreset {
            order: vec!["gamma_mod".to_string()],
            enabled: vec!["gamma_mod".to_string()],
            configuration: ModConfigurations::new(),
        };
        state.apply_preset(&preset);

        // Still-installed mods, in whatever order a sorted directory
        // listing would produce.
        state.sync_active_order(["alpha_mod", "beta_mod", "gamma_mod"]);

        assert_eq!(
            state.active.order,
            vec![
                "gamma_mod".to_string(),
                "alpha_mod".to_string(),
                "beta_mod".to_string(),
            ]
        );
        // Enabled membership from the preset is untouched by the resync.
        assert_eq!(state.active.enabled, vec!["gamma_mod".to_string()]);
    }

    #[test]
    fn apply_preset_sets_active_configuration_and_does_not_touch_presets_map() {
        let mut state = ModsState::default();
        state.active.order = vec!["board_mod".to_string()];
        state.presets.insert(
            "Racing".to_string(),
            ModsPreset {
                order: vec!["board_mod".to_string()],
                enabled: vec!["board_mod".to_string()],
                configuration: HashMap::from([(
                    "board_mod".to_string(),
                    HashMap::from([("Speed".to_string(), serde_json::json!(9.0))]),
                )]),
            },
        );

        let preset = state.presets.get("Racing").unwrap().clone();
        state.apply_preset(&preset);

        assert_eq!(
            state
                .active
                .configuration
                .get("board_mod")
                .and_then(|c| c.get("Speed")),
            Some(&serde_json::json!(9.0))
        );
        // Applying a preset doesn't consume or alter the saved copy.
        assert!(state.presets.contains_key("Racing"));
    }
}