Modding:Migrate to Stardew Valley 1.5.5

The following describes the upcoming SMAPI 3.13.0, and may change before release.

This page is for mod authors. Players: see Modding:Mod compatibility instead.

This page explains how to update your mods for compatibility with Stardew Valley 1.5.5, and documents some of the changes and new functionality.

For SMAPI mods

64-bit MonoGame and .NET 5

Stardew Valley 1.5.5 is available in two branches (with identical content for players): the main branch uses 64-bit MonoGame + .NET 5 across all platforms; and the compatibility branch uses 32-bit XNA Framework + .NET Framework 4.5 on Windows, and 64-bit MonoGame + Mono 4.5 on Linux/macOS. The compatibility branch is only meant to support players with old systems (i.e. 32-bit Windows or macOS 10.12 "Sierra" or earlier), and the vast majority of players will be using the default main branch.

SMAPI only supports the main branch of the game. The Steam hardware stats show that ≈99.69% of players have 64-bit, there are formidable difficulties in supporting both versions, and 32-bit imposes significant restrictions on what mods can do.

To update your C# mod code:

Enable 64-bit compatibility if you haven't already. (Unless you explicitly changed the project settings, mods are 64-bit ready by default.)
Migrate your .csproj files to the new format if you haven't already:
1. Replace your mod's .csproj file with this:
```
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <AssemblyName>EXAMPLE_MOD_NAME</AssemblyName>
    <RootNamespace>EXAMPLE_MOD_NAME</RootNamespace>
    <Version>1.0.0</Version>
    <TargetFramework>net452</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Pathoschild.Stardew.ModBuildConfig" Version="3.3.0" />
  </ItemGroup>
```
2. If the mod uses Harmony, add <EnableHarmony>true</EnableHarmony> to the property group.
3. Update the AssemblyName, RootNamespace, and Version tags. (You can delete the AssemblyName and RootNamespace tags if they just match the project name.)
4. Add any other NuGet packages you used, if any.
5. Delete the Properties/AssemblyInfo.cs file, packages folder, and packages.config file (if present).
Edit your mod's .csproj file, and replace <TargetFramework>net452</TargetFramework> with <TargetFramework>net5.0</TargetFramework>.
Update the mod build package to version 3.4.0.
Exit Visual Studio.
Delete your solution's hidden .vs folder, and every project's bin and obj folders.
Reopen the solution in Visual Studio, click Build > Rebuild Solution, fix any errors, and test the mod in-game.

Specific things to check for:

Constants.GameFramework now always returns MonoGame. Any code which checks for Xna can be removed or rewritten.

If you need help, feel free to ask in #making-mods on the Stardew Valley Discord!

Asset name format change

Some background first:

An asset name identifies an asset you can load through a content API like Game1.content.Load<T>("asset name"). For example: Characters/Abigail.
A file path identifies a physical file on the computer. For example: C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\Content\Characters\Abigail.xnb.

Stardew Valley 1.5.5 makes that distinction more important, since MonoGame uses Linux-style separators in asset names on all platforms. That means asset names no longer match path conventions on Windows.

You should review all code in your mods that creates/compares paths, check whether it's actually creating/comparing asset names, and if so migrate it to the equivalent methods:

code for file paths	code for asset names
`PathUtilities.NormalizePath("a/b")`	`PathUtilities.NormalizeAssetName("a/b")`
`Path.Combine("a", "b")`	`PathUtilities.NormalizeAssetName("a/b")`
`Path.DirectorySeparatorChar`	`PathUtilities.AssetDirectorySeparator`

Consistent game assembly name

Previously the game assembly was Stardew Valley on Windows, and StardewValley on Linux and macOS. The assembly is now named Stardew Valley on all platforms. Most mods shouldn't be affected once you update the mod build package.

For Content Patcher packs

Possible breaking changes

Stardew Valley 1.5.5 has no known breaking changes for content packs. All content packs should work fine once the framework mod that loads them is updated.

Custom festival location names

The location name in the festival-started message (e.g. "The Luau has begun on the beach") was previously hardcoded, so it would always show the internal name for non-vanilla festival locations. You can now add a locationDisplayName field in the Data/Festivals/* file to set the display name.

Custom spouse rooms

Adding spouse rooms for custom NPCs is now much easier. You can edit the Data/SpouseRooms asset to add the spouse room info in this format: "<NPC name>": "<map name>/<map index>".

field	effect
`<NPC name>`	The internal name of the NPC (i.e. their key in `Data/NPCDispositions`).
`<map name>`	The asset name of the map in the game's `Content/Maps` folder. This can be a custom map loaded through Content Patcher's `Load` action or SMAPI's `IAssetLoader` API.
`<map index>`	The index of the spouse room within the map file, to allow multiple spouse rooms in the same file. Each spouse room is 6 tiles across by 9 tiles down, starting with index 0 in the top-left corner. You can have any number of rows and columns (the index will wrap at the end of the row), as long as they fit an integer number of spouse rooms.

Update impact

Stardew Valley 1.5.5 only has technical changes; there are no known changes to the player-visible content.

Known changes:

content file	changes
`Effects/BloomCombine` `Effects/BloomExtract` `Effects/GaussianBlur`	These files were deleted.
`Fonts/*`	The actual font files are unchanged, but the format when unpacked by StardewXnbHack is a bit different due to the XNA Framework → MonoGame change.