SMAPI – Stardew Valley Modding API

What does SMAPI do?

SMAPI can do a lot of useful things for you. For example, it will…

1. Load mods into the game and provide APIs they can use. Many types of mod aren’t possible without SMAPI.
2. Rewrite mods for cross-platform compatibility, so you can use almost any mod on Linux/Mac/Windows.
3. Provide APIs and events for mods. SMAPI let patches interact with the game in ways they otherwise couldn’t.
4. 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.
5. Provide update checks. SMAPI automatically alerts you when a new version of a mod is available.
6. Provide compatibility checks. SMAPI automatically detects when a mod is incompatible and disables it before it causes problems.
7. Back up your save files. SMAPI automatically creates a daily backup of your saves and keeps ten backups, in case something goes wrong.

What’s new in the current version?

SMAPI 3.5 requires Stardew Valley 1.4.1 or later on Linux/Mac/Windows.

1. For players
   • SMAPI now prevents more game errors due to broken items, so you no longer need save editing to remove them.
   • Added option to disable console colors.
   • Updated compatibility list.
   • Improved translations.
     Date format translations were taken from the Lookup Anything mod; thanks to translators FixThisPlz (improved Russian), LeecanIt (added Italian), pomepome (added Japanese), S2SKY (added Korean), Sasara (added German), SteaNN (added Russian), ThomasGabrielDelavault (added Spanish), VincentRoth (added French), Yllelder (improved Spanish), and yuwenlan (added Chinese). Some translations for Korean, Hungarian, and Turkish were derived from the game translations.
2. For the Console Commands mod
   • Commands like world_setday now also affect the ‘days played’ stat (thanks to kdau!). That means what you see in-game matches what you’d get by playing to that date normally (e.g. timed events correctly unlock).
3. For the web UI
   • Updated the JSON validator/schema for Content Patcher 1.13.
   • Fixed rare intermittent “CGI application encountered an error” errors.now prevents more game errors due to invalid item data, so you now trash broken items in-game without save editing.For players
   • SMAPI now prevents more game errors due to broken items, so you no longer need save editing to remove them.
   • Added option to disable console colors.
   • Updated compatibility list.
   • Improved translations.
     Date format translations were taken from the Lookup Anything mod; thanks to translators FixThisPlz (improved Russian), LeecanIt (added Italian), pomepome (added Japanese), S2SKY (added Korean), Sasara (added German), SteaNN (added Russian), ThomasGabrielDelavault (added Spanish), VincentRoth (added French), Yllelder (improved Spanish), and yuwenlan (added Chinese). Some translations for Korean, Hungarian, and Turkish were derived from the game translations.
4. For the Console Commands mod
   • Commands like world_setday now also affect the ‘days played’ stat, so in-game events/randomization match what you’d get if you played to that date normally (thanks to kdau!). It also provides a new translated date string, so mods can use dates in dialogue, map messages, and UI.
5. For the web UI
   • Updated the JSON validator/schema for Content Patcher 1.13.
   • Fixed rare intermittent “CGI application encountered an error” errors.

SMAPI 3.1.0 requires Stardew Valley 1.4 or later on Linux/Mac/Windows. It mainly improves performance and fixes bugs for players and includes various smaller improvements:

• Added separate group in ‘skipped mods’ list for broken dependencies, so it’s easier to see what to fix first.
• Added friendly log message for save file-not-found errors.
• Updated for gamepad modes in Stardew Valley 1.4.1.
• Improved performance in some cases.
• Fixed compatibility with Linux Mint 18 (thanks to techge!), Arch Linux, and Linux systems with libhybris-utils installed.
• Fixed memory leak when repeatedly loading a save and returning to title.
• Fixed memory leak when mods reload assets.
• Fixes for Console Commands mod:
  • added new clothing items;
  • fixed spawning new flooring and rings (thanks to Mizzion!);
  • fixed spawning custom rings added by mods;
  • Fixed errors when some item data is invalid.
• Updated translations. Thanks to L30Bola (added Portuguese), PlussRolf (added Spanish), and shirutan (added Japanese)!

SMAPI 2.11.2 fixes compatibility with some Linux distros, and fixes an error on Mac/Linux with some custom maps.

Installing SMAPI on Linux

1. Install the latest version of Mono for your OC (Ubuntu/Debian/Raspbian/CentOS/RHEL/Fedora).
   The mono-complete package is recommended.
2. Select the appropriate version of SMAPI for your Stardew Valley and extract it somewhere (but not in your game folder!)
   ** The latest version of SMAPI is compatible with Stardew Valley 1.4.1 and up on Linux.
3. Run the install on Linux.sh file, and follow the on-screen instructions. The installer will detect your game and add SMAPI for you.

That’s it! Just launch the game to play with mods. You don’t need to change your Steam launch options (that’s only needed on Windows).

Uninstall

Run mono install.exe and choose uninstall.

Update

Just install the new version; the installer will automatically clean up previous versions.

Installing SMAPI on Mac

• Install the latest version of Mono for Mac (The ‘stable channel’ version is recommended).
• Select the appropriate version of SMAPI for your Stardew Valley and extract it.
  ** The latest version of SMAPI is compatible with Stardew Valley 1.4.1 and up on Mac.
• Enable the installer script:
  • Open Launchpad.
  • Type Terminal and select the Terminal app.
  • Enter this command:

mdfind -0 'kMDItemFSName = "install on Mac.command" && kMDItemContentType = "com.apple.terminal.shell-script"' | xargs -0 xattr -d com.apple.quarantine 

(You might see this error: No such xattr: com.apple.quarantine. If so, just ignore it and continue to the next step.)

• Expand the SMAPI installer folder in your Downloads and double-click install on Mac.command. Then follow the on-screen instructions.

That’s it! Just launch the game to play with mods. You don’t need to change your Steam launch options (that’s only needed on Windows).

Uninstall

• Open the file install on Mac.command.
• Choose to uninstall SMAPI.

Update

Just install the new version; the installer will automatically clean up previous versions.

Installing SMAPI on Windows

Method 1 (Using ModDrop)

ModDrop is a mod manager which supports SMAPI. It can install SMAPI, keep it updated, and simplify installing mods.

1. Install ModDrop and open the client.
2. In the top-right corner, click Install SMAPI or Update Available.
3. A window should appear that says something like “A new version of SMAPI is available.” Click the Install button and follow the on-screen instructions.

Method 2 (Using SMAPI’s installer )

Step 1: Install SMAPI

1. Run the game without SMAPI at least once (so it can do first-time setup).
2. Select and download the SMAPI version, suitable for your game. Extract it somewhere, but not in your game folder, nor the windows %TEMP% folder.
3. Double-click install on Windows.bat, and follow the on-screen instructions.
   The installer will detect your game and add SMAPI for you.
4. If you use Steam, continue to the next section. Otherwise just run StardewModdingAPI.exe in your game folder to play with mods.
   

Path:
GOG: C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley
or C:\GOG Games\Stardew Valley

Step 2: Configure Steam

You can use SMAPI through the Steam client to enable the overlay and achievements. This requires a few more steps.

• Keep SMAPI’s installer window open.
  (If you already closed it, just run it again. No need to uninstall first.)
• Copy the text in the installer window that looks like this:

Note: To highlight this line in the installer box you need to make right-click on the window title bar. Choose Mark or Edit > Mark. Left-click & hold where you want to start, drag to select text, and release the button

• In the Steam client, right-click on Stardew Valley and choose Properties:

• Click General > Set Launch Options:

• Replace anything in the textbox with the text you copied from the installer.(To paste text, click in the box and press CTRL and V.)
• Click OK to save your changes.
• From now on, just launch the game through Steam to run SMAPI with the Steam overlay and achievements.

Uninstall

1. Run install.exe and choose uninstall.
2. Blank the Steam launch options (if you changed them).
   If you want to play without mods temporarily, you can just launch Stardew Valley.exe directly instead.

Update

Method 1 (Using ModDrop)

If you use the ModDrop mod manager, click Update Available in the top-right if it appears and follow the on-screen instructions.

Method 2 (Using SMAPI’s installer )

Just install the new version; the installer will automatically clean up previous versions. (You don’t need to configure Steam again.)