translators
8,445
edits
Changes
Jump to navigation
Jump to search
Modding:Migrate to Stardew Valley 1.5.5 (view source)
Revision as of 02:29, 11 August 2021
, 02:29, 11 August 2021create page
←[[Modding:Index|Index]]
{{SMAPI upcoming|3.13.0}}
{{Modder compatibility header}}
This page explains how to update your mods for compatibility with {{version|1.5.5|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 [https://store.steampowered.com/hwsurvey 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:
<ol>
<li>[[Modding:Migrate to 64-bit on Windows|Enable 64-bit compatibility]] if you haven't already. (Unless you explicitly changed the project settings, mods are 64-bit ready by default.)</li>
<li>Migrate your <tt>.csproj</tt> files to the new format if you haven't already:<ol>
<li>Replace your mod's <tt>.csproj</tt> file with this:
<syntaxhighlight lang="xml">
<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>
</syntaxhighlight>
</li>
<li>If the mod uses [[Modding:Modder Guide/APIs/Harmony|Harmony]], add <code><nowiki><EnableHarmony>true</EnableHarmony></nowiki></code> to the property group.</li>
<li>Update the <tt>AssemblyName</tt>, <tt>RootNamespace</tt>, and <tt>Version</tt> tags. (You can delete the <tt>AssemblyName</tt> and <tt>RootNamespace</tt> tags if they just match the project name.)</li>
<li>Add any other NuGet packages you used, if any.</li>
<li>Delete the <tt>Properties/AssemblyInfo.cs</tt> file, <tt>packages</tt> folder, and <tt>packages.config</tt> file (if present).</li>
</ol>
</li>
<li>Edit your mod's <tt>.csproj</tt> file, and replace <code><nowiki><TargetFramework>net452</TargetFramework></nowiki></code> with <code><nowiki><TargetFramework>net5.0</TargetFramework></nowiki></code>.</li>
<li>Update the mod build package to version 3.4.0.</li>
<li>Exit Visual Studio.</li>
<li>Delete your solution's hidden <tt>.vs</tt> folder, and every project's <tt>bin</tt> and <tt>obj</tt> folders.</li>
<li>Reopen the solution in Visual Studio, click ''Build > Rebuild Solution'', fix any errors, and test the mod in-game.</li>
</ol>
Specific things to check for:
* [[Modding:Modder Guide/APIs/Utilities#Constants|<code>Constants.GameFramework</code>]] now always returns <tt>MonoGame</tt>. Any code which checks for <tt>Xna</tt> can be removed or rewritten.
If you need help, feel free to ask in [[Modding:Community#Discord|#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 <code><nowiki>Game1.content.Load<T>("asset name")</nowiki></code>. For example: <code>Characters/Abigail</code>.
* A ''file path'' identifies a physical file on the computer. For example: <code>C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\Content\Characters\Abigail.xnb</code>.
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:
{| class="wikitable"
|-
! code for file paths
! code for asset names
|-
| <code>PathUtilities.NormalizePath("a/b")</code>
| <code>PathUtilities.NormalizeAssetName("a/b")</code>
|-
| <code>Path.Combine("a", "b")</code>
| <code>PathUtilities.NormalizeAssetName("a/b")</code>
|-
| <code>Path.DirectorySeparatorChar</code>
| <code>PathUtilities.AssetDirectorySeparator</code>
|}
===Consistent game assembly name===
Previously the game assembly was <code>Stardew Valley</code> on Windows, and <code>StardewValley</code> on Linux and macOS. The assembly is now named <code>Stardew Valley</code> 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 <tt>locationDisplayName</tt> field in the <tt>Data/Festivals/*</tt> file to set the display name.
===Custom spouse rooms===
Adding spouse rooms for custom NPCs is now much easier. You can edit the <tt>Data/SpouseRooms</tt> asset to add the spouse room info in this format: <code>"{{t|NPC name}}": "{{t|map name}}/{{t|map index}}"</code>.
{| class="wikitable"
|-
! field
! effect
|-
| <code>{{t|NPC name}}</code>
| The internal name of the NPC (i.e. their key in <tt>Data/NPCDispositions</tt>).
|-
| <code>{{t|map name}}</code>
| The asset name of the map in the game's <tt>Content/Maps</tt> folder. This can be a custom map loaded through Content Patcher's <tt>Load</tt> action or SMAPI's <tt>IAssetLoader</tt> API.
|-
| <code>{{t|map index}}</code>
| 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:
{| class="wikitable"
|-
! content file
! changes
|-
| <tt>Effects/BloomCombine</tt><br /><tt>Effects/BloomExtract</tt><br /><tt>Effects/GaussianBlur</tt>
| These files were deleted.
|-
| <tt>Fonts/*</tt>
| The actual font files are unchanged, but the format when unpacked by StardewXnbHack is a bit different due to the XNA Framework → MonoGame change.
|}
==See also==
* [[User:Pathoschild/Modding wishlist/Completed#Done in Stardew Valley 1.5.5|Modding wishlist items done in Stardew Valley 1.5.5]]
[[Category:Modding]]
{{SMAPI upcoming|3.13.0}}
{{Modder compatibility header}}
This page explains how to update your mods for compatibility with {{version|1.5.5|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 [https://store.steampowered.com/hwsurvey 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:
<ol>
<li>[[Modding:Migrate to 64-bit on Windows|Enable 64-bit compatibility]] if you haven't already. (Unless you explicitly changed the project settings, mods are 64-bit ready by default.)</li>
<li>Migrate your <tt>.csproj</tt> files to the new format if you haven't already:<ol>
<li>Replace your mod's <tt>.csproj</tt> file with this:
<syntaxhighlight lang="xml">
<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>
</syntaxhighlight>
</li>
<li>If the mod uses [[Modding:Modder Guide/APIs/Harmony|Harmony]], add <code><nowiki><EnableHarmony>true</EnableHarmony></nowiki></code> to the property group.</li>
<li>Update the <tt>AssemblyName</tt>, <tt>RootNamespace</tt>, and <tt>Version</tt> tags. (You can delete the <tt>AssemblyName</tt> and <tt>RootNamespace</tt> tags if they just match the project name.)</li>
<li>Add any other NuGet packages you used, if any.</li>
<li>Delete the <tt>Properties/AssemblyInfo.cs</tt> file, <tt>packages</tt> folder, and <tt>packages.config</tt> file (if present).</li>
</ol>
</li>
<li>Edit your mod's <tt>.csproj</tt> file, and replace <code><nowiki><TargetFramework>net452</TargetFramework></nowiki></code> with <code><nowiki><TargetFramework>net5.0</TargetFramework></nowiki></code>.</li>
<li>Update the mod build package to version 3.4.0.</li>
<li>Exit Visual Studio.</li>
<li>Delete your solution's hidden <tt>.vs</tt> folder, and every project's <tt>bin</tt> and <tt>obj</tt> folders.</li>
<li>Reopen the solution in Visual Studio, click ''Build > Rebuild Solution'', fix any errors, and test the mod in-game.</li>
</ol>
Specific things to check for:
* [[Modding:Modder Guide/APIs/Utilities#Constants|<code>Constants.GameFramework</code>]] now always returns <tt>MonoGame</tt>. Any code which checks for <tt>Xna</tt> can be removed or rewritten.
If you need help, feel free to ask in [[Modding:Community#Discord|#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 <code><nowiki>Game1.content.Load<T>("asset name")</nowiki></code>. For example: <code>Characters/Abigail</code>.
* A ''file path'' identifies a physical file on the computer. For example: <code>C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\Content\Characters\Abigail.xnb</code>.
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:
{| class="wikitable"
|-
! code for file paths
! code for asset names
|-
| <code>PathUtilities.NormalizePath("a/b")</code>
| <code>PathUtilities.NormalizeAssetName("a/b")</code>
|-
| <code>Path.Combine("a", "b")</code>
| <code>PathUtilities.NormalizeAssetName("a/b")</code>
|-
| <code>Path.DirectorySeparatorChar</code>
| <code>PathUtilities.AssetDirectorySeparator</code>
|}
===Consistent game assembly name===
Previously the game assembly was <code>Stardew Valley</code> on Windows, and <code>StardewValley</code> on Linux and macOS. The assembly is now named <code>Stardew Valley</code> 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 <tt>locationDisplayName</tt> field in the <tt>Data/Festivals/*</tt> file to set the display name.
===Custom spouse rooms===
Adding spouse rooms for custom NPCs is now much easier. You can edit the <tt>Data/SpouseRooms</tt> asset to add the spouse room info in this format: <code>"{{t|NPC name}}": "{{t|map name}}/{{t|map index}}"</code>.
{| class="wikitable"
|-
! field
! effect
|-
| <code>{{t|NPC name}}</code>
| The internal name of the NPC (i.e. their key in <tt>Data/NPCDispositions</tt>).
|-
| <code>{{t|map name}}</code>
| The asset name of the map in the game's <tt>Content/Maps</tt> folder. This can be a custom map loaded through Content Patcher's <tt>Load</tt> action or SMAPI's <tt>IAssetLoader</tt> API.
|-
| <code>{{t|map index}}</code>
| 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:
{| class="wikitable"
|-
! content file
! changes
|-
| <tt>Effects/BloomCombine</tt><br /><tt>Effects/BloomExtract</tt><br /><tt>Effects/GaussianBlur</tt>
| These files were deleted.
|-
| <tt>Fonts/*</tt>
| The actual font files are unchanged, but the format when unpacked by StardewXnbHack is a bit different due to the XNA Framework → MonoGame change.
|}
==See also==
* [[User:Pathoschild/Modding wishlist/Completed#Done in Stardew Valley 1.5.5|Modding wishlist items done in Stardew Valley 1.5.5]]
[[Category:Modding]]