Modding:Migrate to Stardew Valley 1.5.5

←Index

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

Stardew Valley compatibility branch

Stardew Valley 1.5.5 is available in two branches on each OS (with identical content for players): the main branch which is installed by default, and an optional compatibility branch for older systems. These have identical content for players, but use different technologies:

branch	OS	game framework	runtime
main	Linux/macOS	MonoGame 3.8	64-bit .NET 5
	Windows	MonoGame 3.8	64-bit .NET 5
compatibility	Linux/macOS	MonoGame 3.5.1	64-bit Mono 4.5
	Windows	XNA Framework 4.0	32-bit .NET Framework 4.5

Unfortunately SMAPI only supports the main branch of the game. There are formidable difficulties across all mods in supporting all three variations, the Steam hardware stats show that ≈99.69% of players have 64-bit, and 32-bit imposes significant restrictions on what mods can do.

64-bit MonoGame and .NET 5

Stardew Valley 1.5.5 migrates to 64-bit MonoGame and .NET 5 on all platforms. SMAPI rewrites mods so they should mostly still work, but posting an update for every C# mod is strongly recommended to avoid edge cases.

To update your C# mod code:

1. Enable 64-bit compatibility if you haven't already. (Unless you explicitly changed the project settings, mods are 64-bit ready by default.)
2. 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).
3. Edit your mod's .csproj file, and replace <TargetFramework>net452</TargetFramework> with <TargetFramework>net5.0</TargetFramework>.
4. Update the mod build package to the prerelease 3.4.0 version.
5. Exit Visual Studio.
6. Delete your solution's hidden .vs folder, and every project's bin and obj folders.
7. 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.

New map properties

Stardew Valley 1.5.5 adds several map properties:

valid in	map property	usage
farm	FarmFishLocationOverride <location name> <chance>	Adds an alternative location name when catching fish, where the <chance> is a decimal value between 0 (never happens) and 1 (always happens). For example, FarmFishLocationOverride Mountain 0.5 adds a 50% chance of catching mountain fish instead of the normal fish for that location. The location name is case-sensitive, and matches those shown by the Debug Mode mod.
farm	FarmHouseFurniture [<furniture ID> <tile X> <tile Y>]+	Spawns initial furniture in the farmhouse when creating a new save. If you add multiple furniture to the same tile, the first one will be placed on the ground and the last one will be placed on the first one. This is also required to enable the FarmHouseWallpaper, FarmHouseFlooring, and FarmHouseStarterSeedsPosition properties. You can enable it without spawning any furniture with FarmHouseFurniture -1 0 0.
farm	FarmHouseFlooring <flooring id>	Sets the initial farmhouse floor to the given ID when creating a new save. These are mapped to the 4x4 tile areas in the Maps/walls_and_floors tilesheet starting at tile index 336 (where index 0 is mapped to the top-left square). This is only enabled if FarmHouseFurniture is set.
farm	FarmHouseWallpaper <wallpaper id>	Sets the initial farmhouse wallpaper to the given ID when creating a new save. These are mapped to the 1x4 tile areas in the Maps/walls_and_floors tilesheet starting from the top-left. This is only enabled if FarmHouseFurniture is set.
farm	FarmHouseStarterSeedsPosition <tile X> <tile Y>	Sets the tile position in the farmhouse where the seed package is placed when creating a new save. This is only enabled if FarmHouseFurniture is set.
any	ForceAllowTreePlanting T	Whether to allow planting trees (both wild and fruit) in this location, even if it normally wouldn't be allowed.
farm	SpawnBeachFarmForage T	Whether to randomly spawn beach forage and supply crates on the farm (like the vanilla beach farm). Forage and crates will only appear on tiles which have the BeachSpawn T property on the Back layer, are clear for placement, and don't have a tile on the AlwaysFront layer.
farm	SpawnForestFarmForage T	Whether to randomly spawn forest forage on the farm (like the vanilla forest farm). Forage will only spawn on tiles which have the Type Grass tile property, are clear for placement, and don't have a tile on the AlwaysFront layer.
farm	SpawnMountainFarmOreRect <tile X> <tile Y> <tile width> <tile height>	The tile area on the farm map where ores should randomly spawn (like the vanilla hilltop farm). Ores will only spawn on tiles which have the Type Dirt tile property and are clear for object placement.

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 JSON output for some fonts when unpacked by StardewXnbHack is a bit different due to the XNA Framework → MonoGame change.

See also

• Modding wishlist items done in Stardew Valley 1.5.5