2019-07-06 13:04:05 +08:00
|
|
|
← [SMAPI](../README.md)
|
|
|
|
|
2019-06-19 11:29:05 +08:00
|
|
|
The **mod build package** is an open-source NuGet package which automates the MSBuild configuration
|
2021-04-04 23:37:11 +08:00
|
|
|
for SMAPI mods and related tools. The package is fully compatible with Linux, macOS, and Windows.
|
2017-10-08 10:11:12 +08:00
|
|
|
|
|
|
|
## Contents
|
2019-06-19 08:06:09 +08:00
|
|
|
* [Use](#use)
|
2019-06-19 10:22:09 +08:00
|
|
|
* [Features](#features)
|
2020-09-05 11:40:16 +08:00
|
|
|
* [Configure](#configure)
|
2019-06-19 10:22:09 +08:00
|
|
|
* [Code warnings](#code-warnings)
|
2020-09-05 11:40:16 +08:00
|
|
|
* [FAQs](#faqs)
|
|
|
|
* [How do I set the game path?](#custom-game-path)
|
|
|
|
* [How do I change which files are included in the mod deploy/zip?](#how-do-i-change-which-files-are-included-in-the-mod-deployzip)
|
|
|
|
* [Can I use the package for non-mod projects?](#can-i-use-the-package-for-non-mod-projects)
|
2019-07-06 12:35:51 +08:00
|
|
|
* [For SMAPI developers](#for-smapi-developers)
|
2017-10-09 01:04:36 +08:00
|
|
|
* [Release notes](#release-notes)
|
2017-10-08 10:11:12 +08:00
|
|
|
|
2019-06-19 10:22:09 +08:00
|
|
|
## Use
|
2019-06-19 08:06:09 +08:00
|
|
|
1. Create an empty library project.
|
2017-10-08 10:11:12 +08:00
|
|
|
2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig).
|
2017-10-09 01:15:20 +08:00
|
|
|
3. [Write your code](https://stardewvalleywiki.com/Modding:Creating_a_SMAPI_mod).
|
2017-10-08 10:11:12 +08:00
|
|
|
4. Compile on any platform.
|
2019-06-19 10:22:09 +08:00
|
|
|
5. Run the game to play with your mod.
|
2017-10-08 10:11:12 +08:00
|
|
|
|
2019-06-19 10:22:09 +08:00
|
|
|
## Features
|
2020-09-05 11:40:16 +08:00
|
|
|
The package includes several features to simplify mod development (see [_configure_](#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:
|
2021-09-17 06:48:59 +08:00
|
|
|
`$(GamePath)` and `$(GameModsPath)`.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
* **Add assembly references:**
|
2021-09-17 06:59:25 +08:00
|
|
|
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](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Harmony), it can optionally add
|
|
|
|
a reference to that too.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
* **Copy files into the `Mods` folder:**
|
|
|
|
The package automatically copies your mod's DLL and PDB files, `manifest.json`, [`i18n`
|
2021-09-17 10:47:05 +08:00
|
|
|
files](https://stardewvalleywiki.com/Modding:Translations) (if any), and the `assets` folder (if
|
|
|
|
any) into the `Mods` 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.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
* **Create release zip:**
|
|
|
|
The package adds a zip file in your project's `bin` folder when you rebuild the code, in the
|
2020-09-06 02:55:40 +08:00
|
|
|
format recommended for uploading to mod sites like Nexus Mods. This includes the same files as
|
|
|
|
the previous feature.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
* **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](https://docs.microsoft.com/en-us/visualstudio/debugger/using-breakpoints?view=vs-2019)
|
|
|
|
in your code while the game is running, or [make simple changes to the mod code without needing to
|
|
|
|
restart the game](https://docs.microsoft.com/en-us/visualstudio/debugger/edit-and-continue?view=vs-2019).
|
2021-04-04 23:37:11 +08:00
|
|
|
This is disabled on Linux/macOS due to limitations with the Mono wrapper.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
* **Preconfigure common settings:**
|
|
|
|
The package automatically enables `.pdb` files (so error logs show line numbers to simplify
|
2020-09-06 02:55:40 +08:00
|
|
|
debugging), and enables support for the simplified SDK-style `.csproj` format.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
* **Add code warnings:**
|
|
|
|
The package runs code analysis on your mod and raises warnings for some common errors or
|
|
|
|
pitfalls. See [_code warnings_](#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:
|
2019-06-19 10:22:09 +08:00
|
|
|
```xml
|
2020-09-05 11:40:16 +08:00
|
|
|
<PropertyGroup>
|
|
|
|
<ModFolderName>CustomModName</ModFolderName>
|
|
|
|
<EnableModDeploy>false</EnableModDeploy>
|
|
|
|
</PropertyGroup>
|
2019-06-19 10:22:09 +08:00
|
|
|
```
|
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
There are two places you can put them:
|
2019-06-20 01:47:05 +08:00
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
* **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:
|
2019-06-19 08:06:09 +08:00
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
1. Open the home folder on your computer (see instructions for
|
|
|
|
[Linux](https://superuser.com/questions/409218/where-is-my-users-home-folder-in-ubuntu),
|
2021-04-04 23:37:11 +08:00
|
|
|
[macOS](https://www.cnet.com/how-to/how-to-find-your-macs-home-folder-and-add-it-to-finder/),
|
2020-09-05 11:40:16 +08:00
|
|
|
or [Windows](https://www.computerhope.com/issues/ch000109.htm)).
|
|
|
|
2. Create a `stardewvalley.targets` file with this content:
|
|
|
|
```xml
|
|
|
|
<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.
|
|
|
|
|
|
|
|
### Available properties
|
|
|
|
These are the options you can set:
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li>Game properties:
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>property</th>
|
|
|
|
<th>effect</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>GamePath</code></td>
|
|
|
|
<td>
|
|
|
|
|
2020-09-06 02:55:40 +08:00
|
|
|
The absolute path to the Stardew Valley folder. This is auto-detected, so you usually don't need to
|
|
|
|
change it.
|
2020-09-05 12:14:13 +08:00
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>GameModsPath</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
The absolute path to the folder containing the game's installed mods (defaults to
|
|
|
|
`$(GamePath)/Mods`), used when deploying the mod files.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
2021-03-31 08:10:55 +08:00
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2020-09-05 11:40:16 +08:00
|
|
|
</table>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>Mod build properties:
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>property</th>
|
|
|
|
<th>effect</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>EnableHarmony</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
Whether to add a reference to [Harmony](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Harmony)
|
|
|
|
(default `false`). This is only needed if you use Harmony.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2020-09-05 12:14:13 +08:00
|
|
|
<td><code>EnableModDeploy</code></td>
|
2020-09-05 11:40:16 +08:00
|
|
|
<td>
|
|
|
|
|
2020-09-05 12:14:13 +08:00
|
|
|
Whether to copy the mod files into your game's `Mods` folder (default `true`).
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2020-09-05 12:14:13 +08:00
|
|
|
<td><code>EnableModZip</code></td>
|
2020-09-05 11:40:16 +08:00
|
|
|
<td>
|
|
|
|
|
2020-09-05 12:14:13 +08:00
|
|
|
Whether to create a release-ready `.zip` file in the mod project's `bin` folder (default `true`).
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2020-09-05 12:14:13 +08:00
|
|
|
<td><code>ModFolderName</code></td>
|
2020-09-05 11:40:16 +08:00
|
|
|
<td>
|
|
|
|
|
2020-09-05 12:14:13 +08:00
|
|
|
The mod name for its folder under `Mods` and its release zip (defaults to the project name).
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2020-09-05 12:14:13 +08:00
|
|
|
<td><code>ModZipPath</code></td>
|
2020-09-05 11:40:16 +08:00
|
|
|
<td>
|
|
|
|
|
2020-09-05 12:14:13 +08:00
|
|
|
The folder path where the release zip is created (defaults to the project's `bin` folder).
|
2020-09-05 11:40:16 +08:00
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>Specialized properties:
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>property</th>
|
|
|
|
<th>effect</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
2021-09-17 10:47:05 +08:00
|
|
|
<td><code>BundleExtraAssemblies</code></td>
|
2020-09-05 11:40:16 +08:00
|
|
|
<td>
|
|
|
|
|
2021-09-17 10:47:05 +08:00
|
|
|
**Most mods should not change this option.**
|
|
|
|
|
|
|
|
By default (when this is _not_ enabled), only the mod files [normally considered part of the
|
|
|
|
mod](#Features) 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:
|
|
|
|
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>option</th>
|
|
|
|
<th>result</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>ThirdParty</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
Assembly files which don't match any other category.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>System</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
Assembly files whose names start with `Microsoft.*` or `System.*`.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>Game</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
Assembly files which are part of MonoGame, SMAPI, or Stardew Valley.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>All</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
Equivalent to `System, Game, ThirdParty`.
|
|
|
|
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
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.
|
2020-09-05 11:40:16 +08:00
|
|
|
|
2020-09-05 12:14:13 +08:00
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>EnableGameDebugging</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2021-09-17 05:34:31 +08:00
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>IgnoreModFilePaths</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
```xml
|
|
|
|
<IgnoreModFilePaths>assets/paths.png, assets/springobjects.png</IgnoreModFilePaths>
|
|
|
|
```
|
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td><code>IgnoreModFilePatterns</code></td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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:
|
2019-06-19 10:22:09 +08:00
|
|
|
|
|
|
|
```xml
|
|
|
|
<IgnoreModFilePatterns>\.txt$, \.pdf$, assets[/\\]paths.png</IgnoreModFilePatterns>
|
|
|
|
```
|
2019-06-19 08:06:09 +08:00
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</li>
|
|
|
|
</ul>
|
2019-04-19 10:46:00 +08:00
|
|
|
|
2018-04-10 07:32:00 +08:00
|
|
|
## Code warnings
|
|
|
|
### Overview
|
|
|
|
The NuGet package adds code warnings in Visual Studio specific to Stardew Valley. For example:
|
|
|
|
![](screenshots/code-analyzer-example.png)
|
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
You can [hide the warnings](https://visualstudiomagazine.com/articles/2017/09/01/hide-compiler-warnings.aspx)
|
|
|
|
if needed using the warning ID (shown under 'code' in the Error List).
|
2018-04-10 07:32:00 +08:00
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
See below for help with specific warnings.
|
2018-04-10 07:32:00 +08:00
|
|
|
|
2018-04-15 05:53:58 +08:00
|
|
|
### Avoid implicit net field cast
|
|
|
|
Warning text:
|
2018-04-10 07:32:00 +08:00
|
|
|
> This implicitly converts '{{expression}}' from {{net type}} to {{other type}}, but
|
|
|
|
> {{net type}} has unintuitive implicit conversion rules. Consider comparing against the actual
|
|
|
|
> value instead to avoid bugs.
|
|
|
|
|
2018-04-11 06:23:39 +08:00
|
|
|
Stardew Valley uses net types (like `NetBool` and `NetInt`) to handle multiplayer sync. These types
|
|
|
|
can implicitly convert to their equivalent normal values (like `bool x = new NetBool()`), but their
|
|
|
|
conversion rules are unintuitive and error-prone. For example,
|
2018-04-10 07:32:00 +08:00
|
|
|
`item?.category == null && item?.category != null` can both be true at once, and
|
2018-04-15 08:33:43 +08:00
|
|
|
`building.indoors != null` can be true for a null value.
|
2018-04-10 07:32:00 +08:00
|
|
|
|
|
|
|
Suggested fix:
|
2018-04-11 06:23:39 +08:00
|
|
|
* Some net fields have an equivalent non-net property like `monster.Health` (`int`) instead of
|
2018-04-15 08:33:43 +08:00
|
|
|
`monster.health` (`NetInt`). The package will add a separate [AvoidNetField](#avoid-net-field) warning for
|
2018-04-11 06:23:39 +08:00
|
|
|
these. Use the suggested property instead.
|
2018-04-10 07:32:00 +08:00
|
|
|
* For a reference type (i.e. one that can contain `null`), you can use the `.Value` property:
|
|
|
|
```c#
|
|
|
|
if (building.indoors.Value == null)
|
|
|
|
```
|
|
|
|
Or convert the value before comparison:
|
|
|
|
```c#
|
|
|
|
GameLocation indoors = building.indoors;
|
|
|
|
if(indoors == null)
|
|
|
|
// ...
|
|
|
|
```
|
2018-04-11 06:23:39 +08:00
|
|
|
* For a value type (i.e. one that can't contain `null`), check if the object is null (if applicable)
|
|
|
|
and compare with `.Value`:
|
2018-04-10 07:32:00 +08:00
|
|
|
```cs
|
2018-04-11 06:23:39 +08:00
|
|
|
if (item != null && item.category.Value == 0)
|
2018-04-10 07:32:00 +08:00
|
|
|
```
|
|
|
|
|
2018-04-15 05:53:58 +08:00
|
|
|
### Avoid net field
|
|
|
|
Warning text:
|
2018-04-10 10:33:45 +08:00
|
|
|
> '{{expression}}' is a {{net type}} field; consider using the {{property name}} property instead.
|
|
|
|
|
2018-04-15 08:33:43 +08:00
|
|
|
Your code accesses a net field, which has some unusual behavior (see [AvoidImplicitNetFieldCast](#avoid-implicit-net-field-cast)).
|
|
|
|
This field has an equivalent non-net property that avoids those issues.
|
2018-04-10 10:33:45 +08:00
|
|
|
|
|
|
|
Suggested fix: access the suggested property name instead.
|
|
|
|
|
2018-04-15 05:53:58 +08:00
|
|
|
### Avoid obsolete field
|
|
|
|
Warning text:
|
2018-04-11 06:23:57 +08:00
|
|
|
> 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.
|
|
|
|
|
2021-03-31 08:10:55 +08:00
|
|
|
### 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'](https://docs.microsoft.com/en-ca/visualstudio/ide/how-to-configure-projects-to-target-platforms).
|
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
## 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.
|
2019-06-19 10:22:09 +08:00
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
To do that:
|
2019-06-19 10:22:09 +08:00
|
|
|
|
2020-09-06 02:55:40 +08:00
|
|
|
1. Get the full folder path containing the Stardew Valley executable.
|
2020-09-05 11:40:16 +08:00
|
|
|
2. See [_configure_](#configure) to add this property:
|
|
|
|
```xml
|
|
|
|
<PropertyGroup>
|
2019-06-19 10:22:09 +08:00
|
|
|
<GamePath>PATH_HERE</GamePath>
|
2020-09-05 11:40:16 +08:00
|
|
|
</PropertyGroup>
|
|
|
|
```
|
2021-05-13 08:57:23 +08:00
|
|
|
3. Replace `PATH_HERE` with your game's folder path (don't add quotes).
|
2019-06-19 10:22:09 +08:00
|
|
|
|
|
|
|
The configuration will check your custom path first, then fall back to the default paths (so it'll
|
|
|
|
still compile on a different computer).
|
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
### How do I change which files are included in the mod deploy/zip?
|
2021-09-17 10:47:05 +08:00
|
|
|
* For normal files, you can [add/remove them in the build output](https://stackoverflow.com/a/10828462/262123).
|
|
|
|
* For assembly files (`*.dll`, `*.exe`, `*.pdb`, or `*.xml`), see the
|
|
|
|
[`BundleExtraAssemblies` option](#configure).
|
|
|
|
* To exclude a file which the package copies by default, see the [`IgnoreModFilePaths` or
|
|
|
|
`IgnoreModFilePatterns` options](#configure).
|
2019-06-19 10:22:09 +08:00
|
|
|
|
2020-09-05 11:40:16 +08:00
|
|
|
### Can I use the package for non-mod projects?
|
2021-09-17 10:47:05 +08:00
|
|
|
Yep, this works in unit tests and framework projects too. Just disable the mod-related package
|
|
|
|
features (see [_configure_](#configure)):
|
2019-06-19 10:22:09 +08:00
|
|
|
|
|
|
|
```xml
|
2019-06-20 01:46:10 +08:00
|
|
|
<EnableGameDebugging>false</EnableGameDebugging>
|
|
|
|
<EnableModDeploy>false</EnableModDeploy>
|
|
|
|
<EnableModZip>false</EnableModZip>
|
2019-06-19 10:22:09 +08:00
|
|
|
```
|
|
|
|
|
2021-09-17 10:47:05 +08:00
|
|
|
To copy referenced DLLs into your build output for unit tests, add this too:
|
2019-06-19 10:22:09 +08:00
|
|
|
```xml
|
2021-09-17 10:47:05 +08:00
|
|
|
<BundleExtraAssemblies>All</BundleExtraAssemblies>
|
2019-06-19 10:22:09 +08:00
|
|
|
```
|
|
|
|
|
2019-07-06 12:35:51 +08:00
|
|
|
## 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.
|
|
|
|
|
2020-09-24 08:32:21 +08:00
|
|
|
The NuGet package is generated automatically in `StardewModdingAPI.ModBuildConfig`'s `bin` folder
|
|
|
|
when you compile it.
|
2019-07-06 12:35:51 +08:00
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
## Release notes
|
2023-01-10 01:27:29 +08:00
|
|
|
### 4.1.0
|
|
|
|
Released 08 January 2023.
|
|
|
|
|
2022-11-11 14:35:42 +08:00
|
|
|
* Added `manifest.json` format validation on build (thanks to tylergibbs2!).
|
2023-01-10 01:27:29 +08:00
|
|
|
* Fixed game DLLs not excluded from the release zip when they're referenced explicitly but `BundleExtraAssemblies` isn't set.
|
2022-11-11 14:35:42 +08:00
|
|
|
|
2022-10-10 07:42:24 +08:00
|
|
|
### 4.0.2
|
|
|
|
Released 09 October 2022.
|
|
|
|
|
2022-08-09 07:50:29 +08:00
|
|
|
* Switched to the newer crossplatform `portable` debug symbols (thanks to lanturnalis!).
|
2022-10-07 12:16:00 +08:00
|
|
|
* Fixed `BundleExtraAssemblies` option being partly case-sensitive.
|
|
|
|
* Fixed `BundleExtraAssemblies` not applying `All` value to game assemblies.
|
2022-08-09 07:50:29 +08:00
|
|
|
|
2022-05-24 02:33:01 +08:00
|
|
|
### 4.0.1
|
2022-04-15 07:21:18 +08:00
|
|
|
Released 14 April 2022.
|
|
|
|
|
2022-01-16 09:39:32 +08:00
|
|
|
* Added detection for Xbox app game folders.
|
2022-04-15 06:14:08 +08:00
|
|
|
* Fixed "_conflicts between different versions of Microsoft.Win32.Registry_" warnings in recent SMAPI versions.
|
2022-04-07 10:46:19 +08:00
|
|
|
* Internal refactoring.
|
2022-01-16 09:39:32 +08:00
|
|
|
|
2022-05-24 02:33:01 +08:00
|
|
|
### 4.0.0
|
2021-12-02 06:19:21 +08:00
|
|
|
Released 30 November 2021.
|
|
|
|
|
2021-09-17 10:47:05 +08:00
|
|
|
* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. (Older versions are no longer supported.)
|
2021-09-17 05:34:31 +08:00
|
|
|
* Added `IgnoreModFilePaths` option to ignore literal paths.
|
2021-09-17 10:47:05 +08:00
|
|
|
* Added `BundleExtraAssemblies` option to copy bundled DLLs into the mod zip/folder.
|
|
|
|
* Removed the `GameExecutableName` and `GameFramework` options (since they now have the same value
|
|
|
|
on all platforms).
|
|
|
|
* Removed the `CopyModReferencesToBuildOutput` option (superseded by `BundleExtraAssemblies`).
|
2021-08-08 12:32:19 +08:00
|
|
|
* Improved analyzer performance by enabling parallel execution.
|
|
|
|
|
2021-09-17 06:48:59 +08:00
|
|
|
**Migration guide for mod authors:**
|
|
|
|
1. See [_migrate to 64-bit_](https://stardewvalleywiki.com/Modding:Migrate_to_64-bit_on_Windows) and
|
|
|
|
[_migrate to Stardew Valley 1.5.5_](https://stardewvalleywiki.com/Modding:Migrate_to_Stardew_Valley_1.5.5).
|
|
|
|
2. Possible changes in your `.csproj` or `.targets` files:
|
2021-09-17 10:47:05 +08:00
|
|
|
* Replace `$(GameExecutableName)` with `Stardew Valley`.
|
|
|
|
* Replace `$(GameFramework)` with `MonoGame` and remove any XNA Framework-specific logic.
|
|
|
|
* Replace `<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>` with
|
|
|
|
`<BundleExtraAssemblies>Game</BundleExtraAssemblies>`.
|
|
|
|
* If you need to bundle extra DLLs besides your mod DLL, see the [`BundleExtraAssemblies`
|
|
|
|
documentation](#configure).
|
2021-09-17 06:48:59 +08:00
|
|
|
|
2022-05-24 02:33:01 +08:00
|
|
|
### 3.3.0
|
2021-03-31 08:11:49 +08:00
|
|
|
Released 30 March 2021.
|
|
|
|
|
2021-03-31 08:10:55 +08:00
|
|
|
* Added a build warning when the mod isn't compiled for `Any CPU`.
|
2021-09-17 06:48:59 +08:00
|
|
|
* Added a `GameFramework` build property set to `MonoGame` or `Xna` based on the platform. This can
|
|
|
|
be overridden to change which framework it references.
|
2021-03-31 08:10:55 +08:00
|
|
|
* Added support for building mods against the 64-bit Linux version of the game on Windows.
|
|
|
|
* The package now suppresses the misleading 'processor architecture mismatch' warnings.
|
|
|
|
|
2022-05-24 02:33:01 +08:00
|
|
|
### 3.2.2
|
2020-09-24 08:38:01 +08:00
|
|
|
Released 23 September 2020.
|
|
|
|
|
2020-09-24 08:32:21 +08:00
|
|
|
* Reworked and streamlined how the package is compiled.
|
2021-09-17 06:48:59 +08:00
|
|
|
* Added [SMAPI-ModTranslationClassBuilder](https://github.com/Pathoschild/SMAPI-ModTranslationClassBuilder)
|
|
|
|
files to the ignore list.
|
2020-09-24 08:32:21 +08:00
|
|
|
|
2020-09-12 05:38:04 +08:00
|
|
|
### 3.2.1
|
|
|
|
Released 11 September 2020.
|
2020-09-12 05:25:38 +08:00
|
|
|
|
|
|
|
* Added more detailed logging.
|
2020-09-12 05:36:02 +08:00
|
|
|
* Fixed _path's format is not supported_ error when using default `Mods` path in 3.2.
|
2020-09-12 05:25:38 +08:00
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 3.2.0
|
2020-09-07 08:59:19 +08:00
|
|
|
Released 07 September 2020.
|
|
|
|
|
2020-09-05 12:14:13 +08:00
|
|
|
* Added option to change `Mods` folder path.
|
2020-09-05 11:40:16 +08:00
|
|
|
* Rewrote documentation to make it easier to read.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 3.1.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 01 February 2020.
|
|
|
|
|
2020-02-02 00:09:21 +08:00
|
|
|
* Added support for semantic versioning 2.0.
|
2020-02-02 00:11:44 +08:00
|
|
|
* `0Harmony.dll` is now ignored if the mod references Harmony directly (it's bundled with SMAPI).
|
2020-02-02 00:09:21 +08:00
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 3.0.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 26 November 2019.
|
|
|
|
|
2019-06-18 06:52:19 +08:00
|
|
|
* Updated for SMAPI 3.0 and Stardew Valley 1.4.
|
2019-06-19 11:29:05 +08:00
|
|
|
* Added automatic support for `assets` folders.
|
|
|
|
* Added `$(GameExecutableName)` MSBuild variable.
|
2019-11-24 11:39:57 +08:00
|
|
|
* Added support for projects using the simplified `.csproj` format.
|
2019-06-19 11:29:05 +08:00
|
|
|
* Added option to disable game debugging config.
|
|
|
|
* Added `.pdb` files to builds by default (to enable line numbers in error stack traces).
|
2019-06-20 01:47:05 +08:00
|
|
|
* Added optional Harmony reference.
|
2019-03-30 13:32:54 +08:00
|
|
|
* Fixed `Newtonsoft.Json.pdb` included in release zips when Json.NET is referenced directly.
|
2019-06-14 06:19:27 +08:00
|
|
|
* Fixed `<IgnoreModFilePatterns>` not working for `i18n` files.
|
2019-04-25 12:50:26 +08:00
|
|
|
* Dropped support for older versions of SMAPI and Visual Studio.
|
2020-02-02 00:09:21 +08:00
|
|
|
* Migrated package icon to NuGet's new format.
|
2019-01-11 08:30:11 +08:00
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 2.2.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 28 October 2018.
|
|
|
|
|
2019-01-10 11:54:44 +08:00
|
|
|
* Added support for SMAPI 2.8+ (still compatible with earlier versions).
|
|
|
|
* Added default game paths for 32-bit Windows.
|
|
|
|
* Fixed valid manifests marked invalid in some cases.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 2.1.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 27 July 2018.
|
|
|
|
|
2018-03-26 00:01:19 +08:00
|
|
|
* Added support for Stardew Valley 1.3.
|
2019-01-10 11:54:44 +08:00
|
|
|
* Added support for non-mod projects.
|
2018-04-10 07:32:00 +08:00
|
|
|
* Added C# analyzers to warn about implicit conversions of Netcode fields in Stardew Valley 1.3.
|
2019-01-10 11:54:44 +08:00
|
|
|
* Added option to ignore files by regex pattern.
|
|
|
|
* Added reference to new SMAPI DLL.
|
|
|
|
* Fixed some game paths not detected by NuGet package.
|
2018-03-26 00:01:19 +08:00
|
|
|
|
|
|
|
### 2.0.2
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 01 November 2017.
|
|
|
|
|
2018-03-26 00:01:19 +08:00
|
|
|
* Fixed compatibility issue on Linux.
|
|
|
|
|
|
|
|
### 2.0.1
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 11 October 2017.
|
|
|
|
|
2018-03-26 00:01:19 +08:00
|
|
|
* Fixed mod deploy failing to create subfolders if they don't already exist.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 2.0.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 11 October 2017.
|
|
|
|
|
2017-10-09 06:05:47 +08:00
|
|
|
* Added: mods are now copied into the `Mods` folder automatically (configurable).
|
|
|
|
* Added: release zips are now created automatically in your build output folder (configurable).
|
2017-10-10 00:44:48 +08:00
|
|
|
* Added: mod deploy and release zips now exclude Json.NET automatically, since it's provided by SMAPI.
|
2017-10-09 01:04:36 +08:00
|
|
|
* Added mod's version to release zip filename.
|
2017-10-09 06:05:47 +08:00
|
|
|
* Improved errors to simplify troubleshooting.
|
2017-10-09 01:04:36 +08:00
|
|
|
* 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
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 28 July 2017.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* 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.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.7.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 28 July 2017.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* Added option to create release zips on build.
|
|
|
|
* Added reference to XNA's XACT library for audio-related mods.
|
|
|
|
|
2020-09-05 23:31:15 +08:00
|
|
|
### 1.6.2
|
|
|
|
Released 10 July 2017.
|
|
|
|
|
|
|
|
* Further improved crossplatform game path detection.
|
|
|
|
* Removed undocumented `GamePlatform` build property.
|
|
|
|
|
|
|
|
### 1.6.1
|
|
|
|
Released 09 July 2017.
|
|
|
|
|
|
|
|
* Improved crossplatform game path detection.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.6.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 05 June 2017.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* 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.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.5.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 23 January 2017.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* Added support for setting a custom game path globally.
|
2021-04-04 23:37:11 +08:00
|
|
|
* Added default GOG path on macOS.
|
2017-10-09 01:04:36 +08:00
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.4.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 11 January 2017.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* 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).
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.3.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 31 December 2016.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* Added support for non-default game paths on Windows.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.2.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 24 October 2016.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* Exclude game binaries from mod build output.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.1.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 21 October 2016.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* Added support for overriding the target platform.
|
|
|
|
|
2021-08-08 12:32:19 +08:00
|
|
|
### 1.0.0
|
2020-09-05 23:31:15 +08:00
|
|
|
Released 21 October 2016.
|
|
|
|
|
2017-10-09 01:04:36 +08:00
|
|
|
* 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.
|