Pathoschild.Stardew.ModBuildConfig
4.3.1
dotnet add package Pathoschild.Stardew.ModBuildConfig --version 4.3.1
NuGet\Install-Package Pathoschild.Stardew.ModBuildConfig -Version 4.3.1
<PackageReference Include="Pathoschild.Stardew.ModBuildConfig" Version="4.3.1" />
paket add Pathoschild.Stardew.ModBuildConfig --version 4.3.1
#r "nuget: Pathoschild.Stardew.ModBuildConfig, 4.3.1"
// Install Pathoschild.Stardew.ModBuildConfig as a Cake Addin #addin nuget:?package=Pathoschild.Stardew.ModBuildConfig&version=4.3.1 // Install Pathoschild.Stardew.ModBuildConfig as a Cake Tool #tool nuget:?package=Pathoschild.Stardew.ModBuildConfig&version=4.3.1
← 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
Use
- Create an empty library project.
- Reference the
Pathoschild.Stardew.ModBuildConfig
NuGet package. - Write your code.
- Compile on any platform.
- 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:
The package automatically finds your game folder by scanning the default install paths and Windows registry. It adds two MSBuild properties for use in your.csproj
file if needed:$(GamePath)
and$(GameModsPath)
.Add assembly references:
The package adds assembly references to MonoGame, SMAPI, Stardew Valley, and xTile. It automatically adjusts depending on which OS you're compiling it on. If you use Harmony, it can optionally add a reference to that too.Copy files into the
Mods
folder:
The package automatically copies your mod's DLL and PDB files,manifest.json
,i18n
files (if any), and theassets
folder (if any) into theMods
folder when you rebuild the code, with a subfolder matching the mod's project name. That lets you try the mod in-game right after building it.Create release zip:
The package adds a zip file in your project'sbin
folder when you rebuild the code, in the format recommended for uploading to mod sites like Nexus Mods. This includes the same files as the previous feature.Launch or debug mod:
On Windows only, the package configures Visual Studio so you can launch the game and attach a debugger using Debug > Start Debugging or Debug > Start Without Debugging. This lets you set breakpoints in your code while the game is running, or make simple changes to the mod code without needing to restart the game. This is disabled on Linux/macOS due to limitations with the Mono wrapper.Preconfigure common settings:
The package automatically enables.pdb
files (so error logs show line numbers to simplify debugging), and enables support for the simplified SDK-style.csproj
format.Add code warnings:
The package runs code analysis on your mod and raises warnings for some common errors or pitfalls. See code warnings for more info.
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:
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:
- Open the folder containing your mod's source code.
- Open the
.csproj
file in a text editor (Notepad is fine). - 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
property | effect |
---|---|
GamePath |
The absolute path to the Stardew Valley folder. This is auto-detected, so you usually don't need to change it. |
GameModsPath |
The absolute path to the folder containing the game's installed mods (defaults to $(GamePath)/Mods ), used when deploying the mod files. |
Mod build properties
property | effect |
---|---|
EnableHarmony |
Whether to add a reference to Harmony (default false ). This is only needed if you use Harmony. |
EnableModDeploy |
Whether to copy the mod files into your game's Mods folder (default true ). |
EnableModZip |
Whether to create a release-ready .zip file in the mod project's bin folder (default true ). |
ModFolderName |
The mod name for its folder under Mods and its release zip (defaults to the project name). |
ModZipPath |
The folder path where the release zip is created (defaults to the project's bin folder). |
Specialized properties
These properties should usually be left as-is.
property | effect |
---|---|
EnableGameDebugging |
Whether to configure the project so you can launch or debug the game through the Debug menu in Visual Studio (default true ). There's usually no reason to change this, unless it's a unit test project. |
IgnoreModFilePaths |
A comma-delimited list of literal file paths to ignore, relative to the mod's bin folder. Paths are case-sensitive, but path delimiters are normalized automatically. For example, this ignores a set of tilesheets: <IgnoreModFilePaths>assets/paths.png, assets/springobjects.png</IgnoreModFilePaths> . |
IgnoreModFilePatterns |
A comma-delimited list of regex patterns matching files to ignore when deploying or zipping the mod files (default empty). For crossplatform compatibility, you should replace path delimiters with [/\\] . For example, this excludes all .txt and .pdf files, as well as the assets/paths.png file: <IgnoreModFilePatterns>\.txt$, \.pdf$, assets[/\\]paths.png</IgnoreModFilePatterns> . |
BundleExtraAssemblies
(Specialized) 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:
option | result |
---|---|
ThirdParty |
Assembly files which don't match any other category. |
System |
Assembly files whose names start with Microsoft.* or System.* . |
Game |
Assembly files which are part of MonoGame, SMAPI, or Stardew Valley. |
All |
Equivalent to System, Game, ThirdParty . |
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.
Bundle 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:
property | effect |
---|---|
Include |
(Required) The path to the content pack folder. This can be an absolute path, or relative to the current project. |
Version |
(Required) The expected version of the content pack. This should usually be the same version as your main mod, to keep update alerts in sync. The package will validate that the included content pack's manifest version matches. |
FolderName |
(Optional) The content pack folder name to create. Defaults to the folder name from Include . |
ValidateManifest |
(Optional) Whether to validate that the included mod has a valid manifest.json file and version. Default true . |
IgnoreModFilePaths |
(Optional) A list of file paths to ignore (relative to the content pack's directory); see IgnoreModFilePaths in the main settings. Default none. |
IgnoreModFilePatterns |
(Optional) A list of file regex patterns to ignore (relative to the content pack's directory); see IgnoreModFilePatterns in the main settings. Default none. |
Code warnings
Overview
The NuGet package adds code warnings in Visual Studio specific to Stardew Valley. For example:
You can hide the warnings if needed using the warning ID (shown under 'code' in the Error List).
See below for help with specific warnings.
Avoid net field
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.
Avoid obsolete field
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.
Wrong processor architecture
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'.
FAQs
How do I set the game path?<span id="custom-game-path"></span>
The package detects where your game is installed automatically, so you usually don't need to set it manually. If it can't find your game or you have multiple installs, you can specify the path yourself.
To do that:
- Get the full folder path containing the Stardew Valley executable.
- See configure to add this property:
<PropertyGroup> <GamePath>PATH_HERE</GamePath> </PropertyGroup>
- Replace
PATH_HERE
with your game's folder path (don't add quotes).
The configuration will check your custom path first, then fall back to the default paths (so it'll still compile on a different computer).
How do I change which files are included in the mod deploy/zip?
- For normal files, you can add/remove them in the build output.
- For assembly files (
*.dll
,*.exe
,*.pdb
, or*.xml
), see theBundleExtraAssemblies
option. - To exclude a file which the package copies by default, see the
IgnoreModFilePaths
orIgnoreModFilePatterns
options.
Can I use the package for non-mod projects?
Yep, this works in unit tests and framework projects too. Just disable the mod-related package features (see configure):
<EnableGameDebugging>false</EnableGameDebugging>
<EnableModDeploy>false</EnableModDeploy>
<EnableModZip>false</EnableModZip>
To copy referenced DLLs into your build output for unit tests, add this too:
<BundleExtraAssemblies>All</BundleExtraAssemblies>
For SMAPI developers
The mod build package consists of three projects:
project | purpose |
---|---|
StardewModdingAPI.ModBuildConfig |
Configures the build (references, deploying the mod files, setting up debugging, etc). |
StardewModdingAPI.ModBuildConfig.Analyzer |
Adds C# analyzers which show code warnings in Visual Studio. |
StardewModdingAPI.ModBuildConfig.Analyzer.Tests |
Unit tests for the C# analyzers. |
The NuGet package is generated automatically in StardewModdingAPI.ModBuildConfig
's bin
folder
when you compile it.
See also
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages (10)
Showing the top 5 NuGet packages that depend on Pathoschild.Stardew.ModBuildConfig:
Package | Downloads |
---|---|
Platonymous.PyTK
Modding Toolkit for Stardew Valley |
|
MaxVollmer.StardewValley.DeepWoodsMod.API
API for the DeepWoodsMod for Stardew Valley. |
|
Juice805.StardewConfigFramework
A Unified Mod Options Page For Modders and Users. Keep all your mod settings in one place! |
|
Bookcase
Additional utilities for making stardew mods and ensuring cross compatability. |
|
EventGenerator
A handy Event Generator API for Stardew Valley's "SMAPI by PathosChild" |
GitHub repositories (6)
Showing the top 5 popular GitHub repositories that depend on Pathoschild.Stardew.ModBuildConfig:
Repository | Stars |
---|---|
Pathoschild/StardewMods
Mods for Stardew Valley using SMAPI.
|
|
FlashShifter/StardewValleyExpanded
The Stardew Valley Expanded mod for Stardew Valley.
|
|
Pathoschild/StardewXnbHack
A simple one-way XNB unpacker for Stardew Valley.
|
|
CJBok/SDV-Mods
|
|
spacechase0/StardewValleyMods
New home for my stardew valley mod source code
|
Version | Downloads | Last updated |
---|---|---|
4.3.1 | 0 | 11/5/2024 |
4.3.0 | 625 | 10/7/2024 |
4.2.0 | 729 | 9/5/2024 |
4.1.1 | 13,129 | 6/24/2023 |
4.1.0 | 4,767 | 1/9/2023 |
4.0.2 | 2,870 | 10/9/2022 |
4.0.1 | 5,768 | 4/14/2022 |
4.0.0 | 5,324 | 11/30/2021 |
4.0.0-beta.20210916 | 715 | 9/17/2021 |
3.4.0-beta.20210813 | 429 | 8/13/2021 |
3.3.0 | 4,783 | 3/31/2021 |
3.2.2 | 5,852 | 9/24/2020 |
3.2.1 | 1,940 | 9/11/2020 |
3.2.0 | 2,021 | 9/7/2020 |
3.1.0 | 4,801 | 2/1/2020 |
3.0.0 | 4,198 | 11/26/2019 |
3.0.0-beta.8 | 646 | 7/17/2019 |
3.0.0-beta.7 | 1,482 | 7/9/2019 |
3.0.0-beta.6 | 1,329 | 7/9/2019 |
3.0.0-beta.5 | 424 | 6/28/2019 |
3.0.0-beta.4 | 350 | 6/19/2019 |
3.0.0-beta.3 | 459 | 6/17/2019 |
3.0.0-beta.2 | 337 | 6/13/2019 |
3.0.0-beta | 1,588 | 6/13/2019 |
3.0.0-alpha.20190419 | 418 | 4/19/2019 |
2.2.0 | 9,350 | 10/28/2018 |
2.2.0-beta-20180819 | 2,576 | 8/20/2018 |
2.1.0 | 5,047 | 7/27/2018 |
2.1.0-beta-20180630 | 3,464 | 6/30/2018 |
2.1.0-beta-20180629 | 2,337 | 6/30/2018 |
2.1.0-beta-20180625 | 2,272 | 6/25/2018 |
2.1.0-beta-20180428 | 3,711 | 4/29/2018 |
2.1.0-beta-20180426 | 2,295 | 4/27/2018 |
2.1.0-beta | 2,541 | 4/26/2018 |
2.1.0-alpha20180410 | 2,280 | 4/10/2018 |
2.0.3-alpha20180325 | 2,337 | 3/25/2018 |
2.0.3-alpha20180307 | 2,205 | 3/7/2018 |
2.0.2 | 4,550 | 11/1/2017 |
2.0.1 | 2,815 | 10/11/2017 |
2.0.0 | 2,443 | 10/11/2017 |
1.7.1 | 3,102 | 7/28/2017 |
1.7.0 | 3,031 | 7/28/2017 |
1.6.2 | 2,743 | 7/10/2017 |
1.6.1 | 2,875 | 7/10/2017 |
1.6.0 | 2,705 | 6/5/2017 |
1.5.0 | 3,795 | 1/23/2017 |
1.4.0 | 2,549 | 1/11/2017 |
1.3.0 | 3,198 | 12/31/2016 |
1.2.0 | 2,937 | 10/24/2016 |
1.1.0 | 2,918 | 10/21/2016 |
1.0.1 | 3,231 | 10/21/2016 |