Guide
User guide
Everything Mortar does, a page per topic. New here? Start with the first three.
- 1 Install Download from mortar.rethunk.tech/download, or every file from Releases.
- 2 First run Continue past the welcome screen (it lists the launchers found: Steam, GOG, Heroic, Lutris, Bottles) and open Stardew Valley. Setup has three steps.
- 3 Find and add mods Browse searches every site the game's mods come from at once (for Stardew Valley, Nexus Mods, CurseForge and GitHub). A mod several sites list is one card; its badge picks the site to install from, and Preferred source (the game's settings, Mods page) sets the default. The chips beside All sources narrow to one site, and switching a site off in the game's settings (Mods page) leaves it out of Browse. A mod on the known-broken list is marked on its card, with the mod to use instead.
Set up
- Install Download from mortar.rethunk.tech/download, or every file from Releases.
- First run Continue past the welcome screen (it lists the launchers found: Steam, GOG, Heroic, Lutris, Bottles) and open Stardew Valley. Setup has three steps.
- Sign in to Nexus Mods In Settings › Accounts, choose Sign in to Nexus Mods and approve Mortar in your browser. If that section shows Personal API key instead, copy your key from nexusmods.com (Settings, then API Keys), paste it in and choose Sign in. The key is kept in your system keyring.
- Browser extension The extension is optional. It marks Nexus pages with what your profile already has and sends Mod Manager Download clicks to Mortar. Settings › Downloads has a Download the extension button for mortar-browser-extension.zip from its releases, and says The browser extension is too old for this Mortar (or too new) when versions drift.
- Switch games Click the game's name in the title bar; it opens on the profile you used last. All games… opens Game select, where right-clicking a game offers Hide this game (and Unhide) and clicking a section's heading folds it away. The mouse's back and forward buttons, and Alt with the left and right arrows, move through the pages you opened.
- Game installs A game installed more than once (Steam and GOG, a beta branch, another folder) has a separate install for each. A profile uses the selected install unless you pin it in the game's settings; profiles pinned to different installs can run at once.
Mods
- Find and add mods Browse searches every site the game's mods come from at once (for Stardew Valley, Nexus Mods, CurseForge and GitHub). A mod several sites list is one card; its badge picks the site to install from, and Preferred source (the game's settings, Mods page) sets the default. The chips beside All sources narrow to one site, and switching a site off in the game's settings (Mods page) leaves it out of Browse. A mod on the known-broken list is marked on its card, with the mod to use instead.
- Modrinth and itch.io A game whose catalog entry lists Modrinth or itch.io gets a chip for it beside All sources, and its results join the merged search. Stardew Valley lists neither.
- Lethal Company and Thunderstore Lethal Company's mods are Thunderstore packages on BepInEx. Mortar installs BepInEx, searches Thunderstore alongside Nexus Mods, CurseForge and GitHub, and Add installs a package with its dependencies. A dependency still missing is flagged on the Load order tab and in Before you play.
- Your mod list Favourites: the star on a mod marks it; the profile menu's Add to favourites does the same for a profile.
- Edit a mod's settings Mortar edits a mod's config as a form, and other files a BepInEx mod keeps (YAML, TOML, XML, INI, JSON, text) as text. A mod that has not run yet has no config.
- Antivirus scan Before a mod enters Mortar's store, Mortar scans it with Windows Security or, on Linux, ClamAV's clamd when running. A flagged file refuses the install and deletes the extracted files. The error (Flagged by <scanner>: <name> in <file>) offers Install anyway, which asks to confirm, installs that mod once without a scan and records it in the profile's history. A scan that cannot finish installs the mod and warns you.
- Make your own mods For a game whose loader has a mod template (Lethal Company), Develop in the sidebar starts a mod: New mod… asks for its name, a one-line description, the author, Thunderstore team and id prefix, and where the project goes. Signed in to the gh tool, Mortar can create a GitHub repository for it; otherwise it copies the template into the folder. The project builds against your copy of the game, and every build installs into a development profile (one Mortar creates, or one you pick).
Profiles and sharing
- Profiles A profile is one set of mods. Switching profiles never touches the game folder's own Mods folder.
- Pair your computers Pairing lets a profile sent between two of your computers carry its mod files. An unpaired computer still receives the profile and downloads each mod from its source.
- Sync your profiles between computers A sync folder shares each profile's mod list, sources, settings and mod config files between your computers through a folder another tool carries (Syncthing, Dropbox, a NAS). Mod files are never copied; each computer downloads them from their sources.
- Save backups and restore Mortar zips your saves before it changes them: before a profile update, on every game start with Back up saves before Play, and on a timer with Scheduled save backups (both under the game's Save backups in Settings). A game whose catalog entry has no save folder shows no Saves tab, no Saves card on Home and no Save backups page.
Play and fix
- Play Play applies the profile's mod list and starts the game through its loader. Direct Play (not a Steam or store URL launch) can start more than one instance, spaced by a delay, for local multiplayer: set both in the game's settings under Play (Instances and Delay seconds). Develop's Test starts copies on its own. A Heroic or Lutris copy starts through its own launcher, so the game runs in the prefix and runner the launcher keeps for it. In a BepInEx game whose bridge has a console, the Console tab takes commands. Skip the intro in Stardew Valley's settings skips the title intro. Start first in the game's Play settings starts SteamVR, or the ALVR dashboard (choose its program there; it opens SteamVR itself), before the game; a profile can turn it off to play a flat-screen mod. Launch options… in the menu beside Play opens the profile's own launch options: extra arguments for the game, a command prefix (for example gamemoderun mangohud) and environment variables; the prefix and the environment apply to direct launches only. Launch presets keep several sets, each a Play with choice in that menu.
- Problems The Problems tab checks the open profile for missing requirements, conflicts, broken or outdated mods, damaged files, duplicates and more. It warns and never blocks Play.
- Troubleshooting Mortar does not start: it shows why, with a button that opens the folder holding mortar.log. Starting Mortar again while a copy is stuck offers to end it.
- Notifications and change history The bell in the title bar (Ctrl+Shift+N) opens Notifications. New holds this session's unread toasts. Earlier is the open profile's change history, newest first: Show diff lists what changed and Undo restores the profile to before that change. All changes… opens the full history, which lives with the profile and survives restarts.
- Screenshots The Screenshots tab shows the game's own screenshots and, for a Steam game, Steam's. Use as profile cover sets the open profile's cover.
- Stream overlay For OBS, Mortar's in-game bridge serves live values (Stardew Valley, Lethal Company, Valheim) to a browser source. In the game's settings open Stream overlay, turn it on and press Play (it is read at game start). The page has previews, a copy button for each OBS URL, the OBS steps, the Port and the Token. It listens on this computer only.
Mortar itself
- Updates Mortar: the Mortar menu's Check mods and Mortar for updates, or Settings › Updates (which can include betas). An update applies when you close Mortar, or choose Restart now. The Mortar menu's What is new in <version> shows what changed.
- Appearance Settings › Appearance sets the theme, accent colour (System follows your desktop's), font, Size and background (an image, the desktop wallpaper or a solid colour). Animated backgrounds hold still while a game runs or Reduce motion is on.
- Language Mortar follows your system language once a translation of it is mostly done, and English otherwise. Settings › General › Language picks one yourself; a language still being translated shows how much is done, and the rest stays in English. Volunteers translate Mortar on Hosted Weblate, and Help translate Mortar beside the picker opens it.
- Where your data lives The Mortar menu's Open data folder opens the first row.
- Uninstall Close Steam first so the Steam cleanup sticks: Steam rewrites its shortcut list on exit.
Mortar manages mods for the PC games its catalog enables. It finds the game, installs its mod loader (SMAPI for Stardew Valley), keeps each set of mods in its own profile and starts the game with the profile you pick. Internals: architecture.md.