modde

modde is a game mod manager written in Rust that runs natively on Linux, macOS, and Windows. It gives you declarative, reproducible mod management with a virtual-filesystem deployment that keeps your game directory clean, git-backed save vaults, profile experiments, and graph-based conflict detection — and it installs Wabbajack modlists and Nexus Collections natively, no Windows VM required.

Every platform is a first-class target. Install modde with your system’s package manager, a direct download, or Cargo — and if you happen to use Nix, modde is also a flake, which gives you a reproducible install and the option to declare your mod profiles as code through a home-manager module.

• Project site: https://modde.tartanoglu.com/
• Source: https://codeberg.org/caniko/rs-modde

What modde does

• Virtual filesystem deployment — a symlink farm overlays mods without touching the original game files, with atomic rollback. See Deployment & VFS.
• Wabbajack & Nexus — install .wabbajack modlists and Nexus Collections, browse and search Nexus, and resolve downloads from many backends. See Wabbajack modlists and Nexus Mods.
• Profiles & experiments — per-game mod sets with a non-destructive, git-like experiment stack. See Profiles.
• Save vaults — git-backed save snapshots with SHA-256 fingerprinting and pre-restore compatibility warnings. See Save management.
• Conflict detection — graph-based collision analysis with severity classification. See Conflicts & load order.
• Tools & executables — MangoHud, vkBasalt, GameMode, ReShade, OptiScaler, and Proton, plus named external executables with overwrite capture. See Tools & overlays and Executables.

Where to start

• New here? Read Installation, then Quick start and the end-to-end Your first profile walkthrough.
• Want to know if your game is supported? See Supported games — modde ships 15 titles across seven engine families, plus user-defined games.
• Curious how it compares to Mod Organizer 2? See the MO2 parity & capability audit.
• Looking for a command or option? See the CLI reference, the Home-Manager module, the settings file, and the Architecture overview.

Status claims in this documentation use a deliberately conservative vocabulary — Done, Partial, and Not shipped — anchored to the canonical docs/capability-matrix.toml in the repository. The FAQ answers the most common questions.

Installation

modde runs on Linux, macOS, and Windows — all first-class. Every release ships two binaries: the modde command-line tool and the modde-ui desktop app. Install them through your platform’s native package manager, a direct download, Cargo, or — if you use Nix — a flake with a declarative home-manager module.

There is no single “blessed” method. Pick whatever fits how you already manage software:

Both binaries are included in every package except cargo install modde-cli, which builds the CLI only. After installing, jump to the Quick start.

Linux

Arch Linux (AUR)

Three packages are published to the AUR; install one with your preferred helper (yay, paru, …):

yay -S modde-bin   # prebuilt from the signed release tarball (fastest)
yay -S modde       # build the tagged release from source
yay -S modde-git   # track the development branch

modde-bin depends on glibc >= 2.38 (satisfied by current Arch systems). All three provide the modde and modde-ui binaries and conflict with one another. Release tags are signed by the maintainer GPG key 818D507F1E62139F8A17EAA64623DEA06FDACFE1, also exported in keys/maintainers.gpg.

Fedora / RHEL (COPR)

sudo dnf copr enable caniko/rs-modde
sudo dnf install modde modde-ui

The COPR builds the RPMs from the signed release source. Prerelease builds are published to the separate caniko/rs-modde-testing project.

Debian / Ubuntu (apt)

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://modde.rs/apt/key.gpg.asc | sudo gpg --dearmor -o /etc/apt/keyrings/modde.gpg
echo "deb [signed-by=/etc/apt/keyrings/modde.gpg] https://modde.rs/apt/ stable main" \
  | sudo tee /etc/apt/sources.list.d/modde.list
sudo apt update
sudo apt install modde modde-ui

The repository is signed with a dedicated key (fingerprint CCFE4A8461DF8778F5227684B6DB8F177A951E1B), separate from the maintainer tag-signing key and the minisign release key. See SECURITY.md for the signing-key policy and rotation procedure.

Flatpak

The desktop app is published to Flathub:

flatpak install flathub com.tartanoglu.modde
flatpak run com.tartanoglu.modde

The Flatpak ships modde-ui (the GUI). For scripting with the modde CLI, use one of the other channels.

AppImage

Self-contained, no installation required:

chmod +x modde-ui-<version>-x86_64.AppImage
./modde-ui-<version>-x86_64.AppImage

A CLI AppImage (modde-<version>-x86_64.AppImage) is published alongside the GUI one. Download both from the releases page.

Linux direct download

Grab the tarball for your architecture from the releases page and extract it:

tar xzf modde-<version>-x86_64-linux.tar.gz   # or aarch64-linux
./modde --help

Verify the download first — see Verifying releases.

macOS

Homebrew

brew tap caniko/modde https://codeberg.org/caniko/homebrew-modde
brew install modde

The formula installs both modde and modde-ui on Apple Silicon and Intel Macs (it also works on Linux/Linuxbrew).

macOS direct download

modde ships ad-hoc-signed macOS binaries (no Apple Developer ID, no notarization). macOS quarantines downloaded binaries, so clear the quarantine attribute once after extracting:

tar xzf modde-<version>-aarch64-darwin.tar.gz   # or x86_64-darwin on Intel
xattr -dr com.apple.quarantine modde modde-ui
./modde --help

Subsequent runs work without further intervention. If you would prefer notarized binaries (Apple Developer ID, $99/yr), open an issue to fund or contribute it.

Windows

winget

winget install Caniko.Modde

Scoop

scoop bucket add modde https://codeberg.org/caniko/scoop-modde
scoop install modde

Chocolatey

choco install modde

Each Windows package installs modde.exe and modde-ui.exe on your PATH.

Windows direct download

Download modde-<version>-x86_64-windows.zip from the releases page and extract it. The .exe artifacts are Authenticode-signed; verify the signature before running:

Get-AuthenticodeSignature .\modde.exe
Get-AuthenticodeSignature .\modde-ui.exe

Both should report Status : Valid. On Linux you can verify the same files with osslsigncode verify -in modde.exe.

Cargo

modde publishes its CLI crate to crates.io. This builds the modde binary from source (the GUI lives in a separate crate that is not published to crates.io):

cargo install modde-cli

Because it compiles locally, you need a build environment:

• A Rust 2024 edition toolchain (recent stable rustc / cargo).
• SQLite and OpenSSL development headers (openssl-sys will not build without OpenSSL — see Troubleshooting).

On Debian/Ubuntu, for example:

sudo apt install ca-certificates gcc pkg-config \
  libssl-dev libsqlite3-dev libdbus-1-dev \
  libwayland-dev libxkbcommon-dev libvulkan-dev

On Fedora: sudo dnf install gcc pkg-config openssl-devel sqlite-devel dbus-devel wayland-devel libxkbcommon-devel vulkan-loader-devel.

Build from source

git clone https://codeberg.org/caniko/rs-modde.git
cd rs-modde
nix develop . -c cargo build --release
# Binaries at target/release/modde and target/release/modde-ui

The Nix dev shell provides every system library and is the authoritative build and test environment:

nix develop . -c cargo test --workspace

A plain cargo build/cargo test outside the dev shell often fails in openssl-sys (and the GUI fails to link without the Wayland/libxkbcommon/Vulkan libraries). Either use the dev shell or install the headers listed under Cargo. See Troubleshooting.

Nix

If you use Nix, modde is also a flake. This is not required and not “the” way to install it — but it is a reproducible option, and through the home-manager module it lets you declare your mod profiles as code.

Run or install

# Run without installing
nix run codeberg:caniko/rs-modde

# Install into your profile (both modde and modde-ui)
nix profile install codeberg:caniko/rs-modde

The Nix build wraps each binary with a CA-certificate bundle, so HTTPS downloads from Nexus and friends work with no extra configuration.

Flake input + home-manager module

Add modde to your flake inputs:

{
  inputs.modde = {
    url = "codeberg:caniko/rs-modde";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

Then import the home-manager module and declare profiles — Wabbajack lists, Nexus Collections, and tool overlays — that deploy on activation:

{ inputs, ... }:
{
  imports = [ inputs.modde.homeManagerModules.modde ];

  programs.modde = {
    enable = true;
    profiles.lotf = {
      game = "skyrim-se";
      installMode = "await-game";   # wait until the game is installed
      wabbajackList = {
        url = "https://example.com/lotf.wabbajack";
        hash = "sha256-...";
      };
    };
  };
}

modde waits for launcher-managed game installs; it does not install the base game itself. For every option, see the Home-Manager module reference. You can also drop the package straight into a system or user closure:

environment.systemPackages = [ inputs.modde.packages.x86_64-linux.modde ];

Development shell

nix develop codeberg:caniko/rs-modde
# ...or, in a checkout:
nix develop

The shell carries the pinned Rust 2024 toolchain, coverage tooling, archive extractors, the docs tooling, the simit release CLI, and every system library the workspace links against.

Verifying releases

Every release is built from a GPG-signed Git tag, and every artifact ships with a signed checksum manifest. Tarballs, AppImages, and source RPMs additionally ship Sigstore bundles and SLSA provenance.

Step 1 — verify the signed checksum manifest

Download the artifact plus SHA256SUMS.txt and SHA256SUMS.txt.minisig from the same release, then:

minisign -Vm SHA256SUMS.txt -p keys/minisign.pub
sha256sum -c SHA256SUMS.txt --ignore-missing

The minisign public key is pinned at keys/minisign.pub. If it ever changes, treat the release as a key-rotation event and verify the new key from an independent, maintainer-controlled channel before trusting it.

Step 2 — verify Sigstore signature and SLSA provenance

cosign verify-blob \
  --bundle modde-<version>-x86_64-linux.tar.gz.cosign.bundle \
  --certificate-identity-regexp '.*caniko/rs-modde.*' \
  --certificate-oidc-issuer-regexp '.*' \
  modde-<version>-x86_64-linux.tar.gz

cosign verify-blob-attestation \
  --bundle modde-<version>-x86_64-linux.tar.gz.intoto.bundle \
  --type slsaprovenance1 \
  --certificate-identity-regexp '.*caniko/rs-modde.*' \
  --certificate-oidc-issuer-regexp '.*' \
  modde-<version>-x86_64-linux.tar.gz

The SLSA predicate records the source Git commit, the flake.lock digest, the release-workflow digest, and the Attic substituter trust root used for release builds. Each release also ships CycloneDX (*.cdx.json) and SPDX (*.spdx.json) SBOMs. See SECURITY.md for SBOM scanning and the full signing-key policy.

Troubleshooting

error: cannot find flake 'codeberg:caniko/rs-modde'

codeberg: is a flake-registry shorthand. On older Nix or a trimmed registry, use the explicit Git URL and make sure flakes are enabled:

nix --extra-experimental-features 'nix-command flakes' \
  run "git+https://codeberg.org/caniko/rs-modde"

# /etc/nix/nix.conf (or nix.settings on NixOS)
experimental-features = nix-command flakes

Home-Manager module not recognized

error: The option 'programs.modde' does not exist means the module was not imported. Confirm both halves are present and that inputs is threaded into the module (via extraSpecialArgs/specialArgs):

inputs.modde.url = "codeberg:caniko/rs-modde";
# ...and in your home-manager configuration:
imports = [ inputs.modde.homeManagerModules.modde ];

The attribute is homeManagerModules.modde (note the trailing .modde). See the Home-Manager module reference.

openssl-sys build failure outside the Nix shell

A cargo build/cargo install/cargo test on a bare host typically fails in openssl-sys with Could not find directory of OpenSSL installation. modde does not vendor OpenSSL. Either build inside nix develop . -c …, or install the headers and point pkg-config at them (libssl-dev pkg-config libsqlite3-dev on Debian/Ubuntu; openssl-devel pkg-config sqlite-devel on Fedora). If a build also fails to link with wayland/xkbcommon/vulkan errors, install the GUI system libraries listed under Cargo — or just use the Nix shell.

See also

• Quick start — define and deploy your first profile
• Your first profile — an end-to-end walkthrough
• Home-Manager module reference — every option
• Settings file & environment — the non-Nix config
• SECURITY.md — signing keys, SBOMs, and rotation policy

Quick Start

modde runs natively on Linux, macOS, and Windows, and gives you two ways to drive the same engine:

• Imperative (CLI) — modde detect, modde profile create, modde install …, modde deploy, modde play. The same commands work on every platform. Best for interactive, day-to-day curation where you add and reorder mods by hand.
• Declarative (home-manager) — if you use Nix, describe a profile in your home-manager configuration and let an activation script install and deploy it on rebuild. A reproducible, version-controlled option for Wabbajack lists and Nexus Collections.

Both paths share one database, one mod store, and one save vault, so you can start imperatively and pin things down declaratively later (or vice versa) without losing state.

This page is the fast tour. If you want a single narrated end-to-end run, read Your first profile instead. For installing modde itself, see Installation.

The imperative path (CLI)

The CLI walks the whole lifecycle in explicit steps. A minimal run looks like:

# 1. See which games modde found across Steam and Heroic
modde detect

# 2. Create a profile for one of them
modde profile create my-skyrim --game skyrim-se

# 3. Add mods to it (pick whichever source applies — see below)
modde install mod https://www.nexusmods.com/skyrimspecialedition/mods/12345 \
  --profile my-skyrim

# 4. Build and deploy the symlink farm into the game directory
modde deploy --profile my-skyrim --game skyrim-se

# 5. Deploy (again) and launch, capturing saves on exit
modde play my-skyrim --game skyrim-se

Detect

modde detect

modde detect auto-discovers installed games across Steam and Heroic (GOG, Epic, Sideload) and prints their ids and install paths. Use the printed id (e.g. skyrim-se) for every subsequent --game flag. If your game is not detected, you can still create a profile and pass paths explicitly, or register a user-defined game with modde game add.

Create a profile

A profile ties a set of mods to a specific game.

modde profile create NAME --game ID
# e.g.
modde profile create my-skyrim --game skyrim-se

Game ids are the short identifiers in the supported games table (skyrim-se, cyberpunk2077, stellar-blade, and so on). 15 games ship today; generic, user-defined games are also possible via a GameSpec TOML (see Game support). See Profile management for listing, switching, forking, locking, and the experiment stack.

Add mods

Pick the source that matches what you are installing:

# A single Nexus mod (downloads via CDN — needs a Premium key)
modde install mod https://www.nexusmods.com/skyrimspecialedition/mods/12345 \
  --profile my-skyrim

# A mod with a FOMOD installer, driven by a saved choices file
modde install mod <url> --profile my-skyrim --fomod-config my-choices.toml

# A whole Wabbajack modlist
modde install wabbajack /path/to/modlist.wabbajack \
  --profile my-modlist \
  --game-dir "/path/to/Skyrim Special Edition"

# A Nexus Collection
modde install nexus-collection <slug> --profile my-collection

Set up Nexus authentication first with modde nexus auth (see Nexus Mods). For FOMOD details — generating a choices template and inspecting options — see the FOMOD guide.

Collections (and Wabbajack lists) auto-lock the profile to preserve the curator’s intended load order. See Profile management for forking a locked profile into a freely editable copy. Wabbajack lists that read vanilla game files (Wabbajack GameFileSourceDownloader entries — Legends of the Frost is one example) need --game-dir so modde can read and verify those local files during installation.

Deploy

# Deploy the active profile
modde deploy

# Deploy a specific profile
modde deploy --profile my-skyrim --game skyrim-se

See what deploy actually does below.

Play

modde play my-skyrim --game skyrim-se

modde play switches to the profile (swapping saves), deploys, launches the game through the detected launcher, and auto-captures saves on exit. Useful flags: --no-switch, --no-deploy, --no-capture. See Playing a game.

The declarative path (home-manager)

If you use Nix, modde is also a flake with a home-manager module, so you can declare your mod profiles as code and let them deploy on rebuild. This is one optional path — the CLI above works the same everywhere — but it is handy for reproducible, version-controlled setups. See Installation for adding the flake input and module.

Declared in home-manager, the simplest profile is just a game id:

programs.modde = {
  enable = true;

  profiles.my-skyrim = {
    game = "skyrim-se";
  };
};

After home-manager switch, modde deploys your profiles automatically via an activation script. There is nothing else to run for a plain profile.

Install from a Wabbajack modlist

To install a Wabbajack modlist, add wabbajackList and point gameDir at your installed game. modde reads the manifest, downloads the referenced archives (primarily from Nexus — needs an API key), and deploys the list.

programs.modde = {
  enable = true;

  nexus.apiKeyFile = "/run/secrets/nexus-api-key";  # sops-nix compatible

  profiles.living-skyrim = {
    game = "skyrim-se";
    gameDir = "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition";
    wabbajackList = {
      url = "https://example.com/modlist.wabbajack";
      hash = "sha256-...";
    };
  };
};

hash is the Nix fetch hash for the .wabbajack file itself — see Computing a Wabbajack hash below. Skyrim SE lists that reference vanilla game files (Wabbajack GameFileSourceDownloader entries — Legends of the Frost is one example) need gameDir so modde can read and verify those local files during installation.

For .wabbajack files you already have in the Nix store (via requireFile or a custom fetcher), use a local path instead of url + hash:

programs.modde.profiles.living-skyrim = {
  game = "skyrim-se";
  gameDir = "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition";
  wabbajackList = {
    path = /nix/store/...-Living-Skyrim.wabbajack;
  };
};

Install from a Nexus Collection

programs.modde.profiles.my-collection = {
  game = "skyrim-se";
  nexusCollection = {
    slug = "collection-slug";
    version = "1.0.0";
  };
};

Collections (and Wabbajack lists) auto-lock the profile to preserve the curator’s intended load order. See Profile management for forking a locked profile into a freely editable copy.

Declaring a profile before the game exists

modde never installs the base game; you install it through Steam or Heroic, and modde waits. If the game is not installed yet, set installMode = "await-game" (or simply leave gameDir unset). Activation then skips install/deploy non-fatally and prints the next step instead of failing the whole rebuild:

programs.modde.profiles.living-skyrim = {
  game = "skyrim-se";
  installMode = "await-game";
  wabbajackList = {
    url = "https://example.com/modlist.wabbajack";
    hash = "sha256-...";
  };
};

Install the game through its launcher, set gameDir, change installMode back to "auto" (or remove it), and rebuild. modde then installs and deploys the profile. Wabbajack install runs before deploy only when gameDir exists and contains the expected game-content directory (e.g. Data/ for Skyrim SE). For every option, see the Home-Manager module reference.

Computing a Wabbajack hash

The declarative wabbajackList.url + hash pair needs the Nix fetch hash of the .wabbajack file (SRI format, sha256-…). This is the hash of the archive, not the Wabbajack-internal archive hashes inside the manifest. Compute it with either of these:

# Modern Nix (preferred): prints the SRI hash and stores the file
nix store prefetch-file "https://example.com/modlist.wabbajack"

# Or via the flake prefetch helper
nix flake prefetch "https://example.com/modlist.wabbajack"

Both print a sha256-… value you paste verbatim into hash. If you already have the file locally:

nix hash file ./modlist.wabbajack          # SRI sha256- hash of a local file

Wabbajack registry pages usually link through to an authored-files URL for the real .wabbajack archive. Some of those CDN links now resolve through Wabbajack’s chunked download page rather than a plain file response, so a bare prefetch (and pkgs.fetchurl) can 404 even though modde’s chunk-aware downloader works. In that case, download the file first and use the local path:

modde wabbajack download "<registry-url-or-machine-url>" --output ./list.wabbajack
nix hash file ./list.wabbajack

Then either set wabbajackList.path = ./list.wabbajack; (no hash needed for a path source) or feed it through your own fetcher.

modde can also write the home-manager snippet for you:

modde wabbajack hm-snippet "<url-or-file>" \
  --profile living-skyrim \
  --game skyrim-se \
  --game-dir "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition"

First-run gotchas

A short checklist of things that trip people up on the first profile:

• Install the base game first. modde waits for launcher-managed installs; it never installs Steam or the game itself. For declarative Wabbajack profiles before the game exists, use installMode = "await-game" so activation does not fail the rebuild.
• Set up Nexus auth before installing anything from Nexus. Run modde nexus auth (or set nexus.apiKeyFile). CDN downloads require a Nexus Premium subscription; modde nexus status tells you whether your key is valid and Premium. See Nexus Mods.
• gameDir / --game-dir is required for lists that read vanilla files. Skyrim SE lists with GameFileSourceDownloader entries fail without it.
• Use the detected game id. Run modde detect and copy the exact id; a typo’d --game is the most common “nothing happens” cause.
• The hash is the file’s Nix hash, not a manifest hash. Compute it as above; a mismatch aborts the fetch by design.
• Deploy is reversible and non-destructive. It does not modify your original game files, and modde rollback restores the previous deployment.
• Adopt existing saves before your first switch. If you already have saves, run modde save adopt --game skyrim-se --profile my-skyrim so a later profile switch does not park them unexpectedly. See Save management.

What deploy does

modde deploy builds a symlink farm and links it into the game directory without touching your original game files. The pipeline has three phases:

1. Build — modde resolves the load order and maps each relative file path to its winning source. For any path provided by multiple mods, the mod later in the load order wins; hidden files and profile-level overrides are applied here.
2. Materialize — the farm is written to a staging directory (~/.local/share/modde/staging/<profile>/); each file becomes a symlink to the winning mod’s content.
3. Deploy — the materialized staging tree is symlinked into the game’s mod directory.

The previous deployment is preserved in staging.bak/, so modde rollback --profile my-skyrim atomically swaps back. Wabbajack profiles deploy differently: their pre-built file layouts are hardlinked (or copied) straight into the game directory, bypassing the conflict-resolving symlink farm. Verify a deployment with modde verify --profile my-skyrim. Full detail lives in the Deployment & VFS guide.

See also

• Your first profile — the same flow as one narrated walkthrough
• Installation — get modde onto your system
• Profile management — switch, fork, lock, experiment
• Wabbajack modlists — installing .wabbajack lists
• Nexus Mods — authentication, mods, Collections
• Deployment & VFS — how deploy works in depth
• Playing a game — modde play end to end
• Supported games — game ids and coverage

Your first profile

This walkthrough takes you from a fresh modde install to a deployed, playable Skyrim Special Edition profile with a couple of mods, all from the command line. The commands are identical on Linux, macOS, and Windows, and every one uses the skyrim-se game id. If you use Nix and prefer the declarative home-manager workflow, see the Quick Start; this page is the imperative tour for newcomers.

By the end you will have:

• modde installed and a Nexus key configured
• Skyrim SE detected
• a profile named first-run
• two mods installed (one plain Nexus mod, one with a FOMOD installer)
• a conflict report you understand
• the profile deployed into the game directory
• the game launched and a save captured into the vault

0. Before you start

modde never installs the base game. Install Skyrim Special Edition through Steam or Heroic first and launch it once so the launcher writes its files. modde will detect that install in the next step.

You also need a Nexus Mods account. Downloading mod files over CDN links requires a Nexus Premium subscription.

1. Install modde

Install modde however suits your platform — a native package manager, a direct download, Cargo, or, if you use Nix, the flake. Every channel ships both the modde CLI and the modde-ui desktop app. A few examples:

# Arch Linux (AUR)
yay -S modde-bin

# Fedora / RHEL (COPR)
sudo dnf copr enable caniko/rs-modde && sudo dnf install modde modde-ui

# Debian / Ubuntu (apt) — see Installation for the keyring setup
sudo apt install modde modde-ui

# macOS (Homebrew)
brew tap caniko/modde https://codeberg.org/caniko/homebrew-modde
brew install modde

# Windows (winget)
winget install Caniko.Modde

# Any platform with Cargo (builds the CLI from source)
cargo install modde-cli

If you use Nix, modde is also a flake — nix run codeberg:caniko/rs-modde -- detect to try it without installing, or nix profile install codeberg:caniko/rs-modde to add both binaries to your profile. The home-manager module additionally lets you declare your profiles as code.

See Installation for the full channel list, the exact commands, the macOS Gatekeeper quarantine-clear step, the Windows Authenticode signature check, and release verification. From here on, the walkthrough assumes modde is on your PATH.

2. Configure Nexus authentication

Save your Nexus API key to the system keyring once:

modde nexus auth

This prompts for your key and stores it securely in your OS keyring (the secret-service on Linux, Keychain on macOS, the Credential Manager on Windows). Confirm it worked — and check whether you have Premium — with:

modde nexus status

If you manage secrets declaratively, set nexus.apiKeyFile in home-manager instead. The full credential precedence (OAuth token, key file, env var, keyring, …) is documented in the Nexus Mods guide.

3. Detect your game

modde detect

modde scans Steam and Heroic (GOG, Epic, Sideload) and prints every game it found with its id and install path. You should see a row for Skyrim Special Edition with the id skyrim-se. Copy that id; you will pass it as --game to nearly every command.

If Skyrim does not appear, make sure it is installed and has been launched once. You can still proceed by passing paths explicitly, or register a custom game with modde game add (see Supported games).

4. Create a profile

A profile is a named, per-game collection of mods with its own load order, save assignments, and deployment state. Create one:

modde profile create first-run --game skyrim-se

Confirm it exists and see which profile is active:

modde profile list --game skyrim-se
modde profile active --game skyrim-se

Profiles are cheap. Later you can fork first-run to experiment without risking your working setup — see Profile management.

5. Add your first mod (a plain Nexus mod)

Install a single mod straight from its Nexus page URL into the profile. modde fetches the file list, picks the latest main file, downloads it over CDN (Premium required), extracts it, and adds it to the profile:

modde install mod \
  https://www.nexusmods.com/skyrimspecialedition/mods/12345 \
  --profile first-run

Replace 12345 with the real mod id from the URL of the mod you want. A SkyUI- or USSEP-style utility mod is a good, low-risk first pick.

6. Add a second mod (one with a FOMOD installer)

Many larger Skyrim mods ship a FOMOD installer that asks questions (texture resolution, compatibility patches, optional features). modde detects fomod/ModuleConfig.xml automatically. For a reproducible, non-interactive install you can record your answers in a config file first.

Inspect what a mod offers without installing it:

modde fomod inspect /path/to/extracted-mod

Generate a choices template, edit it, then install with it applied:

modde fomod generate /path/to/extracted-mod --format toml > my-choices.toml
# edit my-choices.toml to pick the options you want

modde install mod \
  https://www.nexusmods.com/skyrimspecialedition/mods/67890 \
  --profile first-run \
  --fomod-config my-choices.toml

Your selections are saved to the profile and replayed on future deployments, so the result is deterministic. The FOMOD guide covers generating, inspecting, and applying configs in depth.

7. Analyze conflicts

Two mods that both ship the same file will collide; only one can win. modde resolves collisions by load order priority — the mod later in the list wins. Before deploying, see what overlaps:

modde collisions --profile first-run

The report groups conflicts by severity:

By default cosmetic conflicts are hidden; add --all to see them. To get ready-to-run commands that hide files which never win anyway:

modde collisions --profile first-run --all --suggest-hides

For a broader health check (missing masters, Form 43 plugins, and more), run:

modde diagnostics --game skyrim-se --profile first-run

For Bethesda games you can also sort plugin order with the LOOT masterlist (modde loot sort --game skyrim-se). Conflict resolution, per-file hiding, and plugin load order are all covered in the Conflicts & load order guide.

8. Deploy

Now build the symlink farm and link it into the game directory:

modde deploy --profile first-run --game skyrim-se

Deployment is non-destructive: it never edits your original game files, stages everything under ~/.local/share/modde/staging/first-run/, and keeps the previous deployment in staging.bak/ so you can modde rollback at any time. Check that deployed files match their sources with:

modde verify --profile first-run

What each phase does — Build, Materialize, Deploy — is detailed in the Deployment & VFS guide.

9. Play

Launch the modded game. modde play switches to the profile (swapping saves), deploys, launches through the detected launcher, and auto-captures saves when the game exits:

modde play first-run --game skyrim-se

A note on launchers:

• Heroic / direct launch — modde waits for the game to exit, then captures saves automatically.
• Steam launch — Steam returns immediately, so modde hands save capture to its launch wrapper. If a save is not captured, run capture manually (next step).

Skip steps with --no-switch, --no-deploy, or --no-capture. See Playing a game.

10. Capture a save

modde keeps a git-backed save vault per game, with one branch per profile and a mod fingerprint embedded in each snapshot. After modde play exits, your save should already be captured. To capture explicitly at any point:

modde save capture --game skyrim-se --profile first-run -m "first run, level 5"

If you launched through Steam and the wrapper has not captured yet:

modde save auto-capture --game skyrim-se

Browse the history and restore an earlier snapshot when you want:

modde save history --game skyrim-se --profile first-run
modde save restore <commit-id> --game skyrim-se --profile first-run

If you already had saves before setting up modde, adopt them once with modde save adopt --game skyrim-se --profile first-run so the first profile switch handles them cleanly. Fingerprinting, watching, and assignments are covered in Save management.

Where to go next

You now have a complete, reproducible modded profile. Branch out from here:

• Profile management — fork first-run, lock load order, and use the experiment stack to try changes non-destructively
• Wabbajack modlists — install a full .wabbajack list instead of hand-picking mods
• Nexus Mods — Collections, the nxm:// handler, and update checks
• Conflicts & load order — deeper conflict resolution and Bethesda plugin sorting
• Tools & overlays — MangoHud, ReShade, OptiScaler, Proton settings, and running xEdit/BodySlide with overwrite capture
• Save management — fingerprinting, watching, and restore

See also

• Quick Start — the same flow, condensed, plus the declarative home-manager path
• Installation — install channels and verification
• Supported games — every shipping game id
• Deployment & VFS — how deploy works
• Playing a game — modde play reference

Supported Games

This table is intentionally conservative:

• Done means the game path is shipped end to end.
• Partial means some core pieces exist, but major workflows are still missing or not yet trustworthy.
• Not shipped means the capability should not be treated as available.
• The canonical status baseline for this page lives in docs/capability-matrix.toml in the repository.

Bethesda titles

Other games

Wabbajack game mapping

When installing Wabbajack modlists, the manifest game names are mapped to modde game IDs:

Per-game guides

Each shipped title has a dedicated guide with its engine, mod directory, save location, installer quirks, and Linux/Proton notes:

• Creation Engine: Skyrim SE/AE, Fallout 4, Fallout 76, Starfield
• Gamebryo: Fallout: New Vegas, Oblivion
• REDengine: Cyberpunk 2077, The Witcher 3
• Unreal 4/5: Stellar Blade, Subnautica 2, Oblivion Remastered
• Other engines: Baldur’s Gate 3 (Larian), Stardew Valley (SMAPI), Mount & Blade II: Bannerlord

Adding game support

modde ships built-in game plugins for the titles above. Each implements the GamePlugin trait, which provides archive analysis and mod-layout recognition, filesystem scanning and mod discovery, conflict classification, Wine/Proton DLL-override detection, and save-game tracking.

Beyond the built-in list, you can register user-defined games at runtime with modde game add (or import a shareable GameSpec TOML). This is the Generic game support capability — it ships today as a Partial feature: deployment, conflict classification, and launcher integration work, but there is no bespoke scanner or save tracker for arbitrary titles. See Generic & user-defined games for the workflow and the TOML schema.

Skyrim Special Edition / Anniversary Edition

Skyrim Special Edition (skyrim-se) and Anniversary Edition (skyrim-ae) are modde’s most complete, end-to-end-tested titles. They share this guide because they are the same game build: identical Steam App ID, install directory, INI files, archive formats, and Nexus domain. The Anniversary Edition is the Special Edition plus Creation Club content, so everything below applies to both ids unless explicitly noted.

Both are marked Done in the supported-games matrix: the scanner, conflict detection, and save tracking are all shipped and user-reachable, and the Wabbajack + home-manager install path described at the end is modde’s strongest worked example.

Engine and overall status

skyrim-ae is registered as a distinct game so you can target it explicitly, but launcher detection reports skyrim-se by default because AE reuses the SE Steam app and install directory. When in doubt, use skyrim-se; pick skyrim-ae only if a modlist or collection demands the AE id specifically.

How modde detects the install

modde locates Skyrim through its launcher ids, then derives the per-user data paths from the Steam App ID. On Linux and macOS Skyrim runs through Proton/Wine, so those paths live inside the compatibility prefix; on Windows the game runs natively and the same paths are their native Windows locations.

• Steam. modde resolves 489830 and the Skyrim Special Edition directory under your Steam libraries. Heroic GOG/Epic ids are not set for Skyrim SE/AE (it is a Steam title), so detection is Steam-based.

• Proton prefix (Linux/macOS). Save and plugins.txt paths are read from the Proton compatibility prefix keyed by App ID:

  <steam>/steamapps/compatdata/489830/pfx/drive_c/users/steamuser/...
  

For Wabbajack lists and any modlist that references the installed base game, you should still point modde at the game directory explicitly with --game-dir (CLI) or gameDir (home-manager) — see Linux/Proton notes and known gotchas.

Mod directory and deploy strategy

Every Bethesda title deploys into the game’s Data/ directory. modde computes the mod directory as <install>/Data and stages mod content there. The deploy itself is symlink-based, consistent with all Bethesda games, so the game’s own Data/ stays a virtual composite of the active profile rather than a destructively merged folder.

Two file classes get special treatment:

• Loose files (meshes, textures, scripts, INIs) are linked into Data/ under their relative paths.
• Archives (.bsa, .ba2) are deployed as-is, not extracted, because the Creation Engine loads them natively. They are placed directly into Data/.

modde recognizes a “bare” extracted layout — a folder that already looks like a Data/ tree — by these root markers, matched case-insensitively:

• Root directories: data, meshes, textures, scripts, interface, sound, music, materials, seq, shadersfx, strings
• Root file extensions: esp, esm, esl, bsa, ba2

This lets modde correctly stage both Data-rooted archives and FOMOD output without you having to flatten them by hand.

See Deployment for the general symlink model and how overwrite/overrides priority works.

What scanning finds

The Skyrim scanner walks Data/ and reconstructs your installed mods, using plugins.txt as the authoritative source of load order and enabled state.

It works in two passes:

1. Authoritative pass. Every plugin listed in plugins.txt that actually exists on disk is emitted as a discovered mod (plugin/<filename>, confidence 0.95). For each plugin stem, the scanner also pulls in companion archives that share the stem — both <stem>.bsa/<stem>.ba2 and the <stem> - Textures.bsa/.ba2 texture-archive convention.
2. Unmanaged pass. Any .esp/.esm/.esl in Data/ not already seen via plugins.txt is emitted with lower confidence (0.8) so disabled or externally-dropped plugins still surface.

Plugin extensions recognized: .esp, .esm, .esl. Archive extensions paired with a plugin: .bsa, .ba2. Each discovered file records its Data/-relative path and size.

See Scanning for how discovered mods feed adoption and stale-duplicate detection.

Conflict classification specifics

Skyrim uses the Bethesda collision classifier, which assigns a severity to every overlapping file by extension — and, crucially, indexes the contents of .bsa/.ba2 archives so two mods that ship conflicting files inside archives are still flagged.

So two mods overwriting the same .dds are a cosmetic (last-wins, usually safe) conflict, while two mods providing the same plugin record or compiled script (.pex/.psc) or native DLL are flagged as dangerous and surfaced prominently. Archive contents (.bsa/.ba2) are read and merged into the collision map, so the analysis is not limited to loose files.

See Conflicts for how severities drive the conflict report and resolution order.

Save tracking

Save tracking is Done for Skyrim SE/AE. modde reads saves from the Proton prefix:

<steam>/steamapps/compatdata/489830/pfx/drive_c/Users/steamuser/Documents/My Games/Skyrim Special Edition/Saves

What it captures and fingerprints:

• It tracks *.ess save files (and *.bak are recognized but skipped as backup copies). The Skyrim .skse co-save written alongside each .ess is explicitly excluded from tracking — it is a SKSE side file, not a save of record.
• For each .ess, modde parses the binary header (magic TESV_SAVEGAME) and extracts the save number and character name, producing labels like Lydia — Save 14. If the header is unreadable or has the wrong magic (e.g. a save from another game dropped in the folder), the file is still captured but without a label.
• Slot category is inferred from the filename: Autosave* → auto, Quicksave* → quick, everything else → manual. A multi-save capture is summarized grouped by character (e.g. Lydia (slots 14, 15); Orc Mage (slot 7)).

Save profiles are enabled for Skyrim, so saves are captured per modde profile — letting you swap modlists without cross-contaminating character saves.

This save fingerprinting matters because Skyrim saves bake in your active plugins: removing or changing a save-breaking mod can corrupt or invalidate an existing character. modde treats the following extensions as save-breaking, which is what triggers a save fingerprint before a destructive change: .esp, .esm, .esl, .pex, .dll, .psc. Cosmetic-only changes (.nif, .dds, .bsa/.ba2, audio, etc.) do not.

See Saves for the general capture/restore workflow.

Plugin and load-order handling

Skyrim is one of the few engines with full plugin/load-order support in modde.

plugins.txt

modde reads and writes the standard Bethesda plugins.txt format inside the Proton prefix:

~/.local/share/Steam/steamapps/compatdata/489830/pfx/drive_c/users/steamuser/AppData/Local/Skyrim Special Edition/plugins.txt

Format rules: a leading * marks a plugin enabled, no prefix means disabled, and # lines are comments. modde-written files start with a generated header comment (# This file is generated by modde. Do not edit manually.).

modde keeps plugin load order separate from mod install priority — “which mod’s files win on disk” is independent from “which .esp loads first” — mirroring MO2’s dual-pane model.

LOOT sorting

modde ships a pure-Rust LOOT masterlist parser (no libloot FFI). It downloads the public LOOT masterlist for Skyrim SE/AE from loot/skyrimse and converts its rules to modde’s internal load-order rules:

• after → load-after rule
• requires → load-after rule (and a missing-master signal if absent)
• incompatible → incompatible-pair rule

Rules are generated only for plugins that are actually in your active set, and matching is case-insensitive. skyrim-se and skyrim-ae share the same masterlist URL.

modde loot sort --game skyrim-se

Plugin diagnostics

modde reads the binary TES4 header of each active plugin (only the first ~1 KB) to run two Skyrim-specific checks plus a shared one:

The Form 43 check is gated to skyrim-se/skyrim-ae specifically, since the Oldrim-vs-SSE plugin format distinction is unique to Skyrim. ESM/ESL flags are read from the same header.

modde loot validate --game skyrim-se

Installer specifics

• FOMOD. Scripted and basic FOMOD installers are supported; FOMOD output is recognized as a Data/-rooted layout via the bare-layout markers above, so the selected options stage correctly into Data/. See the FOMOD installer guide.
• BSA/BA2. Archives are deployed as-is into Data/ and indexed for conflict analysis — they are never unpacked.
• Wabbajack. Skyrim SE is modde’s best-supported Wabbajack target. modde parses Wabbajack manifests, including GameFileSourceDownloader entries (local vanilla game files referenced by the list), Wabbajack CDN authored-files archives, Nexus downloads, and ModDB-style mirror pages. See Wabbajack and the worked example below.
• REDmod / pak / SMAPI do not apply to Skyrim — those are Cyberpunk, UE4/5, and Stardew constructs respectively. Skyrim’s content model is loose files plus .bsa/.ba2 archives plus .esp/.esm/.esl plugins.

Gaming tools that matter for this title

• Proton. Skyrim SE/AE run under Proton; modde derives its save and plugins.txt paths from the Proton prefix automatically once the game is installed.
• SKSE (Skyrim Script Extender). Many mods depend on SKSE. modde does not install SKSE for you, but you can register the SKSE loader as a named executable and launch it through modde — see the executable-management workflow (modde tool add-executable / modde exec) in the tools guide.
• OptiScaler. modde ships no OptiScaler profiles for Skyrim (optiscaler_profiles is empty for both ids); OptiScaler/upscaler tooling is relevant to the UE4/5 titles, not Creation Engine Skyrim.

Linux/Proton notes and known gotchas

These notes concern the game’s runtime on Linux and macOS, where Skyrim runs through Proton/Wine. On Windows the game runs natively, so the prefix-specific points below do not apply — saves, plugins.txt, and INI files live at their native Windows locations. modde itself runs natively on all three platforms.

• --game-dir / gameDir is required for vanilla-referencing modlists. Many Wabbajack lists — Legends of the Frost is the canonical example — reference vanilla Skyrim Data files as install inputs (GameFileSourceDownloader). modde must read and hash-verify those local game files before staging the list, so you have to point it at the installed game directory. Without it, the install fails with a clear missing---game-dir error rather than silently producing a broken profile.
• installMode = "await-game" (home-manager). You can declare a Wabbajack profile before Skyrim is installed. In await-game mode, activation prints the next step and exits successfully instead of failing; once Skyrim is installed through Steam/Heroic, set gameDir and switch installMode to "auto" (or remove it).
• Authored-files availability. Wabbajack lists can break when their upstream authored-files archives are taken down (HTTP 404). modde runs an availability preflight and fails fast, reporting exactly which authored-file ids are missing, before starting bulk downloads. If you have exact local copies, import them by hash with modde wabbajack import-archive (name-only matches are refused).
• Form 43 plugins. Oldrim-era mods ported carelessly to SE/AE can carry the Form 43 header and crash; run modde loot validate --game skyrim-se to catch them.

Worked example

CLI: install a Wabbajack list and deploy

# Install a Wabbajack modlist, verifying vanilla game files under --game-dir.
modde install wabbajack /path/to/lotf.wabbajack \
  --profile skyrim \
  --game-dir "/path/to/Skyrim Special Edition"

# Sort the load order against the LOOT masterlist and check for problems.
modde loot sort --game skyrim-se
modde loot validate --game skyrim-se

# Deploy the profile into the game's Data/ directory.
modde deploy --profile skyrim --game skyrim-se

If you have local copies of authored archives that were pulled upstream:

modde wabbajack import-archive /path/to/list.wabbajack \
  /path/to/Archive-A.7z \
  /path/to/Archive-B.7z

Home Manager: declarative Wabbajack profile

programs.modde = {
  enable = true;
  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles.skyrim = {
    game = "skyrim-se";
    installMode = "auto";
    gameDir = "/path/to/Skyrim Special Edition";
    wabbajackList = {
      url = "https://authored-files.wabbajack.org/...";
      hash = "sha256-...";
    };
  };
};

gameDir is required for lists (like Legends of the Frost) whose manifest references local vanilla game files; modde verifies them before staging.

If Skyrim is not installed yet, declare the profile in awaiting mode and fill in gameDir after installing the game through Steam or Heroic:

programs.modde.profiles.skyrim = {
  game = "skyrim-se";
  installMode = "await-game";
  wabbajackList = {
    url = "https://authored-files.wabbajack.org/...";
    hash = "sha256-...";
  };
};

Activation prints the next step and continues; once Skyrim exists, set gameDir and switch installMode to "auto".

Note: a wabbajackList profile cannot also set a nexusCollection — the two install sources are mutually exclusive.

See also

• Supported games
• Installation
• Wabbajack modlists
• Deployment
• Conflicts
• Scanning
• Saves
• FOMOD installers
• Executables & tools
• Troubleshooting
• Parity reference

Fallout 4

Fallout 4 (game_id fallout4, Steam App ID 377160) is a fully shipped Bethesda title in modde: scanning, conflict detection, plugin load order, and save tracking all work end to end. Its overall status is Done in the supported-games table and the parity audit. It is one of five Creation Engine games modde drives through a single data-driven BethesdaGame plugin, sharing its deploy strategy and conflict logic with Skyrim SE/AE, Fallout 76, and Starfield.

Engine & overall status

Because Fallout 4 is part of the Bethesda plugin family, it inherits the full Creation Engine feature set documented for Skyrim SE/AE and in the Conflicts & load order guide: plugins.txt read/write, a pure-Rust LOOT masterlist parser, binary plugin header validation (Form 43 / missing-master detection), and archive-aware conflict analysis.

Install detection

modde locates a Fallout 4 install through its registered launcher IDs, in this priority order:

1. Steam — App ID 377160, install directory steamapps/common/Fallout 4. This is the primary, best-tested detection path.
2. Heroic (GOG) — GOG app ID 1998527297, for the GOG build (on Linux/macOS run through Heroic + Proton/Wine; on Windows it runs natively).

There is no Epic launcher mapping for Fallout 4. The install root is the directory that contains Fallout4.exe and the Data/ folder; you can also point modde at it explicitly with gameDir (home-manager) or --game-dir (CLI) when auto-detection cannot reach it.

Proton prefix

On Linux, Fallout 4 runs under Proton, so the Windows-side paths modde needs (plugins.txt, the save folder, the per-user My Games tree) live inside the Steam compatibility prefix rather than in your real home directory. modde resolves them under the App-ID-keyed compatdata prefix:

~/.local/share/Steam/steamapps/compatdata/377160/pfx/drive_c/users/steamuser/

plugins.txt is read from and written to:

.../compatdata/377160/pfx/drive_c/users/steamuser/AppData/Local/Fallout4/plugins.txt

and saves from the My Games tree (see Save tracking). If the prefix has not been created yet — for example you have installed the game but never launched it — these paths will not exist, and modde degrades gracefully: the scanner falls back to a plain directory walk and the save tracker reports no saves rather than erroring.

Mod directory & deploy strategy

The mod directory is Data/ under the install root (mod_directory returns install.join("Data")). Every plugin, archive, and loose asset Fallout 4 loads lives here.

modde deploys with its standard symlink farm: mods are staged in ~/.local/share/modde/staging/<profile>/, conflicts are resolved into a single winning layout, and that layout is symlinked into Data/. Your real game install is never overwritten, and a rollback restores the previous deployment atomically. See Deployment & VFS for the full build → materialize → deploy pipeline and modde rollback.

.ba2 archives are deployed as-is, not extracted — the Creation Engine loads them natively, so modde places the archive straight into Data/ and lets the engine mount it. This matches the bare-layout recognizer, which treats a top-level Data/, loose .esp/.esm/.esl/.ba2 files, or the usual asset folders (meshes/, textures/, scripts/, interface/, sound/, materials/, strings/, …) as a valid Bethesda mod root even when the archive was packed without a containing folder.

What scanning finds

The Fallout 4 scanner (FALLOUT4_SCANNER, a BethesdaScanner) discovers installed mods by walking Data/ and cross-referencing plugins.txt:

1. Authoritative pass. It reads plugins.txt from the Proton prefix and, for every listed plugin that exists on disk, emits a plugin/<filename> mod at confidence 0.95. For each plugin it also pairs companion archives that share the plugin’s stem — both <stem>.ba2/<stem>.bsa and the texture-archive convention <stem> - Textures.ba2 — so a plugin and its assets are reported as one mod.
2. Unmanaged pass. It then scans Data/ for any .esp/.esm/.esl files not present in plugins.txt (disabled or hand-dropped plugins) and reports them at confidence 0.8, again pulling in same-stem archives.

Scan results feed duplicate detection: each discovered mod exposes a Data-relative footprint (plugin/Foo.esp → foo.esp) so modde can spot files that are already deployed loose in the game folder versus managed by a profile. See Scanning installed mods for the shared workflow.

Conflict classification

Conflicts are classified by the shared BethesdaCollisionClassifier, which is archive-aware: it reads the file listing inside each .ba2/.bsa and folds those entries into the same collision map as loose files, so two archives that both ship textures/foo.dds are flagged even though neither was extracted.

Severity is assigned per file extension:

This is the same severity ladder modde uses to decide which collisions to surface loudly. See Conflict detection for how severities drive the conflict report and how load-order priority resolves a winner.

Mod-safety classification

Independently of collisions, modde tags whole mods as save-breaking when they contain .esp/.esm/.esl/.pex/.dll/.psc, and cosmetic when they only contain art/sound/archive/config assets. This drives the warnings you see before enabling a mod mid-playthrough.

Plugin & load-order handling

Fallout 4 has a real plugin system (has_plugin_system() is true), and modde manages it as a first-class, dual-pane concern:

• plugins.txt read/write. modde parses the standard format — *Plugin.esp = enabled, Plugin.esp = disabled, #… = comment — from the Proton prefix and writes it back in the same *-prefixed form.
• Dual-pane order. Mod install priority (“which mod’s files win”) is kept separate from plugin load order (“which .esp loads first”), stored in a dedicated plugin_order table per profile — MO2’s core insight.
• LOOT masterlist. modde ships a pure-Rust parser for LOOT’s public YAML masterlist; for Fallout 4 it pulls the loot/fallout4 repository and turns the after/requires/incompatible rules for your active plugins into modde load-order rules.
• Header validation. A binary header reader inspects the first ~1 KB of each plugin to extract the form version, ESM/ESL flags, and master list, flagging Form 43 plugins and missing masters before they cause a crash on load.

# Auto-sort the Fallout 4 load order against the LOOT masterlist
modde loot sort --game fallout4

# Validate plugin headers (Form version, missing masters)
modde loot validate --game fallout4

Not yet shipped for any Bethesda title: plugin pinning (“lock load order”), a dedicated Archives tab, archive content preview/packing, and per-mod INI tweak editing. LOOT sorting prints rules to the terminal rather than a rich report. See the MO2 parity audit for the full feature comparison.

Save tracking

Save tracking for Fallout 4 is Done and opted into the per-profile save layer (with_save_profiles(true)).

modde locates saves inside the Proton prefix at:

.../compatdata/377160/pfx/drive_c/Users/steamuser/Documents/My Games/Fallout4/Saves

The Fallout 4 save tracker (FALLOUT4_SAVE_TRACKER) scans that directory for .ess save files (.bak backups are skipped) and, for each one, parses the binary header to fingerprint it:

• It verifies the FO4_SAVEGAME magic so a stray Skyrim/Starfield save in the same folder is not mislabelled.
• From the header it reads the save number (the slot ID that increments each save) and the player name (a length-prefixed UTF-8 string), producing a label like Sole Survivor — Save 7.
• Slot type is inferred from the filename: Autosave… → auto, Quicksave… → quick, everything else → manual.
• A save whose header cannot be parsed is still captured, just without a label.

Captures are summarized newest-first and grouped by character, so a capture message reads like capture: 3 saves — Sole Survivor (slots 5, 6); …. See Save tracking & profiles for committing, browsing, and restoring save snapshots.

Installer specifics

• FOMOD is fully supported. When a downloaded mod contains a fomod/ModuleConfig.xml, modde detects it and runs the installer — interactively via the GUI wizard, or non-interactively from a saved choices file. Generate a template with modde fomod generate, inspect options with modde fomod inspect, and replay choices with --fomod-config. See the FOMOD installer guide.
• BA2 archives are deployed verbatim (never repacked or extracted), and their contents are still indexed for conflict analysis as described above.
• Loose-file mods (a bare Data/ tree or top-level asset folders) are recognized by the Bethesda bare-layout policy without any installer.
• Fallout 4 does not use REDmod (Cyberpunk), Unreal .pak, or SMAPI installers — those belong to other engine families. Its installer story is FOMOD + loose files + BA2, the standard Creation Engine toolkit.

Gaming tools & overlays

Fallout 4 launches through modde’s Tools & Overlays layer like any other game. The settings that matter most for this title:

• proton — pin a Proton/GE-Proton runner, set extra_env, override the Wine prefix, or force DLL overrides. Fallout 4 Script Extender (F4SE) and many script-extender-dependent mods need the right runner and, occasionally, forced overrides; dll_override_mode=forced with forced_dll_overrides=… is how you apply them through modde’s launcher integration.
• mangohud, vkbasalt, gamemode, reshade — performance overlay, post-processing, the Feral GameMode daemon, and the ReShade shader framework, enabled and configured per game with modde tool enable/configure.
• Overwrite capture. Tools that rewrite files in Data/ (xEdit/FO4Edit, BodySlide, Material Editor) can be run through modde tool run … --game fallout4 so their output is captured into an __overwrite__ mod and survives redeployment.

modde ships no OptiScaler profile for Fallout 4 (optiscaler_profiles is empty for this title). OptiScaler can still be applied as a generic tool, but there is no curated Fallout-4-specific upscaling profile the way there is for Stellar Blade.

Linux / Proton notes & gotchas

These notes apply to the game’s runtime on Linux and macOS, where Fallout 4 runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and plugins.txt, the My Games/Fallout4 tree, and the INI files live at their native Windows locations. modde itself runs natively on all three platforms.

• Launch the game once first. Until Proton has created the compatdata/377160 prefix, plugins.txt, the My Games/Fallout4 save tree, and the per-prefix INI files do not exist. Run the game once so the prefix is populated, then let modde manage it.
• INI files live in the prefix. Fallout4.ini, Fallout4Prefs.ini, and Fallout4Custom.ini are under the prefix’s My Games/Fallout4, not your Linux $HOME. modde patches them comment- and formatting-preserving rather than rewriting them wholesale. Creating Fallout4Custom.ini and enabling loose-file loading is still your responsibility, exactly as on Windows.
• Case sensitivity. Bethesda assets assume Windows’ case-insensitive paths. The bare-layout recognizer matches the standard asset directories case-insensitively, but a poorly packed mod with an unexpected directory name can still mis-deploy on a case-sensitive Linux filesystem — check the conflict report if assets do not load.
• Script extender. F4SE is installed into the game root like on Windows and launched through the script-extender executable; configure the runner with the proton tool and, if a plugin needs it, forced DLL overrides.
• GOG via Heroic. The GOG build (Heroic app ID 1998527297) works, but Steam
  • Proton is the most exercised path; the GOG prefix layout differs, so verify the detected gameDir and save path if you use it.

Worked example

Home-Manager profile

{ inputs, ... }:
{
  imports = [ inputs.modde.homeManagerModules.modde ];

  programs.modde = {
    enable = true;

    profiles.fo4-vanilla-plus = {
      game = "fallout4";
      # Leave gameDir unset (or installMode = "await-game") until Steam/Heroic
      # has installed Fallout 4 and you have launched it once to build the prefix.
      installMode = "await-game";
    };
  };
}

Once Steam has installed Fallout 4 and you have run it once, set gameDir to the install root (the folder containing Fallout4.exe and Data/) and rebuild; modde deploys the profile through its activation script.

CLI

# Install a Nexus mod into a Fallout 4 profile, applying saved FOMOD choices
modde install mod https://nexusmods.com/fallout4/mods/12345 \
  --profile fo4-vanilla-plus \
  --fomod-config my-choices.toml

# Discover what is already in Data/
modde scan --game fallout4

# Sort and validate the load order against the LOOT masterlist
modde loot sort --game fallout4
modde loot validate --game fallout4

# Deploy, then launch through Proton
modde deploy --profile fo4-vanilla-plus --game fallout4
modde play --game fallout4

# Capture xEdit/FO4Edit edits into an __overwrite__ mod
modde tool run /path/to/FO4Edit --game fallout4 -- -quickautoclean

See also

• Supported games — the status baseline and full game list
• Skyrim SE/AE, Starfield — sibling Creation Engine titles
• Deployment & VFS — the symlink-farm deploy pipeline
• Conflict detection — severities and winner resolution
• Scanning installed mods — what the scanner reports
• Save tracking & profiles — committing and restoring saves
• FOMOD installer — interactive and declarative installs
• Tools & Overlays — Proton, OptiScaler, ReShade, overwrite capture
• Parity audit — what is Done vs Partial

Fallout 76

Fallout 76 (game_id = fallout76) is one of the five Bethesda Creation Engine titles modde ships with. It shares the Bethesda deploy strategy, archive format, and INI machinery with Skyrim SE/AE, Fallout 4, and Starfield, but it is the odd one out: it is an always-online game whose saves live on Bethesda’s servers, and whose loose-archive mods are activated through an INI line rather than a local plugins.txt. Because of that, modde marks the title Partial overall, with Partial save tracking in particular.

Honest status: deployment, BA2 scanning, conflict classification, and launcher integration are real and working. What is not fully solved is save tracking (saves are server-side; only a local cache is visible) and load-order parity with single-player Bethesda games (Fallout 76 has no LOOT masterlist equivalent). See Supported games and the parity reference for the canonical status baseline.

Engine and overall status

The game is registered in crates/modde-games/src/registry.rs with the Bethesda engine family, the shared Bethesda collision classifier, a Fallout-76-specific archive scanner, and a Bethesda save tracker tagged as “FO76”. The plugin metadata lives in crates/modde-games/src/bethesda/mod.rs as the FALLOUT76 BethesdaGame record.

How modde detects the install

modde locates Fallout 76 the same way it finds every other Bethesda title: by its launcher IDs. The registration carries:

• steam_app_id = "1151340"
• steam_dir = "Fallout76" (the folder under steamapps/common/)

There are no Heroic GOG or Epic IDs for Fallout 76 — it ships on Steam (and the Microsoft Store / Bethesda launcher, which modde does not detect). On Linux the Steam copy runs under Proton, so modde resolves both the install root and the per-game Proton prefix from the Steam App ID:

~/.local/share/Steam/steamapps/common/Fallout76/          # install root
~/.local/share/Steam/steamapps/compatdata/1151340/pfx/    # Proton prefix

The Proton prefix matters for two things modde reads under drive_c/.../AppData/Local/Fallout76/: the (largely unused for FO76) plugins.txt location and the My Games documents tree where the local save cache lands.

Mod directory and deploy strategy

Like all Bethesda games, the mod directory is Data/ under the install root:

~/.local/share/Steam/steamapps/common/Fallout76/Data/

mod_directory() for the Bethesda plugin returns install.join("Data"), so modde deploys mod files into Data/ through its virtual-filesystem symlink farm — the same overlay mechanism used for every game. Your real Data/ directory stays clean; modde links the active profile’s files in and removes them on profile switch or undeploy. See the Deployment & VFS guide for how the overlay is built and torn down.

When modde extracts an archive whose contents look like a bare Bethesda layout (top-level meshes/, textures/, scripts/, interface/, sound/, strings/, … or loose .esp/.esm/.esl/.bsa/.ba2 files), it recognizes it as a Data-rooted mod and lays it down accordingly. This is the BareLayoutPolicy shared across Bethesda titles and is case-insensitive.

What scanning finds

Fallout 76 uses a dedicated scanner that differs from the Skyrim/Fallout 4 scanner. The single-player Bethesda scanner walks plugins.txt for an authoritative load order; Fallout 76 has no meaningful local load order, so it uses BethesdaArchiveScanner instead.

The Fallout 76 scanner (FALLOUT76_SCANNER):

• scans the Data/ directory only;
• discovers loose .ba2 archive files (the Fallout 76 archive extension);
• skips game-shipped archives by ignoring any file whose name starts with the SeventySix prefix (those are vanilla content, not mods);
• assigns each discovered archive a mod id of the form archive/<stem> and a confidence of 0.8 (a heuristic match, since there is no load-order file to corroborate it);
• maps a mod id back to its on-disk footprint as data/<stem>.ba2, which lets modde detect stale duplicates and reconcile a scanned archive against a managed mod.

In short: scanning Fallout 76 returns the loose .ba2 mods you have dropped in Data/, excluding Bethesda’s own SeventySix*.ba2 archives. Unlike Skyrim or Fallout 4, it does not pair plugins with companion archives or read enabled state from a load-order file, because Fallout 76 mods are activated through the INI rather than a plugin list. See the Scanning guide for the general scan workflow.

Conflict classification

Fallout 76 uses the shared Bethesda collision classifier, the same one used by Skyrim and Fallout 4. modde indexes the contents of .bsa/.ba2 archives (via the archive index reader) and classifies a file collision by its extension:

So two mods that both overwrite a texture inside their .ba2 archives produce a Cosmetic collision (last-deployed wins, cosmetically), whereas two mods that ship the same script or plugin produce a Dangerous collision worth your attention. The classifier reads inside archives, so it can flag conflicts between the contents of two .ba2 files, not just same-named archives.

Caveat for Fallout 76 specifically: Bethesda actively detects and bans certain client modifications in the online game. modde’s conflict severity is about file overwrites, not about whether a given mod is permitted online. Treat Dangerous-class mods (loose scripts, DLLs, plugins) with extra care on an online title.

See the Conflicts & load order guide for how severities surface and how overwrite order is resolved.

Save tracking

This is where Fallout 76 differs most from its single-player siblings, and why its save tracking is Partial.

Fallout 76 is an online game: the authoritative save is on Bethesda’s servers. The local .sav/.ess-style files in the Proton prefix are at best a partial cache, not your real character. modde represents this honestly:

• The Fallout 76 save tracker uses the magic header FO76_SAVEGAME to identify local Bethesda save files (the same binary header family as Skyrim’s TESV_SAVEGAME and Fallout 4’s FO4_SAVEGAME).

• When a save header parses, modde fingerprints the save number (a unique, incrementing slot id) and the player name read from the header.

• The tracker is flagged is_fo76 = true, so every capture is labelled with an explicit warning. Instead of the normal capture: … prefix, Fallout 76 captures read:

  capture (FO76 cache — server saves not tracked): …
  

That warning is the whole point: modde will fingerprint and snapshot what is on disk, but it tells you plainly that this is a local cache and that your real progress lives server-side and is not under modde’s control. The save directory modde looks in is resolved from the Proton prefix:

.../compatdata/1151340/pfx/drive_c/Users/steamuser/Documents/My Games/Fallout 76/Saves

(my_games_dir = "Fallout 76" for this title.) Do not rely on modde save profiles to roll a Fallout 76 character back and forth the way you would for Skyrim — the server state will not follow. For the general save-vault model (git-backed vaults, fingerprints, auto-capture), see the Save management guide.

Plugins and load order

has_plugin_system() returns true for every Bethesda game, and modde knows the Fallout 76 INI files it manages per profile:

• Fallout76.ini
• Fallout76Prefs.ini
• Fallout76Custom.ini

But in practice Fallout 76 has no plugins.txt-driven load order parity with single-player Bethesda titles. There is no LOOT masterlist for Fallout 76, and the game does not consume a plugins.txt the way Skyrim and Fallout 4 do. Instead, loose .ba2 archives are activated by listing them in the sResourceArchive2List / custom archive lines of Fallout76Custom.ini. That is why the scanner is archive-based rather than plugin-based, and why you should think in terms of “which archives are listed in my custom INI” rather than “what is my load order”. modde manages the INI files as part of a profile; you edit the archive list there to enable a loose .ba2 mod.

Installers (FOMOD, BA2, and friends)

Fallout 76 mods come in two common shapes, and modde handles both:

• Loose / archived files (.ba2 or bare Data/ layouts). Drop-in mods are recognized by the Bethesda bare-layout policy and deployed into Data/. A single .ba2 is the canonical Fallout 76 mod unit.
• FOMOD installers. modde includes a FOMOD engine (re-exported from fomod-oxide) shared by all Bethesda titles, so a Fallout 76 mod packaged as a FOMOD with ModuleConfig.xml is installed through the same interactive or declarative flow as a Skyrim FOMOD. See the FOMOD installer guide.

There is no REDmod, pak, or SMAPI handling here — those belong to Cyberpunk 2077, Unreal titles, and Stardew Valley respectively. Fallout 76 is archive-and-INI, plus FOMOD packaging.

Gaming tools for this title

Fallout 76 carries no built-in OptiScaler profile in its registration (optiscaler_profiles is empty) — unlike Stellar Blade, which ships a community-dxgi preset. You can still attach the generic tools modde supports to a Fallout 76 profile through the home-manager module or modde tool commands:

The most relevant of these for an online Proton title is proton itself, for runtime selection and DLL overrides. See the Tools & overlays guide for how tools attach to a profile and the Playing a game guide for the deploy-launch-capture flow.

Linux and Proton notes / known gotchas

The prefix-specific points here describe the game’s runtime on Linux and macOS, where Fallout 76 runs through Proton/Wine. On Windows the game runs natively, so there is no Wine prefix and the local cache and INI files live at their native Windows locations. modde itself runs natively on all three platforms.

• Always-online; saves are server-side. This is the single biggest gotcha. modde can snapshot the local cache but cannot version your real character. Every Fallout 76 capture is labelled FO76 cache — server saves not tracked.
• Anti-cheat / bannable mods. Bethesda enforces what is allowed in the live game. modde’s Dangerous severity flags file risk, not online-policy risk; loose scripts/DLLs/plugins can get you actioned regardless of how modde classifies the overwrite. Mod conservatively on a live online account.
• Activation is via Fallout76Custom.ini, not a load order. If a .ba2 mod does nothing after deploy, confirm its archive name is listed in the custom INI’s archive list — there is no plugins.txt to enable it.
• Vanilla archives are skipped on scan. Anything named SeventySix* is treated as base-game content and excluded from discovery, so it will not show up as a “mod”.
• No Heroic path. Detection is Steam-only for this title; there are no GOG or Epic launcher IDs.

Worked example

Home-Manager profile

A minimal Fallout 76 profile. Because saves are server-side, there is little point in elaborate save automation here — keep the profile focused on deploying loose-archive mods and selecting a Proton runtime:

programs.modde = {
  enable = true;
  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles.fo76 = {
    game = "fallout76";
    installMode = "auto";
    gameDir = "/home/me/.local/share/Steam/steamapps/common/Fallout76";

    tools = {
      proton.enable = true;
      gamemode.enable = true;
      mangohud.enable = true;
    };
  };
};

CLI

# Confirm modde sees the install (Steam App ID 1151340).
modde game list

# Scan Data/ for loose .ba2 mods (skips SeventySix* vanilla archives).
modde scan --game fallout76

# Inspect conflicts between deployed archives' contents.
modde conflicts --game fallout76

# Deploy the active profile's mods into Data/ and launch under Proton.
modde play --game fallout76

# Snapshot the local save cache. Note the FO76 server-side warning in output.
modde save auto-capture --game fallout76

modde save auto-capture --game fallout76 will print a capture line prefixed with capture (FO76 cache — server saves not tracked), reflecting that the real character lives on Bethesda’s servers.

See also

• Supported games — the canonical status table
• Fallout 4 and Starfield — sibling Creation Engine titles with full single-player save tracking
• Deployment & VFS
• Mod scanning
• Conflicts & load order
• Save management
• FOMOD installer
• Tools & overlays
• Playing a game
• Parity reference

Starfield

Starfield is one of modde’s five built-in Bethesda Creation Engine titles. It shares the data-driven BethesdaGame plugin with Skyrim SE/AE and the Fallout games, so its deploy strategy, conflict classification, and plugin handling are the same engine-wide machinery — only the per-title metadata (app ID, save folder, INI names, archive extension) differs.

Engine & overall status

Overall status: Partial. The scanner, conflict classifier, plugin/load-order handling, and diagnostics are all wired in and exercised, but Starfield’s overall path is held at Partial because the broader modding workflow around it is still maturing relative to the fully battle-tested Skyrim SE / Fallout 4 paths.

Save tracking is Done. Starfield ships a dedicated .sfs save tracker that is reachable end to end through the same git-backed save vault every other game uses. See Save tracking below and the canonical status table for how this lines up with the other titles.

Status vocabulary follows the repository’s docs/capability-matrix.toml and the parity audit. Done means shipped end to end and user-reachable; Partial means core logic exists but the surrounding workflow is not yet fully trustworthy.

How modde detects the install

Starfield is registered with a Steam App ID (1716740) and the Steam library folder name Starfield. modde’s launcher detection uses these to locate the install under your Steam libraries. No Heroic GOG or Epic IDs are registered for Starfield, so launcher auto-detection is Steam-oriented; for any other source you can always point a profile at the install directory explicitly.

Because Starfield runs through Proton on Linux, modde reads its Windows-side game data — plugins.txt and the per-profile INI files — from inside the Proton prefix rather than from a native Linux path. The relevant locations under the Steam compatibility prefix are:

# Save games (auto-detected by the plugin)
~/.local/share/Steam/steamapps/compatdata/1716740/pfx/drive_c/Users/steamuser/Documents/My Games/Starfield/Saves

# Load order (read by the scanner)
~/.local/share/Steam/steamapps/compatdata/1716740/pfx/drive_c/users/steamuser/AppData/Local/Starfield/plugins.txt

The save directory is resolved relative to your detected Steam common/ folder, so a non-default Steam library still resolves correctly as long as the compatdata/1716740/pfx prefix exists. If the prefix has not been created yet (you have never launched the game), save detection returns nothing rather than guessing a path.

Mod directory & deploy strategy

Like every Bethesda title, Starfield’s mod directory is Data/ under the game’s install root. modde deploys with the standard symlink-farm virtual filesystem: mods are staged in an intermediate directory and symlinked into Data/, leaving the original game files untouched and the whole deployment reversible.

The build/materialize/deploy pipeline, priority ordering (profile overrides win, then later mods in the load order), rollback, and modde verify all behave exactly as documented in Deployment & VFS. Nothing about Starfield changes the deploy model — it is the same engine-wide path used by Skyrim SE and Fallout 4.

When modde recognizes a bare (loose-files) mod layout during extraction, it keys off the shared Bethesda layout policy: recognized root directories include data, meshes, textures, scripts, interface, sound, music, materials, seq, shadersfx, and strings (matched case-insensitively), plus root-level files with .esp, .esm, .esl, .bsa, or .ba2 extensions. A mod archive that unpacks into one of these is treated as already rooted at Data/.

What scanning finds

Starfield uses the data-driven BethesdaScanner, the same plugins.txt-aware scanner as Skyrim SE and Fallout 4 (Fallout 76 is the exception — it uses the loose-archive scanner). Scanning the Data/ directory does the following:

1. Reads plugins.txt for authoritative load order. modde locates plugins.txt inside the Proton prefix (path above) and parses it. Each line is a plugin; a leading * marks it enabled, an unprefixed line is disabled, and #/blank lines are ignored.
2. Emits plugins listed in plugins.txt first, at high confidence (0.95). For each plugin it pairs companion archives that share the plugin’s stem — both <stem>.ba2 and the texture-suffixed <stem> - Textures.ba2 — into the same discovered mod.
3. Also scans for plugins not in plugins.txt (disabled or unmanaged) by walking Data/ for .esp, .esm, and .esl files, emitting them at lower confidence (0.8) so you can see plugins the load order does not yet track.

Each discovered mod’s footprint is recorded Data-relative, which is how modde compares against MO2-style manifests when detecting stale duplicates. Plugin file extensions recognized are esp, esm, esl; companion archive extensions are bsa and ba2 (Starfield ships .ba2).

Conflict classification

Starfield uses the shared BethesdaCollisionClassifier. When two mods provide the same relative path, modde classifies the severity of the overlap by file type. It can also read inside .bsa/.ba2 archives (via the archive index) to classify conflicts on archived contents, not just loose files.

“Dangerous” overlaps (plugins, script bytecode/source, native DLLs) are the ones that change game logic and most often need a real resolution; cosmetic texture and mesh overlaps are usually a matter of which look wins. The same extension set feeds the save-breaking fingerprint described below. For the full conflict workflow — how to inspect, hide files, and reorder — see the Conflicts guide.

Save tracking

Save tracking for Starfield is Done. Unlike the older Bethesda titles, which parse a binary .ess header for the character name and save number, Starfield’s saves are .sfs files and are tracked with modde’s declarative pattern-based tracker.

What the tracker captures:

• File type: .sfs files in the Saves directory (non-recursive).

• Slot category, derived from the filename prefix:

  Prefix	Category
  Autosave	auto
  Quicksave	quick
  Exitsave	exit
  Save	manual

  Any .sfs that does not match a known prefix still falls back to manual, so no save is silently dropped.

• Label: the file stem (the save’s filename without the .sfs extension).

• Capture summary: grouped by category, so a capture reads like capture: 6 saves (2 auto, 1 exit, 3 manual) rather than a flat count.

These detected saves feed the same git-backed save vault as every other game: a per-game git repository with per-profile branches, automatic capture on profile switch and on game exit, history browsing, and restore. Each snapshot embeds a SHA-256 fingerprint of the profile’s enabled save-breaking mods (the Dangerous-classified extensions above), so restoring a save that was made under a different mod set warns you about which save-breaking mods were added or removed. The end-to-end save workflow — adopt, capture, watch, history, restore, fingerprint semantics — is documented in the Save management guide.

Plugin & load-order handling

Starfield has a plugin system (has_plugin_system() is true). modde reads and writes plugins.txt in the *-prefix enabled/disabled format. When modde writes the file it prepends a generated header marker and emits one line per plugin, prefixing enabled plugins with *:

# This file is generated by modde. Do not edit manually.
*Starfield.esm
*BlueprintShips-Starfield.esm
SomeDisabledMod.esp

The load order read from plugins.txt is authoritative for the scanner and is the order modde uses when resolving conflicts (later wins).

Diagnostics

Starfield participates in the shared Bethesda diagnostics engine, which runs:

• Missing masters (Error): flags an active plugin whose required master is not present in the load order — the game would crash on load. The suggested fix is to install and enable the mod that provides the missing master.
• Orphaned overrides (Info): notes when the profile’s overrides directory contains files, since those take top priority over every mod.
• Empty / store-presence checks from the base diagnostics engine.

The Form 43 (“Oldrim” plugin format) diagnostic is Skyrim SE/AE only — it does not apply to Starfield. Do not expect a Form-43 warning here.

Installer specifics

• FOMOD: Starfield benefits from the same scripted-installer support as the rest of the engine. modde’s FOMOD support is provided by the fomod-oxide installer, so option-tree FOMOD packages (the common Nexus install format for Bethesda mods) are handled by the shared installer path. See the FOMOD guide for how the option tree is presented.
• Loose archives / plugins: Mods that are just .ba2 archives and/or .esp/.esm/.esl plugins dropped into Data/ are recognized directly by the scanner and bare-layout policy; no scripted installer is required.
• There is no REDmod, SMAPI, or .pak step for Starfield — those belong to other engines (Cyberpunk, Stardew Valley, and Unreal/Larian titles respectively). Starfield is a plugin + .ba2 Creation Engine title.

Gaming tools that matter

Starfield ships with no built-in OptiScaler profiles (optiscaler_profiles is empty in its registration), so unlike Stellar Blade it has no preconfigured OptiScaler/OptiPatcher setup. You can still manage the generic gaming tools through modde’s tool system:

• proton — per-game Proton version, Wine prefix, environment variables, and DLL overrides. This is the most relevant tool for Starfield on Linux; several script-extender and ASI-loader mods need forced DLL overrides (see below).
• mangohud, vkbasalt, gamemode — performance overlay, Vulkan post-processing, and the GameMode daemon.
• reshade / optiscaler — file-patching tools that place DLLs and configs into the game directory; modde records what it patched so tool revert can cleanly remove them.

Named executables (script extenders, xEdit/SF1Edit-style tools, ASI managers) are managed through modde’s Executables system with args, working directory, environment, Wine DLL overrides, a configurable output mod, and overwrite capture. See the Tools & overlays guide for modde tool and modde exec usage.

Linux / Proton notes & known gotchas

These notes cover the game’s runtime on Linux and macOS, where Starfield runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and the Saves directory, plugins.txt, and INI files live at their native Windows locations. modde itself runs natively on all three platforms.

• Launch the game once before expecting save or load-order detection. Both the Saves directory and plugins.txt live inside compatdata/1716740/pfx, which Proton only creates after the first launch. Until then, save detection returns empty and the scanner falls back to scanning loose Data/ plugins without an authoritative order.

• DLL-based mods (script extenders, ASI loaders) usually need DLL overrides. Configure them through the proton tool rather than hand-editing the prefix:

  modde tool configure proton --game starfield dll_override_mode=forced forced_dll_overrides=sfse_loader
  

  Use whatever proxy/loader DLL name the specific mod requires.

• StarfieldCustom.ini may need creating. Many loose-file and archive-invalidation workflows expect a StarfieldCustom.ini in the My Games folder; modde manages both StarfieldPrefs.ini and StarfieldCustom.ini per profile, but the game itself does not always ship a Custom INI by default.

• Steam Cloud-aware saves. modde preserves Steam’s cloud marker and parks inactive root saves under its own .modde/ directory during profile switches, so cloud-synced Starfield saves are not clobbered. See the Save management guide for the Steam Cloud behavior.

Worked example

Home-Manager profile

Declare a Starfield profile with the home-manager module. You can declare it before the game is installed and let modde wait for the install:

{ inputs, ... }:
{
  imports = [ inputs.modde.homeManagerModules.modde ];

  programs.modde = {
    enable = true;

    profiles.my-starfield = {
      game = "starfield";
      # Wait for Steam/Proton to create the install before deploying.
      installMode = "await-game";
      # Once Steam has installed the game, set the Data/-bearing install root:
      # gameDir = "/path/to/SteamLibrary/steamapps/common/Starfield";
    };
  };
}

After Steam has installed Starfield, set gameDir to the install root (the folder containing Data/) and rebuild; modde deploys the profile via its activation script.

CLI

# Deploy the Starfield profile, then launch through modde (captures saves on exit)
modde play --game starfield --profile my-starfield

# Or deploy without launching
modde deploy --profile my-starfield --game starfield

# Scan the install for plugins and loose .ba2 archives
modde scan --game starfield

# Adopt pre-existing saves into a profile (first capture in the vault)
modde save adopt --game starfield --profile my-starfield

# Manually capture .sfs saves with a message
modde save capture --game starfield --profile my-starfield -m "before the Unity"

# Watch for new saves when launching outside `modde play`
modde save watch --game starfield --interval 60

# Configure forced DLL overrides for a script-extender / ASI loader
modde tool configure proton --game starfield dll_override_mode=forced forced_dll_overrides=sfse_loader

# Run an external tool (e.g. a conflict cleaner) with overwrite capture
modde tool run /path/to/sf-tool --game starfield -- --some-flag

See also

• Supported games — the canonical status table and Wabbajack mapping
• Deployment & VFS — the symlink-farm deploy model used for Data/
• Save management — the git-backed save vault and fingerprinting
• Conflicts — inspecting and resolving the conflicts modde classifies
• FOMOD installers — scripted-installer option trees
• Tools & overlays — Proton, OptiScaler, executables, and modde tool
• Scanning — how modde scan discovers installed mods
• Parity audit — what is Done vs Partial

Fallout: New Vegas

Fallout: New Vegas (game_id fallout-new-vegas) is a built-in modde title backed by the shared, data-driven Gamebryo game plugin. The same plugin code drives Oblivion; the per-game differences (Steam app id, save folder name, INI set, Nexus domain) are configuration on a single GamebryoGame record.

Overall status: Partial. Deployment, filesystem scanning, BSA-aware conflict classification, save tracking, and plugins.txt load-order read/write all ship. What keeps New Vegas from Done is the absence of a bespoke, end-to-end script-extender (NVSE) bootstrap workflow and the deeper plugin-management UX (automatic master/ESM ordering, in-app conflict resolution) that the Bethesda Creation-Engine titles get. Treat New Vegas as a solid deploy-and-scan target, not a full Mod-Organizer replacement. The canonical status baseline is docs/capability-matrix.toml and the supported-games table.

Engine and overall status

The plugin advertises has_plugin_system() == true and supports_save_profiles() == true, so New Vegas participates in modde’s load-order and save-profile machinery.

How modde detects the install

New Vegas is registered with a Steam launcher binding and no Heroic GOG/Epic ids:

modde locates the install by walking your Steam libraries for app 22380, landing on steamapps/common/Fallout New Vegas. Because there is no Heroic binding shipped, GOG/Epic copies are not auto-detected for this title — point modde at the directory explicitly (--game-dir on the CLI, or gameDir in the home-manager module) if you run a non-Steam copy.

The numeric Nexus game id is intentionally None for New Vegas: the newvegas domain is enough for URL-based installs and update tracking, but the in-app “Browse Nexus” picker (which needs the numeric id) will not list this title until the id is confirmed. URL installs from nexusmods.com/newvegas/mods/<id> resolve correctly via the domain.

Mod directory and deploy strategy

The mod directory is <install>/Data — the same Data/ folder New Vegas itself reads plugins, meshes, textures, sound, and BSAs from.

modde never copies mods on top of your game files. It uses the standard symlink-farm virtual filesystem described in Deployment & VFS: mods are staged, the winning file for each relative path is resolved by load order, and the result is symlinked into Data/. This keeps the base install clean and every deploy reversible.

When modde unpacks a downloaded archive, the Gamebryo plugin’s analyze_mod_archive looks for a top-level Data/ directory inside the extracted mod. If present, it applies StripContentRoot { root: "Data" }, so a mod packaged as Data/MyMod.esp deploys its contents directly into the game’s Data/ rather than nesting a redundant Data/Data/. For archives that are not wrapped in Data/, the plugin’s bare-layout recogniser accepts the mod when it sees the expected loose roots — data, meshes, textures, sound, music, menus, scripts, shaders (matched case-insensitively) — or top-level .esp / .esm / .bsa files. This is what lets older “drop into Data” mods install without manual repackaging.

What scanning finds

modde scan --game fallout-new-vegas runs the Gamebryo scanner over the single Data directory. The scanner:

• reads the top level of <install>/Data (non-recursive);
• treats every .esp and .esm file as a discovered mod;
• pairs each plugin with a same-stem .bsa archive when one exists (e.g. MyMod.esp + MyMod.bsa are reported together as one mod’s files);
• assigns each mod the id plugin/<filename> with a fixed match confidence of 0.85;
• records each file’s install-relative path and on-disk size.

Loose meshes/textures dropped straight into Data/ without an accompanying plugin are not surfaced as distinct mods by this scanner — discovery is plugin-anchored. For matching an existing install against a Wabbajack manifest (including New Vegas lists, see below), combine the scan with --manifest; the scanner’s per-mod footprint is the lowercased plugin filename, which is what manifest matching keys on. See Mod Scanning for threshold, dry-run, and import flags.

Conflict classification

Two layers cooperate when New Vegas mods overlap.

Per-file collision severity (used when two deployed mods write the same relative path) comes from the BSA-aware collision policy:

.bsa is registered as the archive extension for the New Vegas collision classifier, so archive overlaps are reasoned about as packed content rather than loose files.

Per-mod safety classification (classify_mod, used to flag whether installing/toggling a mod can invalidate saves) uses the Gamebryo content policy:

• Save-breaking extensions: .esp, .esm, .pex, .dll, .obse, .nvse, plus anything under a scripts/ directory. Adding or removing these changes the form-id / script footprint a save depends on.
• Cosmetic extensions: .nif, .bsa, .dds, .png, .tga, .jpg, .kf, .wav, .mp3, .ogg, .ini, .xml.

The same policy also classifies content into categories used across the UI and reports — Plugin (esp/esm), Texture, Mesh, Sound, Script (including .obse/.nvse), Archive (bsa), Config, and Binary (dll). See Conflicts for how severities surface in the conflict report.

Save tracking

New Vegas save tracking is shipped (Done). On Linux and macOS the game runs through Proton/Wine, so the Gamebryo save tracker points at the compatibility prefix:

<Steam>/steamapps/compatdata/22380/pfx/drive_c/users/steamuser/Documents/My Games/FalloutNV/Saves

i.e. modde derives the save folder from the Steam compatdata directory for app 22380, then descends into the Wine prefix’s Documents/My Games/FalloutNV/Saves. (Note the on-disk folder name is FalloutNV, not the modde id fallout-new-vegas.) On Windows the game runs natively, so the same saves live at their native Windows location with no prefix involved.

What is fingerprinted in that directory:

• files with the .ess (save) and .fos (co-save) extensions;
• *.bak backups are excluded;
• detection is non-recursive (the top level of Saves only);
• every match is filed under the manual category, with the relative filename as its label, sorted newest-first by modification time.

Capture summaries use the by-category form, e.g. capture: 3 saves (3 manual), so save-profile snapshots tell you how many saves were rolled into each profile. Save profiles are enabled for this title. See Save Management for snapshot, restore, and per-profile isolation.

Plugin and load-order handling

New Vegas orders plugins through a plugins.txt-style file. modde ships read/write helpers for that format:

• Reading strips comment lines (# or ;), ignores blanks, and removes a leading * enabled-marker from each plugin name, yielding the ordered list of active plugins.
• Writing emits one plugin per line, each prefixed with * to mark it enabled (creating the parent directory if needed).

This gives modde a faithful round-trip of the active-plugin list. What is not yet shipped for New Vegas is the higher-level plugin UX the Creation-Engine titles have — automatic master/ESM sorting, LOOT-style ordering, or in-app conflict resolution. Curate complex load orders with an external sorter and let modde persist the result; this is part of why New Vegas is Partial.

Installer specifics

• FOMOD is the primary scripted-installer path. New Vegas mods that ship a fomod/ModuleConfig.xml are driven through modde’s FOMOD installer just like the Bethesda titles — see the FOMOD Installers guide for the option/flag selection flow.
• Data/-rooted and bare archives install without FOMOD via the StripContentRoot / bare-layout recognition described above.
• BSA archives (.bsa) deploy as opaque packed content; modde does not unpack them, and same-stem BSAs are tracked alongside their plugin.
• NVSE / OBSE / script plugins (.nvse, .obse, .dll) deploy as files into Data/ and are flagged save-breaking, but modde does not currently bootstrap the NVSE loader executable for you — install the script extender itself manually into the game root, then manage its plugins through modde.
• REDmod, .pak, and SMAPI installers are not applicable to this engine.

Gaming tools and Proton

New Vegas ships no OptiScaler profiles (optiscaler_profiles is empty for this title), so the upscaler presets that exist for Unreal titles like Stellar Blade do not apply here. The engine-agnostic overlays and the Proton tool still work: MangoHud, vkBasalt, ReShade, GameMode, and the per-game proton tool (Proton build selection, Wine prefix, environment variables, and DLL overrides) are all available through Tools & Overlays. DLL overrides matter for script extenders and ENB-style injectors that ship a d3d9.dll/dxgi.dll — set those through the proton tool’s override settings so the Wine prefix loads them.

Linux / Proton notes and gotchas

These notes cover the game’s runtime on Linux and macOS, where New Vegas runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and saves and INI files live at their native Windows locations. modde itself runs natively on all three platforms.

• Saves live in the Proton prefix, not your home directory. They are under steamapps/compatdata/22380/pfx/..., which is why a fresh prefix (deleting compatdata, switching Proton builds) appears to “lose” saves. modde reads them from exactly that path, so launch the game once under Proton before expecting save detection to find anything.
• No Heroic detection ships for New Vegas. GOG/Epic copies need an explicit game directory.
• Run the game once before deploying so Proton creates the prefix and the My Games/FalloutNV tree exists; INI files (Fallout.ini, FalloutPrefs.ini, FalloutCustom.ini) are generated on first launch.
• Script extenders are DLL injection. NVSE relies on Proton honouring the loader; verify the override and that the extender’s own files sit in the game root, not in Data/.
• The numeric Nexus id is unset, so use direct nexusmods.com/newvegas/... URLs rather than the in-app browse picker.

Worked example

Home-Manager profile

programs.modde = {
  enable = true;

  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles.viva-new-vegas = {
    game = "fallout-new-vegas";
    installMode = "auto";
    gameDir = "/home/me/.local/share/Steam/steamapps/common/Fallout New Vegas";

    wabbajackList = {
      url = "https://example.com/viva-new-vegas.wabbajack";
      hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
    };

    tools = {
      mangohud.enable = true;
      gamemode.enable = true;
      proton = {
        enable = true;
        # Honour a script-extender / injector DLL inside the prefix.
        settings.dllOverrides = "d3d9=n,b";
      };
    };
  };
};

If New Vegas is not installed yet, omit gameDir or set installMode = "await-game"; activation prints the next step and continues without failing, then deploys once you set gameDir and rebuild. See the Home-Manager Module reference for every option.

CLI

# Discover what is already in Data/ and import it into a profile
modde scan --game fallout-new-vegas --import-to viva-new-vegas

# Match an existing install against a Wabbajack New Vegas list
modde scan --game fallout-new-vegas \
  --manifest /path/to/viva-new-vegas.wabbajack \
  --import-to viva-new-vegas \
  --prune-duplicates

# Deploy the symlink farm into <install>/Data
modde deploy --profile viva-new-vegas --game fallout-new-vegas

# Snapshot saves from the Proton prefix into the profile
modde save snapshot --game fallout-new-vegas --profile viva-new-vegas

# Deploy then launch through Proton
modde play --game fallout-new-vegas

Wabbajack manifests that name the game FalloutNewVegas or FalloutNV both map to the fallout-new-vegas id, so either spelling in a modlist resolves to this title. See Wabbajack for the full modlist workflow.

See also

• Supported Games — status table and Wabbajack mapping
• Oblivion — the other Gamebryo title sharing this plugin
• Deployment & VFS
• Mod Scanning
• Conflicts
• Save Management
• FOMOD Installers
• Tools & Overlays
• Wabbajack
• Home-Manager Module
• Parity & capability matrix

The Elder Scrolls IV: Oblivion

The Elder Scrolls IV: Oblivion (game_id oblivion) is one of modde’s two Gamebryo-engine titles. It shares a single data-driven game plugin (GamebryoGame in crates/modde-games/src/gamebryo/mod.rs) with Fallout: New Vegas, so its mod-directory rules, conflict policy, and plugins.txt handling match that engine generation.

Status at a glance

The canonical, test-coupled status row lives in the supported games table. This page expands on the mechanics behind that Partial rating.

Engine and registration

Oblivion is registered in crates/modde-games/src/registry.rs with the EngineFamily::Gamebryo engine and the following identifiers:

The plugin reports has_plugin_system() == true and supports_save_profiles() == true, and exposes the Nexus domain oblivion so a nexusmods.com/oblivion/mods/<id> URL resolves straight to this game.

Not to be confused with the 2025 Unreal Engine remaster. That is a separate registration, Oblivion Remastered (game_id oblivion-remastered, Steam App ID 2623190), which uses the Unreal pak/ucas/utoc pipeline — not the Gamebryo path described here.

Install detection

modde does not install the base game; it locates a launcher-managed install. For Oblivion the registration carries only the Steam identifiers (steam_app_id = "22330", steam_dir = "Oblivion"); the Heroic GOG/Epic app-id fields are None, so detection is Steam-oriented. Under launcher_games() Oblivion is matched by its Steam App ID, and the standard Steam library scan finds the install at .../steamapps/common/Oblivion/.

If you install through a non-default path (or via Heroic/GOG), set the game directory explicitly — gameDir in the home-manager module, or --game-dir on the CLI — and modde will use that instead of probing Steam.

Mod directory and deploy strategy

The Gamebryo plugin places mods under the game’s Data/ folder:

<install>/Data/

That is the value returned by mod_directory(install) — install.join("Data"). Deployment uses modde’s standard symlink-farm VFS: mods are staged, the winning file for each relative path is resolved by load order, and the staging tree is symlinked into Data/. See Deployment & VFS for the build → materialize → deploy pipeline and rollback.

Archive recognition on install

When you install a downloaded archive, the plugin’s analyze_mod_archive detects the common “the mod ships its own Data/ folder” layout and strips it, mapping the archive’s Data/ contents to the game’s Data/ (InstallMethod::StripContentRoot { root: "Data" }). Archives that instead ship a bare Gamebryo layout — loose meshes/, textures/, sound/, music/, menus/, scripts/, shaders/ folders, or top-level .esp/.esm/.bsa files — are recognized by recognizes_bare_layout (case-insensitively) and deployed directly into Data/ without a wrapper directory. See the FOMOD guide for installers that present optional sub-packages.

What scanning finds

modde scan --game oblivion runs the Gamebryo scanner (OBLIVION_SCANNER), which inspects only the Data/ directory and looks for plugin files:

• It enumerates top-level files in Data/ and keeps those with an .esp or .esm extension (case-insensitive). Sub-directories are skipped at this level.
• For each plugin it also pulls in a sibling .bsa archive that shares the plugin’s stem (e.g. MyMod.esp + MyMod.bsa), grouping them into one discovered mod.
• Each discovered mod is reported with mod_id = "plugin/<filename>", the plugin filename as the display name, its Data/-relative file list with sizes, and a detection confidence of 0.85.

The scanner’s footprint for matching against a Wabbajack manifest is the lowercased plugin filename, so manifest archives that carry a known .esp/.esm line up with on-disk plugins. See Mod Scanning for --import-to, --manifest, and threshold options.

The scanner intentionally does not walk loose-asset trees or open BSA contents — it discovers plugins and their paired archives. Loose textures and meshes are still resolved and conflict-checked at deploy time; they are just not enumerated as standalone “mods” by scan.

Conflict classification

Oblivion uses the shared Gamebryo collision classifier with a bsa-aware archive comparison (gamebryo_collision_classifier, built over BSA_ARCHIVE_EXTENSIONS = ["bsa"]). When two mods provide the same relative path, the later mod in the load order wins, and the per-extension severity comes from the default policy:

Run modde collisions --profile <name> for the critical/major report, or add --all to include cosmetic overlaps. See Conflicts & Load Order for shadowed-mod and redundant-file reporting and per-file hiding.

Content categories and save-breaking classification

Separately from collision severity, the Gamebryo content policy classifies file types so save-tracking knows what is risky. Extensions are mapped to categories — esp/esm → Plugin, dds/png/tga/jpg → Texture, nif/kf → Mesh, wav/mp3/ogg → Sound, pex/obse/nvse → Script, bsa → Archive, ini/xml → Config, dll → Binary — and the following are treated as save-breaking:

• Extensions: esp, esm, pex, dll, obse, nvse
• Any file under a scripts/ directory

Cosmetic file types (nif, bsa, dds, png, tga, jpg, kf, wav, mp3, ogg, ini, xml) are not save-breaking. This set is what feeds the save fingerprint described below.

Plugin / load-order handling

Gamebryo games carry a real plugin system. modde reads and writes plugins.txt-style load-order files via read_plugin_order_file / write_plugin_order_file:

• Reading strips blank lines, #/; comments, and the leading * enabled-marker, returning a clean ordered list of plugin names.
• Writing emits one plugin per line, each prefixed with * to mark it enabled.

This is the same plugins.txt convention Bethesda’s Creation-Engine titles use, so modde’s plugin-order backup/restore (modde backup plugins / backup restore-plugins) applies to Oblivion as well. Note that Oblivion’s classic engine does not use light plugins (.esl); load order is .esm masters first, then .esp plugins. modde’s shared LOOT tooling is built for the Bethesda masterlists; treat any cross-engine LOOT sorting for Oblivion as best-effort rather than a guaranteed masterlist — fall back to a curated order captured with backup plugins.

Save tracking

On Linux and macOS Oblivion runs through Proton/Wine, so save_directory() resolves saves inside the compatibility prefix rather than at a native path:

<steam>/steamapps/compatdata/22330/pfx/drive_c/users/steamuser/Documents/My Games/Oblivion/Saves/

That path is assembled from the Steam common root, the compatdata/<app_id> prefix, and the game’s my_games_dir (Oblivion). On Windows the game runs natively, so the same saves live at their native Windows location with no prefix involved. The Gamebryo save tracker (GAMEBRYO_SAVE_TRACKER) then:

• Matches save files by extension — .ess (Oblivion saves) and .fos (shared Gamebryo extension) — non-recursively in that directory.
• Excludes *.bak backups.
• Categorizes every match as manual and labels it by its relative filename.

Saves flow into modde’s git-backed vault (one repo per game, one branch per profile). Each snapshot embeds a SHA-256 fingerprint computed over the sorted list of enabled save-breaking mods (the esp/esm/pex/dll/obse/ nvse + scripts/ set above). On restore, modde compares fingerprints and warns when the save-breaking mod set has changed since the snapshot was taken. See Save Management for capture, history, restore, and save adopt for existing saves.

Installer specifics

• FOMOD — Oblivion mods are frequently packaged as FOMOD installers. modde’s FOMOD support (interactive wizard plus declarative TOML/JSON/Nix config) works for any game; pre-resolve choices declaratively where you can. See the FOMOD guide.
• Bare / Data-rooted archives — handled automatically by analyze_mod_archive / recognizes_bare_layout as described above.
• OBMM/OMOD — Oblivion’s legacy OMOD format is not a modde installer type. Extract such mods to a plain Data/ layout (or convert) before installing.
• Script extenders (OBSE) — the Oblivion Script Extender is an external runtime, not a mod modde installs. .obse/.dll plugins that ride along with OBSE are scanned/classified (as Script/Binary, and save-breaking), but you launch the game through the script-extender loader yourself — see Proton notes.

There is no REDmod, .pak, or SMAPI path here; those belong to other engines (Cyberpunk 2077, Baldur’s Gate 3, Stardew Valley respectively).

Tools that matter for Oblivion

Oblivion has no OptiScaler profiles registered (optiscaler_profiles: &[]), which is expected for a 2006 DX9 title — DLSS/FSR upscaling frameworks are not a fit. The tools that do matter are launch-and-config integrations:

• Proton — version selection, Wine prefix, environment, and DLL overrides. The script extender needs obse_loader.exe/obse_*.dll to be honored, which usually means a forced DLL override and launching via the loader (see below).
• MangoHud / vkBasalt / GameMode — overlay, post-processing, and performance tuning; all apply to Oblivion as launch/environment integrations.
• xEdit / BodySlide-style tools — run external editors with overwrite capture via modde tool run, which snapshots Data/ before and after and parks new/changed files into an __overwrite__ mod.

See Tools & Overlays for the full tool surface, and Playing with modde for deploy-then-launch.

Linux / Proton notes and gotchas

These notes cover the game’s runtime on Linux and macOS, where Oblivion runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and saves and INI files live at their native Windows locations. modde itself runs natively on all three platforms.

• Saves live in the Proton prefix, under compatdata/22330/... — not in your Linux home directory. If you change Proton/compat tools or wipe the prefix, the save path moves with it; re-run modde save adopt if needed.
• Script extender launch — OBSE must be invoked through its loader inside the prefix. Configure Proton DLL overrides for the OBSE DLLs (e.g. via modde tool configure proton --game oblivion dll_override_mode=forced forced_dll_overrides=...) and set Steam’s launch command to the loader.
• Data/ case-sensitivity — Windows is case-insensitive; Linux is not. modde recognizes bare layouts case-insensitively at install time, but mods that reference assets with a different case than the file on disk can still fail to load. Keep the on-disk casing matching what plugins expect.
• INI is not auto-merged — modde detects Oblivion.ini as a config file and classifies INI collisions as Config severity, but it does not perform an MO2-style INI tweak/merge. Edit the INI under the prefix’s My Games/Oblivion/ directly when a mod requires it.
• Partial rating — the core path (install → scan → deploy → conflicts → saves) is solid, but there is no Oblivion-specific BSA browser, no INI editor, and no engine-validated LOOT masterlist. Plan load order with backup plugins/restore-plugins snapshots.

Worked example

CLI

# 1. Confirm modde resolves the install (Steam App ID 22330)
modde scan --game oblivion --dry-run

# 2. Create a profile and import what is already in Data/
modde scan --game oblivion --import-to my-oblivion

# 3. Install a Nexus mod (oblivion domain resolves automatically)
modde install mod "https://www.nexusmods.com/oblivion/mods/12345" \
  --game oblivion --profile my-oblivion

# 4. Inspect conflicts before playing
modde collisions --profile my-oblivion --all

# 5. Back up the current plugin order, then deploy and play
modde backup plugins --profile my-oblivion --game oblivion
modde play --game oblivion --profile my-oblivion

# 6. Adopt pre-existing saves into the vault (one-time)
modde save adopt --game oblivion --profile my-oblivion

Home-Manager profile

programs.modde.profiles.my-oblivion = {
  game = "oblivion";
  # Set once Steam has installed the game; until then omit it or use await-game.
  gameDir = "/home/me/.local/share/Steam/steamapps/common/Oblivion";
  installMode = "auto";

  tools = {
    gamemode.enable = true;
    mangohud.enable = true;
    proton = {
      enable = true;
      settings = {
        # Honor OBSE DLLs inside the Proton prefix.
        dll_override_mode = "forced";
        forced_dll_overrides = "dxgi";
      };
    };
  };
};

Declare the profile before the game exists by leaving gameDir unset (or installMode = "await-game"); activation prints the next step and continues. modde never installs the base game itself.

See also

• Supported games — the canonical status table
• Fallout: New Vegas — the sibling Gamebryo title
• Oblivion Remastered — the separate Unreal remaster
• Mod Scanning — scan, --import-to, manifest matching
• Conflicts & Load Order — severity, hiding, plugin order
• Deployment & VFS — symlink-farm deploy and rollback
• Save Management — vault, fingerprinting, restore
• FOMOD — interactive and declarative installers
• Tools & Overlays — Proton, MangoHud, overwrite capture
• MO2 parity & capability audit — what is Done vs Partial

The Elder Scrolls IV: Oblivion Remastered

Oblivion Remastered is a hybrid: an Unreal Engine 5 presentation layer wrapped around the original Gamebryo simulation. modde models that split directly — the plugin recognises both the UE pak ~mods layout (.pak / .ucas / .utoc) and Bethesda-style .esp / .esm plugins, and its scanner walks both the UE pak directory and a Data/ plugin tree. The game id is oblivion-remastered.

Overall status: Partial. Deployment, scanning, conflict classification, Wine DLL-override detection, and save tracking all work, and the title is wired into the install pipeline (Steam/Heroic detection, Nexus, Wabbajack). What keeps it short of Done is the same ceiling as the other UE titles: no bespoke load-order editor for the ESP/ESM side, no pak-internal asset conflict resolution (conflicts are classified by filename, not by archive contents), and the install-method coverage is narrower than the mature Creation Engine games. See Supported games for the status baseline and Parity for the MO2/Vortex/Wabbajack comparison.

Engine and registration

The plugin is its own GamePlugin implementation rather than a plain instance of the shared UE4 game type — that is what lets it carry the Bethesda plugin extensions, the Gamebryo-style save layout, and the blended content policy.

Install detection

modde finds the install through the launcher integration, keyed on the Steam App ID 2623190 (Steam install dir Oblivion Remastered). There is no registered Heroic/GOG/Epic mapping, so detection is Steam-first; a manually specified install path also works for non-Steam copies.

On Linux and macOS the game runs through Proton/Wine, so modde resolves the prefix-rooted paths (saves, and the Wine DLL overrides described below) under the Steam compat data tree (on Windows these are native paths, no prefix involved):

<steam>/steamapps/compatdata/2623190/pfx/drive_c/...

If you have never launched the game, that prefix will not exist yet. modde’s prefix-dependent lookups return “not found” in that case — launch the game once through Steam/Proton so Proton creates the prefix, then re-run.

Mod directory and deploy strategy

The deploy root for pak-style mods is the UE ~mods directory under the project’s Content/Paks:

<install>/OblivionRemastered/Content/Paks/~mods

The leading tilde is load-bearing: UE’s pak mounter sorts ~mods after the shipping paks, so mod paks override base content. modde deploys mods here the same way it deploys for every other game — a profile’s enabled mods are linked into the live game tree, and switching profiles re-links the set. Plugin-style content (.esp / .esm) belongs in the game’s Data/ tree, which the scanner also walks (see below).

What scanning finds

The scanner inspects two locations:

Content/Paks/~mods     # UE pak mods
Data                   # Bethesda-style plugins

• Pak mods are discovered by grouping files that share a stem across the .pak / .ucas / .utoc extensions into a single mod (so a .pak and its sidecar .ucas/.utoc count as one mod, not three). These come from the paks-mods source location at confidence 0.9, with mod ids prefixed pak/.
• Plugins are discovered as one mod per top-level .esp file directly in Data/ (source location Data, confidence 0.8, mod ids prefixed plugin/). No prefixes are ignored, so master files are listed too.

Each discovered mod also has a footprint used for matching against a known mod:

Conflict classification

Oblivion Remastered uses modde’s pak collision classifier (archive extensions pak / ucas / utoc, default severity table). When two enabled mods write the same relative path, the severity is decided by file type:

Conflicts are detected by overlapping deployed paths, not by cracking open pak archives — two paks that touch different in-game assets but never collide on a file path are not flagged. Texture/mesh collisions are reported but treated as cosmetic (last-writer-wins is usually fine); plugin and pak collisions are flagged as dangerous because they can change game logic or load behaviour. See Conflict detection for how severities drive the UI and resolution.

Save-breaking classification

Separately from path collisions, modde classifies each mod’s content to decide whether enabling or disabling it should invalidate save compatibility. For Oblivion Remastered:

• Save-breaking extensions: esp, esm, pak, ucas, utoc, dll, lua
• Save-breaking directories: plugins, logicmods
• Cosmetic extensions: dds, png, jpg, tga, nif

This classification feeds the save-fingerprint logic below: only save-breaking mods contribute to the fingerprint, so swapping a texture pack will not trigger a false “incompatible save” warning, while toggling a plugin or a logic pak will.

Save tracking

Saves live under the Proton prefix, in the remastered Documents tree:

<steam>/steamapps/compatdata/2623190/pfx/drive_c/users/steamuser/Documents/My Games/Oblivion Remastered/Saves

The save tracker is non-recursive over that directory and matches two extensions, .ess and .sav, excluding *.bak. Every match is filed under the manual category and labelled by its relative filename. What the tracker records per save is its path, category, label, and last-modified time — it does not hash individual save files.

Save fingerprinting happens at the vault layer, and it fingerprints your mod set, not the save bytes: modde computes a SHA-256 over the sorted list of enabled save-breaking mods (per the classification above) and embeds it as a git commit trailer in each snapshot:

Mod-Fingerprint: a1b2c3d4e5f6
Save-Breaking-Mods: pak/some-overhaul, plugin/somequest

On restore, modde compares the snapshot’s fingerprint to your current profile and warns if save-breaking mods were added or removed since that save was taken. Oblivion Remastered opts into per-profile save layering, so each profile gets its own branch in the git-backed vault and profile switches capture/restore automatically. See Save management for the full vault, fingerprint, and restore workflow.

Plugins and load order

modde recognises the ESP/ESM plugin system (it is reported as a plugin-capable game) and scans Data/ for plugins, so plugin mods are discovered, classified as save-breaking, and conflict-checked by path. There is no dedicated load-order editor for the Bethesda side of this title in modde today — load order for plugins is managed by the game/community tooling you already use, and pak ordering is governed by UE’s ~mods mounting. Treat plugin ordering as out-of-band for now.

Installer specifics

When you add a downloaded archive, modde’s analyzer picks the layout:

modde also recognises a bare archive layout for this game: an archive whose root contains any of the directories data, mods, content, paks, or ~mods (matched case-insensitively), or root files with the extensions esp, esm, pak, ucas, or utoc. That recognition lets it accept the loosely packed archives common on Nexus for this title without a wrapper directory.

FOMOD installers are handled by modde’s generic FOMOD pipeline when an archive ships a fomod/ModuleConfig.xml; that path is engine-agnostic and not specific to this game. There is no REDmod or SMAPI path here — those belong to Cyberpunk 2077 and Stardew Valley respectively. See FOMOD installers and the installer pipeline for the staging and uninstall model.

Gaming tools that matter here

Mod loaders, ReShade/ENB-style injectors, and upscalers for this title ship as proxy DLLs dropped next to the shipping executable in:

<install>/OblivionRemastered/Binaries/Win64

modde detects which proxy DLLs are present from this set and surfaces them as Wine DLL overrides (see below):

dwmapi   xinput1_3   d3d11   dxgi   version   winmm

That covers the usual suspects — generic ASI/loader proxies (version, winmm), UE-loader proxies (dwmapi, xinput1_3), and the graphics-swapper slots (d3d11, dxgi) used by ReShade and DLSS/FSR swappers such as OptiScaler.

This game does not ship a curated OptiScaler profile in modde (unlike Stellar Blade), so OptiScaler is installed and tuned manually as a dxgi/d3d11 proxy. The named-executable and proxy-DLL machinery is fully supported regardless — see Tools and executables for adding a launcher executable with arguments, working dir, env, and DLL overrides, and capturing its output.

Linux and Proton notes

These notes cover the game’s runtime on Linux and macOS, where Oblivion Remastered runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix or WINEDLLOVERRIDES, the save directory is its native Windows location, and proxy DLLs load directly. modde itself runs natively on all three platforms.

• Run the game once first. The save directory and the proxy-DLL overrides are resolved relative to the Proton prefix at compatdata/2623190/pfx. If you have not launched the game, that prefix does not exist and prefix-rooted lookups will report “not found”.
• DLL overrides are automatic from what is present. modde builds WINEDLLOVERRIDES from the proxy DLLs it finds in Binaries/Win64 (or in a mod’s staging dir), so Wine loads the native (mod) DLL instead of its built-in stub. You do not hand-write the override string.
• ~mods ordering is a UE convention, not a modde trick. If a pak mod is not taking effect, confirm it landed in Content/Paks/~mods and not loose in Content/Paks.
• Texture/mesh collisions are last-writer-wins. They are reported as cosmetic; if a visual mod loses to another, adjust which one deploys, since modde does not merge pak contents.

Worked example

CLI

# Detect installs and confirm the game is found
modde game list

# Install a Nexus pak mod by URL (domain resolves to oblivion-remastered)
modde mod install "https://www.nexusmods.com/oblivionremastered/mods/1234"

# Scan the live install for already-present mods (paks + Data plugins)
modde mod scan --game oblivion-remastered

# Inspect conflicts for the active profile
modde conflicts --game oblivion-remastered

# Adopt existing saves into a profile, then capture
modde save adopt --game oblivion-remastered --profile main
modde save capture --game oblivion-remastered --profile main -m "fresh start"

# Add OptiScaler (or any injector) as a dxgi proxy executable launcher
modde tool add-executable \
  --game oblivion-remastered \
  --name "Oblivion Remastered (modded)" \
  --working-dir "OblivionRemastered/Binaries/Win64"
modde exec --game oblivion-remastered "Oblivion Remastered (modded)"

home-manager profile snippet

A minimal modde profile for this title via the home-manager module:

{
  programs.modde = {
    enable = true;

    profiles.oblivion-remastered = {
      game = "oblivion-remastered";
      mods = [
        # Nexus URLs or local archive paths; paks land in
        # OblivionRemastered/Content/Paks/~mods, plugins in Data/.
        "https://www.nexusmods.com/oblivionremastered/mods/1234"
      ];
    };
  };
}

modde installs the same way for every game — through your platform’s native package manager, a direct download, Cargo, or, if you use Nix, the flake and its home-manager module. The home-manager module additionally lets you declare this profile as code. See Installation for the full set of install channels.

See also

• Supported games
• Oblivion (the Gamebryo original) and the sibling UE titles in the per-game list
• Conflict detection
• Save management
• Deployment and the installer pipeline
• FOMOD installers
• Tools and executables
• Scanning
• Parity reference

Cyberpunk 2077

Cyberpunk 2077 is one of the few non-Bethesda titles that modde supports end to end. Its overall status is Done in docs/capability-matrix.toml and on the supported games page: the scanner, conflict classifier, and save tracker are all wired up, and deployment runs a real REDmod deploy pass after staging.

The game id is cyberpunk2077. Use it verbatim with every CLI command and in home-manager profiles.

Engine and status

The numeric Nexus id is present, so Cyberpunk 2077 appears in the UI’s Browse Nexus picker (which needs the numeric id), and the Nexus side panel can fetch mod metadata via REST v1 and GraphQL v2. The mod information dialog is still Partial: only the Nexus-metadata side panel exists — there is no MO2-style file-tree / INI / conflict dialog yet.

Install detection

modde locates the install through its launcher ids. For Steam it uses App ID 1091500 and the steamapps/common/Cyberpunk 2077 directory; for Heroic it matches the GOG app id 1423049311 or the Epic app id Ginger. The same ids drive Proton-prefix discovery for save tracking.

Because Cyberpunk runs through Proton/Wine on Linux, the game writes its saves inside a Wine prefix rather than a native Linux path. modde checks two prefixes, in order:

1. Heroic (GOG / sideload): ~/Games/Heroic/Prefixes/default/Cyberpunk 2077/pfx/drive_c/users/steamuser/Saved Games/CD Projekt Red/Cyberpunk 2077
2. Steam Proton: the Steam compat prefix under steamapps/compatdata/1091500/pfx/drive_c/users/steamuser/Saved Games/CD Projekt Red/Cyberpunk 2077

The first prefix that exists on disk wins. If neither is present (for example, the game has never been launched under that launcher, so the prefix has not been created), save tracking reports no save directory.

Mod directory and deploy strategy

The canonical mod directory is <install>/mods/ — the REDmod loader’s directory. Deployment is a two-step process:

1. Per-mod symlink. For every entry in the profile’s staging directory, modde symlinks the mod directory into <install>/mods/<name>/. If a target name already exists (a real directory, a file, or a stale symlink), it is removed first so the new symlink is clean. This keeps the game directory pointing at modde-managed staging rather than copying bytes around.
2. Post-deploy REDmod deploy hook. After symlinking, modde runs a REDmod deploy pass (see below). This is what turns the symlinked REDmod packages into the game’s loadable mod archives.

Symlink deployment means an uninstall or redeploy is cheap and non-destructive to your staged sources.

The REDmod deploy hook

modde looks for the redmod binary in two places:

• <install>/tools/redmod/bin/redmod (or redmod.exe on Windows) — the copy CD Projekt Red ships alongside the game, and
• anywhere on PATH.

If a redmod binary is found and <install>/mods/ contains at least one subdirectory, modde invokes:

redmod deploy -mod <mods/dir-1> -mod <mods/dir-2> ...

with the game directory as the working directory, passing one -mod flag per mod subdirectory. If the binary is not found, modde logs a warning and skips the step — it does not fail the deploy. That means loose-file content (redscript, TweakXL, CET, .archive files) is still deployed by the symlink pass; only the REDmod-packaged content needs the deploy hook to be registered. A non-zero exit from redmod deploy does surface as a deploy error, with the tool’s stderr attached.

Gotcha: REDmod is an optional component in the GOG/Steam installers. If you intend to use REDmod packages, install the REDmod DLC/tool so the tools/redmod/bin/redmod binary exists, or put a redmod binary on PATH.

Bare-layout recognition

When you install an archive that is not a REDmod package, modde recognizes a “bare” Cyberpunk layout if the extraction root contains any of these top-level directories: r6, archive, archives, bin, engine, mods, red4ext. A bare extract is treated as a single mod and symlinked into <install>/mods/<name>/, preserving the loose-file tree the mod author shipped.

What scanning finds

modde scan --game cyberpunk2077 walks five known mod roots under the install directory and reports a confidence score per discovered mod:

For REDmod packages, the scanner reads the info.json manifest and pulls the mod’s name and version from it (falling back to the directory name when the manifest is missing or unparseable). The manifest fields modde parses are name, version, custom_sounds, and scripts.

Each discovered mod’s id footprint is stable and lowercased, so modde can detect stale duplicates across redeploys — for example a CET mod maps to the directory footprint bin/x64/plugins/cyber_engine_tweaks/mods/<name>/ and a loose archive maps to the file footprint archive/pc/mod/<stem>.archive.

Conflict classification

modde classifies conflicts at the loose-file level. Cyberpunk’s .archive container format is proprietary and not yet reverse-engineered in this codebase, so the classifier does not index inside .archive files — two mods that both ship archive/pc/mod/foo.archive collide on the file itself, but modde cannot peek at the resources packed within.

Conflicts are graded by extension into three severities:

A Dangerous collision means two mods are fighting over executable game logic (scripts, tweaks, or a native DLL) and the result is likely a crash or broken behavior. Config collisions usually need a manual merge. Cosmetic collisions are last-writer-wins texture/material overrides and are generally safe.

See the conflicts guide for how modde surfaces and resolves these.

Save tracking

Save tracking is Done. Once the save directory is resolved (see Install detection), modde treats each top-level save folder as a save and categorizes it by directory-name prefix:

Anything that does not match a known prefix is bucketed as manual (the default category). The scan is non-recursive (each save is one directory), and the user.gls settings file is explicitly excluded so it is never mistaken for a save.

What is fingerprinted. For each save, modde tries to extract a human-readable label. When a save uses CDPR’s NamedSaves, the directory contains a metadata.9.json; modde reads it and uses the customName (or name) field as the label. If that file is missing or has no usable name, it falls back to the save’s directory name. The capture summary is reported by category, so a snapshot tells you how many manual / auto / quick / point-of-no-return saves were captured.

Cyberpunk 2077 also declares supports_save_profiles = true, so its saves participate in save profiles.

Plugin and load-order handling

Cyberpunk 2077 has no ESP/ESM plugin list or loadorder.txt-style ordering the way Bethesda titles do. There is therefore no plugin enable/disable or load-order panel for this title. Ordering is whatever the underlying frameworks impose:

• REDmod order is established by the redmod deploy pass over the mods in <install>/mods/.
• redscript, TweakXL, and CET each resolve their own loading; modde’s job is to deploy the files into the correct roots, not to sequence them.

If two logic mods genuinely conflict, modde flags it as a Dangerous collision (see above) rather than trying to reorder them.

Installer specifics

modde inspects an extracted archive and picks an install method:

• REDmod packages are detected by a top-level info.json plus an archives/ (or archive/) subdirectory. modde records the install as a REDmod install whose manifest is info.json, and the post-deploy hook later registers it with redmod deploy.
• Bare Cyberpunk extracts (loose redscript / TweakXL / CET / .archive trees) are recognized by the top-level directory names listed under Bare-layout recognition and symlinked wholesale into mods/.
• FOMOD installers are handled by modde’s general FOMOD engine when a mod ships an XML installer; see the FOMOD guide. This is the same engine used across all supported titles.

There is no SMAPI or .pak/.ucas/.utoc handling for Cyberpunk — those belong to Stardew Valley and the Unreal titles respectively.

Gaming tools that matter

modde’s tool integrations (modde tool ...) apply to Cyberpunk just as they do to other titles — MangoHud, vkBasalt, GameMode, ReShade, OptiScaler, and per-game Proton settings. See the Tools & Overlays guide for the full workflow.

Cyberpunk does not ship a built-in OptiScaler profile in modde’s registry (its optiscaler_profiles list is empty, unlike Stellar Blade). You can still enable and apply OptiScaler manually with modde tool enable optiscaler / modde tool apply optiscaler, but you choose the proxy DLL and release yourself — modde does not auto-select a known-good proxy for this title. dxgi.dll is the proxy most OptiScaler/upscaling setups use on Cyberpunk.

Wine DLL overrides

Many Cyberpunk frameworks ship as proxy DLLs that hijack a Windows system DLL name in the executable directory bin/x64. Under Wine/Proton these need a native,builtin override so Wine loads the mod’s DLL instead of its own built-in stub. modde scans bin/x64 and emits overrides for any of these it finds:

modde can compute these overrides both from the live game directory and from the staging directory before deploy (it searches nested mods/.../bin/x64 layouts). The detected overrides are surfaced through the Proton tool integration so they end up in your launch environment automatically — no manual WINEDLLOVERRIDES editing required for the proxies modde knows about. If you use a proxy DLL not in the list above, set it explicitly, e.g.:

modde tool configure proton --game cyberpunk2077 \
  dll_override_mode=forced forced_dll_overrides=dxgi,version

Linux / Proton notes and known gotchas

These notes cover the game’s runtime on Linux and macOS, where Cyberpunk runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and saves and proxy DLLs live at their native Windows locations. modde itself runs natively on all three platforms.

• Launch the game once first. Saves live inside the Proton/Heroic prefix. Until the game has been run under your launcher, the prefix (and the save directory) does not exist, and save tracking has nothing to find.
• Install REDmod if you use REDmod packages. Without the tools/redmod/bin/redmod binary (or a redmod on PATH), the post-deploy hook is skipped with a warning. Loose-file mods still deploy.
• Proxy DLLs need overrides. CET (version.dll), ReShade (d3d11/dxgi), OptiScaler (dxgi), and friends will silently do nothing under Wine without the native,builtin override. modde detects the common ones in bin/x64; verify with modde tool status --game cyberpunk2077 and the troubleshooting guide if a framework does not load.
• .archive internals are opaque. modde detects archive-vs-archive collisions by filename but cannot diff their contents, so two large .archive mods that touch overlapping resources may both report clean while still visually conflicting in-game.
• Game runtime differs by platform. The Proton/Heroic prefix paths above are how Cyberpunk runs on Linux and macOS, where it runs through Proton/Wine. On Windows the game runs natively, so there is no Wine prefix — saves and proxy DLLs live at their native Windows locations. modde itself runs natively on all three platforms; see installation.

Worked example

Home-Manager profile

programs.modde = {
  enable = true;

  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles = {
    cyberpunk-mods = {
      game = "cyberpunk2077";
      installMode = "auto";
      gameDir = "/home/me/.local/share/Steam/steamapps/common/Cyberpunk 2077";

      nexusCollection = {
        slug = "my-cyberpunk-collection";
        version = "2.1.0";
      };

      tools = {
        gamemode.enable = true;
        proton = {
          enable = true;
          settings = {
            # CET ships as version.dll; force the override so Wine loads it.
            dllOverrideMode = "forced";
            forcedDllOverrides = "version,dxgi";
          };
        };
      };
    };
  };
};

See the home-manager module reference for every profile and tool option.

CLI

# Discover the install and inspect what is already there
modde scan --game cyberpunk2077

# Install a mod from a Nexus URL (REDmod, CET, redscript, TweakXL, or .archive)
modde install --game cyberpunk2077 https://www.nexusmods.com/cyberpunk2077/mods/107

# Deploy the active profile: symlinks into mods/, then runs `redmod deploy`
modde deploy --game cyberpunk2077

# Check for conflicts before playing
modde conflicts --game cyberpunk2077

# Capture and list saves from the resolved Proton/Heroic prefix
modde saves list --game cyberpunk2077

# Force a Wine DLL override if a proxy framework is not loading
modde tool configure proton --game cyberpunk2077 \
  dll_override_mode=forced forced_dll_overrides=version,dxgi

See also

• Supported games
• The Witcher 3 — the other REDengine title
• Deployment
• Scanning
• Conflicts
• Saves
• FOMOD installers
• Tools & Overlays
• Nexus integration
• Home-Manager module
• Parity reference

The Witcher 3: Wild Hunt

The Witcher 3: Wild Hunt is the second REDengine title modde supports (alongside Cyberpunk 2077). It ships as a built-in plugin under the witcher3 game id.

Engine & overall status

The status is Partial, matching the supported games table. Deployment, the filesystem scanner, .ws script-conflict classification, save tracking, and Wine/Proton DLL-override detection are wired up and reachable, but The Witcher 3 does not yet have the deeper engine integrations some Bethesda titles enjoy (there is no LOOT-style load-order sorter and no plugin validation — REDengine has no .esp/.esm plugin model). Treat it as solid for loose-folder mods and script mods, with the usual REDengine caveat that heavily-scripted modlists still benefit from manual review.

Install detection

modde locates the game through its launcher registration:

On a typical Linux Steam install the game directory resolves to something like ~/.local/share/Steam/steamapps/common/The Witcher 3. Run modde detect to see what modde found, and confirm the resolved path before deploying:

modde detect

Because no Heroic GOG/Epic app ids are registered for this title yet, GOG and Epic copies are not auto-detected. You can still point a profile at any install directory manually (see the worked example below) — detection only affects auto-discovery, not the ability to deploy into a known path.

Proton prefix

The Witcher 3 runs through Proton on Linux. modde does not install Proton or the game; the proton tool stores per-game launch settings (runner version, prefix path override, extra environment, DLL-override mode). The DLL proxies modde detects for script-extender-style mods (below) are surfaced as Wine DLL overrides so they take effect inside the Proton prefix. See Tools & Overlays for the proton tool options.

Mod directory & deploy strategy

The mod directory is mods/ directly under the game install:

<install>/mods/

REDengine loads mods from a small set of well-known top-level roots. modde recognises the multi-root REDkit/REDmod-style layout — mods/, dlc/, bin/, and content/ — and chooses its deploy path accordingly:

• Multi-root overlay — If the staged content already contains any of mods/, dlc/, bin/, or content/ at its top level, modde symlinks those roots straight into the install (a symlink farm, leaving the original game files untouched). This is what most archive mods that bundle their own mods/modFoo/ directory will hit.
• Single mod-root deploy — Otherwise modde treats the staged tree as the contents of one mod and deploys it into the resolved mod root under mods/.

Either way deployment is non-destructive and reversible — see Deployment & VFS for the build → materialize → deploy pipeline and modde rollback.

Archive analysis

When modde unpacks a downloaded archive it picks an install method:

• If the extracted tree contains any of mods, dlc, bin, or content, it is installed as a multi-root overlay preserving those roots.
• Otherwise, if there is a single top-level directory whose name begins with mod (case-insensitive, e.g. modFoo), it is installed as a directory mod under mods/.

The same mod*-prefixed-directory heuristic is also used to recognise a “bare” mod layout (a folder that is a single mod, with no wrapper directory).

What scanning finds

modde scan --game witcher3 walks the install and discovers already-present mods in two directories:

Each immediate sub-directory of mods/ becomes a discovered mod (mod/<name>), and each sub-directory of dlc/ becomes a discovered DLC-style mod (dlc/<name>). The on-disk footprint modde records for a discovered mod is the directory itself, lowercased — mods/<name>/ or dlc/<name>/ — so it can be matched and removed cleanly later. Import the results into a profile with:

modde scan --game witcher3 --import-to my-witcher3

See Mod Scanning for --dry-run, threshold tuning, and manifest matching.

Conflict classification

The Witcher 3 collision classifier treats .bundle and .cache as archive extensions and otherwise uses modde’s default per-extension severities. The most important entries for this title:

Run the standard conflict report:

modde collisions --profile my-witcher3

.ws script conflicts

The defining gotcha for Witcher 3 modding is script merging: many mods ship gameplay scripts under content/scripts/, and REDengine compiles only one copy of each script file. Two mods that both ship r4Player.ws will silently clobber each other unless their changes are merged.

modde detects this specifically:

• has_script_conflict(mod_dir) returns true if a mod directory contains any .ws file anywhere in its tree (case-insensitive).
• script_conflict_paths(mods_root) walks every installed mod under mods/, records the relative .ws paths each one provides (lowercased, forward-slashed), and returns exactly the script paths provided by more than one mod — i.e. the scripts that actually collide.

Because .ws is classified Dangerous and content/scripts is flagged as a save-breaking directory, script-shipping mods also contribute to the save fingerprint (below). When two mods collide on the same .ws file you generally need a manual or tool-assisted script merge — modde tells you which files collide, but it does not merge REDengine scripts for you. See Conflicts & Load Order for the general workflow and per-file hiding.

Save tracking

Saves live in a git-backed vault per the Save Management guide, with one branch per profile. For The Witcher 3 modde tracks *.sav files at the top level of the save directory and ignores the *.png save-thumbnail images that sit alongside them.

What is fingerprinted

modde computes a SHA-256 mod fingerprint from the sorted list of enabled mods classified as save-breaking, and stores it as a commit trailer on each save snapshot. For The Witcher 3 the save-breaking surface is:

• Save-breaking extensions: ws, xml, bundle, cache, csv, dll
• Save-breaking directory: content/scripts

Cosmetic-only mods (textures such as dds, png, jpg, xbm) do not move the fingerprint, so swapping a texture pack will not trigger a save-compatibility warning. Adding or removing a script/archive mod will. On restore, modde compares fingerprints and warns when the snapshot’s save-breaking set differs from your current profile.

Plugin / load-order handling

REDengine has no Bethesda-style plugin system, so there is no .esp/.esm load order, no LOOT sorting, and no plugin validation for this title. Mod precedence is the ordinary modde load-order priority (later mods win file conflicts), resolved during the VFS build phase. The one ordering-sensitive area is .ws script conflicts, which modde surfaces (see above) but does not auto-resolve. There is no built-in mods.settings/modList priority writer.

Installer specifics

The Witcher 3 modding ecosystem does not use FOMOD, REDmod CLI packaging, UE .pak chunks, or SMAPI. In practice mods are distributed as archives that either:

1. contain the REDengine root layout (mods/, dlc/, bin/, content/), or
2. contain a single mod*-prefixed directory.

modde handles both via the archive-analysis heuristics described above — there is no separate scripted-installer step for this title. (For games that do use guided installers, see FOMOD Installers.)

bundle and cache are treated as packed archive formats for conflict reporting; modde does not repack them.

Gaming tools that matter

modde does not ship any built-in OptiScaler presets for The Witcher 3 — the title’s OptiScaler profile list is empty — so upscaling is best handled through the generic optiscaler tool or your own pin if you want one. The tools that matter most here:

• proton — runner version, prefix override, extra_env, and DLL-override mode. This is where you control how the game launches under Proton.
• mangohud / vkbasalt / gamemode — overlay, post-processing, and the Feral GameMode daemon, all wired through modde’s launcher integration.
• Script-extender-style DLLs — see the Wine DLL proxies below.

See Tools & Overlays for enabling and configuring each.

Wine DLL proxies

Several Witcher 3 mods inject through a proxy DLL placed next to the game executable (in bin/x64). modde knows the proxy names this title uses and emits the corresponding Wine DLL overrides so they load inside the Proton prefix:

dxgi, d3d11, version, winmm

When a staged mod (or the live executable directory) contains one of these DLLs, modde adds it to the game’s Wine DLL overrides automatically, so the proxy is picked up under Proton without hand-editing the prefix.

Linux / Proton notes & gotchas

These notes cover the game’s runtime on Linux and macOS, where The Witcher 3 runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, proxy DLLs load directly, and saves live at their native Windows location. modde itself runs natively on all three platforms.

• Documents path. The save directory is the Wine/Proton-mapped ~/Documents/The Witcher 3/gamesaves. If your distro or home setup relocates Documents, confirm modde detect/save scanning is looking where the Proton prefix actually writes saves.
• Script merging is on you. modde flags colliding .ws files but does not merge REDengine scripts. For modlists that touch the same scripts, plan to do a manual or tool-assisted merge — and re-check modde collisions afterward.
• Proxy DLLs need the override. A mod that relies on a dxgi/d3d11/ version/winmm proxy will silently do nothing under Proton if the override is missing. modde sets these automatically when it sees the DLL; if you install such a mod outside modde, you may need to set the override yourself via the proton tool.
• No Heroic auto-detect. GOG/Epic copies are not auto-discovered; point the profile’s gameDir at the install directory explicitly.

Worked example

Home-Manager profile

programs.modde = {
  enable = true;

  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles.my-witcher3 = {
    game = "witcher3";
    installMode = "auto";
    gameDir = "/home/me/.local/share/Steam/steamapps/common/The Witcher 3";

    tools = {
      gamemode.enable = true;
      vkbasalt = {
        enable = true;
        settings = {
          enableOnLaunch = true;
          casSharpness = 0.4;
        };
      };
      proton = {
        enable = true;
        settings = {
          version_mode = "launcher_default";
        };
      };
    };
  };
};

Declare the profile before the game is installed by omitting gameDir or setting installMode = "await-game"; activation prints the next step instead of failing. After Steam finishes installing, set gameDir and rebuild. See the Home-Manager Module reference for every option.

CLI workflow

# 1. Confirm modde found the install
modde detect

# 2. Import any mods already sitting in mods/ and dlc/
modde scan --game witcher3 --import-to my-witcher3

# 3. Check for colliding files (especially .ws scripts)
modde collisions --profile my-witcher3

# 4. Adopt your existing saves into the vault
modde save adopt --game witcher3 --profile my-witcher3

# 5. Deploy and launch (captures saves on exit)
modde play my-witcher3 --game witcher3

See also

• Supported Games
• Cyberpunk 2077 — the other REDengine title
• Deployment & VFS
• Mod Scanning
• Conflicts & Load Order
• Save Management
• Tools & Overlays
• Playing a Game
• Home-Manager Module
• Parity reference

Stellar Blade

Stellar Blade (game_id stellar-blade, Steam App ID 3489700) is one of modde’s two data-driven Unreal Engine titles, sharing the Ue4Game plugin with Subnautica 2. Its overall status is Partial: scanning, conflict classification, save tracking, deployment, OptiScaler wiring, and Wine DLL-override detection all ship and are user-reachable, but Stellar Blade does not get a bespoke installer wizard or a curated load-order model beyond UE4’s ~mods mount order, and the title is held back from the UI’s “Browse Nexus” picker (see the Nexus Mods guide). Treat it as a solid pak-mod manager for the game, not a full guided experience.

For the authoritative status row see Supported games; the capability vocabulary (Done / Partial / Not shipped) is defined there and in docs/capability-matrix.toml.

Engine and project layout

Unreal titles share a near-identical on-disk shape: a project folder under the install root (here SB/) that holds SB/Content/Paks/ for pak archives and SB/Binaries/Win64/ for the shipping executable and any proxy DLLs. Because the whole plugin is parameterised by that project short name, every path below is just <install>/SB/....

How modde detects the install

modde resolves Stellar Blade through its registered launcher IDs. Only the Steam path is wired:

• Steam — App ID 3489700, library subfolder Stellar Blade. modde walks your Steam library folders (including extra libraries from libraryfolders.vdf) to find the install root.
• Heroic (GOG/Epic) — not configured for this title; there is no Heroic GOG or Epic app ID in the registry, so Heroic auto-detection does not apply.

You can always bypass detection by passing --game-dir <path> to commands that take it (for example modde scan and modde install wabbajack), or by setting gameDir in a home-manager profile.

Proton prefix

On Linux and macOS Stellar Blade runs through Proton/Wine, so both save tracking and the UE Saved/Config deploy target read from the compatibility prefix that Steam creates at (on Windows these are native paths, no prefix involved):

<steam_root>/steamapps/compatdata/3489700/pfx/

modde derives this from the Steam common directory’s parent, then compatdata/3489700/pfx. If the prefix does not exist yet, the save directory and the ue4-saved-config deploy target both resolve to None — the expected fix is to launch the game once so Proton materialises the prefix, then retry.

Mod directory and deploy strategy

The deploy target is the standard UE pak drop folder:

<install>/SB/Content/Paks/~mods

The leading tilde in ~mods is load-bearing: UE’s pak mounter orders mount points lexically, and ~mods sorts after the shipping paks so your mods override base content. modde creates and deploys into this directory; it does not invent a custom VFS for UE titles — deployment is a real on-disk layout under Content/Paks/~mods.

A mod archive is recognised as a single-file-set install when its extracted root contains at least one .pak, .ucas, or .utoc file (InstallMethod::SingleFileSet). That is the common case for Nexus pak mods, which extract a loose Name.pak (optionally with Name.ucas / Name.utoc siblings) you drop straight into ~mods.

In addition to ~mods, the plugin exposes one named deploy target for user config:

This second target is how Engine.ini / GameUserSettings.ini style tweaks land in the right place inside the Proton prefix. It resolves to None until the prefix exists.

What scanning finds

modde scan --game stellar-blade runs the UE4 scanner, which walks two subdirectories of SB/Content/Paks/:

Within each, files are grouped by file stem across the .pak / .ucas / .utoc extensions. A Name.pak plus its Name.ucas and Name.utoc siblings collapse into a single discovered mod with mod_id = "pak/Name" and a fixed scan confidence of 0.9. The scanner reads pak archives by directory and by their grouped stems only — it does not crack open pak contents, parse asset trees, or read mod-author metadata from inside the archives.

For change-tracking, a discovered mod’s footprint is its .pak file, recorded as sb/content/paks/~mods/<stem>.pak (lower-cased). The .ucas/.utoc sidecars collapse into that same row, which keeps the mod list one-entry-per-mod even though several files back it.

# Discover already-installed Stellar Blade paks and import them into a profile
modde scan --game stellar-blade --import-to default

Conflict classification

Conflicts use the shared UE collision policy. Stellar Blade declares pak, ucas, and utoc as archive extensions, so two mods shipping the same-named pak family are a real overwrite conflict. Severities are assigned per file extension:

The same extension lists also drive mod safety classification (whether a mod is considered save-affecting versus purely cosmetic): pak, ucas, utoc, dll, and lua are treated as save-breaking/logic-altering, while png, jpg, dds, tga, and ini are treated as cosmetic. So a texture-only retexture conflicting with another texture is flagged Cosmetic, while two paks clobbering one another are Dangerous.

See Conflicts & load order for how modde presents and resolves these.

Save tracking

Save tracking is enabled for Stellar Blade (with_save_profiles(true)), and it is wired into modde’s per-profile save layer.

Location. Saves are read from the Proton prefix:

<steam_root>/steamapps/compatdata/3489700/pfx/drive_c/users/steamuser/AppData/Local/SB/Saved/SaveGames

modde returns this directory only if it already exists on disk.

What is fingerprinted. The save tracker matches files by extension .sav, recursively under the save directory, with no prefix rules and no exclusions. Every matching file is captured under the default category manual, its label taken from the file stem (falling back to the relative path). Captured saves are summarised by category. Because matching is purely extension-and-recursion based, modde tracks the .sav files themselves — it does not parse Stellar Blade’s save binary format or extract in-game playtime, character, or chapter metadata.

See Save management for how captures attach to profiles.

Plugin and load-order handling

Stellar Blade has no plugin file (.esp/.esm) load order — it is not a Bethesda title. Ordering is purely the UE pak mount convention: paks in ~mods mount after base game paks, and within ~mods UE orders by name. If two mods need a deterministic order relative to each other, the lever is the pak file name (the conventional zzz_-style prefixes that sort late). modde does not synthesize or rewrite a load-order file for this game; there is no curated load order beyond what the file names express.

A separate LogicMods folder is also scanned (tagged logic-mods) for setups that keep Blueprint/logic paks distinct from content paks, but modde treats both folders uniformly as grouped pak mods.

Installer specifics

• Pak / ucas / utoc — the native format. Archives whose root contains a pak-family file install as a single file set straight into ~mods. This is the path most Nexus Stellar Blade mods take.
• FOMOD — modde’s FOMOD installer is engine-agnostic, so a mod that ships a ModuleConfig.xml can be driven through modde fomod inspect / modde fomod apply (or a declarative config). FOMOD is not Stellar Blade-specific and is uncommon for this title, but it is available when an author uses it.
• REDmod / SMAPI / BSA — not applicable. Those are Cyberpunk, Stardew, and Bethesda installer paths respectively; Stellar Blade uses none of them.

There is no bespoke Stellar Blade installer wizard — this is part of why the title is Partial. Most installs are “extract pak, deploy to ~mods”.

Gaming tools that matter

OptiScaler — the community-dxgi profile

Stellar Blade ships exactly one curated OptiScaler profile, community-dxgi (“Community tested dxgi.dll”). It is the recommended way to add modern upscaling/frame generation. Its pinned settings, straight from the registry:

The profile uses OptiPatcher to unlock the game’s DLSS and DLSS-FG inputs without spoofing a DLSS-capable GPU — so you get the DLSS/DLSS-FG code paths re-routed through OptiScaler/FSR rather than faking vendor detection. The latest_fp8 FSR4 variant with emulate_fp8 = true is what lets RDNA3-class cards run the FP8 model via emulation.

Known OptiScaler gotchas for this title (from the bundled profile notes):

• The game may crash on first boot with the proxy in place but work on the next launch — if the first launch dies, just relaunch before assuming a bad install.
• If DLSSG/frame-gen HUD elements look wrong (interpolation artifacts on the HUD), set the in-game sharpness slider to 0 as a workaround.

Enable and apply it through the tools system:

# Enable OptiScaler for Stellar Blade and select the curated profile
modde tool enable optiscaler --game stellar-blade
modde tool configure optiscaler --game stellar-blade optiscaler_profile=community-dxgi
modde tool apply optiscaler --game stellar-blade

modde tool apply writes the dxgi.dll proxy and companion files into the game’s Binaries/Win64. See Tools & overlays and the OptiScaler source selector (official releases versus GOverlay builds) documented there.

Proton, overlays, and Wine DLL overrides

The other tool IDs apply normally for this Proton game: proton (version mode, extra env, DLL-override mode), mangohud, vkbasalt, gamemode, and reshade. Because Stellar Blade runs through Wine/Proton, any native proxy DLLs you stage must be loaded native first. modde scans SB/Binaries/Win64 (and mod staging) for the common UE proxy DLL names and surfaces them as WINEDLLOVERRIDES:

dwmapi, xinput1_3, d3d11, dxgi, version, winmm, dinput8

So a UE4SS install (dwmapi), a ReShade/DLSS swapper (dxgi/d3d11), or a generic ASI loader (version/winmm) is detected and overridden automatically — the OptiScaler profile’s own dxgi.dll is exactly one of these.

Linux / Proton notes and gotchas

These notes cover the game’s runtime on Linux and macOS, where Stellar Blade runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix or WINEDLLOVERRIDES, and the save directory and config live at their native Windows locations. modde itself runs natively on all three platforms.

• Launch the game once before first deploy. The save directory and the ue4-saved-config target both live inside the Proton prefix and resolve to None until Proton has created compatdata/3489700/pfx.
• OptiScaler first-boot crash. Expected with this profile; relaunch. (See the OptiScaler section above.)
• HUD interpolation under DLSSG. Set the in-game sharpness slider to 0.
• DLL override ordering. If a proxy DLL mod is staged but not taking effect, confirm the matching WINEDLLOVERRIDES entry is present — modde derives it from the proxy name in Binaries/Win64, so the file must be the recognised name.
• Pak mount order is name-driven. There is no load-order editor; rename paks (e.g. a late-sorting prefix) when one mod must win over another.

Worked example

CLI

# 1. Discover the install (Steam App ID 3489700 / "Stellar Blade") and scan it,
#    importing what is already in ~mods into the default profile.
modde scan --game stellar-blade --import-to default

# 2. Install a pak mod from a Nexus URL into a profile.
modde install mod https://www.nexusmods.com/stellarblade/mods/<id> --profile default

# 3. Deploy the active profile into SB/Content/Paks/~mods.
modde deploy --game stellar-blade --profile default

# 4. Add upscaling/frame-gen via the curated OptiScaler profile.
modde tool enable optiscaler --game stellar-blade
modde tool configure optiscaler --game stellar-blade optiscaler_profile=community-dxgi
modde tool apply optiscaler --game stellar-blade

# 5. (Optional) Register a named external tool/executable for this game so it runs
#    with overwrite capture and the right Wine DLL overrides.
modde tool add-executable --game stellar-blade --name my-tool /path/to/tool.exe
modde exec my-tool --game stellar-blade

Home-Manager profile

The home-manager module exposes Stellar Blade as a declarative profile. The tools.optiscaler.profile option is type-checked against the registered profile list, so community-dxgi is the valid value for this game.

{
  programs.modde = {
    enable = true;
    profiles.stellar-blade-main = {
      game = "stellar-blade";

      # Auto-detected from Steam; set explicitly if your library is non-standard.
      # gameDir = "/path/to/SteamLibrary/steamapps/common/Stellar Blade";

      installMode = "auto";

      tools.optiscaler = {
        enable = true;
        profile = "community-dxgi";
      };
    };
  };
}

On activation modde enables, configures, and applies the OptiScaler profile for the stellar-blade game, writing the dxgi.dll proxy into SB/Binaries/Win64. Remember to launch the game once first so the Proton prefix exists.

See also

• Supported games
• Subnautica 2 — the other data-driven UE title
• Oblivion Remastered — another UE pak-based game
• Mod scanning
• Conflicts & load order
• Deployment & VFS
• Save management
• Tools & overlays
• FOMOD installer
• MO2 parity & capability audit

Subnautica 2

Subnautica 2 (game_id = subnautica2) is one of modde’s Unreal Engine titles. It shares the data-driven UE4 plugin with Stellar Blade and Oblivion Remastered: a single Ue4Game definition parameterised per title, with the trait implementation reused across every Unreal game. Its overall status is Partial — the engine path (detection, deployment, conflict classification, save tracking, Wine/Proton DLL overrides) is wired and shipped, but there is no bespoke Subnautica-specific scanner, save format parser, or mod-loader integration beyond the generic pak layout. Treat it as “the UE4 pipeline pointed at Subnautica 2”, not a hand-tuned per-game experience.

Status baseline. The authoritative per-game status lives in Supported games and in docs/capability-matrix.toml. This page expands on the engine mechanics; it does not change the status.

Engine and overall status

The Unreal4 engine family is modde’s umbrella for Unreal pak/IoStore games regardless of whether the title is technically UE4 or UE5 — the on-disk layout (<Project>/Content/Paks/, <Project>/Binaries/Win64/, ~mods mount ordering, pak/ucas/utoc chunk triples) is the same, so the same code path drives both.

How modde detects the install

Subnautica 2 is registered with Steam launcher IDs only:

Detection walks your Steam libraries (parsed from libraryfolders.vdf, so extra drives are covered) and looks for steamapps/common/Subnautica2. There is no Heroic (GOG/Epic) mapping for this title today, so a non-Steam copy must be pointed at explicitly with --game-dir (CLI) or gameDir (home-manager). Run modde detect to see what modde resolves before you commit a profile to it.

The install root is the directory that contains the UE project folder Subnautica2/. modde derives everything else from there:

• Paks root: <install>/Subnautica2/Content/Paks
• Executable / proxy-DLL dir: <install>/Subnautica2/Binaries/Win64

Proton prefix

Saves and per-user config live inside the Proton prefix Steam creates for App ID 1962700, not in the install directory. modde resolves the prefix as <steam_library>/steamapps/compatdata/1962700/pfx. If you have never launched the game, that prefix does not exist yet and modde’s save/config resolution returns nothing — the fix is to launch Subnautica 2 once through Steam (Proton) so the prefix is created, then re-run modde.

Mod directory and deploy strategy

modde deploys mods into the tilde-prefixed ~mods folder under the paks root:

<install>/Subnautica2/Content/Paks/~mods/

The leading tilde is deliberate: Unreal’s pak mounter loads ~mods after the shipping paks, so modded content overrides base game content rather than the other way around. modde creates this directory if it does not exist.

Deployment uses modde’s standard staging-and-link model (see Deployment): mods live in per-mod staging directories, and the active profile is materialised into ~mods by linking the enabled mods’ files. A pak/ucas/utoc triple that shares a file stem is treated as one logical mod — the IoStore container (.ucas/.utoc) and its .pak header travel together.

When modde analyses a downloaded archive, it recognises the Subnautica 2 layout when the archive root contains at least one .pak, .ucas, or .utoc file and classifies it as a single file set (InstallMethod::SingleFileSet) — i.e. “drop these chunk files into ~mods”. Archives that do not present pak files at their root fall through to the generic installer flow.

What scanning finds

modde scan --game subnautica2 walks two directories under the paks root and groups .pak/.ucas/.utoc files by file stem into discovered mods:

LogicMods is included because UE4SS-style Blueprint/logic mods conventionally ship there; modde reports anything it finds in that folder even though it deploys its own managed mods into ~mods. Each discovered mod gets an ID of the form pak/<stem> and is recorded at a confidence of 0.9. Sibling .ucas/.utoc files collapse into the same row as their .pak (the footprint is represented by subnautica2/content/paks/~mods/<stem>.pak), so a multi-chunk mod shows up once rather than three times.

Scanning is filesystem discovery only — it tells you which pak sets are physically present. It does not parse pak contents, read UE asset trees, or resolve load-order semantics. See Scanning for how discovered rows reconcile with manifest-driven installs.

Conflict classification

Conflicts are classified by the shared UE4 collision policy. Two mods “collide” when they ship a file at the same relative path; the severity of that overlap is decided by file extension:

The archive extensions that participate in pak-aware collision handling are pak, ucas, and utoc. Because Subnautica 2 mods are predominantly pak sets, most real conflicts you will see are Dangerous same-path pak overlaps: two mods both shipping, say, ~mods/zMyOverhaul.pak cannot coexist without one shadowing the other. modde surfaces these so you can choose a winner via load order / filename prefixing rather than discovering it in-game. See Conflicts for the full classification model and how to resolve overlaps.

Save tracking

Save tracking is shipped (Done) and Subnautica 2 opts into modde’s per-profile save layer (supports_save_profiles = true).

Location

modde resolves the save directory inside the Proton prefix:

<steam_library>/steamapps/compatdata/1962700/pfx/drive_c/users/steamuser/
  AppData/Local/Subnautica2/Saved/SaveGames

If the prefix does not exist yet (game never launched), save resolution returns nothing — launch once through Proton first.

What is captured and fingerprinted

The UE4 save tracker is a pattern tracker that recursively matches *.sav files under the save directory, labels each by its file stem, and files them under the manual category. “Recursive” matters for Subnautica 2 because UE titles often nest per-slot save folders; modde descends into them.

Captured saves are committed into a per-game git vault (one repository per game_id, one branch per profile), which gives history, branching, and rollback for free. Each capture commit also records a mod fingerprint:

• The fingerprint is a SHA-256 over the sorted, de-duplicated list of enabled, save-breaking mod IDs in the active profile.
• A mod is “save-breaking” if it ships any of the save-affecting extensions pak, ucas, utoc, dll, or lua — i.e. exactly the content types that can change game logic. Purely cosmetic mods (png, jpg, dds, tga, ini) do not move the fingerprint, so two profiles that differ only in textures stay compatible.
• The fingerprint and a human-readable mod list are stored as Mod-Fingerprint: / Save-Breaking-Mods: git trailers on the capture commit.

When you later restore a snapshot, modde compares the stored fingerprint against the current profile and warns if the save-breaking mod set has changed (which mods were added/removed), so you do not silently load a save into an incompatible mod configuration. See Saves for the capture/restore/rollback workflow.

Note: the file content itself is not hashed — the fingerprint identifies the mod configuration that produced the save, not the bytes of the save file.

Per-user config deploy target

Beyond saves, the UE4 plugin exposes one deploy target for user-editable config:

This lets modde place INI tweaks into the prefix’s Saved/Config/Windows directory. As with saves, the target resolves to nothing until the Proton prefix exists.

Plugin and load-order handling

Unreal pak games have no plugins.txt-style master/plugin list the way Bethesda titles do. Load order is filename/mount order within ~mods: paks mount in a deterministic order, and ~mods mounts after the base paks. There is no Subnautica 2 load-order editor in modde; if two pak sets conflict, you resolve it by choosing which mod wins (renaming with a sorting prefix, or disabling one). modde’s job here is to make the conflict visible and the deployment reproducible — not to arbitrate UE pak precedence automatically.

Installer specifics

Subnautica 2 mods are pak-based, so there is no FOMOD/REDmod/SMAPI flow specific to this title:

• Pak sets are the native format. modde’s archive analysis detects a root-level .pak/.ucas/.utoc and deploys the set into ~mods.
• FOMOD installers are still supported generically (the FOMOD engine is engine-agnostic), but most Subnautica 2 mods are plain pak archives that need no scripted installer. See FOMOD installers if you do hit one.
• No REDmod / no SMAPI / no Bethesda plugin tooling applies here — those belong to Cyberpunk and Stardew/Creation-Engine titles respectively.

Gaming tools that matter

modde manages external gaming tools per game (see Tools). For Subnautica 2:

• Proton is the runtime. modde’s proton tool selects the Proton build and can apply DLL overrides; everything below the executable runs inside the App ID 1962700 prefix.

• Wine DLL overrides for proxy DLLs. UE mod loaders (UE4SS) and overlays ship as proxy DLLs that must be loaded as native instead of Wine’s built-in stub. modde scans Subnautica2/Binaries/Win64/ (or a mod’s staging dir) for known proxies and emits the right WINEDLLOVERRIDES. The recognised proxy DLLs are:

  Proxy DLL	Typical use
  dwmapi	UE4SS default proxy
  xinput1_3	UE4SS alternate / some trainers
  d3d11	ReShade / ENB-style
  dxgi	ReShade / DLSS swappers
  version	Generic ASI loader
  winmm	Generic ASI loader
  dinput8	Generic hook

• No OptiScaler profile ships for Subnautica 2. Unlike Stellar Blade — which has a community-tested community-dxgi OptiScaler preset — subnautica2 registers an empty OptiScaler profile list. You can still enable the generic optiscaler tool if you know what you are doing, but modde provides no curated, game-specific preset for this title, so there is no profile = "..." value to select. Overlays like MangoHud, VkBasalt, and GameMode are engine-agnostic and work as for any Proton title.

Linux / Proton notes and gotchas

These notes cover the game’s runtime on Linux and macOS, where Subnautica 2 runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and saves and per-user config live at their native Windows locations. modde itself runs natively on all three platforms.

• Launch once before modding state resolves. Saves, the ue4-saved-config target, and prefix-based config all require the Proton prefix to exist. A fresh install has no compatdata/1962700 until you run the game once.
• ~mods lives in the install, saves live in the prefix. These are two different trees on disk. Deploy/scan operate on <install>/Subnautica2/Content/Paks; save capture operates on the prefix. Do not look for saves under the install directory.
• IoStore triples must stay together. Deploying or removing a .pak without its .ucas/.utoc (or vice versa) produces a broken mount. modde groups them by stem, so let modde manage the set rather than hand-copying single files.
• Browse Nexus picker. Subnautica 2 has a Nexus domain (subnautica2) but no numeric Nexus game ID recorded, so URL-based installs and update tracking work while the UI’s “Browse Nexus” game picker may hide the title until the numeric ID is confirmed. You can still install from a nexusmods.com/subnautica2/mods/<id> URL or nxm:// link.
• Verify your runtime against the game’s current state. Subnautica 2 is an evolving title; pak mods can break across game patches. Capture a save before a big mod change so the fingerprint lets you roll back cleanly.

Worked example

Home-Manager profile

A minimal declarative Subnautica 2 profile. Point gameDir at the Steam install (the directory containing Subnautica2/), and let activation manage the rest.

programs.modde = {
  enable = true;

  profiles.subnautica2-modded = {
    game = "subnautica2";
    installMode = "auto";
    gameDir =
      "/home/me/.local/share/Steam/steamapps/common/Subnautica2";

    tools = {
      # Engine-agnostic overlays work fine on this Proton title.
      mangohud.enable = true;
      gamemode.enable = true;
      # No OptiScaler preset ships for subnautica2, so there is no
      # `profile = "..."` to set here.
    };
  };
};

If the game is not installed yet, omit gameDir or set installMode = "await-game"; activation prints the next step instead of failing. See the Home-Manager module reference for every option.

CLI

# See what modde resolves for the install and Proton prefix.
modde detect

# Create a profile and scan the pak directories for existing mods.
modde profile create modded --game subnautica2
modde scan --game subnautica2 --import-to modded

# Install a pak mod from a Nexus URL into the profile.
modde install mod "https://www.nexusmods.com/subnautica2/mods/123" \
  --profile modded

# Deploy the active profile's mods into Content/Paks/~mods.
modde deploy --game subnautica2 --profile modded

# Switch profile, deploy, capture the outgoing profile's saves, and launch.
modde play modded --game subnautica2

If your copy is not a default Steam install, add --game-dir <path> to the commands that take it (scan, deploy), pointing at the directory that contains Subnautica2/.

Named executables (modding tools)

modde can manage named launch targets — UE4SS-driven tools, trainers, or any helper executable — with overwrite capture, custom working dir, environment, and Wine DLL overrides. The exec commands are a thin alias for the executable subset of tool; the two share storage.

# Register a tool as a named launch target for subnautica2.
modde exec add my-tool "/path/to/Tool.exe" --game subnautica2 \
  --wine-dll-overrides "dinput8=n,b" \
  --env "SOME_VAR=1" \
  -- --tool-arg value

# Equivalent via the tool surface:
modde tool add-executable my-tool "/path/to/Tool.exe" --game subnautica2

# Run it, capturing any files it writes into the overwrite mod.
modde exec run my-tool --game subnautica2 --profile modded

Captured output defaults to the __overwrite__ mod; pass --output-mod <name> to route writes into a named mod instead. See Tools and Playing for the full launch model.

See also

• Supported games — the canonical status table and per-game guide index
• Stellar Blade — sibling Unreal title (has an OptiScaler preset)
• Oblivion Remastered — another Unreal4 pak title
• Deployment — staging-and-link deployment model
• Scanning — filesystem discovery and manifest reconciliation
• Conflicts — collision classification and resolution
• Saves — capture, fingerprints, restore, and rollback
• Tools — Proton, overlays, and named executables
• Playing — switch-deploy-capture-launch flow
• Home-Manager module — declarative profile options
• Parity reference — how modde’s coverage maps to MO2/Vortex

Baldur’s Gate 3

Baldur’s Gate 3 (baldurs-gate3) runs on Larian Studios’ Divinity engine and is modelled in modde as the Larian engine family. Mods are distributed as .pak archives, the enabled module list lives in modsettings.lsx, and the writable game data lives inside the Steam Proton prefix rather than the install directory. modde ships built-in support for all of these.

Overall status

Baldur’s Gate 3 is Partial. Deployment, scanning, conflict classification, save tracking, and modsettings.lsx load-order generation are wired and reachable, but several BG3-specific workflows are deliberately conservative and there is no FOMOD-grade installer UI for the game’s .pak-with-info.json ecosystem. Treat it as solid for .pak-based content and load order, and verify by hand for anything that touches the Script Extender or non-standard archive layouts.

The canonical status baseline for every game lives in docs/capability-matrix.toml; this page describes how the BG3 plugin behaves, not a promise beyond that matrix.

Install detection

modde locates the install through its launcher IDs:

Only Steam is registered for BG3 today. The GOG and Epic Heroic app ids are not populated, so if you run a non-Steam copy you must point modde at the install yourself with --game-dir (CLI) or gameDir (home-manager).

Mod directory and path resolution

The writable BG3 data root is not in the install directory. Under Proton it lives inside the prefix that Steam creates for app 1086940. modde resolves the data root by walking up from the install path to the steamapps/common directory and then descending into the matching compatdata prefix:

steamapps/compatdata/1086940/pfx/drive_c/users/steamuser/AppData/Local/Larian Studios/Baldur's Gate 3/

From that data root, modde derives:

If modde cannot find a steamapps/common ancestor (for example a manually specified non-Steam path), it falls back to an install-relative Larian Studios/Baldur's Gate 3 data root and the same sub-paths under it. Directory matching for the bare-layout heuristics is case-insensitive, so Mods / mods and PlayerProfiles / playerprofiles are both recognised.

The deploy strategy is modde’s standard symlink farm: .pak files are staged and symlinked into the resolved Mods/ directory, leaving the original install untouched and fully reversible. See Deployment & VFS for the build → materialize → deploy pipeline.

What scanning finds

The BG3 scanner discovers root .pak files inside Mods/. It prefers the Proton-prefix data root, but if that prefix has no Mods/ directory yet it falls back to scanning the install directory’s Mods/ instead, so a fresh prefix does not silently produce an empty scan.

• It looks only at the Mods directory (single-file .pak rule).
• Each discovered mod is reported with a pak/ mod-id prefix and a confidence of 0.95.
• A mod’s on-disk footprint is the lower-cased mods/<stem>.pak file, which is what conflict detection compares between mods.

Scanning is shallow by design: it enumerates the .pak archives that BG3 itself loads, not the contents inside each archive. There is no MO2-style file-tree or per-archive INI inspection for BG3, which is part of why the title is Partial. See Scanning for the general model.

Conflict classification

BG3 uses modde’s pak-aware collision classifier. Two mods are flagged when they ship the same relative file path, and the severity is decided by file extension:

pak, ucas, and utoc are treated as archive extensions for collision purposes, so two mods packing identically named loose files are compared rather than two opaque archives being declared incompatible outright. Resolution follows the load order: the later mod wins each conflicting path. See Conflicts for how to inspect and resolve them.

Save-breaking content

Separately from collision severity, the BG3 plugin classifies individual mods for save safety. A mod is treated as save-breaking when it contains .pak, .dll, .json, or .lsx files, or when it ships a Script Extender directory (Script Extender / ScriptExtender). Purely cosmetic mods (.png, .jpg, .dds, .tga) are treated as safe. This classification is what feeds the save fingerprint described below, so adding or removing a Script Extender mod is correctly surfaced as a save-compatibility change.

Save tracking

Save tracking is Done. BG3 stores saves as .lsv files under:

PlayerProfiles/Public/Savegames/

modde’s BG3 save tracker:

• Matches **/*.lsv recursively under the save directory (each campaign save is its own folder containing an .lsv, so recursion is required).
• Categorises every detected save as manual and labels it by its path relative to the save directory.
• Sorts captures newest-first by modification time.

Saves are stored in a per-game git-backed vault at ~/.local/share/modde/saves/baldurs-gate3/, with one branch per profile. Each snapshot embeds a SHA-256 fingerprint of the save-breaking mods (the .pak / .dll / .json / .lsx / Script-Extender content described above), so restoring a save into a profile whose dangerous mods differ raises a compatibility warning instead of silently loading an incompatible save. See Save Management for vault mechanics, adoption, and restore.

Load order and modsettings.lsx

BG3 reads its enabled module list from an LSX (Larian XML) file at PlayerProfiles/Public/modsettings.lsx. modde manages this file for you:

• After every deploy, the plugin’s post-deploy step reads the deployed Mods/ directory, collects the file stem of each .pak, sorts the list, and writes a fresh modsettings.lsx enabling those modules in order. If no .pak files are present, the existing file is left untouched.
• The generated XML uses the standard ModuleSettings region with one ModuleShortDesc node per module, keyed on the Folder attribute.
• modde can also read an existing modsettings.lsx, parsing the ordered list of enabled module folders back out, which is how it reconciles against what the game currently has enabled.

The important limitation: the generated order is the sorted .pak stem order, not a dependency-aware load order. For modlists whose .pak stems do not encode the intended order (BG3 mods frequently need a specific sequence and carry UUID/dependency metadata in their meta.lsx), you should review and adjust modsettings.lsx — or use BG3 Mod Manager in the prefix — after deploying. modde does not parse per-mod meta.lsx UUIDs or dependency declarations.

Installer specifics

BG3 mod packaging is varied, and modde handles the two layouts that map cleanly to a symlink farm:

A bare extracted layout is recognised as a BG3 mod when it contains mods or playerprofiles directories, or root .pak / .lsx files (case-insensitive).

There is no FOMOD installer path for BG3 here — FOMOD is an XML installer format used by Bethesda-style mods, and BG3’s .pak-with-info.json packaging is not FOMOD. There is likewise no REDmod (Cyberpunk) or SMAPI (Stardew) handling, because those belong to other engines. Archives that bundle a loose-file overlay alongside .paks, or that expect a manual info.json merge, are not auto-resolved; install those by hand and re-run a deploy.

Gaming tools and Proton

The BG3 registration ships no OptiScaler profile, so there is no curated DLSS/FSR/XeSS preset for this title the way there is for, say, Stellar Blade. You can still enable the generic tools per profile — mangohud, vkbasalt, gamemode, reshade, and especially proton — from the Tools & Overlays guide and the home-manager module.

The proton tool is the relevant one for BG3: it manages the per-game Proton runtime selection, Wine prefix, environment, and DLL overrides. Because BG3’s mod directory and load-order file live inside the Proton prefix, the prefix that proton targets must be the same one your Mods/ and modsettings.lsx resolve into.

Linux and Proton notes (gotchas)

These notes cover the game’s runtime on Linux and macOS, where Baldur’s Gate 3 runs through Proton/Wine and its writable data lives inside the compatibility prefix. On Windows the game runs natively — there is no Wine prefix, and Mods/, modsettings.lsx, and saves live at their native Windows locations. modde itself runs natively on all three platforms.

• The mod directory is inside the prefix, not the install. This is the most common surprise: editing files under steamapps/common/Baldurs Gate 3 does not affect the modded game. modde resolves the prefix path for you, but if you ever inspect things manually, look under compatdata/1086940/pfx/.../AppData/Local/Larian Studios/Baldur's Gate 3/.
• The prefix must exist before scanning the prefix data root. If you have never launched BG3 through Proton, the compatdata/1086940 prefix may not have a Mods/ directory yet; the scanner falls back to the install directory, but load-order generation and saves only become meaningful once the prefix is populated. Launch the game once through Steam first.
• Script Extender is save-breaking. BG3’s Script Extender lands as a Script Extender directory and is classified as dangerous/save-breaking. Toggling it changes the save fingerprint, so expect a compatibility warning if you restore older saves after enabling or disabling it. Script Extender itself is injected via the prefix and is not something modde installs for you.
• modsettings.lsx ordering is heuristic. As noted above, modde writes a sorted-stem order; if your list needs a specific sequence, adjust the file (or use a BG3-specific load-order tool inside the prefix) after deploying.
• Steam-only detection. Non-Steam copies need an explicit game directory.

Worked example

Home-manager profile

programs.modde = {
  enable = true;

  # Optional: needed for Nexus downloads / update tracking.
  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles.bg3-mods = {
    game = "baldurs-gate3";
    installMode = "auto";

    # Point at the Steam install. modde derives the in-prefix Mods/ and
    # modsettings.lsx from this path automatically.
    gameDir = "/home/me/.local/share/Steam/steamapps/common/Baldurs Gate 3";

    tools = {
      gamemode.enable = true;
      # Keep modde's prefix targeting aligned with the game's actual prefix.
      proton.enable = true;
    };
  };
};

If BG3 is not installed yet, omit gameDir or set installMode = "await-game"; activation prints the next step and continues without failing. Set gameDir and rebuild once Steam has the game.

CLI

# Scan the resolved in-prefix Mods/ directory for installed .pak mods.
modde scan --game baldurs-gate3

# Install a mod archive (root .pak files or a top-level Mods/ folder).
modde install ./SomeBg3Mod.zip --game baldurs-gate3

# Deploy the profile. This symlinks .pak files into the prefix Mods/ and
# regenerates PlayerProfiles/Public/modsettings.lsx from what was deployed.
modde deploy --game baldurs-gate3

# Inspect conflicts between deployed mods.
modde conflicts --game baldurs-gate3

# Adopt existing .lsv saves into a profile vault.
modde save adopt --game baldurs-gate3 --profile bg3-mods

After deploying, review PlayerProfiles/Public/modsettings.lsx if your modlist relies on a specific load order, since modde generates a sorted-stem order rather than a dependency-resolved one.

See also

• Supported Games — the status matrix and the full per-game guide index
• Deployment & VFS — the symlink-farm pipeline
• Scanning — how installed mods are discovered
• Conflicts — inspecting and resolving collisions
• Save Management — git-backed vaults, fingerprinting, restore
• Tools & Overlays — Proton, OptiScaler, and overlays
• Home-Manager Module — declarative profile options
• Feature parity — how modde compares to MO2/Vortex

Stardew Valley

Stardew Valley is modde’s SMAPI-engine title. It is the only game in the registry on the Smapi engine family, and unlike the Bethesda, REDengine, and Unreal games it is a managed-content loader: mods are self-describing directories under Mods/ rather than archives, plugins, or .pak overlays. This page documents exactly what modde knows about the title, sourced from crates/modde-games/src/stardew/.

Engine and overall status

The Partial rating matches the supported-games matrix: the core path — detection, the SMAPI mod layout, scanning, conflict classification, and save tracking — is implemented, but it has not been promoted to Done the way the Bethesda Creation Engine titles and Cyberpunk 2077 have. Treat installer coverage and end-to-end UX as work in progress, not as a turnkey SMAPI manager. The canonical, test-coupled status baseline lives in docs/capability-matrix.toml.

How modde detects the install

modde resolves the Stardew Valley install through its launcher IDs. The registration carries a Steam App ID of 413150 and a Steam library directory name of Stardew Valley, so a Steam install is located by walking your Steam libraries for steamapps/common/Stardew Valley. No Heroic GOG or Epic IDs are registered for this title, so Heroic auto-detection is not wired up — point modde at the install directory directly if you run it from GOG or another launcher.

Stardew Valley runs natively on Linux. The default Steam Linux build is a native Linux binary, so there is no Proton prefix involved for the base game, and modde does not need to resolve a Wine prefix to find the install or the saves. (You can still choose to run the Windows build under Proton — see Linux/Proton notes — but that is not the default path.)

You can always override detection and pass the resolved game directory explicitly when a command needs it; the game directory is the folder that contains the Stardew Valley executable and the Mods/ directory.

Mod directory and deploy strategy

modde’s plugin resolves the mod directory to Mods/ directly under the install root (<install>/Mods). This is SMAPI’s standard mod folder: SMAPI loads every subdirectory of Mods/ that contains a manifest.json.

Deployment uses modde’s standard symlink-farm VFS — the same pipeline as every other game. Mods are staged in ~/.local/share/modde/staging/<profile>/, the winning file for each relative path is resolved by load-order priority, and the staging tree is symlinked into Mods/. Your real Stardew install is never mutated in place, so deactivating modde or switching profiles is fully reversible. The plugin’s executable_dir is the install root itself, which is where overlay-style tools (proxy DLLs) land when applicable.

See Deployment & VFS for the full pipeline and rollback behaviour.

What scanning finds

modde scan --game stardew-valley discovers SMAPI mods already on disk. The scanner walks the Mods/ directory and applies a directory-mod rule:

• Each immediate subdirectory of Mods/ is a candidate mod.
• The presence of a manifest.json marker file inside a candidate raises detection confidence to 0.98 — that file is SMAPI’s own mod manifest and is the authoritative signal that a directory is a SMAPI mod.
• Directories without the marker are still reported at a lower base confidence (0.75), so loose content packs are not silently dropped.
• Discovered mods are namespaced under a smapi/ mod-id prefix, and a mod’s on-disk footprint is recorded as mods/<name>/ (lower-cased), reflecting that SMAPI directory names are matched case-insensitively.

Import discovered mods straight into a profile:

modde scan --game stardew-valley --import-to my-stardew

This is the path for adopting an existing hand-managed Mods/ folder into modde. See Mod Scanning for dry-run mode and threshold filtering.

Conflict classification specifics

Stardew Valley uses modde’s generic policy collision classifier (it has no bespoke per-game collision classifier the way Bethesda and Cyberpunk do). The generic classifier registers no archive extensions — SMAPI mods are loose directory content, not packed archives — and applies the default severity table to overlapping files:

In practice that means two content packs that both ship assets/foo.png collide as a cosmetic conflict (last in load order wins), while two mods that both ship a SMAPI .dll or a Content Patcher-style content.json are flagged at the more serious end. Resolve conflicts by load-order priority exactly as for any other game:

modde collisions --profile my-stardew
modde collisions --profile my-stardew --all   # include cosmetic conflicts

Separately from collision severity, the plugin also classifies each mod for save safety, which feeds save fingerprinting (next section):

A mod containing any save-breaking extension is classified SaveBreaking; a mod that contains only cosmetic files is SaveSafe; an empty or unrecognised mod is Unknown and treated conservatively as save-breaking for fingerprinting. Note that xnb appears in both lists — it is content that can be either gameplay data (save-breaking) or a recolour (cosmetic), and modde errs toward the save-breaking reading because any save-breaking extension in the mod wins. For per-file content categorisation, extensions map as: dll → binary, json/tmx/tbin → config, xnb → archive, png/jpg → texture.

See Conflicts & Load Order for severity meanings and the hide workflow.

Save tracking

Save tracking is Done for Stardew Valley. The save directory is the native Linux XDG config location:

~/.config/StardewValley/Saves

modde resolves this through its platform-aware config-directory helper, so on Linux it honours $XDG_CONFIG_HOME (defaulting to ~/.config). Each farm is its own subdirectory named <FarmName>_<id> (e.g. Pelican_123456789).

The save tracker enumerates directories under the saves folder whose name contains an underscore — that is the <name>_<id> farm convention — and reports each as a save in the farm category, labelled by its directory name. The startup_preferences entry is excluded. Results are sorted newest-first by modification time.

supports_save_profiles is true, so Stardew participates in modde’s full git-backed save vault: each profile is a branch, switching profiles captures and restores the appropriate farm snapshots, and every snapshot embeds a SHA-256 fingerprint computed from the sorted list of enabled save-breaking mods (the classification above). On restore, if the snapshot’s fingerprint does not match your current profile, modde warns you which save-breaking mods were added or removed — so you do not load a farm into a mod set it was never saved against.

# Adopt an existing farm into a profile
modde save adopt --game stardew-valley --profile my-stardew

# Capture, browse history, and restore
modde save capture  --game stardew-valley --profile my-stardew -m "year 2 spring"
modde save history  --game stardew-valley --profile my-stardew
modde save restore  abc12345 --game stardew-valley --profile my-stardew

See Save Management for the vault model, auto-capture, and the fingerprint trailer format.

Plugin and load-order handling

Stardew Valley has no Bethesda-style plugin (.esp/.esm) load order. SMAPI loads mods by their manifest.json and resolves inter-mod dependencies itself at runtime. modde therefore does not manage an external plugin/load-order file for this title; ordering is handled entirely through modde’s standard mod load-order priority (later mods win file conflicts during deployment), which is what the collision classifier and the VFS builder consume. There is no separate plugin table to edit.

Installer specifics

There are no FOMOD, REDmod, BAIN, or .pak flows for Stardew Valley — those are Bethesda/Cyberpunk/Unreal concepts. The plugin recognises two SMAPI-native archive layouts when you install a downloaded mod:

1. SMAPI directory mod — if the extracted archive root contains a manifest.json, the archive is one SMAPI mod. It installs as a DirectoryMod (the whole directory is staged under a stable mod directory). This is the common case for a single SMAPI mod packaged at the archive root.
2. Mods/-rooted archive — if the extracted root instead contains a Mods/ directory, modde strips that content root (StripContentRoot { root: "Mods" }) so the inner mod folders stage directly into the game’s Mods/. This handles archives that bundle one or more mods already nested under a Mods/ folder.

For bare-layout recognition (used when an archive has no obvious nesting), the plugin accepts a root manifest.json, or a mods/ directory, or root files with a json/dll extension; directory matching is case-insensitive. Anything modde cannot classify falls through to the generic installer, which writes a dossier so the layout can be handled later — it is not silently discarded. See the FOMOD Installer guide for the interactive/declarative installer machinery that the Bethesda titles use; Stardew does not need it.

Gaming tools that matter

Stardew Valley registers no OptiScaler profiles — it is a 2D pixel-art game, so DLSS/FSR upscaling is not relevant, and there is no Unreal-style upscaler swap to manage. The tools that matter here are modde’s general overlay/launcher tools:

• MangoHud / GameMode — useful as always for an FPS overlay and CPU governor tuning, even on a lightweight title.
• Proton — only relevant if you deliberately run the Windows build under Proton (see below). The proton tool stores launch/compat settings; it does not install Proton or the game.

See Tools & Overlays for enabling and configuring these.

Linux and Proton notes

• Native Linux is the default and the happy path. The Steam Linux depot ships a native build, SMAPI has a first-class Linux installer, and the save directory is the native ~/.config/StardewValley/Saves. No Wine prefix is involved, and modde does not look for one.
• SMAPI itself must be installed and set as the launch command. modde manages your Mods/ content; it does not install or bootstrap SMAPI. After running SMAPI’s installer, set Stardew’s Steam launch options to run SMAPI (the standard StardewModdingAPI %command% pattern) so the loader actually starts.
• If you run the Windows build under Proton on Linux instead, the save directory moves into the Proton prefix’s emulated %APPDATA% (steamapps/compatdata/413150/pfx/drive_c/users/steamuser/AppData/Roaming/StardewValley/Saves) rather than ~/.config/StardewValley/Saves. On Linux modde’s save tracker targets the native Linux path, so prefer the native Linux build to keep save tracking accurate; running the Windows build under Proton on Linux is a known gotcha for the save vault. (On Windows itself, where the native build is the only option, the tracker targets the native Windows save path, and on macOS the native build’s config path.) modde itself runs natively on Linux, macOS, and Windows.
• Case sensitivity. SMAPI mod directory names are matched case-insensitively by modde’s scanner, which is the right behaviour for mods authored on Windows but deployed onto a case-sensitive Linux filesystem.

Worked example

Home-Manager profile

Declare a Stardew profile in your home-manager configuration. You can declare it before the game is installed and let modde wait for the Steam install:

{ inputs, ... }:
{
  imports = [ inputs.modde.homeManagerModules.modde ];

  programs.modde = {
    enable = true;

    profiles.my-stardew = {
      game = "stardew-valley";
      # Wait for Steam to install the game, then set gameDir and rebuild.
      installMode = "await-game";
    };
  };
}

Once Steam has installed the game, set gameDir to the resolved install path and rebuild; modde deploys the profile through its activation script. See the Home-Manager module reference for the full option set.

CLI

# 1. Adopt an already-managed Mods/ folder into a profile
modde scan --game stardew-valley --import-to my-stardew

# 2. Inspect conflicts (cosmetic png overlaps are expected and harmless)
modde collisions --profile my-stardew --all

# 3. Deploy the symlink farm into <install>/Mods
modde deploy --profile my-stardew --game stardew-valley

# 4. Adopt an existing farm and capture a baseline snapshot
modde save adopt   --game stardew-valley --profile my-stardew
modde save capture --game stardew-valley --profile my-stardew -m "baseline"

# 5. Play (SMAPI must already be set as the launch command); saves capture on exit
modde play --game stardew-valley

See also

• Supported Games
• Baldur’s Gate 3 — the other non-Bethesda/non-Creation-Engine title
• Deployment & VFS
• Mod Scanning
• Conflicts & Load Order
• Save Management
• Tools & Overlays
• Playing a Game
• Feature Parity

Mount & Blade II: Bannerlord

Mount & Blade II: Bannerlord (bannerlord) is TaleWorlds’ medieval sandbox built on its in-house engine. modde models it as its own engine family (EngineFamily::Bannerlord) because its mod layout — a flat Modules/ directory where each module carries a SubModule.xml manifest — does not match any of the Bethesda, Unreal, REDengine, or SMAPI families.

Overall status

Bannerlord ships as a Partial title in the supported-games matrix. What that means in practice:

• Scanner — Yes. modde discovers installed modules under Modules/ and parses each SubModule.xml for identity and dependencies.
• Conflict detection — Yes, via the generic policy classifier plus Bannerlord-specific save-breaking and cosmetic classification.
• Save tracking — Done. The git-backed save vault, fingerprinting, and capture/restore all work against the Bannerlord save directory.

The Partial label reflects what is not yet built rather than broken behavior: there is no Bannerlord-aware load-order manager (the game’s own Launcher / Mod Options screen still owns load order), and the mod information dialog only surfaces a Nexus-metadata side panel, not a file-tree / dependency-graph inspector. Deployment, scanning, conflict classification, save management, and launcher integration are all functional.

How modde detects the install

Bannerlord is registered with a Steam app id of 261550 and a default Steam library directory name of Mount & Blade II Bannerlord. When modde walks your Steam libraries, it matches by app id first and falls back to the directory name. No Heroic (GOG/Epic) ids are registered, because Bannerlord is a Steam title; if you run it from a non-Steam source you can still point modde at the install explicitly with --game-dir (see the worked example).

On Linux, Steam runs Bannerlord through Proton. The mod directory and save directory modde uses are host-side paths — modde reads and writes Modules/ directly in the real game install and the save directory under your real $HOME/Documents, so you do not generally need to reach inside the Proton prefix to manage mods. The game’s Windows-side view of those paths is provided by Proton’s drive mapping. The Windows executable lives under bin/Win64_Shipping_Client/ relative to the install root; modde records that as the game’s executable directory so tools and launch integrations can find it.

Mod directory and deploy strategy

The mod directory is Modules/ under the game install root. Each mod is a self-contained subdirectory (for example Modules/MyAwesomeMod/) that contains, at minimum, a SubModule.xml and usually a bin/, ModuleData/, GUI/, or AssetPackages/ tree.

modde deploys mods with its standard symlink-farm VFS: mods are staged in ~/.local/share/modde/staging/<profile>/ and then linked into Modules/, leaving the original game files untouched and the deployment fully reversible. Conflict resolution (later mods in the load order win) happens during the build phase. See Deployment & VFS for the full pipeline.

Archive analysis (what modde does when you install a mod)

When you install a Bannerlord mod archive, modde inspects the extracted contents and picks a layout strategy:

• Module-root archives — if the archive extracts to a directory that already contains a SubModule.xml at its top level, modde treats the whole archive as a single module. It uses the module’s own Id.value attribute (from SubModule.xml) as the mod id when one is present.
• Modules/-prefixed archives — if the archive instead contains a top-level Modules/ directory, modde strips that prefix and deploys its contents into the game’s Modules/ directory, so a mod packaged as Modules/CoolMod/... lands at Modules/CoolMod/....

The same two shapes are recognized as a “bare layout” (a loose, already-extracted folder you point modde at): a directory holding a SubModule.xml, or a directory whose root contains a modules/ folder and .xml files (the directory match is case-insensitive). This is what lets you adopt manually downloaded mods without a wrapping archive.

What scanning finds

modde scan --game bannerlord walks the Modules/ directory and reports one discovered mod per immediate subdirectory that contains a SubModule.xml. For each such module it:

1. Parses SubModule.xml for the module id (<Id value="...">) and human-readable name (<Name value="...">). If <Id> is missing it falls back to the directory name; if <Name> is missing it falls back to the id.
2. Records every file under the module directory, relative to the install root, as the module’s footprint.
3. Emits a discovered mod with id module/<id>, the parsed display name, and a high confidence score (0.95). Modules with no files are skipped.

A directory without a SubModule.xml is not reported — modde only counts a subfolder as a Bannerlord module when that manifest is present. See Mod Scanning for importing scan results into a profile and for Wabbajack-manifest matching.

Dependency checking

Beyond identity, SubModule.xml parsing collects every <DependedModule Id="..."> entry. modde can then cross-reference the declared dependencies of all discovered modules against the set of module ids that are actually present and report missing dependencies as (module_id, missing_dependency_id) pairs. This catches the classic Bannerlord failure mode where a mod silently refuses to load because a required module (for example Bannerlord.Harmony or Bannerlord.UIExtenderEx) is not installed. modde does not reorder modules to satisfy dependencies — load order remains the in-game Launcher’s job — it only surfaces what is missing.

Conflict classification

Bannerlord uses the generic policy collision classifier for file-level overwrite severity, layered on top of a Bannerlord content policy that maps file types to save-breaking, cosmetic, and content categories:

The save-breaking extension set is dll, xml, xslt, xsl, pak; the cosmetic set is png, jpg, dds, tga. In addition, anything under a module’s bin/ directory or a submodule.xml file is treated as save-breaking, because those carry the compiled assemblies and the module manifest that actually change how a campaign behaves. Texture overwrites are classified as cosmetic — visible, but they will not invalidate a save.

Run modde collisions --profile <name> to see conflicting module pairs with severity and file counts, or add --all to include cosmetic overlaps. The conflict model (load-order priority, shadowed mods, redundant files, per-file hiding) is the same one described in Conflicts & Load Order; the LOOT plugin-sorting parts of that guide are Bethesda-only and do not apply to Bannerlord.

Save tracking

Bannerlord saves are tracked from:

~/Documents/Mount and Blade II Bannerlord/Game Saves/Native/

The tracker matches *.sav files (non-recursively) in that directory and files them all under the campaign category. Each file’s relative name is used as its label, and the capture summary is reported by category.

These saves flow into modde’s standard git-backed save vault: a per-game repository under ~/.local/share/modde/saves/bannerlord/, with one branch per profile. Switching profiles captures the outgoing saves and restores the incoming profile’s. Every snapshot embeds a SHA-256 fingerprint of the profile’s enabled save-breaking mods (the dll/xml/xslt/xsl/pak + bin/ + submodule.xml set above), so that on restore modde can warn you when a snapshot was taken with a different set of save-breaking modules than your current profile:

Mod-Fingerprint: a1b2c3d4e5f6
Save-Breaking-Mods: module/Bannerlord.Harmony, module/CoolMod

Adopt pre-existing saves with modde save adopt --game bannerlord --profile <name>, then capture/restore/history as in Save Management. Because Bannerlord saves carry the active module list inside the .sav itself, the fingerprint warning is a strong signal: loading a campaign save against a mismatched module set is the most common cause of corrupted Bannerlord saves.

Plugin / load-order handling

Bannerlord has no separate plugin format (no .esp/.esl equivalent); a module either loads or it does not, and order is resolved by the game’s own Launcher → Mods screen and the LauncherData.xml it writes. modde does not ship a Bannerlord load-order manager and does not write LauncherData.xml. What modde provides instead is:

• Dependency visibility — missing-<DependedModule> reporting (above), so you know which modules must be present and roughly in what dependency relationship.
• Deployment ordering — modde’s load-order priority decides which mod wins a file-level conflict during deployment, which is independent from the runtime module activation order TaleWorlds’ Launcher controls.

After deploying with modde, enable and order your modules in the in-game Launcher (or a third-party launcher such as the Bannerlord Mod Launcher / BUTR tools) as you normally would.

Installer specifics

Bannerlord does not use FOMOD, REDmod, .pak mod managers, or SMAPI. Its packaging is simpler and modde handles it directly:

• No FOMOD wizard — most Bannerlord mods are plain module folders. modde’s two archive shapes (a top-level SubModule.xml, or a top-level Modules/ prefix to strip) cover the vast majority of Nexus downloads. The FOMOD installer described in FOMOD installer is used by Bethesda-style mods and generally does not apply here.
• .pak files are Bannerlord asset packages, classified as save-breaking archives — they are content, not an installer format, and are deployed like any other module file.
• Harmony / UIExtenderEx / ButterLib / MCM are themselves ordinary modules: install them like any other mod and let dependency checking confirm they are present.

Install a single mod from Nexus with modde install mod <url> --profile <name>; the Nexus domain for Bannerlord is mountandblade2bannerlord, which modde uses to resolve Nexus URLs to this game.

Gaming tools, Proton, and overlays

Bannerlord registers no OptiScaler profile, so the bundled DLSS/FSR upscaling workflow that ships for titles like Stellar Blade is not pre-configured here. The general tool integrations still apply: you can enable MangoHud, vkBasalt, GameMode, ReShade, and per-game Proton settings through modde tool ..., exactly as documented in Tools & Overlays.

The most relevant tool for a Linux Bannerlord install is the proton integration, which stores per-game launch settings (Proton version mode, prefix override, extra environment variables, and DLL overrides) without installing Steam or the game itself:

# Keep Steam's default Proton runner for Bannerlord
modde tool configure proton --game bannerlord version_mode=launcher_default

# Force a DLL override if a native-loader mod needs it
modde tool configure proton --game bannerlord dll_override_mode=forced forced_dll_overrides=dxgi

modde’s executable management is fully shipped and is useful for Bannerlord’s out-of-game tools: register a named executable (with arguments, working directory, environment, Wine DLL overrides, and an output-capture mod) via modde tool add-executable ... and run it with modde exec ..., capturing any files the tool writes into an overwrite mod. This is handy for running modding utilities against the deployed Modules/ tree.

Linux / Proton notes and known gotchas

These notes cover the game’s runtime on Linux and macOS, where Bannerlord runs through Proton/Wine. On Windows the game runs natively — there is no Wine prefix, and Modules/ and the save directory live at their native Windows locations. modde itself runs natively on all three platforms.

• Run the game once before modding. Let Steam/Proton create the prefix and let Bannerlord generate ~/Documents/Mount and Blade II Bannerlord/ (Proton maps this from the prefix’s drive_c/users/steamuser/Documents, but on a typical setup it surfaces at your real $HOME/Documents). modde’s save tracker reads the Game Saves/Native/ directory there.
• Modules live host-side. Because modde links into the real Modules/ directory under the install root, you usually do not touch the Proton prefix to add or remove mods — but the game still needs to be launched through the same Proton runner you configured.
• Enable modules in the Launcher after deploying. Deployment puts the files in place; it does not toggle modules on. A freshly deployed module that is not enabled in the in-game Launcher will appear “missing” even though its files are present.
• .NET module DLLs are save-breaking. Adding or removing a dll-bearing module changes the save fingerprint. Expect (and heed) modde’s mismatch warning when restoring an older campaign save.
• Case sensitivity. modde’s bare-layout recognition treats the Modules/modules directory case-insensitively, which matters on Linux’s case-sensitive filesystem when a mod ships an oddly-cased folder; the on-disk Modules/ directory itself is whatever the game created.

Worked example

Declarative (home-manager)

Define a Bannerlord profile and wait for the game to be installed before modde deploys into it:

programs.modde.profiles.my-bannerlord = {
  game = "bannerlord";
  # Point at the real Steam install once it exists; until then modde
  # prints an awaiting message instead of failing activation.
  installMode = "await-game";
  # gameDir = "/home/you/.steam/steam/steamapps/common/Mount & Blade II Bannerlord";

  tools.proton.settings = {
    version_mode = "launcher_default";
  };
};

After Steam has installed the game, set gameDir to the install path and switch installMode = "auto", then rebuild your home-manager configuration; modde deploys the profile during activation.

Imperative (CLI)

# 1. Create a Bannerlord profile
modde profile create my-bannerlord --game bannerlord

# 2. Install a mod from Nexus into it
modde install mod \
  https://www.nexusmods.com/mountandblade2bannerlord/mods/2018 \
  --profile my-bannerlord

# 3. Import any modules already sitting in Modules/
modde scan --game bannerlord --import-to my-bannerlord

# 4. Inspect conflicts (add --all for cosmetic overlaps)
modde collisions --profile my-bannerlord

# 5. Deploy the symlink farm into the game's Modules/ directory
modde deploy --profile my-bannerlord --game bannerlord \
  --game-dir "$HOME/.steam/steam/steamapps/common/Mount & Blade II Bannerlord"

# 6. Adopt existing campaign saves into the git-backed vault
modde save adopt --game bannerlord --profile my-bannerlord

Then launch through Steam (Proton), enable your modules in the in-game Launcher, and order them there.

See also

• Supported games
• Deployment & VFS
• Mod Scanning
• Conflicts & Load Order
• Save Management
• Tools & Overlays
• Feature parity reference

Generic & user-defined games

modde ships 15 built-in games with bespoke scanners, save trackers, and conflict logic. For everything else, there is the generic game path: a configurable plugin driven by a small TOML file (a GameSpec) that you write — or generate — and drop into modde’s data directory. This lets you point modde at an arbitrary title and get the deployment engine, conflict detection, launcher integration, and executable management without waiting for a hand-coded profile.

Generic game support is Partial. A user-defined game gives you the engine-agnostic parts of modde — virtual-filesystem deployment, conflict classification, launcher detection, and executable management — but it does not give you a bespoke filesystem scanner or a save tracker. There is no plugin author writing game-specific heuristics behind it; you are describing the game with a handful of paths and IDs. Treat it as “modde can deploy and launch mods for this game”, not “modde fully understands this game”. See the supported-games matrix for the canonical status vocabulary (the baseline lives in docs/capability-matrix.toml).

What a user-defined game can and cannot do

A generic game is registered with EngineFamily::Generic. modde treats it like any other game for the parts of the pipeline that do not need game-specific knowledge, and explicitly opts out of the parts that do.

The short version: deployment, conflict, and launcher work; there is no bespoke scanner and no save tracker. Those two gaps are the defining limits of the Partial status.

Where specs live on disk

User-defined game specs are plain TOML files in modde’s data directory:

<data dir>/modde/games/<id>.toml

<data dir> resolves per-platform:

• Linux: $XDG_DATA_HOME/modde/games/ or ~/.local/share/modde/games/
• Overridable by the active instance data directory.

Each game is one file named after its id (for example factorio.toml). The loader reads this directory at startup:

• only files ending in .toml are considered;
• files ending in .optiscaler.toml are skipped (those are OptiScaler profile sidecars, not game specs);
• specs are loaded in sorted filename order;
• each spec is validated, and any spec whose id collides with a built-in game or a previously-loaded user game is skipped with a warning;
• invalid or unparseable specs are skipped (with a warning) rather than aborting the load.

You can edit these files by hand, but the recommended path is the modde game CLI, which validates before writing.

The GameSpec TOML schema

A GameSpec is a flat TOML table. Only three fields are required.

# games/<id>.toml
id = "factorio"                 # required
display_name = "Factorio"       # required
executable_dir = "."            # required (relative to install root)

# All of the following are optional:
steam_app_id = "427520"         # Steam AppID, as a string
install_dir_name = "Factorio"   # steamapps/common/<name>
install_path_override = "/games/factorio"  # absolute path; bypasses detection
mod_dir = "mods"                # where mods deploy, relative to install root
nexus_domain = "factorio"       # Nexus game domain for browse/search
proxy_dlls = ["dxgi", "winmm"]  # candidate Wine DLL overrides

Validation rules

Both the CLI and the on-disk loader run the same validation before a spec is accepted:

• id must match ^[a-z0-9][a-z0-9-]*$ (lowercase ASCII letters/digits and hyphens, starting with a letter or digit).
• id must not collide with a built-in game ID.
• executable_dir and mod_dir (if present) must be relative and must not contain .., a root component, or a Windows drive prefix — they cannot escape the install root.
• display_name must not be empty after trimming whitespace.

A spec that fails validation is rejected by modde game add / modde game import and silently skipped (with a warning) by the loader.

Install detection order

When modde needs to find the install directory for a generic game, it tries, in order:

1. install_path_override, if set and the directory exists.
2. install_dir_name under any detected steamapps/common/ library.
3. modde’s generic launcher detection (Steam/Heroic) keyed on the game ID.

The first hit wins.

The modde game CLI surface

All user-defined-game management lives under modde game. The full subcommand set:

modde game add

modde game add <id> \
  --display-name <name> \
  --executable-dir <relative-path> \
  [--steam-app-id <id>] \
  [--install-dir-name <name>] \
  [--mod-dir <relative-path>] \
  [--nexus-domain <domain>] \
  [--proxy-dll <name>]... \
  [--force]

add writes (or overwrites, with --force) <data dir>/modde/games/<id>.toml. install_path_override is not settable from add — it is always written as unset; use install_dir_name/steam_app_id for detection, or edit the TOML by hand (or import a spec that contains it) if you need an absolute override. Re-running add for an existing id without --force fails and tells you to re-run with --force. On success it prints whether it Saved or Overwrote the spec and the path it wrote.

modde game list

modde game list

Prints the user-defined games as a table: id | display name | executable_dir | source, where source is the on-disk path of each spec. Prints No user-defined games configured. when the games directory is empty or absent. Built-in games are not listed here.

modde game show

modde game show <id>

Shows a resolved registration. If <id> is a user-defined game it prints the full spec (display name, executable_dir, mod_dir, steam_app_id, install_dir_name, nexus_domain, proxy_dlls, and the source path). If <id> is a built-in game it prints the built-in summary (display name, steam_app_id, nexus_domain, and source: built-in registry). Unknown IDs error with the list of supported game IDs.

modde game remove

modde game remove <id> [--yes]

Deletes <data dir>/modde/games/<id>.toml. By default it prompts Remove user-defined game '<id>'? [y/N]; pass --yes to skip the prompt. Attempting to remove a built-in game errors with game '<id>' is built in and cannot be removed; removing an unknown id errors with no user-defined game named '<id>' exists.

modde game detect

modde game detect <install-path>

Walks <install-path> looking for directories that contain .exe files, to help you choose an executable_dir (and confirm the install layout). For each directory containing at least one executable it reports the relative path, the sorted list of .exe names, and the combined size of those executables in bytes. Behavior:

• the search recurses up to 4 directory levels deep below the install root;
• .exe matching is case-insensitive;
• results are sorted by total executable size descending, then by relative path — so the largest-executable directory (usually the real game binary) is listed first;
• a non-existent install path errors;
• when nothing is found it prints No executable-bearing directories found under <path>.

This is purely advisory — detect never writes a spec. Use its top result as your --executable-dir.

modde game export

modde game export <id> [--with-optiscaler] [--output <path>]

Serializes any resolvable game (built-in or user-defined) to a GameSpec TOML. Exporting a built-in game gives you a starting point you can rename and tweak: it carries the built-in display_name, steam_app_id, install_dir_name, and nexus_domain, with executable_dir = "." and no mod_dir/proxy_dlls. With --with-optiscaler the exported TOML also includes the game’s resolved OptiScaler profiles (appended after the spec). With --output <path> it writes to that file; otherwise it prints to stdout.

modde game import

modde game import <path> [--force]

Reads a GameSpec TOML from <path>, parses and validates it, then copies it to <data dir>/modde/games/<spec-id>.toml. The destination filename comes from the spec’s id, not from the source filename. Without --force, an existing destination errors; with --force it overwrites. This is how you install a spec someone shared with you.

modde game import-profile

modde game import-profile <path> --for <game-id> [--force]

Imports OptiScaler profiles (not a game spec) from <path> and writes them to the sidecar <data dir>/modde/games/<game-id>.optiscaler.toml. The --for flag names the game the profiles belong to. Importing for an unknown game id warns but proceeds. Without --force, an existing sidecar errors; with --force it overwrites. On success it reports how many profiles were imported and where.

Detecting executable-bearing directories

Before registering a game you usually do not know where the real binary lives — some titles ship a tiny launcher at the root and the actual game several folders deep. modde game detect answers that:

modde game detect "/home/you/Games/factorio"

Executable-bearing directories under /home/you/Games/factorio:
1. bin/x64
   executables: factorio.exe
   total exe size: 41203712 bytes
2. .
   executables: launcher.exe
   total exe size: 524288 bytes

The first entry has the largest executables, so bin/x64 is almost certainly the executable_dir you want. Feed it straight into modde game add --executable-dir bin/x64.

Sharing a spec

GameSpecs are designed to be portable text files:

# On the authoring machine: write the spec to a file you can commit/share.
modde game export factorio --output factorio.toml

# Or hand-author games/factorio.toml and copy it out of the games directory.

# On another machine: install it (filename is taken from the spec id).
modde game import factorio.toml

Because the destination filename is derived from the spec’s id, the source file can be named anything. import re-validates the spec before installing it, so a malformed or id-colliding spec is rejected up front rather than being silently dropped at load time. Keep specs in version control or share them in issues — they are small and contain no secrets.

Worked example: registering a new title

Suppose you want to manage mods for a Steam game called Voidrunner that modde does not ship a profile for. Its Steam AppID is 998877, it installs to steamapps/common/Voidrunner, the real binary lives in Binaries/Win64, and mods drop into a top-level Mods/ folder. It uses a dxgi.dll proxy for an upscaler, and there is a Nexus page under the voidrunner domain.

1. Find the executable directory.

modde game detect "$HOME/.local/share/Steam/steamapps/common/Voidrunner"

Executable-bearing directories under .../Voidrunner:
1. Binaries/Win64
   executables: Voidrunner-Win64-Shipping.exe
   total exe size: 78905344 bytes
2. .
   executables: VoidrunnerLauncher.exe
   total exe size: 1048576 bytes

Binaries/Win64 is the winner.

2. Register the game.

modde game add voidrunner \
  --display-name "Voidrunner" \
  --executable-dir "Binaries/Win64" \
  --steam-app-id 998877 \
  --install-dir-name "Voidrunner" \
  --mod-dir "Mods" \
  --nexus-domain voidrunner \
  --proxy-dll dxgi

Saved user-defined game 'voidrunner' at /home/you/.local/share/modde/games/voidrunner.toml

This writes:

# /home/you/.local/share/modde/games/voidrunner.toml
id = "voidrunner"
display_name = "Voidrunner"
steam_app_id = "998877"
install_dir_name = "Voidrunner"
mod_dir = "Mods"
executable_dir = "Binaries/Win64"
nexus_domain = "voidrunner"
proxy_dlls = ["dxgi"]

3. Confirm it.

modde game list
modde game show voidrunner

4. Use it like any other game. From here, --game voidrunner works across the CLI: create a profile, install mods, deploy, and register a launch target.

modde profile create main --game voidrunner
# install mods into the profile (nexus / mediafire / local files) ...
modde deploy --game voidrunner

# Register a named executable launch target (see the CLI reference):
modde exec add voidrunner-game "Binaries/Win64/Voidrunner-Win64-Shipping.exe" \
  --game voidrunner
modde play main --game voidrunner

modde will detect the install (via the override-free detection chain: install_dir_name under Steam, then launcher data), deploy mods into Mods/, classify conflicts, and — because dxgi.dll exists in Binaries/Win64 after you deploy the upscaler — register the dxgi Wine DLL override at launch.

What you do not get: modde scan --game voidrunner has no Voidrunner-aware heuristics to discover pre-existing mods, and modde save save-profile features are unavailable, because generic games ship neither a scanner nor a save tracker. That is the boundary of the Partial status.

See also

• Supported games
• CLI reference
• Architecture

Nexus Mods

Overview

modde integrates with Nexus Mods for authentication, browsing, searching, downloading, installing, and update-checking mods. The integration uses both the v1 REST API (https://api.nexusmods.com/v1) and the v2 GraphQL API (https://api.nexusmods.com/v2/graphql). A Nexus Mods account with an API key is required for every authenticated call, and automated CDN downloads additionally require a Premium subscription — see Premium and what free accounts get.

This page covers the full surface: the six-source key-resolution chain, browse/search/trending feeds, rate-limit behaviour, single-mod installs, Nexus Collections, the nxm:// handler, and update checking with its safety guardrails.

Authentication

The six-source resolution chain

When modde needs a Nexus credential, it walks an ordered chain and uses the first source that yields a non-empty key. Higher entries win over lower ones — a configured config file beats an environment variable, which beats the keyring, and so on.

If none of the six yields a key, modde fails with:

No Nexus API key found. Set NEXUS_API_KEY env var or run `modde nexus auth`.

Every key is trimmed of surrounding whitespace before use, and empty/whitespace-only sources are skipped (they do not short-circuit the chain). The OAuth entry at priority 1 is checked first but falls through to the API-key chain when no token is stored or the stored token has expired.

Note on the keyring vs. the config file. Priority 2 (the modde nexus auth config file) and priority 4 (the system keyring) are distinct. The current modde nexus auth flow writes the mode-0600 config file at ~/.config/modde/nexus_api_key; the keyring slot is also read if present (e.g. written by another tool or a future flow). Because the config file sits above the keyring in the chain, a key written by modde nexus auth always takes precedence.

Recommendation per environment

Saving your API key (modde nexus auth)

modde nexus auth

This stores your personal API key so that subsequent commands can authenticate non-interactively. Get your key from Nexus Mods → My Account → API Keys.

Using sops-nix (declarative, recommended on NixOS)

For NixOS/home-manager setups, point modde at a secret file. The home-manager module wires apiKeyFile to NEXUS_API_KEY_FILE, which is priority 5 in the chain:

programs.modde = {
  enable = true;
  nexus.apiKeyFile = "/run/secrets/nexus-api-key";
};

The file contents are the raw key; modde trims trailing newlines. Because the path is read at runtime, the secret never enters the Nix store. This is compatible with sops-nix, agenix, and systemd credentials. See the Home-Manager module reference for the full option.

Checking status (modde nexus status)

modde nexus status

This calls the v1 users/validate.json endpoint and reports the resolved account name and whether it has Premium. Use it to confirm both that your key is valid and that automated downloads will work.

Premium and what free accounts get

Automated CDN downloads — the download_link.json endpoint that returns a time-limited CDN URL — are Premium-only. Before generating any download link, modde validates the account and refuses non-Premium keys with:

Nexus Premium is required for automated downloads.
Please upgrade at https://next.nexusmods.com/premium

Free accounts can still drive a nxm:// “Download with modde” link when the link carries its own short-lived key/expires pair issued by the website (see the nxm:// handler), because that path does not require the Premium download_link.json call. Everything that resolves a CDN URL through the API requires Premium.

Browsing and searching

modde queries the v2 GraphQL endpoint first for browse/search, because it returns richer per-tile data (thumbnails, summaries, endorsement and download counts) in a single round-trip. If the GraphQL schema shifts or the endpoint errors, modde transparently falls back to the v1 REST equivalent so the UI keeps rendering.

Additional v1 REST endpoints back the rest of the integration:

The mod-image gallery is fetched via a small dedicated GraphQL query (modImages), falling back to the single picture_url from the v1 mod response when GraphQL is unavailable.

The base URLs honour MODDE_NEXUS_BASE_URL and MODDE_NEXUS_GRAPHQL_URL for pointing the client at a mock server in tests. Production never sets them.

Rate-limit awareness

Nexus enforces hourly and daily request limits. modde reads the response headers on every v1 call and reacts:

• x-rl-hourly-remaining — when fewer than 10 requests remain in the hour, modde logs a warning so you can slow down before hitting the wall.
• HTTP 429 — a hard rate-limit error. modde surfaces it as Nexus API rate limit exceeded. Please wait before retrying. Respect the Retry-After header the server returns and wait before re-running.

Update checking is designed to be frugal here: mods are grouped by game domain and modde issues exactly one updated_mods call per domain regardless of how many mods you track in that game (see Checking for updates).

Installing a single mod

modde install mod https://www.nexusmods.com/skyrimspecialedition/mods/12345 --profile my-skyrim

The pipeline:

1. Resolve the mod, pick the latest MAIN file, and generate a CDN download link (Premium-gated).
2. Download the archive into the store, then extract into a temporary staging tree (not the store) for analysis.
3. Hash the archive (xxhash64) and record it on the install plan.
4. Analyze the staged tree to detect the install method (simple copy, FOMOD, BAIN, …).
5. Move files into the canonical store layout store/{domain}_{mod}_{file}/, or, when more input is needed, keep the staged copy and route you to a wizard.

The pipeline is idempotent: if store/{domain}_{mod}_{file}/ already exists it returns AlreadyStaged and skips the download. The same code path backs both the CLI and the UI Browse Nexus → Install button.

Non-interactive FOMOD installs

If the mod uses a FOMOD installer, supply a declarative config to answer its choices without a wizard:

modde install mod <url> --profile my-skyrim --fomod-config my-choices.toml

The config can be TOML or JSON. Without it, a FOMOD mod is staged and marked pending_user_input so a wizard can run later without re-downloading. See the FOMOD guide for authoring --fomod-config files.

When detection fails

If modde cannot classify the archive, it writes a dossier (mod name, author, version, Nexus URL, and a probe trace) next to the staged files and marks the install unknown. This is the same dossier the skill tooling consumes to add bespoke handling.

Nexus Collections

A Nexus Collection is a curated, version-pinned set of mods. modde resolves them in two steps, which lets you install by slug alone without knowing the game domain up front:

1. Discover — GET /collections/{slug}.json returns the collection’s game domain and its latest published revision number.
2. Fetch the manifest — GET /games/{domain}/collections/{slug}/revisions/{rev}.json returns the full, pinned manifest.

From the CLI

# Install the latest published revision
modde install nexus-collection <slug> --profile my-collection

# Pin a specific revision/version
modde install nexus-collection <slug> --version 7 --profile my-collection

When --version is omitted, modde uses the latest published revision discovered in step 1. When it is supplied, step 1 is still used to learn the game domain, but the given revision is fetched directly.

Declaratively (home-manager)

programs.modde.profiles.my-collection = {
  game = "skyrim-se";
  nexusCollection = {
    slug = "collection-slug";
    version = "1.0.0";
  };
};

nexusCollection is mutually exclusive with wabbajackList. See the Home-Manager module reference.

Version pinning and the profile lock

Installing a collection locks the profile with a NexusCollection lock reason. The lock preserves the curator’s intended load order and prevents modde update apply from silently drifting the profile away from the pinned revision. To update a locked profile you must opt in explicitly — see the update guardrails.

nxm:// protocol handler

Nexus’s “Download with [manager]” buttons emit nxm:// URIs. To make modde the system handler:

modde nxm install

This registers an XDG desktop entry for the nxm:// scheme. Clicking a download link on the Nexus website then hands the URI to modde, which fetches the file. You can also handle a URI by hand:

modde nxm handle "nxm://skyrimspecialedition/mods/12345/files/67890?key=abc&expires=123" \
  --profile my-skyrim

The URI carries the game domain, mod ID, file ID, and a short-lived key/expires pair the website mints for the download. --profile routes the result into a specific profile.

Checking for updates

modde update check

# Check for updates in the last week (default period)
modde update check --profile my-skyrim

# Check updates from the last day or month
modde update check --profile my-skyrim --period 1d
modde update check --profile my-skyrim --period 1m

--period accepts 1d, 1w (default), or 1m. Only enabled mods that carry Nexus metadata (nexus_mod_id + nexus_game_domain + installed_timestamp) are considered — mods installed via modde install mod and Nexus Collections record this automatically. modde groups the tracked mods by game domain, makes one updated_mods call per domain, and reports a mod as updatable when its latest_file_update timestamp is newer than your local installed_timestamp.

modde update check --mods checks your Nexus-tracked profile mods. Without --mods (and with no profile mods to check) the same command surface also covers modde’s own product update check.

modde update apply

The companion command downloads and installs the latest MAIN file for each updatable mod and rewrites the profile entries to point at the fresh (mod_id, file_id) pair. Pair check and apply in a scheduled task to keep a profile current.

# Preview only — list what would change, download nothing
modde update apply --profile my-skyrim --dry-run

# Apply non-breaking updates
modde update apply --profile my-skyrim

Safety guardrails

update apply is deliberately conservative because auto-updating can corrupt a curated setup:

• Locked-profile guard. Wabbajack, Nexus Collection, and TOML-import profiles ship a pinned, authoritative load order. apply refuses to run on a locked profile and tells you to either pass --confirm-locked (acknowledging the drift) or run modde profile unlock <name> first. With --confirm-locked it proceeds but warns that the locked source will not be re-verified afterward.
• Breaking-semver guard. Updates that look like a major version bump (e.g. 1.x → 2.0) are flagged breaking. They are skipped unless you pass --accept-breaking, and even then each breaking mod prompts for an interactive y/N confirmation. --yes assumes “yes” to those per-mod prompts but still refuses any breaking update unless --accept-breaking is also set. Version strings that can’t be parsed fall through as “not breaking”.

# Update a locked Collection profile, accepting major bumps non-interactively
modde update apply --profile my-collection --confirm-locked --accept-breaking --yes

See also

• Download backends — every transport modde can fetch from, and the resume/queue model
• Wabbajack modlists — the other major Nexus-backed install surface
• FOMOD installers — authoring --fomod-config files
• Home-Manager module reference — nexus.apiKeyFile, nexusCollection
• Parity audit — what is Done vs Partial

Wabbajack Modlists

Overview

Wabbajack is a modlist installer originally built for Windows. A .wabbajack file is a recipe — not a bundle of mods — that records exactly which archives to download from the internet and exactly how to reconstruct a curated mod setup from them. modde reads that recipe and replays it natively on Linux: no Windows VM, no Wine-hosted Wabbajack client, no .NET runtime. modde parses the manifest, resolves and verifies every download, applies binary patches, repacks Bethesda archives, and stages the result, all in Rust.

This means a .wabbajack list authored on Windows installs the same way a NixOS user expects any other package to install: content-addressed, hash-verified, resumable, and reproducible.

How it works

A .wabbajack file is a ZIP archive. Inside it is a single JSON manifest (named modlist or *.json) plus inline patch/data blobs. modde reads the manifest into a WabbajackManifest with two top-level lists:

• Archives — every external file the list needs, each identified by its Wabbajack hash (an xxHash64 stored as little-endian base64), its size, and a source State describing where to fetch it.
• Directives — the ordered list of operations that turn downloaded archives plus inline data into the final mod layout.

modde converts the raw archives into typed download directives and the raw directives into typed install directives, then drives them through a pipeline: download/verify → resumable staging → apply directives → optional BSA/BA2 repack → validate → deploy.

modde does not install Steam or Heroic games; install the game with its launcher first, then point gameDir at the installed game directory.

Archive sources (download directives)

Each Archive carries a State whose $type selects a downloader. modde maps them to typed download directives:

Every download is verified against its manifest hash before it is trusted. modde never substitutes a similarly named file — the hash is the only safe identity for an archive.

Install directives

modde supports the full set of directives a typical Bethesda/MO2 modlist uses. Each directive writes into the MO2-style staging layout (mods/<Mod Name>/…) before deployment.

Directives that read from a single source archive are grouped per archive so each downloaded archive is opened once, all of its outputs (extractions and patches) are produced together, and the archive can then be released or pruned. This keeps memory and I/O bounded even for lists with thousands of directives.

Unknown / unsupported directive $types parse as Unknown and are surfaced as hard blockers by modde wabbajack assess rather than being silently skipped.

GameFileSource: vanilla game files

Some lists reference files that ship with the base game instead of downloading them. Wabbajack records these as GameFileSourceDownloader archives that name a game-relative path (e.g. Data\Skyrim.esm). These entries are not downloads — modde reads and verifies them straight out of your installed game directory.

For example, several Skyrim SE lists (including Legends of the Frost) carry GameFileSourceDownloader entries. Pass --game-dir (CLI) or set gameDir (Home Manager) so modde can locate and hash those files. If a list has game-file sources and no game directory is provided, the install is blocked until you point it at the install.

Prerequisites

• A Nexus Mods API key — required for every NexusDownloader archive (the bulk of most lists). See Nexus integration.
• The base game installed — install it via Steam/Heroic first; modde does not install games.
• The game install path for lists that reference vanilla files (GameFileSourceDownloader) — supply --game-dir / gameDir.
• Sufficient disk space — you need room for the downloaded archives and the staged/deployed output simultaneously. Large Bethesda lists routinely need hundreds of gigabytes. Staging compresses eligible files (see resumable zstd staging) to soften this, but plan for the full footprint.

Declarative installation (Home Manager)

programs.modde = {
  enable = true;
  nexus.apiKeyFile = "/run/secrets/nexus-api-key";

  profiles.my-modlist = {
    game = "skyrim-se";
    installMode = "auto";
    gameDir = "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition";
    wabbajackList = {
      url = "https://example.com/modlist.wabbajack";
      hash = "sha256-...";
    };
  };
};

If the modlist is already available locally, for example through pkgs.requireFile or a custom fetcher, use path instead of url and hash:

programs.modde.profiles.my-modlist = {
  game = "skyrim-se";
  gameDir = "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition";
  wabbajackList = {
    path = /nix/store/...-Legends-of-the-Frost.wabbajack;
  };
};

Use installMode = "await-game" while the game is not installed yet. Activation will skip install/deploy and print the next step instead of failing.

CLI installation

modde install wabbajack /path/to/modlist.wabbajack \
  --profile my-modlist \
  --game-dir "/home/me/.local/share/Steam/steamapps/common/Skyrim Special Edition"

Wabbajack registry pages usually link through to an authored-files URL for the actual .wabbajack archive. Some authored-files CDN links now resolve through Wabbajack’s chunked download page instead of a plain file response, so pkgs.fetchurl may 404 even when modde’s chunk-aware downloader works. In that case, download the file with modde wabbajack download and use wabbajackList.path, or use a dedicated fetcher that reconstructs the chunks.

The full modde install wabbajack flag set

modde install wabbajack <PATH> [flags]