SMAPI/docs/mod-build-config.md

Stardew.ModBuildConfig is an open-source NuGet package which automates the build configuration for Stardew Valley SMAPI mods.

The package...

• lets you write your mod once, and compile it on any computer. It detects the current platform (Linux, Mac, or Windows) and game install path, and injects the right references automatically.
• configures Visual Studio so you can debug into the mod code when the game is running (Windows only).
• packages the mod automatically into the game's mod folder when you build the code (optional).

Contents

• Install
• Simplify mod development
• Troubleshoot
• Release notes

Install

When creating a new mod:

1. Create an empty library project.
2. Reference the Pathoschild.Stardew.ModBuildConfig NuGet package.
3. Write your code.
4. Compile on any platform.

When migrating an existing mod:

1. Remove any project references to Microsoft.Xna.*, MonoGame, Stardew Valley, StardewModdingAPI, and xTile.
2. Reference the Pathoschild.Stardew.ModBuildConfig NuGet package.
3. Compile on any platform.

Simplify mod development

Package your mod into the game folder automatically

You can copy your mod files into the Mods folder automatically each time you build, so you don't need to do it manually:

1. Edit your mod's .csproj file.

2. Add this block above the first </PropertyGroup> line:

   <DeployModFolderName>$(MSBuildProjectName)</DeployModFolderName>
   

That's it! Each time you build, the files in <game path>\Mods\<mod name> will be updated with your manifest.json, build output, and any i18n files.

Notes:

• To add custom files, just add them to the build output.
• To customise the folder name, just replace $(MSBuildProjectName) with the folder name you want.
• If your project references another mod, make sure the reference is not marked 'copy local'.

Debug into the mod code (Windows-only)

Stepping into your mod code when the game is running is straightforward, since this package injects the configuration automatically. To do it:

1. Package your mod into the game folder automatically.
2. Launch the project with debugging in Visual Studio or MonoDevelop.

This will deploy your mod files into the game folder, launch SMAPI, and attach a debugger automatically. Now you can step through your code, set breakpoints, etc.

Create release zips automatically (Windows-only)

You can create the mod package automatically when you build:

1. Edit your mod's .csproj file.

2. Add this block above the first </PropertyGroup> line:

   <DeployModZipTo>$(SolutionDir)\_releases</DeployModZipTo>
   

That's it! Each time you build, the mod files will be zipped into _releases\<mod name>.zip. (You can change the value to save the zips somewhere else.)

Troubleshoot

"Failed to find the game install path"

That error means the package couldn't figure out where the game is installed. You need to specify the game location yourself. There's two ways to do that:

• Option 1: set the path globally.
  This will apply to every project that uses version 1.5+ of package.

  1. Get the full folder path containing the Stardew Valley executable.

  2. Create this file path:

     platform	path
     Linux/Mac	~/stardewvalley.targets
     Windows	%USERPROFILE%\stardewvalley.targets

  3. Save the file with this content:

     <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
        <PropertyGroup>
          <GamePath>PATH_HERE</GamePath>
        </PropertyGroup>
     </Project>
     

  4. Replace PATH_HERE with your custom game install path.

• Option 2: set the path in the project file.
  (You'll need to do it for every project that uses the package.)

  1. Get the folder path containing the Stardew Valley .exe file.

  2. Add this to your .csproj file under the <Project line:

     <PropertyGroup>
       <GamePath>PATH_HERE</GamePath>
     </PropertyGroup>
     

  3. Replace PATH_HERE with your custom game install path.

The configuration will check your custom path first, then fall back to the default paths (so it'll still compile on a different computer).

Release notes

1.8

• Added mod's version to release zip filename.
• Fixed release zip not having a mod folder.
• Fixed release zip failing if mod name contains characters that aren't valid in a filename.

1.7.1

• Fixed issue where i18n folders were flattened.
• The manifest/i18n files in the project now take precedence over those in the build output if both are present.

1.7

• Added option to create release zips on build.
• Added reference to XNA's XACT library for audio-related mods.

1.6

• Added support for deploying mod files into Mods automatically.
• Added a build error if a game folder is found, but doesn't contain Stardew Valley or SMAPI.

1.5

• Added support for setting a custom game path globally.
• Added default GOG path on Mac.

1.4

• Fixed detection of non-default game paths on 32-bit Windows.
• Removed support for SilVerPLuM (discontinued).
• Removed support for overriding the target platform (no longer needed since SMAPI crossplatforms mods automatically).

1.3

• Added support for non-default game paths on Windows.

1.2

• Exclude game binaries from mod build output.

1.1

• Added support for overriding the target platform.

1.0

• Initial release.
• Added support for detecting the game path automatically.
• Added support for injecting XNA/MonoGame references automatically based on the OS.
• Added support for mod builders like SilVerPLuM.