Modding:Migrate to Stardew Valley 1.3

←Index

This page is for modders. Players: see Modding:SMAPI compatibility instead. For updating Content Patcher or XNB mods, see Migrate XNB changes to Stardew Valley 1.3.

This page explains how to update your SMAPI mod code for compatibility with Stardew Valley 1.3.

Overview

At a high level, here's how to update a SMAPI mod:

1. Update the mod build NuGet package to 2.1-beta. (You may need to enable the 'include prerelease' checkbox to see the beta.)
   This adds support for Stardew Valley 1.3, and adds code analysis which will report common problems in Stardew Valley 1.3 as compiler warnings.
2. Restart Visual Studio to fully install the package.
3. Rebuild your solution.
4. Fix any compiler errors and warnings you see in the Error List pane in Visual Studio (or equivalent for other editors).
5. See below for help with specific changes and warnings.
6. Test all mod features to make sure they work.

That should take care of compatibility in single-player mode. The game will automatically synchronise most world changes to other players, but you might need further changes to work in multiplayer mode. Questions to consider: will your mod cause any problems if two players both have it installed? Do you have any custom objects/buildings/etc that might get synchronised to other players, and will that synchronisation work correctly? What if they have different configuration? Maybe it should only work for the main player? You can use SMAPI's Context.IsSinglePlayer and Context.IsMainPlayer flags in your logic to avoid conflicts.

If you need help updating your code, feel free to ask questions on the Stardew Valley Discord.

Major changes

Net fields

A 'net type' is any of several new classes which Stardew Valley 1.3 uses to sync data between players, named for the Net prefix in their name. A net type can represent a simple value like NetBool, or complex values like NetFieldDictionary. Many existing fields have been converted to net types (called 'net fields'), each wrapping the underlying value:

NetString str = new NetString("bar");
if (str.Value == "bar") // true

Impact on mods:

• The game will regularly collect all the net fields reachable from Game1.netWorldState and sync them with other players. That means that many mod changes will be synchronised automatically in multiplayer.
• Net fields can implicitly convert to their equivalent normal values (like bool x = new NetBool(true)), but their conversion rules can be counterintuitive and error-prone. For example, item?.category == null && item?.category != null can both be true at once. Always avoid implicit casts to minimise bugs.

Suggested fix:

• With the latest mod build package installed, rebuild your project. The package will detect net field references you need to update, and show an appropriate warning. See fix common warnings below.

Game1.player.friendships

This field is always null in Stardew Valley 1.3. Use the new Game1.player.friendshipData field instead, which wraps the raw data with a model.

Texture constructor arguments

Many constructors which previously accepted Texture2D texture arguments now take a string textureName argument instead. It's usually better to use SMAPI's content API to override textures instead. You can change the cached texture after the object is constructed (may need reflection), but don't change the texture name to avoid multiplayer sync issues.

Fix common compiler warnings

Make sure you check your Error List pane in Visual Studio (or equivalent in other IDEs) and fix any warnings. Here are some common ones:

Mismatch between the processor architecture...

Sample warning: "There was a mismatch between the processor architecture of the project being built "{0}" and the processor architecture of the reference "{1}". This mismatch may cause runtime failures."

That warning is normal. The error is saying that your build is set to 'Any CPU', but Stardew Valley is x86-only so it'll only work in x86 anyway. You can either ignore it, or change your platform target to x86.

This implicitly converts...

Sample warning: "This implicitly converts '{0}' from {1} to {2}, but {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. The field you're referencing 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 {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/smapi003 for details."

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