From 5161ceae5285a1fb66e66ba9bedf36d371516193 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 8 Oct 2017 13:15:20 -0400 Subject: [PATCH] rewrite mod build package docs for proposed changes --- docs/mod-build-config.md | 112 +++++++++++++++++++++------------------ 1 file changed, 59 insertions(+), 53 deletions(-) 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: +## 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. -1. Edit your mod's `.csproj` file. -2. Add this block above the first `` line: +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).) - ```xml - $(MSBuildProjectName) - ``` +You can change the mod's folder name by adding this above the first `` in your +`.csproj`: +```xml +YourModName +``` -That's it! Each time you build, the files in `\Mods\` will be updated with -your `manifest.json`, build output, and any `i18n` files. +If you don't want to deploy the mod automatically, you can add this: +```xml +False +``` -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). +### 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. -### 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: +You can change the zipped folder name (and zip name) by adding this above the first +`` in your `.csproj`: +```xml +YourModName +``` -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. +You can change the folder path where the zip is created like this: +```xml +$(SolutionDir)\_releases +``` -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. +Finally, you can disable the zip creation with this: +```xml +False +``` -### Create release zips automatically (Windows-only) -You can create the mod package automatically when you build: +### 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: -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._ +* **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 `