Modding:Player Guide/Getting Started - Stardew Valley Wiki (2024)

Modding:Index

Player's guide to using mods

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

Contents

  • 1 Intro
  • 2 Getting started
    • 2.1 Install SMAPI
    • 2.2 Find mods
    • 2.3 Find your game folder
    • 2.4 Install mods
    • 2.5 Configure mods
    • 2.6 Update mods
    • 2.7 Remove mods
  • 3 XNB mods
  • 4 Frequent questions
    • 4.1 Which platforms allow mods?
    • 4.2 Can mods corrupt my save?
    • 4.3 Can I stop using mods later?
    • 4.4 Do mods disable Steam achievements?
    • 4.5 Do mods work in multiplayer?
    • 4.6 What is SMAPI?
    • 4.7 Where are my...
    • 4.8 Can I have different mod groups?

Intro

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.

Using mods is easy! You just need to...

  1. Install SMAPI. That's the mod loader for Stardew Valley — 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.
  2. Unzip mods into your Mods folder.

See frequent questions below, or keep reading to get started!

Getting started

Install SMAPI

First you'll need to install the mod loader, SMAPI.

See the instructions for:

  • Windows;
  • macOS;
  • Linux;
  • Steam Deck (the handheld console);
  • or Android.

Find mods

Next you can download the mods you want. Some suggestions:

Before you download a mod, check if it works with the latest version of the game. For SMAPI mods, see the mod compatibility list; SMAPI will also automatically disable most incompatible SMAPI mods. You're on your own for XNB mods; try checking the mod description or comments for those.

Find your game folder

Next you'll need to open your game folder (the one containing Stardew Valley.exe or StardewValley.exe). Here's where to find it by default:

PlatformPath
WindowsGOG: C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley
or C:\GOG Games\Stardew Valley
Steam: C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley
Xbox App:C:\XboxGames\Stardew Valley
Android/storage/emulated/0/StardewValley/Mods
(Usually file manager apps show StardewValley in the root)
LinuxGOG: ~/GOGGames/StardewValley/game
Steam: ~/.local/share/Steam/steamapps/common/Stardew Valley
MacGOG: /Applications/Stardew Valley.app/Contents/MacOS
Steam: ~/Library/Application Support/Steam/SteamApps/common/Stardew Valley/Contents/MacOS

See also a pictorial guide to finding the folder on macOS.

Not there? Here are some other ways to find it:

more options
Option 2: find it through SMAPI
  1. Launch SMAPI.
  2. Enter this command in the SMAPI console (the second window that opens with the game):
    show_game_files
Option 3: find it through Steam
  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.
Option 4: find it through GOG Galaxy
  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.
Option 5: finding it through Xbox Gamepass
  1. Open the Xbox game client.
  2. On the main page for the game, click the ... button.
  3. Select Open Mods Folder

For images, please see Modding:Installing_SMAPI_on_Windows#Xbox_app

Install mods

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

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

Tips:

  • If you have a lot of mods, you can optionally organize them into subfolders. SMAPI will automatically search inside each folder until it finds one with files.
    📁 Stardew Valley/ 📁 Mods/ 📁 Fruit mods/ 📁 PineapplesEverywhere/ 🗎 PineapplesEverywhere.dll 🗎 manifest.json 📁 ApplesNowhere/ 🗎 ApplesNowhere.dll 🗎 manifest.json
  • To disable a folder, just add a dot in front of the folder name (like .disabled mods). If Windows doesn't let you do that, put a dot at the end too and it'll let you (like .disabled mods.).
  • Download mods into a folder other than Mods, unzip them there, and then move their folder(s) into Mods. That helps prevent errors related to extra files.
  • If you have a folder that looks like PineapplesEverywhere-1234567890, check inside it for the actual mod folder. Folders named like this often have more folders and possibly readme files inside them.

Configure mods

Some mods have a config.json file in their mod folder, which lets you customise the mod settings. The file is usually created the first time you launch the game with that mod installed.

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.

Update mods

To update a mod, just replace its files with the new versions (making sure to keep generated files like config.json).

More detailed steps:

  1. Download the new mod version.
  2. Check the mod page for any special update instructions.
  3. Unzip it somewhere else (not in your Mods folder).
  4. Open the mod's old and new folders, so the manifest.json is visible in both.
  5. Copy all the files/subfolders from the new folder into the old folder.

Remove mods

Delete a mod from the Mods folder to uninstall it. Make sure to check the mod page in case it mentions any special uninstall instructions.

XNB mods

XNB mods replace files in your game's Content folder with custom versions. If a mod has some .xnb files and no manifest.json, it's an XNB mod. This is an older type of mod that's no longer recommended, but see Modding:Using XNB mods if you're still interested.

Frequent questions

Which platforms allow mods?

Mod support for each platform:

PlatformMod support
PCLinux✓ fully supported
Mac✓ fully supported
Windows✓ fully supported
consoleNintendo Switch✖ no mod support
PS4✖ no mod support
PS Vita✖ no mod support
Steam Deck✓ fully supported, but may increase power usage
XBox One✖ no mod support
mobileAndroid✓ most mods supported
iOS✖ no mod support

Almost all mods will work on any supported platform, since SMAPI rewrites them for compatibility.

(For more technical info, see the SMAPI tracking ticket.)

Can mods corrupt my save?

Yes, but it's extremely rare. Only a few mods affect your save file at all. If you avoid those, mods are very unlikely to corrupt your save file. In most cases, you can fix save corruption by undoing the last save.

If you're worried, just back up your save files occasionally. That's strongly recommended even if you don't use mods, since save corruption is almost always caused by the game itself. SMAPI also creates a daily backup of your saves automatically; you can retrieve those from the Mods/SaveBackup folder.

Can I stop using mods later?

Yep. With a few exceptions (see previous question), mods don't directly affect your save file so you can stop using them anytime.

Do mods disable Steam achievements?

Steam achievements work fine, as long as you launch SMAPI through Steam. Make sure you follow the install instructions to configure Steam on Windows (no Steam changes needed on Linux or Mac). If the Steam overlay works, the achievements should work too.

Do mods work in multiplayer?

Yep, but it depends on the mod. Usually each player can have their own mods, and you can mix modded and vanilla players. Some mods don't work (or work poorly) in multiplayer, or affect other players too. Try checking the mod description for details about multiplayer (often under a 'compatibility' header).

Here are some approximate rules for mods that don't specify:

type of modaffectssummary
Content PatcherdependsSee Multiplayer in the Content Patcher readme (applies for XNB mods too).
Map replacementslocalThat includes mods which replace an existing map (without adding special logic with SMAPI). These are only visible to players who install them. Players without the custom map will see the normal map and will be subject to the normal bounds (e.g., they may see other players walk through walls, but they won't be able to follow).
Custom itemsglobalThat includes new crops, fruit trees, craftables, cooking recipes, furniture, wallpapers and floors, weapons, rings, clothing, and hats. Mods which add new items should be installed by all players; players missing a custom item mod may see Error Items.
Custom locationsglobalThat includes new locations and buildables added by TMXL or other frameworks. All players should have the same location mods. Entering a custom location that not everyone has installed can cause crashes. Buildables can only be built by the main player.
Custom NPCsglobalThat includes any mod that adds new characters to the game. All players should have the same custom NPCs installed to avoid issues.
Visual changesdependsThat includes custom portraits and sprites, custom farmer appearance, recolors, etc. Most of these mods only affect the players who installed them. Other players won't be affected. If both players have the same mods, they'll see the same visual changes. The exception is Content Patcher farmer appearance mods that add, rather than recolor, the existing sprites. All players need to have the same amount of new sprites (e.g., hairstyles or shirts) or there can be visual bugs for other players.
"Cheat"/"efficiency" modslocalThat includes mods that increase player speed, make farm tasks easier, give infinite energy, spawn items, etc. Other players will see the effects, but won't be able to use the mod unless they have it installed. It won't affect other players.
Time changesglobalThat includes any mod which pauses time, changes the current time, or changes the rate of time. These mods only work when installed by the main player, but will affect all players. They will have no effect when used by farmhands.
Custom UIlocalThat includes mods that add new icons, tooltips, and menus. These mods only affect the players who installed them. Other players won't be affected.
World changesglobalThat includes any mods which edit things in the world — durable fences, monster stat changes, etc. These mods affect all players, no matter who installs them.
Other modsdependsSee the mod's description for details, or ask the author.

What is SMAPI?

SMAPI is the mod loader for Stardew Valley. It works fine with GOG and Steam achievements, it's compatible with Linux/Mac/Windows and (unofficially) Android, you can uninstall it anytime, and there's a friendly community if you need help. SMAPI is required for most types of Stardew Valley mods.

SMAPI does a lot for you. For example, it will...

  1. Load mods into the game and provide APIs they can use. Many types of mods aren't possible without SMAPI.
  2. Rewrite mods for crossplatform compatibility, so you can use almost any mod on any platform.
  3. Intercept errors. If a mod crashes or causes an error, SMAPI will intercept the error, show the error details in the console window, and in most cases automatically recover the game.
  4. Provide update checks. SMAPI automatically alerts you when a new version of a mod is available.
  5. Provide compatibility checks. SMAPI automatically detects when a mod is incompatible and disables it before it causes problems.

Where are my...

  • Game folder: see Getting Started#Find your game folder.
  • SMAPI log: see smapi.io/log (and Modding:Help if you need help with something).
  • Save files: see Saves.

Can I have different mod groups?

Yep, SMAPI has built-in support for different mod groups. The instructions may seem complex, but it's easy once you get the hang of it:

For simplicity, you can also just rename the Mods folder to something else.

PlatformInstructions
Windows
  1. Create a separate folder for each mod group in your game folder, like Mods and Mods (multiplayer).
  2. Create a shortcut to the StardewModdingAPI.exe file in your game folder.
  3. Right-click the shortcut, choose Properties, and add this to the end of the Target field: --mods-path "Mods (multiplayer)" (changing folder name as needed). Don't delete any of the existing text in that field! This should be added to the end of what's already there. Done correctly, it should look something like "your-path-here\SteamLibrary\steamapps\common\Stardew Valley\StardewModdingAPI.exe" --mods-path "Mods (multiplayer)".
  4. Double-click that shortcut to launch SMAPI with the specified mod folder.
Windows (Steam)
  1. Create a separate folder for each mod group in your game folder, like Mods and Mods (multiplayer).
  2. Create a shortcut to your steam.exe file.
  3. Right-click the shortcut, choose Properties, and add this to the end of the Target field: -applaunch 413150 --mods-path "Mods (multiplayer)" (changing folder name as needed). Don't delete any of the existing text in that field! This should be added to the end of what's already there. Done correctly, it should look something like "your-path-here\Steam\steam.exe" -applaunch 413150 --mods-path "Mods (multiplayer)".
  4. Optionally you can click the "Change Icon..." button and browse to your Stardew Valley folder to change the icon of the shortcut from the Steam icon to the Stardew Valley Icon.
  5. Double-click that shortcut to make Steam launch SMAPI with the specified mod folder and all steam features.
Windows (Steam, Non-Steam Game Method)
  1. Create a separate folder for each mod group in your game folder, like Mods and Mods (multiplayer).
  2. Add SMAPI as a Non-Steam Game to your library a second time. Follow the second set of instructions in installing SMAPI on Windows - it is highly suggested you alter the title in your Steam Library to differentiate between mod groups, such as "Stardew Valley Modded" and "Stardew Valley Modded Multiplayer".
  3. Right-click the new SMAPI entry in your Steam Library, select "Properties", and add this to the end of the Target field: --mods-path "Mods (multiplayer)". Don't delete any of the existing text in that field! This should be added to the end of what's already there. Done correctly, it should look something like "your-path-here\SteamLibrary\steamapps\common\Stardew Valley\StardewModdingAPI.exe" --mods-path "Mods (multiplayer)".
  4. Click the "Play" button in the new SMAPI entry in Steam to make Steam launch SMAPI with the specified mod folder and all Steam features.
Linux
  1. Create a separate folder for each mod group in your game folder, like Mods and Mods (multiplayer).
  2. Create a file like SMAPI_multiplayer.sh on your desktop.
  3. Edit the file and set the text to this (change the folder name as needed, and replace /path/to/StardewValley with the full path to the StardewValley file in your game folder):
    #!/bin/bashSMAPI_MODS_PATH="Mods (multiplayer)" /path/to/StardewValley
  4. Mark the file executable (see instructions for Linux or Mac).
  5. Double-click the script to launch SMAPI with the specified mod folder.
Mac (non-Steam)
  1. Create a separate folder for each mod group in your game folder, like Mods and Mods(multiplayer) (no spaces).
  2. Create a text file on your desktop with the same name as the mod group, for example SMAPI_multiplayer and format as Plain Text.
  3. Input ~ followed by your folder path (your game folder). Add the following text to the end of the string:
     --mods-path "Mods(multiplayer)"
  4. Example: ~/Library/Application\ Support/Steam/steamapps/common/Stardew\ Valley/Contents/MacOS/StardewModdingAPI --mods-path "Mods(multiplayer)"
  5. Save the file, then mark the file executable (see instructions for Linux or Mac).
  6. If you get the error: "The file “SMAPI multiplayer.command” could not be executed because you do not have appropriate access privileges. To view or change access privileges, select the file in the Finder and choose File > Get Info." Then use the following code in the terminal: chmod u+x /path/to/SMAPI multiplayer.command to give yourself these access privileges.
  7. Double-click the script on your desktop to launch SMAPI with the specified mod folder.
Mac (Steam)
  1. Create a separate folder for each mod group in your game folder, like Mods and Mods(multiplayer). Note there shouldn't be a space between "Mods" and "(multiplayer)".
  2. Create a file SMAPI_multiplayer.command on your desktop.
  3. Edit the file and set the text to this (change the folder name as needed, and replace /path/to/steam_osx with the full path to the steam_osx file (you can find the path for steam_osx by using find /Applications -name steam_osx or if that does not work use the longer search sudo find / -name steam_osx):
    /path/to/steam_osx -applaunch 413150 --mods-path "Mods(multiplayer)"
  4. Example: /Applications/Steam.app/Contents/MacOS/steam_osx -applaunch 413150 --mods-path "Mods(multiplayer)"
  5. Mark the file executable (see instructions for Linux or Mac).
  6. If you get the error: "The file “SMAPI multiplayer.command” could not be executed because you do not have appropriate access privileges. To view or change access privileges, select the file in the Finder and choose File > Get Info." Then use the following code in the terminal: chmod u+x /path/to/SMAPI multiplayer.command to give yourself these access privileges.
  7. Double-click the script to make Steam launch SMAPI with the specified mod folder and all steam features.

On Windows only, the ModDrop mod manager also supports up to three 'mod loadouts' which you can switch between.

Troubleshooting

Modding:Player Guide/Getting Started - Stardew Valley Wiki (2024)

FAQs

Is modding Stardew Valley hard? ›

Intro. 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. Using mods is easy!

How to add Stardew Valley mods? ›

Installing Mods
  1. Download your mods.
  2. Locate your local Stardew Valley Folder. Below are the default file locations for each Operating System. Operating System. Default File Path. Windows. ...
  3. Open /mods folder.
  4. Extract the downloaded mods to this folder, each mod should have its own folder.

How to edit mods in Stardew Valley? ›

Configuring Mods
  1. Access your control panel and Stop your server.
  2. Connect to your server via FTP, we would suggest FileZilla.
  3. Navigate to /StardewValley/Mods .
  4. Open the folder of the mod you wish to configure.
  5. Locate config. ...
  6. Make any changes, close the file and select Finish editing and delete local file on Filezilla.

Is Stardew grindy? ›

In truth, the grind never stops. Take the simple task of harvesting your crops every morning; it's a minimal task when you first start out, but soon you have acres of farm growing every crop available, with you having to dash around to try and get them watered and fertilised before the day is wasted.

Is smapi safe to use? ›

Since the SMAPI mod manager isn't a part of Stardew Valley official game files, some might wonder whether the tool is truly safe to use. In general, SMAPI is a reliable and safe open-source based tool, meaning that its code is openly available for review and inspection.

Are there cheat codes for Stardew Valley? ›

Item Spawning Cheat

Instead of a name, you must name your character using a string of 1-3 item code values, each surrounded by brackets (for example, you might name your character [611][577][532] or just[72].

What language are Stardew Valley mods written in? ›

Since mods are written in C#, it's a good idea to get acquainted with it first. You don't need to memorise everything, but a grasp of the basics (like fields, methods, variables, and classes) will make everything else much easier.

Are mods allowed in Stardew Valley? ›

Adding mods to Stardew Valley can be very straightforward if there are only a couple you want to use. Many are installed just by placing the downloaded files in the "Mods" folder in your Stardew Valley directory.

Can I use Smapi without Steam? ›

Alternatively, you can add SMAPI as a non-Steam game if you would like separate Steam play buttons for an unmodded and modded version of the game. To configure it this alternate way: Keep SMAPI's installer window open, as in the previous method. (If you already closed it, just run it again.

What does Smapi stand for Stardew Valley? ›

A lot of mods require SMAPI (Stardew Modding Application Programming Interface), a third-party application.

How do I run Smapi commands? ›

How to use console commands on a Stardew Valley server
  1. Download the SMAPI Mod for Stardew Valley.
  2. Once installed, launch the game and connect to the server.
  3. Open the SMAPI command window.
  4. Commands are entered from this window. ...
  5. Input any command, and execute it by pressing Enter.

How do I manually add Mods to Stardew Valley? ›

Under the Stardew Valley installation folder, open the Mods folder. Unzip the downloaded mod files and drag the unzipped folders into the Mods folder. Then, you can launch Stardew Valley to enjoy the mods.

How to open mod config stardew? ›

How to use the Generic Mod Config Menu on a Stardew Valley server
  1. Launch the game, and connect to the server.
  2. Open the menu by pressing the Escape Key, scroll to the bottom, and choose the Mod Options button.
  3. Select any mod to begin editing settings.

Is it hard to make a Stardew Valley mod? ›

Modding Stardew Valley is extremely easy, and very rewarding. If you're looking for new ways to play, this is the way to go.

Is Stardew Valley good with mods? ›

Stardew Valley is a beloved title with immersive gameplay and a passionate modding community. Mods like Visible Fish and Tool Smart Switch improve gameplay experience and customization. Stardew Valley Expanded offers a massive fan-made expansion for players wanting more content.

How hard is modding a game? ›

Game mods can be simple or highly complex. For example, creating a skin for a Minecraft character can be done in a 2D editor with no coding knowledge, whereas total conversion of a game will take years of work and require the collaboration of a team of creators.

What happens if you cheat in Stardew Valley? ›

In 1.6, a cutscene with the mysterious Mr. Qi will play the first time a player breaks into the Summit. The background glitches out as Mr. Qi chews you out for cheating your way into the Summit with a monologue.

What is the hardest thing to get in Stardew Valley? ›

Highlights
  • Some items in Stardew Valley, such as the Prismatic Shard, Living Hat, and Tea Set, are extremely rare and difficult to obtain.
  • The drop rates for these rare items are generally less than 1%, making them frustrating for players to acquire.
Sep 8, 2023

References

Top Articles
Latest Posts
Recommended Articles
Article information

Author: Dong Thiel

Last Updated:

Views: 6303

Rating: 4.9 / 5 (59 voted)

Reviews: 90% of readers found this page helpful

Author information

Name: Dong Thiel

Birthday: 2001-07-14

Address: 2865 Kasha Unions, West Corrinne, AK 05708-1071

Phone: +3512198379449

Job: Design Planner

Hobby: Graffiti, Foreign language learning, Gambling, Metalworking, Rowing, Sculling, Sewing

Introduction: My name is Dong Thiel, I am a brainy, happy, tasty, lively, splendid, talented, cooperative person who loves writing and wants to share my knowledge and understanding with you.