Modding:Modder Guide/Test and Troubleshoot

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

This page helps you test your mods and solve common issues. For issues using mods, see Modding:Player Guide/Troubleshooting.

Test the mod

Basic testing

Testing is pretty straightforward for most mods:

1. Click Build > Rebuild Solution (Visual Studio) or Build > Rebuild All (MonoDevelop).
2. Make sure there are no build errors and the mod gets copied to your Mods folder.
3. Try the mod in-game.
4. Make sure there are no errors or warnings for your mod in the SMAPI console.

In general, if a mod works on one platform it'll work fine on the others.

Testing in multiplayer

You can test mods in multiplayer on the same computer, by launching two instances of the game:

1. Prepare player one:
   1. Launch SMAPI like usual.
   2. From the title screen: click co-op, then host.
   3. Start a new save slot (unless you've already created one). Make sure to set 'starting cabins' to at least one (you'll need one cabin per extra player).
2. Prepare player two:
   1. Launch SMAPI again. (This will automatically create a separate log file.)
   2. From the title screen: click co-op, then join LAN game.
   3. Leave the 'Enter IP...' box empty and click OK.

Testing on all platforms

For complex mods, you may need to test your mod on all platforms. The game is mostly the same on Linux/Mac, so you only need to test your mod twice: once on Windows, and again on Linux or Mac. You can do that by testing one version on your computer, and the other in a virtual machine.

If your main computer is Windows 10 or 11:

1. Install Windows Subsystem for Linux (WSL).
2. Install the required software in WSL:
1. Install Steam.
2. Launch export TERM=xterm && steam, then install & launch Stardew Valley through its UI. This will also install its dependencies.
3. (optional) Download and install your preferred IDE, if you plan to compile the code on Linux. For the latest standalone Rider version (not free):

   wget "<download url here>" -O rider-install.tar.gz
   sudo tar -xzvf rider-install.tar.gz -C /opt
   ln -s "/opt/JetBrains Rider-<version>/bin/rider.sh"
   ./rider.sh
   

4. Install SMAPI.
3. To launch the game, launch steam and run the game through its UI.

If your main computer is Windows 8 or earlier:

1. Install VirtualBox.
2. Create a ZorinOS Core VM in VirtualBox.
   • See this setup guide for more details. The ZorinOS installer might be a bit different than shown, but should be pretty intuitive.
   • If you don't see any options for 64-bit OSes in VirtualBox, see how to enable them.
   • When creating the virtual disk, at least 20GB is recommended.
3. Download the Steam installer in the VM and run it.
4. Launch Steam to finish installation. If nothing happens, see these extra steps to fix it.
5. Install Stardew Valley through Steam.
6. Install SMAPI.
7. (optional) Install mono-complete and MonoDevelop in your VM. This is only needed if you want to compile separately for Linux/Mac. When installing .deb files, use the instructions for the Ubuntu version shown here. If you run into errors, may Linux have mercy on your soul.
8. (optional) For unlocking Mac OS only: Virtual Machine Unlocker 2.1.1 for VmWare Workstation 11/12/14, VmWare Player 7/12/14, or Fusion 7/8/10. This is needed to boot Mac OS on a virtual Machine

If your main computer is Linux or macOS:

1. Install VirtualBox.
2. Create a VM with Windows.
3. Install Stardew Valley in your VM.
4. Install SMAPI.
5. (optional) Install Visual Studio Community in your VM. This is only needed if you want to compile separately for Windows.

Fix common build warnings

After building your project, you can see build warnings via Visual Studio > View > Error List or MonoDevelop > View > Pads > Errors. Here are some common ones.

This implicitly converts...

Sample warning: "This implicitly converts '{0}' from Net{1} to {2}, but Net{1} has unintuitive implicit conversion rules. Consider comparing against the actual value instead to avoid bugs. See https://smapi.io/buildmsg/avoid-implicit-net-field-cast for details."

Your code is referencing a net field, which can cause subtle bugs. This field has an equivalent non-net property, like monster.Health (int) instead of monster.health (NetBool). Change your code to use the suggested property instead.

FieldName is a Net* field...

Sample warning: "'{0}' is a Net{1} field; consider using the {2} property instead. See https://smapi.io/buildmsg/avoid-net-field for details."

Your code is referencing a net field, which can cause subtle bugs. You should access the underlying value instead:

• For a reference type (i.e., one that can contain null), you can use the .Value property (or .FieldDict for a NetDictionary):

  if (building.indoors.Value == null)
  

  Or convert the value before comparison:

  GameLocation indoors = building.indoors.Value;
  if(indoors == null)
     // ...
  

• For a value type (i.e., one that can't contain null), check if the parent is null (if needed) and compare with .Value:

  if (item != null && item.category.Value == 0)
  

The FieldName field is obsolete...

Sample warning: "The 'Character.friendships' field is obsolete and should be replaced with 'friendshipData'. See https://smapi.io/buildmsg/avoid-obsolete-field for details."

You're referencing a field which should no longer be used. Use the suggested field name instead to fix it.

An instance of analyzer ... cannot be created

Update to the latest Visual Studio; the NuGet package uses a recent feature that isn't available in older versions.

Feature 'global using directive' is not available in C# 9.0

Go to your solution's project file (the .csproj file) and change the <ImplicitUsings> property from "enable" to "disable".

Other issues

Can't target .NET 5

If the target framework list has options starting with...

• .NET Framework: you created the wrong type of project. Make sure you create a .NET 5 project for your mod instead. (The naming is a bit confusing.)
• .NET Core, .NET Standard, or .NET 5+: use .NET 5 for compatibility with the game. If you don't have that option, you can install the .NET 5 SDK to add it.

Visual Studio can't find the game/SMAPI/MonoGame DLLs

Common solutions:

• Restart Visual Studio.
• Make sure the game and SMAPI are correctly installed and work fine.
• Check for an error like "Failed to find game install path". If it's present, you need to specify your game path.
• Make sure you created a .NET 5 project, not .NET Framework. (See how to set the target framework; if you see options starting with .NET Framework, delete the project and create a .NET 5 project instead.)
• Make sure you target .NET 5 (see how to).

If those didn't fix it:

1. Click Build > Rebuild Solution (Visual Studio) or Build > Rebuild All (MonoDevelop).
2. Check the Output pane or error list (Visual Studio), or the Errors pad (MonoDevelop).
3. If you don't see anything relevant, post the Output text to hastebin, ask for help on Discord, and include a link to your hastebin.

Ask for help

See Modding:Help for how to get help!