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) before installing SMAPI. +* The installer on Linux now finds games installed to `~/.steam/steam/steamapps/common/Stardew Valley` too. +* The installer now removes old SMAPI logs to prevent confusion. +* The console now has simpler error messages. +* The console now has improved command handling & feedback. +* The console no longer shows the game's debug output (unless you use a _SMAPI for developers_ build). +* Fixed the game-needs-an-update error not pausing before exit. +* Fixed installer errors for some players when deleting files. +* Fixed installer not ignoring potential game folders that don't contain a Stardew Valley exe. +* Fixed installer not recognising Linux/Mac paths starting with `~/` or containing an escaped space. +* Fixed TrainerMod letting you add invalid items which may crash the game. +* Fixed TrainerMod's `world_downminelevel` command not working. +* Fixed rare issue where mod dependencies would override SMAPI dependencies and cause unpredictable bugs. +* Fixed errors in mods' console command handlers crashing the game. + +For mod developers: +* Added a simpler API for console commands (see `helper.ConsoleCommands`). +* Added `TimeEvents.AfterDayStarted` event triggered when a day starts. This happens no matter how the day started (including new game, loaded save, or player went to bed). +* Added `ContentEvents.AfterLocaleChanged` event triggered when the player changes the content language (for the upcoming Stardew Valley 1.2). +* Added `SaveEvents.AfterReturnToTitle` event triggered when the player returns to the title screen (for the upcoming Stardew Valley 1.2). +* Added `helper.Reflection.GetPrivateProperty` method. +* Added a `--log-path` argument to specify the SMAPI log path during testing. +* SMAPI now writes XNA input enums (`Buttons` and `Keys`) to JSON as strings automatically, so mods no longer need to add a `StringEnumConverter` themselves for those. +* The SMAPI log now has a simpler filename. +* The SMAPI log now shows the OS caption (like "Windows 10") instead of its internal version when available. +* The SMAPI log now always uses `\r\n` line endings to simplify crossplatform viewing. +* Fixed `SaveEvents.AfterLoad` being raised during the new-game intro before the player is initialised. +* Fixed SMAPI not recognising `Mod` instances that don't subclass `Mod` directly. +* Several obsolete APIs have been removed (see [deprecation guide](http://canimod.com/guides/updating-a-smapi-mod)), + and all _notice_-level deprecations have been increased to _info_. +* Removed the experimental `IConfigFile`. + +For SMAPI developers: +* Added support for debugging SMAPI on Linux/Mac if supported by the editor. + ## 1.8 See [log](https://github.com/Pathoschild/SMAPI/compare/1.7...1.8). diff --git a/src/StardewModdingAPI.AssemblyRewriters/Finders/EventFinder.cs b/src/StardewModdingAPI.AssemblyRewriters/Finders/EventFinder.cs new file mode 100644 index 00000000..c0051469 --- /dev/null +++ b/src/StardewModdingAPI.AssemblyRewriters/Finders/EventFinder.cs @@ -0,0 +1,83 @@ +using Mono.Cecil; +using Mono.Cecil.Cil; + +namespace StardewModdingAPI.AssemblyRewriters.Finders +{ + /// <summary>Finds incompatible CIL instructions that reference a given event and throws an <see cref="IncompatibleInstructionException"/>.</summary> + public class EventFinder : IInstructionRewriter + { + /********* + ** Properties + *********/ + /// <summary>The full type name for which to find references.</summary> + private readonly string FullTypeName; + + /// <summary>The event name for which to find references.</summary> |