Difference between revisions of "Modding:Installing SMAPI on Windows"

From Stardew Valley Wiki
Jump to navigation Jump to search
(update for new Steam Deck page)
(format executable names)
Line 40: Line 40:
 
==Configure your game client==
 
==Configure your game client==
 
===Steam===
 
===Steam===
−
You need to launch SMAPI through Steam if you want the Steam overlay, achievements, and playtime tracking to work. (If you don't care about achievements or tracking game time, you can just launch <samp>StardewModdingAPI.exe</samp> in [[Modding:Player Guide/Getting Started#Find your game folder|your game folder]] to play with mods.)
+
You need to launch SMAPI through Steam if you want the Steam overlay, achievements, and playtime tracking to work. (If you don't care about achievements or tracking game time, you can just launch {{executable name|StardewModdingAPI}} in [[Modding:Player Guide/Getting Started#Find your game folder|your game folder]] to play with mods.)
  
 
Here's how to configure it:
 
Here's how to configure it:
Line 53: Line 53:
  
 
===GOG Galaxy===
 
===GOG Galaxy===
−
You need to launch SMAPI through GOG Galaxy if you want its playtime tracking to work. (If you don't care about tracking game time, you can just launch <samp>StardewModdingAPI.exe</samp> in [[Modding:Player Guide/Getting Started#Find your game folder|your game folder]] to play with mods.)
+
You need to launch SMAPI through GOG Galaxy if you want its playtime tracking to work. (If you don't care about tracking game time, you can just launch {{executable name|StardewModdingAPI}} in [[Modding:Player Guide/Getting Started#Find your game folder|your game folder]] to play with mods.)
  
 
Here's how to configure it:
 
Here's how to configure it:
Line 85: Line 85:
 
; After you install SMAPI&#x3A;
 
; After you install SMAPI&#x3A;
 
:# In your game folder:
 
:# In your game folder:
−
:## rename <samp>Stardew Valley.exe</samp> to another name such as <samp>Stardew Valley original.exe</samp>;
+
:## rename {{executable name|Stardew Valley}} to another name such as {{executable name|Stardew Valley original}};
−
:## make a copy of <samp>StardewModdingAPI.exe</samp> and name the copy <samp>Stardew Valley.exe</samp>.
+
:## make a copy of {{executable name|StardewModdingAPI}} and name the copy {{executable name|Stardew Valley}}.
  
 
That's it! Now just launch the game through the Xbox app to play with mods. '''Note that when the game updates, you'll need to redo the last two sections.'''
 
That's it! Now just launch the game through the Xbox app to play with mods. '''Note that when the game updates, you'll need to redo the last two sections.'''
Line 113: Line 113:
 
#* '''Xbox app:'''
 
#* '''Xbox app:'''
 
## follow the [[#Xbox app|installation steps for Xbox app]] to open your game folder;
 
## follow the [[#Xbox app|installation steps for Xbox app]] to open your game folder;
−
## rename <samp>Stardew Valley.exe</samp> to <samp>StardewModdingAPI.exe</samp>;
+
## rename {{executable name|Stardew Valley}} to {{executable name|StardewModdingAPI}};
−
## rename the orginal exe that you renamed when you installed SMAPI back to <samp>Stardew Valley.exe</samp>.
+
## rename {{executable name|StardewModding Valley original}} (or the name you chose when installing SMAPI) back to {{executable name|Stardew Valley}}.
  
−
(If you want to play without mods temporarily, you can just launch <samp>Stardew Valley.exe</samp> directly or rename your <samp>Mods</samp> folder instead. Not applicable for Xbox app.)
+
(If you want to play without mods temporarily, you can just launch {{executable name|Stardew Valley}} directly or rename your <samp>Mods</samp> folder instead. Not applicable for Xbox app.)
  
 
==Troubleshooting==
 
==Troubleshooting==

Revision as of 17:02, 15 June 2022

Modding:Player Guide/header

This page explains how to install SMAPI (the tool which lets you use mods) on Windows.

See instructions for: Android • Linux • macOS • Steam Deck.

Install SMAPI

  1. Run the game without SMAPI at least once (so it can do first-time setup).
  2. Download the latest version of SMAPI.
  3. Extract the .zip file somewhere. (Your downloads folder is fine.)
  4. Double-click install on Windows¹, and follow the on-screen instructions.
  5. Configure your game client: see the instructions for Steam, GOG Galaxy, or Xbox app.

¹ This is a batch (bat) file with the full filename of install on Windows.bat, but Windows hides file extensions by default. To install manually instead, see instructions in the installer's readme.

Configure your game client

Steam

You need to launch SMAPI through Steam if you want the Steam overlay, achievements, and playtime tracking to work. (If you don't care about achievements or tracking game time, you can just launch SMAPI mascot.png StardewModdingAPI.exe in your game folder to play with mods.)

Here's how to configure it:

  1. Keep SMAPI's installer window open.
    (If you already closed it, just run it again. No need to uninstall first.)
  2. Copy the text in the installer window that looks like this (see how to copy text):
    Modding - installing SMAPI on Windows - installer Steam text.png
    Make sure you copy the entire line, including both quotation marks " and the %command% part.
    Your final path should look something like this: "Your path here" %command%
  3. In the Steam client, right-click on Stardew Valley and choose Properties:
    Modding - installing SMAPI on Windows - Steam 1.png
  4. Click the textbox under Launch Options:
    Modding - installing SMAPI on Windows - Steam 2.png
  5. 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.
  6. This text should consist of "Your SMAPI API Filepath" %command%
    Default for most users is "C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\StardewModdingAPI.exe" %command%
  7. From now on, just launch the game through Steam to run SMAPI with the Steam overlay and achievements.

GOG Galaxy

You need to launch SMAPI through GOG Galaxy if you want its playtime tracking to work. (If you don't care about tracking game time, you can just launch SMAPI mascot.png StardewModdingAPI.exe in your game folder to play with mods.)

Here's how to configure it:

  1. Open Notepad and paste in the following: start "" "C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley\StardewModdingAPI.exe"
    (If your game is installed to a different folder, replace the path in the command above.)
  2. Click on File and then Save As.
    Save batch script.png
  3. In the Save As window that appears: navigate to your Stardew Valley game folder, change Save as type to All Files, change the file name to start.bat, and click Save.
    Choose batch extension.png
    Name batch script.png
  4. In the GOG Galaxy client, click on Stardew Valley > settings icon > Manage installation > Configure.
    Gog galaxy configure.png
  5. In the menu that appears, enable the "Custom executables / arguments" checkbox.
    Gog galaxy custom launch.png
  6. Click Add another executable / arguments.
    Gog galaxy add exectuable.png
  7. Choose start.bat in the window that appears and click Open.
    Select batch file.png
  8. Enable the Default Executable radio button under the File 2 section you just added, and click OK.
    Gog galaxy select default executable.png

From now on, you can launch Stardew Valley through GOG Galaxy and both the SMAPI console and game will load as expected!

Xbox app

Mods work with the Xbox app, but there's a few extra steps.

Before you install SMAPI:
  1. Open the Stardew Valley section in the Xbox app.
  2. Click the ... > Manage button:
    Modding - Enable SMAPI in Xbox app 1.png
  3. Click the Files tab and then Browse to open your game folder:
    Modding - Enable SMAPI in Xbox app 3.png
  4. Open the Stardew Valley > Content folder. You should see a lot of files with names like api-ms-win-core-*:
    Modding - Enable SMAPI in Xbox app 4.png
  5. Copy the full path from the address bar at the top.
Run the SMAPI installer:
  1. Run the SMAPI installer like usual, but:
    • Download the installer to somewhere that's not the game directory (like your downloads folder).
    • When it asks where to install, enter the path you copied from the previous step.
After you install SMAPI:
  1. In your game folder:
    1. rename Stardew Valley executable icon.png Stardew Valley.exe to another name such as Stardew Valley original.exe;
    2. make a copy of SMAPI mascot.png StardewModdingAPI.exe and name the copy Stardew Valley executable icon.png Stardew Valley.exe.

That's it! Now just launch the game through the Xbox app to play with mods. Note that when the game updates, you'll need to redo the last two sections.

Update SMAPI

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

Uninstall

  1. Run run the installer again, but choose uninstall to remove SMAPI. (Not applicable for Xbox app.)
  2. If you configured Steam or GOG Galaxy to launch SMAPI, undo your changes:
    • Steam: in the Steam client: right-click on Stardew Valley, choose Properties > General > Set Launch Options, and blank the launch options textbox.
    • GOG Galaxy: in the GOG Galaxy client: click on Stardew Valley, click the settings icon next to the 'Play' button, click Manage installation > Configure, and clear the Custom executables / arguments checkbox.
    • Xbox app:
    1. follow the installation steps for Xbox app to open your game folder;
    2. rename Stardew Valley executable icon.png Stardew Valley.exe to SMAPI mascot.png StardewModdingAPI.exe;
    3. rename StardewModding Valley original.exe (or the name you chose when installing SMAPI) back to Stardew Valley executable icon.png Stardew Valley.exe.

(If you want to play without mods temporarily, you can just launch Stardew Valley executable icon.png Stardew Valley.exe directly or rename your Mods folder instead. Not applicable for Xbox app.)

Troubleshooting

"Oops, couldn't find the game automatically"

If you are using Game Pass, folder permissions will probably cause problems if you try this. Otherwise, if the installer shows that message, you can help it find the game folder. To do that:

  1. Exit the installer.
  2. Find your game folder.
  3. Move the installer folder into the game folder. (Make sure you move the whole folder, not just the files inside it!)
  4. Run the installer again and it should auto-detect the game folder now.

You can safely delete the installer folder when it's done.

I can't find a specific file mentioned in the guide!

Windows hides file extensions by default. To reveal them, simply tick the option in file explorer.

Select the View tab, and then check "File Name Extensions

If using Windows 11, refer to this screenshot instead:

Click on "View" menu, click on the "Show" menu, and click on "File name extensions"

Issues with SMAPI or mods

See the troubleshooting page for help with issues after installation.

Retrieved from "https://stardewvalleywiki.com/mediawiki/index.php?title=Modding:Installing_SMAPI_on_Windows&oldid=138759"