diff options
95 files changed, 4519 insertions, 2707 deletions
@@ -1,11 +1,7 @@  -**SMAPI** is an [open-source](LICENSE) modding API for [Stardew Valley](http://stardewvalley.net/). -It takes care of loading mods into the game context, and exposes events they can use to interact -with the game. It's safely installed alongside the game's executable, and doesn't change any of -your game files. - ## Contents +* [What is SMAPI?](#what-is-smapi) * **[For players](#for-players)** * **[For mod developers](#for-mod-developers)** * [For SMAPI developers](#for-smapi-developers) @@ -16,6 +12,34 @@ your game files. * [Configuration file](#configuration-file) * [Command-line arguments](#command-line-arguments) +## What is SMAPI? +**SMAPI** is an [open-source](LICENSE) modding API for [Stardew Valley](http://stardewvalley.net/) +that lets you play the game with mods. It's safely installed alongside the game's executable, and +doesn't change any of your game files. It serves five main purposes: + +1. **Load mods into the game.** + _SMAPI loads mods when the game is starting up so they can interact with it. (Code mods aren't + possible without SMAPI to load them.)_ + +2. **Provide APIs and events for mods.** + _SMAPI provides low-level APIs and events which let mods interact with the game in ways they + otherwise couldn't._ + +3. **Rewrite mods for crossplatform compatibility.** + _SMAPI rewrites mods' compiled code before loading them so they work on Linux/Mac/Windows + without the mods needing to handle differences between the Linux/Mac and Windows versions of the + game._ + +4. **Rewrite mods to update them.** + _SMAPI detects when a mod accesses part of the game that changed in a recent update which + affects many mods, and rewrites the mod so it's compatible._ + +5. **Intercept errors.** + _SMAPI intercepts errors that happen in the game, displays the error details in the console + window, and in most cases automatically recovers the game. This prevents mods from accidentally + crashing the game, and makes it possible to troubleshoot errors in the game itself that would + otherwise show a generic 'program has stopped working' type of message._ + ## For players * [How to install SMAPI & use mods](http://canimod.com/guides/using-mods#installing-smapi) * [Release notes](release-notes.md#release-notes) @@ -26,7 +50,7 @@ your game files. * [How to develop mods](http://canimod.com/guides/creating-a-smapi-mod) * [How to update mods](http://canimod.com/guides/updating-a-smapi-mod) * [Release notes](release-notes.md#release-notes) -* [SMAPI/Farmhand Discord](https://discordapp.com/invite/0t3fh2xhHVc6Vdyx) (chat with SMAPI developers) +* [Chat on Discord](https://discord.gg/KCJHWhX) with SMAPI developers and other modders ## For SMAPI developers _This section is about compiling SMAPI itself from source. If you don't know what that means, this @@ -81,12 +105,10 @@ folder containing `src`). Mono/ Mods/* Mono.Cecil.dll - Mono.Cecil.Rocks.dll Newtonsoft.Json.dll StardewModdingAPI StardewModdingAPI.AssemblyRewriters.dll StardewModdingAPI.config.json - StardewModdingAPI.data.json StardewModdingAPI.exe StardewModdingAPI.exe.mdb steam_appid.txt @@ -95,11 +117,9 @@ folder containing `src`). Windows/ Mods/* Mono.Cecil.dll - Mono.Cecil.Rocks.dll Newtonsoft.Json.dll StardewModdingAPI.AssemblyRewriters.dll StardewModdingAPI.config.json - StardewModdingAPI.data.json StardewModdingAPI.exe StardewModdingAPI.pdb StardewModdingAPI.xml @@ -107,27 +127,28 @@ folder containing `src`). ``` 4. Open a terminal in the `SMAPI <version>` folder and run `chmod 755 internal/Mono/StardewModdingAPI`. 5. Copy & paste the `SMAPI <version>` folder as `SMAPI <version> for developers`. - 6. In the `SMAPI <version>` folder, delete the following files: - * `internal/Mono/StardewModdingAPI.config.json` - * `internal/Windows/StardewModdingAPI.config.json` - * `internal/Windows/StardewModdingAPI.xml` + 6. In the `SMAPI <version>` folder... + * edit `internal/Mono/StardewModdingAPI.config.json` and + `internal/Windows/StardewModdingAPI.config.json` to disable developer mode; + * delete `internal/Windows/StardewModdingAPI.xml`. 7. Compress the two folders into `SMAPI <version>.zip` and `SMAPI <version> for developers.zip`. ## Advanced usage ### Configuration file You can customise the SMAPI behaviour by editing the `StardewModdingAPI.config.json` file in your -game folder. If it's missing, it'll be generated automatically next time SMAPI runs. It contains -these fields: +game folder. It contains these fields: field | purpose ----- | ------- `DeveloperMode` | Default `false` (except in _SMAPI for developers_ releases). Whether to enable features intended for mod developers. Currently this only makes `TRACE`-level messages appear in the console. `CheckForUpdates` | Default `true`. Whether SMAPI should check for a newer version when you load the game. If a new version is available, a small message will appear in the console. This doesn't affect the load time even if your connection is offline or slow, because it happens in the background. +`ModCompatibility` | A list of mod versions SMAPI should consider compatible or broken regardless of whether it detects incompatible code. Each record can be set to `AssumeCompatible` or `AssumeBroken`. Changing this field is not recommended and may destabilise your game. ### Command-line arguments -SMAPI recognises the following command-line arguments. These are intended for internal use and may -change without warning. +SMAPI recognises the following command-line arguments. These are intended for internal use or +testing and may change without warning. argument | purpose -------- | ------- +`--log path "path"` | The relative or absolute path of the log file SMAPI should write. `--no-terminal` | SMAPI won't write anything to the console window. (Messages will still be written to the log file.) diff --git a/release-notes.md b/release-notes.md index 1ff868a4..a5ef4a0b 100644 --- a/release-notes.md +++ b/release-notes.md @@ -1,5 +1,62 @@ # Release notes +<!-- +## 2.0 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.10...2.0). + +For mod developers: +* Added `ContentEvents.AssetLoading` event with a helper which lets you intercept the XNB content + load, and dynamically adjust or replace the content being loaded (including support for patching + images). + +## 1.10 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.9...1.10). +* Updated for Stardew Valley 1.2. +* SMAPI now rewrites many mods for compatibility with game updates, but some mods will need an update. +--> + +## 1.9 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.8...1.9). + +For players: +* SMAPI now detects incompatible mods and disables them before they cause problems. +* SMAPI now allows mods nested into an otherwise empty parent folder (like `Mods\ModName-1.0\ModName\manifest.json`), since that's a common default behaviour when unpacking mods. +* The installer now detects if you need to update .NET Framework before installing SMAPI. +* The installer now detects if you need to run the game at least once (to let it perform first-time setup) |