Pathoschild.Stardew.ModBuildConfig 4.4.0

← SMAPI

The mod build package is an open-source NuGet package which automates the MSBuild configuration for SMAPI mods and related tools. The package is fully compatible with Linux, macOS, and Windows.

Contents

• Basic usage
• Features
  • Detect game path
  • Install and debug your mod
  • Release zip
  • Bundled content packs
  • Manifest tokens
  • Code warnings
  • Unit tests
  • Other features
• Configure
  • How to set options
  • Available properties
• For SMAPI developers
• See also

Basic usage

1. Create an empty library project.
2. Reference the Pathoschild.Stardew.ModBuildConfig NuGet package.
3. Write your code.
4. Compile on any platform.
5. Run the game to play with your mod.

Features

The package includes several features to simplify mod development (see configure to change how these work).

Detect game path<span id="custom-game-path"></span>

The package...

• finds your game folder by scanning the default install paths and Windows registry;
• sets up your project so the code can reference SMAPI and game code;
• and adds two MSBuild properties for use in your .csproj file if needed: $(GamePath) and $(GameModsPath).

[!TIP] If it can't find your game or you have multiple installs, you can specify the path yourself. To do that:

1. Find your computer's home folder (see instructions for Linux, macOS, or Windows).
2. Create a stardewvalley.targets file with this content:

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

3. Replace PATH_HERE with the full folder path containing the Stardew Valley executable.

See configure for more info.

Install and debug your mod<span id="deploy"></span>

The package automatically installs your mod when you build the code, and sets up Visual Studio so it can launch the game and debug your code. That lets you try the mod in-game right after building it.

[!TIP] Here's how to use the features in Visual Studio.

<dl> <dt>To install and run your mod:</dt> <dd>

1. Open the code in Visual Studio.
2. Click Build > Rebuild Solution to copy the mod files into your game folder.
3. Click Debug > Start Without Debugging to launch the game.

</dd>

<dt>To debug your mod code:</dt> <dd>

On Windows only, use Debug > Start Debugging instead to launch the game with a debugger. That lets you set breakpoints or make simple changes code without needing to restart the game.

(Debugging is disabled on Linux/macOS due to limitations with the Mono wrapper.)

</dd> </dl>

[!TIP] The package automatically detects which files need to be included. If you need to change that:

• For normal files, you can add/remove them in the build output.
• For assembly files (*.dll, *.exe, *.pdb, or *.xml), see the BundleExtraAssemblies option.
• To exclude a file which the package copies by default, see the IgnoreModFilePaths or IgnoreModFilePatterns options.

Release zip

The package adds a zip file in your project's bin folder when you rebuild the code, in the format recommended for uploading to mod sites like Nexus Mods.

See install and debug your mod for more info. You can also change where the zips are stored.

Bundled content packs

You can bundle any number of content packs with your main C# mod. They'll be grouped with the main mod into a parent folder automatically, which will be copied to the Mods folder and included in the release zip.

To do that, add an ItemGroup with a ContentPacks line for each content pack you want to include:

<ItemGroup>
    <ContentPacks Include="content packs/[CP] SomeContentPack" Version="$(Version)" />
    <ContentPacks Include="content packs/[CP] AnotherContentPack" Version="$(Version)" />
</ItemGroup>

You can use these properties for each line:

Manifest tokens

It's best practices in .NET to set the code version in your .csproj project file. For example:

<PropertyGroup>
    <Version>1.0.0</Version>
</PropertyGroup>

If you do, you can use %ProjectVersion% in your manifest.json. This will be replaced with your project version automatically in your game folder and the release zip.

For example:

{
    "Name": "Your Mod Name",
    "Author": "Your Name",
    "Version": "%ProjectVersion%",
    ...
}

This also works with bundled content packs. When your mod consists of multiple parts, this lets you keep their versions in sync automatically.

Code warnings

The package runs code analysis on your mod and raises warnings for some common errors or pitfalls specific to Stardew Valley modding.

For example:

You can hide the warnings if needed using the warning ID (shown under 'code' in Visual Studio's Error List).

Warnings raised:

<table> <tr> <th>error</th> <th>info</th> </tr> <tr id="avoid-net-field"> <td>Avoid net field</td> <td>

Warning text:

'{{expression}}' is a {{net type}} field; consider using the {{property name}} property instead.

Your code accesses a net field, but the game has an equivalent non-net property.

Suggested fix: access the suggested property name instead.

</td> </tr> <tr id="avoid-obsolete-field"> <td>Avoid obsolete field</td> <td>

Warning text:

The '{{old field}}' field is obsolete and should be replaced with '{{new field}}'.

Your code accesses a field which is obsolete or no longer works. Use the suggested field instead.

</td> </tr> <tr id="wrong-processor-architecture"> <td>Wrong processor architecture</td> <td>

Warning text:

The target platform should be set to 'Any CPU' for compatibility with both 32-bit and 64-bit versions of Stardew Valley (currently set to '{{current platform}}').

Mods can be used in either 32-bit or 64-bit mode. Your project's target platform isn't set to the default 'Any CPU', so it won't work in both. You can fix it by setting the target platform to 'Any CPU'.

</td> </tr> </table>

Unit tests

You can use the projects to set up unit test and framework projects too. (Note that you still need a game install on the machine running the tests.)

Recommended settings for a unit test project (see configure):

<EnableGameDebugging>false</EnableGameDebugging>
<EnableModDeploy>false</EnableModDeploy>
<EnableModZip>false</EnableModZip>
<BundleExtraAssemblies>All</BundleExtraAssemblies>

Other features

The package preconfigures your Visual Studio project using the recommended settings for Stardew Valley mods. For example, it enables debug symbols so error logs show line numbers to simplify debugging.

Configure

How to set options

You can configure the package by setting build properties, which are essentially tags like this:

<PropertyGroup>
    <ModFolderName>CustomModName</ModFolderName>
    <EnableModDeploy>false</EnableModDeploy>
</PropertyGroup>

There are two places you can put them:

• Global properties apply to every mod project you open on your computer. That's recommended for properties you want to set for all mods (e.g. a custom game path). Here's where to put them:

  1. Open the home folder on your computer (see instructions for Linux, macOS, or Windows).
  2. Create a stardewvalley.targets file with this content:

     <Project>
        <PropertyGroup>
        </PropertyGroup>
     </Project>
     

  3. Add the properties between the <PropertyGroup> and </PropertyGroup>.

• Project properties apply to a specific project. This is mainly useful for mod-specific options like the mod name. Here's where to put them:

  1. Open the folder containing your mod's source code.
  2. Open the .csproj file in a text editor (Notepad is fine).
  3. Add the properties between the first <PropertyGroup> and </PropertyGroup> tags you find.

Note: you can't use a property before it's defined. That mainly means that when setting GameModsPath, you'll need to either specify GamePath manually or put the full path in GameModsPath.

Available properties

These are the options you can set.

Common properties

Mod build properties

Specialized properties

These properties should usually be left as-is.

BundleExtraAssemblies

[!IMPORTANT]
This is a specialized option. Most mods should not change this option.

By default (when this is not enabled), only the mod files normally considered part of the mod will be added to the release .zip and copied into the Mods folder (i.e. "deployed"). That includes the assembly files (*.dll, *.pdb, and *.xml) for your mod project, but any other DLLs won't be deployed.

Enabling this option will add all dependencies to the build output, then deploy some of them depending on the comma-separated value(s) you set:

Most mods should omit the option. Some mods may need ThirdParty if they bundle third-party DLLs with their mod. The other options are mainly useful for unit tests.

When enabling this option, you should manually review which files get deployed and use the IgnoreModFilePaths or IgnoreModFilePatterns options to exclude files as needed.

For SMAPI developers

The mod build package consists of three projects:

The NuGet package is generated automatically in StardewModdingAPI.ModBuildConfig's bin folder when you compile it.

See also

• Release notes