Mod management

[NotGhoull]

Mod Management Proposal

This proposal requires changes in lib-vmm’s GameProvider, and should be incorporated into the “ModManagement changes” section before merging.

TL;DR

The frontend (e.g., VMM) becomes the source of truth for installed mods.

GameProviders will need to be updated*[1] to work with this new lifecycle.
This approach ensures consistent behavior across frontends, predictable mod state tracking, and a unified UX. Other frontends are free to implement this spec however they choose, but the behavior defined here is the recommended standard.

---

GameProvider Changes

Install mod

The install_mod function remains similar, but its return value changes.
Instead of: Result<(), GameInstallError>
(GameInstallError should eventually be renamed to ModInstallError)

…the provider will now return a new ModInstallationMeta object.

New ModInstallationMeta structure

pub struct ModInstallationMeta {
    /// Identifies the provider that installed this mod.
    pub provider_id: String,

    /// Provider-specific identifier for this mod.
    pub mod_id: String,

    /// Human-readable name for UIs.
    pub display_name: String,

    /// Optional semantic or arbitrary version string.
    pub version: Option<String>,

    /// List of provider-specific mod IDs that this mod depends on.
    pub depends_on: Vec<String>,

    /// Directory or root path where the mod was installed.
    /// Frontends use this for "Open in File Manager" actions.
    pub install_root: Option<String>,

    /// Optional icon as a binary blob or encoded string
    /// (format to be decided; URL-based icons are being phased out).
    pub icon: Option<Vec<u8>>,

    /// Optional checksum for integrity verification.
    pub checksum: Option<Checksum>,
}

pub struct Checksum {
    pub algo: String,   // e.g., "sha256"
    pub digest: String, // hex digest
}

New uninstall_mod function

A new function is introduced

fn uninstall_mod(&self, mod_id: &str, root: Option<String> -> Result<(), ModUninstallError>;

Providers receive only the provider-specific mod_id, not the full metadata object.
This prevents frontends from accidentally (or maliciously) supplying incorrect metadata.
Providers will also get given the installation path that was provided, for them to use.

Providers can maintain whatever internal state they require to uninstall the mod correctly.

New Capability: ConfigurableMods

This proposal introduces a new provider capability: ConfigurableMods.

It defines a single function:

fn configure_mod(&self, mod_id: &str) -> Result<Form, ConfigError>;

The provider returns a declarative Form, similar to the API Key capability.
The provider is responsible for:

• knowing where configuration files are,
• defining what “settings” mean,
• performing validation or manipulations.
  Frontends simply render the returned form.

Frontend spec

Frontends should store mod metadata in:

$XDG_DATA_HOME/<frontend>/<game>/<profile>/mods.json

---

*[1] Rewriting the providers is mostly a mechanical update: they must return ModInstallationMeta on install, implement uninstall and optionally implement new configuration capability.