From e40e8dd42bf547fd6f04543cef01b5d685c3ba56 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Fri, 4 Sep 2020 23:40:16 -0400 Subject: reorganize mod build package readme for readability --- docs/technical/mod-package.md | 382 ++++++++++++++++++++++++------------------ 1 file changed, 223 insertions(+), 159 deletions(-) (limited to 'docs') diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index e771d7a9..0f3afe9e 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -6,16 +6,12 @@ for SMAPI mods and related tools. The package is fully compatible with Linux, Ma ## Contents * [Use](#use) * [Features](#features) - * [Detect game path](#detect-game-path) - * [Add assembly references](#add-assembly-references) - * [Copy files into the `Mods` folder and create release zip](#copy-files-into-the-mods-folder-and-create-release-zip) - * [Launch or debug game](#launch-or-debug-game) - * [Preconfigure common settings](#preconfigure-common-settings) - * [Add code warnings](#add-code-warnings) +* [Configure](#configure) * [Code warnings](#code-warnings) -* [Special cases](#special-cases) - * [Custom game path](#custom-game-path) - * [Non-mod projects](#non-mod-projects) +* [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) * [For SMAPI developers](#for-smapi-developers) * [Release notes](#release-notes) @@ -27,133 +23,218 @@ for SMAPI mods and related tools. The package is fully compatible with Linux, Ma 5. Run the game to play with your mod. ## Features -The package automatically makes the changes listed below. In some cases you can configure how it -works by editing your mod's `.csproj` file, and adding the given properties between the first -`` and `` tags. - -### Detect game path -The package 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: - -property | description --------- | ----------- -`$(GamePath)` | The absolute path to the detected game folder. -`$(GameExecutableName)` | The game's executable name for the current OS (`Stardew Valley` on Windows, or `StardewValley` on Linux/Mac). - -If you get a build error saying it can't find your game, see [_custom game path_](#custom-game-path). - -### Add assembly references -The package adds assembly references to SMAPI, Stardew Valley, xTile, and MonoGame (Linux/Mac) or XNA -Framework (Windows). It automatically adjusts depending on which OS you're compiling it on. - -The assemblies aren't copied to the build output, since mods loaded by SMAPI won't need them. For -non-mod projects like unit tests, you can set this property: +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: + $(GamePath)` and `$(GameExecutableName)`. + +* **Add assembly references:** + The package adds assembly references to SMAPI, Stardew Valley, xTile, and MonoGame (Linux/Mac) or + XNA Framework (Windows). It automatically adjusts depending on which OS you're compiling it on. + If you use [Harmony](https://github.com/pardeike/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](https://stardewvalleywiki.com/Modding:Translations) (if any), the `assets` folder (if + any), and [build output](https://stackoverflow.com/a/10828462/262123) into your game's `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. + +* **Create 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. This includes the same files and + options 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](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). + + This is disabled on Linux/Mac 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 `.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_](#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: ```xml -true + + CustomModName + false + ``` -If your mod uses [Harmony](https://github.com/pardeike/Harmony) (not recommended for most mods), -the package can add a reference to SMAPI's Harmony DLL for you: -```xml -true -``` +There are two places you can put them: -### Copy files into the `Mods` folder and create release zip -
-
Files considered part of your mod
-
+* **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: -These files are selected by default: `manifest.json`, -[`i18n` files](https://stardewvalleywiki.com/Modding:Translations) (if any), the `assets` folder -(if any), and all files in the build output. You can select custom files by [adding them to the -build output](https://stackoverflow.com/a/10828462/262123). (If your project references another mod, -make sure the reference is [_not_ marked 'copy local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).) - -You can deselect a file by removing it from the build output. For a default file, you can set the -property below to a comma-delimited list of regex patterns to ignore. For crossplatform -compatibility, you should replace path delimiters with `[/\\]`. + 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), + [MacOS](https://www.cnet.com/how-to/how-to-find-your-macs-home-folder-and-add-it-to-finder/), + or [Windows](https://www.computerhope.com/issues/ch000109.htm)). + 2. Create a `stardewvalley.targets` file with this content: + ```xml + + + + + ``` + 3. Add the properties between the `` and ``. + +* **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 `` and `` tags you find. + +### Available properties +These are the options you can set: + +
    +
  • Game properties: + + + + + + + + + + + + + +
    propertyeffect
    GamePath + +The absolute path to the Stardew Valley folder. This is auto-detected, so you shouldn't need to +change it in most cases. + +
    GameExecutableName + +The name of the game's executable file (i.e. `StardewValley.exe` on Linux/Mac or +`Stardew Valley.exe` on Windows). This is auto-detected, and you should almost never change this. + +
    +
    • + +
  • Mod build properties: + + + + + + + + + + + + + + + + + + + + + + + + + +
    propertyeffect
    EnableHarmony + +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. + +
    ModFolderName + +The mod name for its folder under `Mods` and its release zip (defaults to the project name). + +
    EnableModDeploy + +Whether to copy the mod files into your game's `Mods` folder (default `true`). + +
    ModZipPath + +The folder path where the release zip is created (defaults to the project's `bin` folder). + +
    EnableModZip + +Whether to create a release-ready `.zip` file in the mod project's `bin` folder (default `true`). + +
    +
    • + +
  • Specialized properties: + + + + + + + + + + + + + + + + + +
    propertyeffect
    CopyModReferencesToBuildOutput + +Whether to copy game and framework DLLs into the mod folder (default `false`). This is useful for +unit test projects, but not needed for mods that'll be run through SMAPI. + +
    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: ```xml \.txt$, \.pdf$, assets[/\\]paths.png ``` - -
    Copy files into the `Mods` folder
    -
    - -The package copies the selected files into your game's `Mods` folder when you rebuild the code, -with a subfolder matching the mod's project name. - -You can change the folder name: -```xml -YourModName -``` - -Or disable deploying the files: -```xml -false -``` - -
    -
    Create release zip
    -
    - -The package adds a zip file in your project's `bin` folder when you rebuild the code, in the format -recommended for sites like Nexus Mods. The zip filename can be changed using `ModFolderName` above. - -You can change the folder path where the zip is created: -```xml -$(SolutionDir)\_releases -``` - -Or disable zip creation: -```xml -false -``` - -
    - - -### Launch or debug game -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). +
    EnableGameDebugging -This is disabled on Linux/Mac due to limitations with the Mono wrapper. +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. -To disable game debugging (only needed for some non-mod projects): - -```xml -false -``` - -### Preconfigure common settings -The package also automatically enables PDB files (so error logs show line numbers for simpler -debugging), and enables support for the simplified `.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_](#code-warnings) for more info. +
    +
    • +
## Code warnings ### Overview The NuGet package adds code warnings in Visual Studio specific to Stardew Valley. For example: ![](screenshots/code-analyzer-example.png) -You can hide the warnings using the warning ID (shown under 'code' in the Error List). See... -* [for specific code](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning); -* for a method using this attribute: - ```cs - [System.Diagnostics.CodeAnalysis.SuppressMessage("SMAPI.CommonErrors", "AvoidNetField")] - ``` -* for an entire project: - 1. Expand the _References_ node for the project in Visual Studio. - 2. Right-click on _Analyzers_ and choose _Open Active Rule Set_. - 4. Expand _StardewModdingAPI.ModBuildConfig.Analyzer_ and uncheck the warnings you want to hide. +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). -See below for help with each specific warning. +See below for help with specific warnings. ### Avoid implicit net field cast Warning text: @@ -202,57 +283,37 @@ Warning text: Your code accesses a field which is obsolete or no longer works. Use the suggested field instead. -## Special cases -### Custom game path -The package usually detects where your game is installed automatically. If it can't find your game -or you have multiple installs, you can specify the path yourself. There's two ways to do that: +## FAQs +### How do I set the game path? +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. -* **Option 1: global game path (recommended).** - _This will apply to every project that uses the package._ +To do that: - 1. Get the full folder path containing the Stardew Valley executable. - 2. Create this file: - - platform | path - --------- | ---- - Linux/Mac | `~/stardewvalley.targets` - Windows | `%USERPROFILE%\stardewvalley.targets` - - 3. Save the file with this content: - - ```xml - - - PATH_HERE - - - ``` - - 4. Replace `PATH_HERE` with your game's folder path. - -* **Option 2: path in the project file.** - _You'll need to do this for each 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 ` +1. Get the full path containing the Stardew Valley executable. +2. See [_configure_](#configure) to add this property: + ```xml + PATH_HERE - - ``` - - 3. Replace `PATH_HERE` with your custom game install path. + + ``` +3. Replace `PATH_HERE` with your game's folder 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). -You access the game path via `$(GamePath)` in MSBuild properties, if you need to reference another -file in the game folder. +### How do I change which files are included in the mod deploy/zip? +For custom files, you can [add/remove them in the build output](https://stackoverflow.com/a/10828462/262123). +(If your project references another mod, make sure the reference is [_not_ marked 'copy +local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).) + +To exclude a file the package copies by default, see `IgnoreModFilePatterns` under +[_configure_](#configure). -### Non-mod projects +### Can I use the package for non-mod projects? You can use the package in non-mod projects too (e.g. unit tests or framework DLLs). Just disable -the mod-related package features: +the mod-related package features (see [_configure_](#configure)): ```xml false @@ -287,6 +348,9 @@ That will create a `Pathoschild.Stardew.ModBuildConfig-.nupkg` file in which can be uploaded to NuGet or referenced directly. ## Release notes +### Upcoming release +* Rewrote documentation to make it easier to read. + ### 3.1 * Added support for semantic versioning 2.0. * `0Harmony.dll` is now ignored if the mod references Harmony directly (it's bundled with SMAPI). -- cgit