From 49f414bec51b99fda2d2a77117dc9ca0447217b4 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 8 Oct 2017 02:37:41 -0400 Subject: move mod build config readme into docs --- docs/mod-build-config.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/mod-build-config.md (limited to 'docs/mod-build-config.md') diff --git a/docs/mod-build-config.md b/docs/mod-build-config.md new file mode 100644 index 00000000..c261e705 --- /dev/null +++ b/docs/mod-build-config.md @@ -0,0 +1,121 @@ +**Stardew.ModBuildConfig** is an open-source NuGet package which automates the build configuration +for [Stardew Valley](http://stardewvalley.net/) [SMAPI](https://github.com/Pathoschild/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](#install) +* [Simplify mod development](#simplify-mod-development) +* [Troubleshoot](#troubleshoot) +* [Versions](#versions) + +## Install +**When creating a new mod:** + +1. Create an empty library project. +2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig). +3. [Write your code](http://canimod.com/guides/creating-a-smapi-mod). +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](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig). +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 `` line: + + ```xml + $(MSBuildProjectName) + ``` + +That's it! Each time you build, the files in `\Mods\` 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](https://stackoverflow.com/a/10828462/262123). +* 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'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx). + +### 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](#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 `` line: + + ```xml + $(SolutionDir)\_releases + ``` + +That's it! Each time you build, the mod files will be zipped into `_releases\.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: + + ```xml + + + PATH_HERE + + + ``` + + 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 ` + PATH_HERE + + ``` + + 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). + +## Versions +See [release notes](release-notes.md). -- cgit From fd060a092786d703817fa5a65452b4efe52db8cd Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 8 Oct 2017 13:04:36 -0400 Subject: move release notes into mod build package docs --- docs/mod-build-config.md | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) (limited to 'docs/mod-build-config.md') diff --git a/docs/mod-build-config.md b/docs/mod-build-config.md index c261e705..f76a69ad 100644 --- a/docs/mod-build-config.md +++ b/docs/mod-build-config.md @@ -13,7 +13,7 @@ The package... * [Install](#install) * [Simplify mod development](#simplify-mod-development) * [Troubleshoot](#troubleshoot) -* [Versions](#versions) +* [Release notes](#release-notes) ## Install **When creating a new mod:** @@ -117,5 +117,46 @@ the game location yourself. There's two ways to do that: The configuration will check your custom path first, then fall back to the default paths (so it'll still compile on a different computer). -## Versions -See [release notes](release-notes.md). +## 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. -- cgit From 5161ceae5285a1fb66e66ba9bedf36d371516193 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 8 Oct 2017 13:15:20 -0400 Subject: rewrite mod build package docs for proposed changes --- docs/mod-build-config.md | 130 +++++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 62 deletions(-) (limited to 'docs/mod-build-config.md') diff --git a/docs/mod-build-config.md b/docs/mod-build-config.md index f76a69ad..b091c2c0 100644 --- a/docs/mod-build-config.md +++ b/docs/mod-build-config.md @@ -1,17 +1,17 @@ -**Stardew.ModBuildConfig** is an open-source NuGet package which automates the build configuration -for [Stardew Valley](http://stardewvalley.net/) [SMAPI](https://github.com/Pathoschild/SMAPI) mods. +The **mod build package** is an open-source NuGet package which automates the MSBuild configuration +for 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. +* lets your code compile on any computer (Linux/Mac/Windows) without needing to change the assembly + references or game path. +* packages the mod into the game's `Mods` folder when you rebuild the code (configurable). * 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](#install) -* [Simplify mod development](#simplify-mod-development) +* [Configure](#configure) * [Troubleshoot](#troubleshoot) * [Release notes](#release-notes) @@ -20,7 +20,7 @@ The package... 1. Create an empty library project. 2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig). -3. [Write your code](http://canimod.com/guides/creating-a-smapi-mod). +3. [Write your code](https://stardewvalleywiki.com/Modding:Creating_a_SMAPI_mod). 4. Compile on any platform. **When migrating an existing mod:** @@ -30,59 +30,56 @@ The package... 2. Reference the [`Pathoschild.Stardew.ModBuildConfig` NuGet package](https://www.nuget.org/packages/Pathoschild.Stardew.ModBuildConfig). 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 `` line: - - ```xml - $(MSBuildProjectName) - ``` - -That's it! Each time you build, the files in `\Mods\` 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](https://stackoverflow.com/a/10828462/262123). -* 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'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx). - -### 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](#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 `` line: - - ```xml - $(SolutionDir)\_releases - ``` - -That's it! Each time you build, the mod files will be zipped into `_releases\.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._ +## Configure +### Deploy files into the `Mods` folder +By default, your mod will be copied into the game's `Mods` folder (with a subfolder matching your +project name) when you rebuild the code. The package will automatically include your +`manifest.json`, any `i18n` files, and the build output. + +To add custom files to the mod folder, just [add 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 change the mod's folder name by adding this above the first `` in your +`.csproj`: +```xml +YourModName +``` + +If you don't want to deploy the mod automatically, you can add this: +```xml +False +``` + +### Create release zip +By default, a zip file will be created in the build output when you rebuild the code. This zip file +contains all the files needed to share your mod in the recommended format for uploading to Nexus +Mods or other sites. + +You can change the zipped folder name (and zip name) by adding this above the first +`` in your `.csproj`: +```xml +YourModName +``` + +You can change the folder path where the zip is created like this: +```xml +$(SolutionDir)\_releases +``` + +Finally, you can disable the zip creation with this: +```xml +False +``` + +### 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: + +* **Option 1: global game path (recommended).** + _This will apply to every project that uses the package._ 1. Get the full folder path containing the Stardew Valley executable. - 2. Create this file path: + 2. Create this file: platform | path --------- | ---- @@ -99,10 +96,11 @@ the game location yourself. There's two ways to do that: ``` - 4. Replace `PATH_HERE` with your custom game install path. + 4. Replace `PATH_HERE` with your game path. + +* **Option 2: path in the project file.** + _You'll need to do this for each project that uses the package._ -* **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 ` Date: Sun, 8 Oct 2017 18:05:47 -0400 Subject: rewrite mod build package per new docs --- docs/mod-build-config.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs/mod-build-config.md') diff --git a/docs/mod-build-config.md b/docs/mod-build-config.md index b091c2c0..f02981b9 100644 --- a/docs/mod-build-config.md +++ b/docs/mod-build-config.md @@ -71,6 +71,11 @@ Finally, you can disable the zip creation with this: False ``` +Or only create it in release builds with this: +```xml +False +``` + ### 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: @@ -118,14 +123,15 @@ still compile on a different computer). ## Troubleshoot ### "Failed to find the game install path" -That error means the package couldn't find your game. You need to specify the game path yourself; -see _[Game path](#game-path)_ above. +That error means the package couldn't find your game. You can specify the game path yourself; see +_[Game path](#game-path)_ above. ## Release notes ### 2.0 -* Mods are now copied into the `Mods` folder automatically (configurable). -* The release zip is now created automatically in your build output folder (configurable). +* Added: mods are now copied into the `Mods` folder automatically (configurable). +* Added: release zips are now created automatically in your build output folder (configurable). * Added mod's version to release zip filename. +* Improved errors to simplify troubleshooting. * Fixed release zip not having a mod folder. * Fixed release zip failing if mod name contains characters that aren't valid in a filename. -- cgit From c456a0f56ed0fba55042c167afa83c9922a5db33 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Mon, 9 Oct 2017 12:44:48 -0400 Subject: don't include Json.NET in mod deploy or release zip since it's loaded by SMAPI --- docs/mod-build-config.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/mod-build-config.md') diff --git a/docs/mod-build-config.md b/docs/mod-build-config.md index f02981b9..ca750c86 100644 --- a/docs/mod-build-config.md +++ b/docs/mod-build-config.md @@ -130,6 +130,7 @@ _[Game path](#game-path)_ above. ### 2.0 * Added: mods are now copied into the `Mods` folder automatically (configurable). * Added: release zips are now created automatically in your build output folder (configurable). +* Added: mod deploy and release zips now exclude Json.NET automatically, since it's provided by SMAPI. * Added mod's version to release zip filename. * Improved errors to simplify troubleshooting. * Fixed release zip not having a mod folder. -- cgit