Modding:Player Guide

←Index

Do you want to play Stardew Valley with mods? This page is for you!

Intro

What are mods?

A mod is just a package of files which changes Stardew Valley in some way. Mods can add features (like showing NPCs on the map), change game mechanics (like making fences decay more slowly), make cosmetic changes (like making your house look like a hobbit home), and more.

There are generally two types of mods:

• SMAPI mods use SMAPI (a modding API) to run code within the game. These mods are powerful and convenient. After installing SMAPI, you can install mods by dropping them into a folder and uninstall them by deleting their folder. You can use multiple SMAPI mods, and they'll rarely conflict. Ideally you would only use SMAPI mods, but there are a few things they can't do yet.
• XNB mods replace the game's data files (which have an .xnb extension, thus the name). These are harder to manage (you'll need to keep track of which files you overwrote and keep backups), and you can't use two mods that change the same files. These are often used to change images in the game, which is currently harder with SMAPI.

If you're just starting out, you should avoid XNB mods. It's easier for something to go wrong with those, and harder to fix when it does. However, you can use XNB and SMAPI mods together.

What is SMAPI?

SMAPI is a modding API — it launches the game with mod support and lets mods interact directly with the game code. It's safely installed alongside your normal game, and you can uninstall it anytime.

Can I use mods on Linux/Mac/Windows?

Yep. SMAPI is officially compatible with Linux, Mac, and Windows. You can use almost all mods on any platform, since SMAPI rewrites them for compatibility.

Can I use mods on consoles?

You can't use a mod launcher on consoles, unfortunately.

Are mods safe?

Most mods are entirely safe:

• SMAPI doesn't change any of the game files, so you can stop using it anytime.
• Most mods don't affect your save file, so you can add or remove them at will. (It's a good idea to back up your save files even if you don't use mods; save problems are almost always caused by the game itself.)
• Steam achievements work fine.

Using mods

Install SMAPI

Before you can use most mods, you need to install the SMAPI mod loader:

• Install SMAPI

Find mods

You can find mods in a few places:

site	description
Nexus Mods	Most mods are released here. If you're looking for mods, the most popular are a good place to start; see also this list of mod recommendations for a first playthrough.
Chucklefish mods	Some mods are released here (most are also on Nexus).
ModDrop	Pretty new. Not many mods yet, but you can install those it has very quickly through their (Windows-only) client.
Stardew Valley forums	Some mods are posted directly in the forums. Some hidden gems are only here, but finding them can be a challenge.

Before you download a mod...

• Does it work with the latest version of the game? (SMAPI will automatically disable most incompatible SMAPI mods, but you're on your own with XNB mods. Try checking the mod description or comments.)
• Don't download from stardewvalleymods.net. (Mods here are usually outdated, since the site republishes mods without permission for ad revenue.)

Add or remove mods

To install a mod, just unzip it into the Mods folder inside your game folder. Make sure each mod has its own subfolder; for example, if you have a PineapplesEverywhere mod, you should have a file structure like this:

Stardew Valley/
   Mods/
      PineapplesEverywhere/
         PineapplesEverywhere.dll
         manifest.json

To uninstall a mod, just remove it from the Mods folder.

Configure mods

Some mods have a config.json file in their mod folder. It might be created the first time you launch the game with that mod. This file lets you customise the mod settings.

To edit the config.json file, just open it in a text editor. Make sure the game isn't running when you edit it, or your changes might not take effect. See a basic guide to JSON; basically make sure your values are surrounded by quotes (like "value"). You can use this JSON validator to make sure the format is correct.

Files

SMAPI log

The SMAPI log has useful info for troubleshooting problems. It includes your game and SMAPI version, which mods you have, where the game is installed, any errors that occurred, and what happened.

Here's how to share it:

1. Find the log file here:

   Platform	Path
   Windows	%appdata%\StardewValley\ErrorLogs\SMAPI-latest.txt (Paste "%appdata%" into the address bar, Windows knows where it is.)
   Linux	~/.config/StardewValley/ErrorLogs/SMAPI-latest.txt (The folder is hidden by default. From Files, click Go » Enter Location and enter "~/.config".)
   Mac	~/.config/StardewValley/ErrorLogs/SMAPI-latest.txt (The folder is hidden by default. From Finder, click Go » Go to Folder and enter "~/.config".)

   (If you see a MODDED_ProgramLog.Log_LATEST.txt file instead, you have an older version of SMAPI. Try updating to the latest version.)

2. If you're sharing it...
   • In the #modding Discord channel: just drag the file onto the channel to attach it.
   • Somewhere else: attach the file, or send a pastebin link.

Save files

The game puts save files here:

Platform	Path
Windows	%appdata%\StardewValley\Saves (Paste "%appdata%" into the address bar, Windows knows where it is.)
Linux	~/.config/StardewValley/Saves (The folder is hidden by default. From Files, click Go » Enter Location and enter "~/.config".)
Mac	~/.config/StardewValley/Saves (The folder is hidden by default. From Finder, click Go » Go to Folder and enter "~/.config".)

Each save has a folder like JonSnow_123456789, with two main files inside it: JonSnow_123456789 and SaveGameInfo. Both files are needed to load the save.

To share or backup your save, zip the entire JonSnow_123456789 folder.

Game folder

The "game folder" is the folder that contains the Stardew Valley.exe (Windows) or StardewValley.exe (Linux/Mac) file. Here's how to find it:

1. Check the default location:

   Platform	Path
   Windows	GOG: C:\Program Files (x86)\GalaxyClient\Games\Stardew Valley Steam: C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley
   Linux	GOG: ~/GOG Games/Stardew Valley/game Steam: ~/.local/share/Steam/steamapps/common/Stardew Valley
   Mac	GOG: /Applications/Stardew Valley.app/Contents/MacOS Steam: ~/Library/Application Support/Steam/steamapps/common/Stardew Valley/Contents/MacOS

2. If your game wasn't there, try this:
   • If you have the GOG version:
     1. Open the GOG Galaxy client.
     2. In the game sidebar, right-click on Stardew Valley.
     3. Choose Manage Installation > Show Folder to open the game folder.
   • If you have the Steam version:
     1. Open the Steam client.
     2. Right-click on Stardew Valley.
     3. Click Properties.
     4. Click the Local Files tab.
     5. Click the Browse Local Files... button to open the game folder.

Troubleshooting

Fix common error messages

• "Oops! SMAPI can't find the game."
  • Make sure you're running StardewModdingAPI.exe in your game folder (see the install instructions).
  • Did you install SMAPI manually (not using install.exe)? Make sure you copied the right files: internal/Windows for Windows, or internal/Mono for Linux/Mac.

• "Oops! SMAPI doesn't seem to be compatible with your game."
  • Make sure you have Stardew Valley 1.2.30 or later.

• "Skipped '...' because it doesn't have a manifest.json"
  • SMAPI couldn't find the manifest.json file for the mod in that folder. That usually means it's not a SMAPI mod, so it won't work from the Mods folder. See that mod's documentation for install instructions.

StardewModdingAPI.exe disappears or your antivirus complains

Some antivirus programs may remove or complain about SMAPI. This is based on heuristic detection — SMAPI rewrites your mods so they work on your computer, and rewriting files is something trojans also do, so your antivirus got suspicious. SMAPI doesn't have a trojan (you can can read the code or decompile the download to check), so you just need to tell your antivirus that SMAPI is okay. Try searching online for your antivirus name with the words "add exception" to find instructions.

Check your versions

1. Make sure you have the latest version of SMAPI.
   The SMAPI version is shown at the top of the SMAPI console window.
2. Make sure you have Stardew Valley 1.2.30 or later.
   Click the "?" button on the title screen, and the version will appear in the bottom-left.

Reset your content files

Many problems are caused by broken files in the game's Content folder (especially if you installed an old XNB mod). You can reset your game files to default; this won't affect SMAPI mods, but any XNB mods will need to be reinstalled. See:

• Instructions for Steam
• Instructions for GOG Galaxy

Other problems

Run the game without SMAPI by launching Stardew Valley.exe (on Windows) or StardewValley-original (on Linux/Mac) in your game folder.

• If it still happens without SMAPI: see this guide to fixing your game. If you still need help, see asking for help.
• If it only happens with SMAPI: see asking for help.

Asking for help

Find help

For help with a mod, the mod author is the best person to ask. These are the best ways to contact them:

1. the discussion thread linked to on the mod page (if any);
2. the 'bugs' section on the Nexus mod page (if any);
3. otherwise contact the author directly (e.g. use the 'Contact' button on the Nexus mod page).

For help with SMAPI, or if you can't ask the mod author, post in this thread or ask in Discord.

What to include in a bug report

Figuring out why something went wrong for someone else can be tough, so it helps if you include as much information as possible. Here's the most useful information you can give.

1. Describe your problem:
   • Which mod has an issue?
   • What is the problem? Be as descriptive as possible. (Does the game freeze or close? Does the screen go black? Does nothing at all happen?)
   • What were you doing when it broke? Did you notice a pattern? For example, maybe it always breaks when you do a certain thing.
2. Describe your context:
   • Do you use a mod manager? If so, which one?
   • Do you play on Linux, Mac, or Windows?
3. Cause the problem again (so any details are in the log), then attach a copy of the latest log file (see next section).