diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CONTRIBUTING.md | 17 | ||||
| -rw-r--r-- | docs/LICENSE.md | 165 | ||||
| -rw-r--r-- | docs/README.md | 36 | ||||
| -rw-r--r-- | docs/imgs/SMAPI.png | bin | 252371 -> 0 bytes | |||
| -rw-r--r-- | docs/release-notes.md | 471 | ||||
| -rw-r--r-- | docs/technical-docs.md | 137 |
6 files changed, 826 insertions, 0 deletions
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..52d47a4b --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,17 @@ +Do you want to... + +* **Ask for help using SMAPI?** + Please post a message in the [SMAPI support thread](http://community.playstarbound.com/threads/108375), + don't create a GitHub issue. + +* **Report a bug?** + Please post a message in the [SMAPI support thread](http://community.playstarbound.com/threads/108375) + instead, unless you're sure it's a bug in SMAPI itself. + +* **Submit a pull request?** + Pull requests are welcome! If you're submitting a new feature, it's best to discuss first to make + sure it'll be accepted. Feel free to come chat in [#modding on Discord](https://discord.gg/kH55QXP) + or post in the [SMAPI support thread](http://community.playstarbound.com/threads/108375). + + Documenting your code and using the same formatting conventions is appreciated, but don't worry too + much about it. We'll fix up the code after we accept the pull request if needed. diff --git a/docs/LICENSE.md b/docs/LICENSE.md new file mode 100644 index 00000000..02bbb60b --- /dev/null +++ b/docs/LICENSE.md @@ -0,0 +1,165 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + + This version of the GNU Lesser General Public License incorporates +the terms and conditions of version 3 of the GNU General Public +License, supplemented by the additional permissions listed below. + + 0. Additional Definitions. + + As used herein, "this License" refers to version 3 of the GNU Lesser +General Public License, and the "GNU GPL" refers to version 3 of the GNU +General Public License. + + "The Library" refers to a covered work governed by this License, +other than an Application or a Combined Work as defined below. + + An "Application" is any work that makes use of an interface provided +by the Library, but which is not otherwise based on the Library. +Defining a subclass of a class defined by the Library is deemed a mode +of using an interface provided by the Library. + + A "Combined Work" is a work produced by combining or linking an +Application with the Library. The particular version of the Library +with which the Combined Work was made is also called the "Linked +Version". + + The "Minimal Corresponding Source" for a Combined Work means the +Corresponding Source for the Combined Work, excluding any source code +for portions of the Combined Work that, considered in isolation, are +based on the Application, and not on the Linked Version. + + The "Corresponding Application Code" for a Combined Work means the +object code and/or source code for the Application, including any data +and utility programs needed for reproducing the Combined Work from the +Application, but excluding the System Libraries of the Combined Work. + + 1. Exception to Section 3 of the GNU GPL. + + You may convey a covered work under sections 3 and 4 of this License +without being bound by section 3 of the GNU GPL. + + 2. Conveying Modified Versions. + + If you modify a copy of the Library, and, in your modifications, a +facility refers to a function or data to be supplied by an Application +that uses the facility (other than as an argument passed when the +facility is invoked), then you may convey a copy of the modified +version: + + a) under this License, provided that you make a good faith effort to + ensure that, in the event an Application does not supply the + function or data, the facility still operates, and performs + whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of + this License applicable to that copy. + + 3. Object Code Incorporating Material from Library Header Files. + + The object code form of an Application may incorporate material from +a header file that is part of the Library. You may convey such object +code under terms of your choice, provided that, if the incorporated +material is not limited to numerical parameters, data structure +layouts and accessors, or small macros, inline functions and templates +(ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the + Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license + document. + + 4. Combined Works. + + You may convey a Combined Work under terms of your choice that, +taken together, effectively do not restrict modification of the +portions of the Library contained in the Combined Work and reverse +engineering for debugging such modifications, if you also do each of +the following: + + a) Give prominent notice with each copy of the Combined Work that + the Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license + document. + + c) For a Combined Work that displays copyright notices during + execution, include the copyright notice for the Library among + these notices, as well as a reference directing the user to the + copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this + License, and the Corresponding Application Code in a form + suitable for, and under terms that permit, the user to + recombine or relink the Application with a modified version of + the Linked Version to produce a modified Combined Work, in the + manner specified by section 6 of the GNU GPL for conveying + Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (a) uses at run time + a copy of the Library already present on the user's computer + system, and (b) will operate properly with a modified version + of the Library that is interface-compatible with the Linked + Version. + + e) Provide Installation Information, but only if you would otherwise + be required to provide such information under section 6 of the + GNU GPL, and only to the extent that such information is + necessary to install and execute a modified version of the + Combined Work produced by recombining or relinking the + Application with a modified version of the Linked Version. (If + you use option 4d0, the Installation Information must accompany + the Minimal Corresponding Source and Corresponding Application + Code. If you use option 4d1, you must provide the Installation + Information in the manner specified by section 6 of the GNU GPL + for conveying Corresponding Source.) + + 5. Combined Libraries. + + You may place library facilities that are a work based on the +Library side by side in a single library together with other library +facilities that are not Applications and are not covered by this +License, and convey such a combined library under terms of your +choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities, + conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it + is a work based on the Library, and explaining where to find the + accompanying uncombined form of the same work. + + 6. Revised Versions of the GNU Lesser General Public License. + + The Free Software Foundation may publish revised and/or new versions +of the GNU Lesser General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the +Library as you received it specifies that a certain numbered version +of the GNU Lesser General Public License "or any later version" +applies to it, you have the option of following the terms and +conditions either of that published version or of any later version +published by the Free Software Foundation. If the Library as you +received it does not specify a version number of the GNU Lesser +General Public License, you may choose any version of the GNU Lesser +General Public License ever published by the Free Software Foundation. + + If the Library as you received it specifies that a proxy can decide +whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is +permanent authorization for you to choose that version for the +Library.
\ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..92a39dbe --- /dev/null +++ b/docs/README.md @@ -0,0 +1,36 @@ +**SMAPI** is an [open-source](LICENSE.md) 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 six 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._ + +6. **Provide update checks.** + _SMAPI automatically checks for new versions of your installed mods, and notifies you when any + are available._ + +## Documentation +* [For players & mod creators](http://stardewvalleywiki.com/Modding:Index) +* [Release notes](release-notes.md) +* [Technical docs](technical-docs.md) +* [Chat on Discord](https://discord.gg/KCJHWhX) with SMAPI developers and other modders diff --git a/docs/imgs/SMAPI.png b/docs/imgs/SMAPI.png Binary files differdeleted file mode 100644 index 50f375b6..00000000 --- a/docs/imgs/SMAPI.png +++ /dev/null diff --git a/docs/release-notes.md b/docs/release-notes.md new file mode 100644 index 00000000..5b102df3 --- /dev/null +++ b/docs/release-notes.md @@ -0,0 +1,471 @@ +# Release notes +## 2.0 (upcoming) +<!--See [log](https://github.com/Pathoschild/SMAPI/compare/1.10...2.0).--> + +For players: +* SMAPI now alerts you when mods have new versions available. +* SMAPI now warns you about mods which may impact game stability or compatibility. +* The console is now simpler and easier to read, and adjusts its colors to fit your terminal background color. +* Renamed installer folder to avoid confusion. +* Updated compatibility list. +* Fixed update check errors on Linux/Mac. +* Fixed collection-changed errors during startup for some players. + +For mod developers: +* Added support for editing, injecting, and reloading XNB data loaded by the game at any time. + <small>_This let SMAPI mods do anything previously only possible with XNB mods, and enables new mod scenarios not possible with XNB mods (e.g. seasonal textures, NPC clothing that depend on the weather or location, etc)._</small> +* Added support for automatic mod update checks. + <small>_Add your Chucklefish, GitHub, or Nexus mod ID to the manifest and SMAPI will check for updates automatically. SMAPI will retroactively enable updates for most existing mods._</small> +* Added unified input events. + <small>_The new `InputEvents` combine keyboard + mouse + controller input into one event and constant for easy handling, add metadata like the cursor position and grab tile to support click handling._</small> +* Added support for suppressing input. + <small>_You can prevent the game from receiving input via `InputEvents`, to enable new scenarios like action highjacking and UI overlays._</small> +* Added support for optional dependencies. +* Added support for specifying the mod version as a string (like `"1.0-alpha"`) in `manifest.json`. +* Added day of week to `SDate` instances. +* Added `IEquatable<ISemanticVersion>` to `ISemanticVersion`. +* Removed the TrainerMod's `save` and `load` commands. +* Removed all deprecated code. +* Removed support for mods with no `Name`, `Version`, or `UniqueID` in their manifest. +* Removed support for mods with a non-unique `UniqueID` value in their manifest. +* Removed access to SMAPI internals through the reflection helper, to discourage fragile mods. +* Fixed `TimeEvents.AfterDayStarted` being raised during the new-game intro. + +For power users: +* Added command-line arguments to the SMAPI installer so it can be scripted. + +For SMAPI developers: +* Significantly refactored SMAPI to support changes in 2.0 and upcoming releases. +* Overhauled `StardewModdingAPI.config.json` format to support mod data like update keys. +* Removed SMAPI 1._x_ compatibility mode. + +## 1.15.4 +For players: +* Fixed errors when loading some custom maps on Linux/Mac or using XNB Loader. +* Fixed errors in rare cases when a mod calculates an in-game date. + +For modders: +* Added UTC timestamp to log file. + +For SMAPI developers: +* Internal changes to support the upcoming SMAPI 2.0 release. + +## 1.15.3 +For players: +* Fixed mods being wrongly marked as duplicate in some cases. + +## 1.15.2 +For players: +* Improved errors when a mod DLL can't be loaded. +* Improved errors when using very old versions of Stardew Valley. +* Updated compatibility list. + +For mod developers: +* Added `Context.CanPlayerMove` property for mod convenience. +* Added content helper properties for the game's current language. +* Fixed `Context.IsPlayerFree` being false if the player is performing an action. +* Fixed `GraphicsEvents.Resize` being raised before the game updates its window data. +* Fixed `SemanticVersion` not being deserialisable through Json.NET. +* Fixed terminal not launching on Xfce Linux. + +For SMAPI developers: +* Internal changes to support the upcoming SMAPI 2.0 release. + +## 1.15.1 +For players: +* Fixed controller mod input broken in 1.15. +* Fixed TrainerMod packaging unneeded files. + +For modders: +* Fixed mod registry lookups by unique ID not being case-insensitive. + +## 1.15 +For players: +* Cleaned up SMAPI console a bit. +* Revamped TrainerMod's item commands: + * `player_add` is a new command to add any item to your inventory (including tools, weapons, equipment, craftables, wallpaper, etc). This replaces the former `player_additem`, `player_addring`, and `player_addweapon`. + * `list_items` now shows all items in the game. You can search by item type like `list_items weapon`, or search by item name like `list_items galaxy sword`. + * `list_items` now also matches translated item names when playing in another language. + * `list_item_types` is a new command to see a list of item types. +* Fixed unhelpful error when a `config.json` is invalid. +* Fixed rare crash when window loses focus for a few players (further to fix in 1.14). +* Fixed invalid `ObjectInformation.xnb` causing a flood of warnings; SMAPI now shows one error instead. +* Updated mod compatibility list. + +For modders: +* Added `SDate` utility for in-game date calculations (see [API reference](http://stardewvalleywiki.com/Modding:SMAPI_APIs#Dates)). +* Added support for minimum dependency versions in `manifest.json` (see [API reference](http://stardewvalleywiki.com/Modding:SMAPI_APIs#Manifest)). +* Added more useful logging when loading mods. +* Added a `ModID` property to all mod helpers for extension methods. +* Changed `manifest.MinimumApiVersion` from string to `ISemanticVersion`. This shouldn't affect mods unless they referenced that field in code. +* Fixed `SemanticVersion` parsing some invalid versions into close approximations (like `1.apple` → `1.0-apple`). +* Fixed `SemanticVersion` not treating hyphens as separators when comparing prerelease tags. + <small>_(While that was technically correct, it leads to unintuitive behaviour like sorting `-alpha-2` _after_ `-alpha-10`, even though `-alpha.2` sorts before `-alpha.10`.)_</small> +* Fixed corrupted state exceptions not being logged by SMAPI. +* Increased all deprecations to _pending removal_. + +For SMAPI developers: +* Added SMAPI 2.0 compile mode, for testing how mods will work with SMAPI 2.0. +* Added prototype SMAPI 2.0 feature to override XNB files (not enabled for mods yet). +* Added prototype SMAPI 2.0 support for version strings in `manifest.json` (not recommended for mods yet). +* Compiling SMAPI now uses your `~/stardewvalley.targets` file if present. + +## 1.14 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.13...1.14). + +For players: +* SMAPI now shows friendly errors when... + * it can't detect the game; + * a mod dependency is missing (if it's listed in the mod manifest); + * you have Stardew Valley 1.11 or earlier (which aren't compatible); + * you run `install.exe` from within the downloaded zip file. +* Fixed "unknown mod" deprecation warnings by improving how SMAPI detects the mod using the event. +* Fixed `libgdiplus.dylib` errors for some players on Mac. +* Fixed rare crash when window loses focus for a few players. +* Bumped minimum game version to 1.2.30. +* Updated mod compatibility list. + +For modders: +* You can now add dependencies to `manifest.json` (see [API reference](http://stardewvalleywiki.com/Modding:SMAPI_APIs#Manifest)). +* You can now translate your mod (see [API reference](http://stardewvalleywiki.com/Modding:SMAPI_APIs#Translation)). +* You can now load unpacked `.tbin` files from your mod folder through the content API. +* SMAPI now automatically fixes tilesheet references for maps loaded from the mod folder. + <small>_When loading a map from the mod folder, SMAPI will automatically use tilesheets relative to the map file if they exists. Otherwise it will default to tilesheets in the game content._</small> +* Added `Context.IsPlayerFree` for mods that need to check if the player can act (i.e. save is loaded, no menu is displayed, no cutscene is in progress, etc). +* Added `Context.IsInDrawLoop` for specialised mods. +* Fixed `smapi-crash.txt` being copied from the default log even if a different path is specified with `--log-path`. +* Fixed the content API not matching XNB filenames with two dots (like `a.b.xnb`) if you don't specify the `.xnb` extension. +* Fixed `debug` command output not printed to console. +* Deprecated `TimeEvents.DayOfMonthChanged`, `SeasonOfYearChanged`, and `YearOfGameChanged`. These don't do what most modders think they do and aren't very reliable, since they depend on the SMAPI/game lifecycle which can change. You should use `TimeEvents.AfterDayStarted` or `SaveEvents.BeforeSave` instead. + +## 1.13.1 +For players: +* Fixed errors when loading a mod with no name or version. +* Fixed mods with no manifest `Name` field having no name (SMAPI will now shows their filename). + +## 1.13 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.12...1.13). + +For players: +* SMAPI now recovers better from mod draw errors and detects when the error is irrecoverable. +* SMAPI now recovers automatically from errors in the game loop when possible. +* SMAPI now remembers if your game crashed and offers help next time you launch it. +* Fixed installer sometimes finding redundant game paths. +* Fixed save events not being raised after the first day on Linux/Mac. +* Fixed error on Linux/Mac when a mod loads a PNG immediately after the save is loaded. +* Updated mod compatibility list for Stardew Valley 1.2. + +For mod developers: +* Added a `Context.IsWorldReady` flag for mods to use. + <small>_This indicates whether a save is loaded and the world is finished initialising, which starts at the same point that `SaveEvents.AfterLoad` and `TimeEvents.AfterDayStarted` are raised. This is mainly useful for events which can be raised before the world is loaded (like update tick)._</small> +* Added a `debug` console command which lets you run the game's debug commands (e.g. `debug warp FarmHouse 1 1` warps you to the farmhouse). +* Added basic context info to logs to simplify troubleshooting. +* Added a `Mod.Dispose` method which can be overriden to clean up before exit. This method isn't guaranteed to be called on every exit. +* Deprecated mods that don't have a `Name`, `Version`, or `UniqueID` in their manifest. These will be required in SMAPI 2.0. +* Deprecated `GameEvents.GameLoaded` and `GameEvents.FirstUpdateTick`. You can move any affected code into your mod's `Entry` method. +* Fixed maps not recognising custom tilesheets added through the SMAPI content API. +* Internal refactoring for upcoming features. + +## 1.12 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.11...1.12). + +For players: +* The installer now lets you choose the install path if you have multiple copies of the game, instead of using the first path found. +* Fixed mod draw errors breaking the game. +* Fixed mods on Linux/Mac no longer working after the game saves. +* Fixed `libgdiplus.dylib` errors on Mac when mods read PNG files. +* Adopted pufferchick. + +For mod developers: +* Unknown mod manifest fields are now stored in `IManifest::ExtraFields`. +* The content API now defaults to `ContentSource.ModFolder`. +* Fixed content API error when loading a PNG during early game init (e.g. in mod's `Entry`). +* Fixed content API error when loading an XNB from the mod folder on Mac. + +## 1.11 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.10...1.11). + +For players: +* SMAPI now detects issues in `ObjectInformation.xnb` files caused by outdated XNB mods. +* Errors when loading a save are now shown in the SMAPI console. +* Improved console logging performance. +* Fixed errors during game update causing the game to hang. +* Fixed errors due to mod events triggering during game save in Stardew Valley 1.2. + +For mod developers: +* Added a content API which loads custom textures/maps/data from the mod's folder (`.xnb` or `.png` format) or game content. +* `Console.Out` messages are now written to the log file. +* `Monitor.ExitGameImmediately` now aborts SMAPI initialisation and events more quickly. +* Fixed value-changed events being raised when the player loads a save due to values being initialised. + +## 1.10 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.9...1.10). + +For players: +* Updated to Stardew Valley 1.2. +* Added logic to rewrite many mods for compatibility with game updates, though some mods may still need an update. +* Fixed `SEHException` errors affecting some players. +* Fixed issue where SMAPI didn't unlock some files on exit. +* Fixed rare issue where the installer would crash trying to delete a bundled mod from `%appdata%`. +* Improved TrainerMod commands: + * Added `world_setyear` to change the current year. + * Replaced `player_addmelee` with `player_addweapon` with support for non-melee weapons. + +For mod developers: +* Mods are now initialised after the `Initialize`/`LoadContent` phase, which means the `GameEvents.Initialize` and `GameEvents.LoadContent` events are deprecated. You can move any logic in those methods to your mod's `Entry` method. +* Added `IsBetween` and string overloads to the `ISemanticVersion` methods. +* Fixed mouse-changed event never updating prior mouse position. +* Fixed `monitor.ExitGameImmediately` not working correctly. +* Fixed `Constants.SaveFolderName` not set for a new game until the save is created. + +## 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). + +For players: +* Mods no longer generate `.cache` subfolders. +* Fixed multiple issues where mods failed during assembly loading. +* Tweaked install package to reduce confusion. + +For mod developers: +* The `SemanticVersion` constructor now accepts a string version. +* Increased deprecation level for `Extensions` to _pending removal_. +* **Warning:** `Assembly.GetExecutingAssembly().Location` will no longer reliably + return a valid path, because mod assemblies are loaded from memory when rewritten for + compatibility. This approach has been discouraged since SMAPI 1.3; use `helper.DirectoryPath` + instead. + +For SMAPI developers: +* Rewrote assembly loading from the ground up. The new implementation... + * is much simpler; + * eliminates the `.cache` folders by loading rewritten assemblies from memory; + * ensures DLLs are loaded in leaf-to-root order (i.e. dependencies first); + * improves dependent assembly resolution; + * no longer loads DLLs if they're not referenced; + * reduces log verbosity. + +## 1.7 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.6...1.7). + +For players: +* The console now shows the folder path where mods should be added. +* The console now shows deprecation warnings after the list of loaded mods (instead of intermingled). + +For mod developers: +* Added a mod registry which provides metadata about loaded mods. +* The `Entry(…)` method is now deferred until all mods are loaded. +* Fixed `SaveEvents.BeforeSave` and `.AfterSave` not triggering on days when the player shipped something. +* Fixed `PlayerEvents.LoadedGame` and `SaveEvents.AfterLoad` being fired before the world finishes initialising. +* Fixed some `LocationEvents`, `PlayerEvents`, and `TimeEvents` being fired during game startup. +* Increased deprecation levels for `SObject`, `LogWriter` (not `Log`), and `Mod.Entry(ModHelper)` (not `Mod.Entry(IModHelper)`) to _pending removal_. Increased deprecation levels for `Mod.PerSaveConfigFolder`, `Mod.PerSaveConfigPath`, and `Version.VersionString` to _info_. + +## 1.6 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.5...1.6). + +For players: +* Added console commands to open the game/data folders. +* Updated list of incompatible mods. +* Fixed `config.json` values being duplicated in some cases. +* Fixed some Linux users not being able to launch SMAPI from Steam. +* Fixed the installer not finding custom install paths on 32-bit Windows. +* Fixed error when loading a mod which was released with a `.cache` folder for a different platform. +* Fixed error when the console doesn't support colour. +* Fixed error when a mod reads a custom JSON file from a directory that doesn't exist. + +For mod developers: +* Added three events: `SaveEvents.BeforeSave`, `SaveEvents.AfterSave`, and `SaveEvents.AfterLoad`. +* Deprecated three events: + * `TimeEvents.OnNewDay` is unreliable; use `TimeEvents.DayOfMonthChanged` or `SaveEvents` instead. + * `PlayerEvents.LoadedGame` is replaced by `SaveEvents.AfterLoad`. + * `PlayerEvents.FarmerChanged` serves no purpose. + +For SMAPI developers: + * Added support for specifying a lower bound in mod incompatibility data. + * Added support for custom incompatible-mod error text. + * Fixed issue where `TrainerMod` used older logic to detect the game path. + +## 1.5 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.4...1.5). + +For players: + * Added an option to disable update checks. + * SMAPI will now show a friendly error with update links when you try to use a known incompatible mod version. + * Fixed an error when a mod uses the new reflection API on a missing field or method. + * Fixed an issue where mods weren't notified of a menu change if it changed while SMAPI was still notifying mods of the previous change. + +For developers: + * Deprecated `Version` in favour of `SemanticVersion`. + _This new implementation is [semver 2.0](http://semver.org/)-compliant, introduces `NewerThan(version)` and `OlderThan(version)` convenience methods, adds support for parsing a version string into a `SemanticVersion`, and fixes various bugs with the former implementation. This also replaces `Manifest` with `IManifest`._ + * Increased deprecation levels for `SObject`, `Extensions`, `LogWriter` (not `Log`), `SPlayer`, and `Mod.Entry(ModHelper)` (not `Mod.Entry(IModHelper)`). + +## 1.4 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.3...1.4). + +For players: + * SMAPI will now prevent mods from crashing your game with menu errors. + * The installer will now automatically detect most custom install paths. + * The installer will now automatically clean up old SMAPI files. + * Each mod now has its own `.cache` folder, so removing the mod won't leave orphaned cache files behind. + * Improved installer wording to reduce confusion. + * Fixed the installer not removing TrainerMod from appdata if it's already in the game mods directory. + * Fixed the installer not moving mods out of appdata if the game isn't installed on the same Windows partition. + * Fixed the SMAPI console not being shown on Linux and Mac. + +For developers: + * Added a reflection API (via `helper.Reflection`) that simplifies robust access to the game's private fields and methods. + * Added a searchable `list_items` console command to replace the `out_items`, `out_melee`, and `out_rings` commands. + * Added `TypeLoadException` details when intercepted by SMAPI. + * Fixed an issue where you couldn't debug into an assembly because it was copied into the `.cache` directory. That will now only happen if necessary. + +## 1.3 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.2...1.3). + +For players: + * You can now run most mods on any platform (e.g. run Windows mods on Linux/Mac). + * Fixed the normal uninstaller not removing files added by the 'SMAPI for developers' installer. + +## 1.2 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.1.1...1.2). + +For players: + * Fixed compatibility with some older mods. + * Fixed mod errors in most event handlers crashing the game. + * Fixed mod errors in some event handlers preventing other mods from receiving the same event. + * Fixed game crashing on startup with an audio error for some players. + +For developers: + * Improved logging to show `ReflectionTypeLoadException` details when it's caught by SMAPI. + +## 1.1 +See [log](https://github.com/Pathoschild/SMAPI/compare/1.0...1.1.1). + +For players: + * Fixed console exiting immediately when some exceptions occur. + * Fixed an error in 1.0 when mod uses `config.json` but the file doesn't exist. + * Fixed critical errors being saved to a separate log file. + * Fixed compatibility with some older mods.<sup>1.1.1</sup> + * Fixed race condition where some mods would sometimes crash because the game wasn't ready yet.<sup>1.1.1</sup> + +For developers: + * Added new logging interface: + * easier to use; + * supports trace logs (written to the log file, but hidden in the console by default); + * messages are now listed in order; + * messages now show which mod logged them; + * more consistent and intuitive console color scheme. + * Added optional `MinimumApiVersion` to `manifest.json`. + * Added emergency interrupt feature for dangerous mods. + * Fixed deprecation warnings being repeated if the mod can't be identified.<sup>1.1.1</sup> + +## 1.0 +See [log](https://github.com/Pathoschild/SMAPI/compare/0.40.1.1-3...1.0). + +For players: + * Added support for Linux and Mac. + * Added installer to automate adding & removing SMAPI. + * Added background update check on launch. + * Fixed missing `steam_appid.txt` file. + * Fixed some mod UIs disappearing at a non-default zoom level for some users. + * Removed undocumented support for mods in AppData folder **(breaking change)**. + * Removed `F2` debug mode. + +For mod developers: + * Added deprecation warnings. + * Added OS version to log. + * Added zoom-adjusted mouse position to mouse-changed event arguments. + * Added SMAPI code documentation. + * Switched to [semantic versioning](http://semver.org). + * Fixed mod versions not shown correctly in the log. + * Fixed misspelled field in `manifest.json` schema. + * Fixed some events getting wrong data. + * Simplified log output. + +For SMAPI developers: + * Simplified compiling from source. + * Formalised release process and added automated build packaging. + * Removed obsolete and unfinished code. + * Internal cleanup & refactoring. + +## 0.x +* 0.40.1.1 (2016-09-30, [log](https://github.com/Pathoschild/SMAPI/compare/0.40.0...0.40.1.1-3)) + * Added support for Stardew Valley 1.1. + +* 0.40.0 (2016-04-05, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.7...0.40.0)) + * Fixed an error that ocurred during minigames. + +* 0.39.7 (2016-04-04, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.6...0.39.7)) + * Added 'no check' graphics events that are triggered regardless of game's if checks. + +* 0.39.6 (2016-04-01, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.5...0.39.6)) + * Added game & SMAPI versions to log. + * Fixed conflict in graphics tick events. + * Bug fixes. + +* 0.39.5 (2016-03-30, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.4...0.39.5)) +* 0.39.4 (2016-03-29, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.3...0.39.4)) +* 0.39.3 (2016-03-28, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.2...0.39.3)) +* 0.39.2 (2016-03-23, [log](https://github.com/Pathoschild/SMAPI/compare/0.39.1...0.39.2)) +* 0.39.1 (2016-03-23, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.8...0.39.1)) +* 0.38.8 (2016-03-23, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.7...0.38.8)) +* 0.38.7 (2016-03-23, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.6...0.38.7)) +* 0.38.6 (2016-03-22, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.5...0.38.6)) +* 0.38.5 (2016-03-22, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.4...0.38.5)) +* 0.38.4 (2016-03-21, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.3...0.38.4)) +* 0.38.3 (2016-03-21, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.2...0.38.3)) +* 0.38.2 (2016-03-21, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.0...0.38.2)) +* 0.38.0 (2016-03-20, [log](https://github.com/Pathoschild/SMAPI/compare/0.38.1...0.38.0)) +* 0.38.1 (2016-03-20, [log](https://github.com/Pathoschild/SMAPI/compare/0.37.3...0.38.1)) +* 0.37.3 (2016-03-08, [log](https://github.com/Pathoschild/SMAPI/compare/0.37.2...0.37.3)) +* 0.37.2 (2016-03-07, [log](https://github.com/Pathoschild/SMAPI/compare/0.37.1...0.37.2)) +* 0.37.1 (2016-03-06, [log](https://github.com/Pathoschild/SMAPI/compare/0.36...0.37.1)) +* 0.36 (2016-03-04, [log](https://github.com/Pathoschild/SMAPI/compare/0.37...0.36)) +* 0.37 (2016-03-04, [log](https://github.com/Pathoschild/SMAPI/compare/0.35...0.37)) +* 0.35 (2016-03-02, [log](https://github.com/Pathoschild/SMAPI/compare/0.34...0.35)) +* 0.34 (2016-03-02, [log](https://github.com/Pathoschild/SMAPI/compare/0.33...0.34)) +* 0.33 (2016-03-02, [log](https://github.com/Pathoschild/SMAPI/compare/0.32...0.33)) +* 0.32 (2016-03-02, [log](https://github.com/Pathoschild/SMAPI/compare/0.31...0.32)) +* 0.31 (2016-03-02, [log](https://github.com/Pathoschild/SMAPI/compare/0.3...0.31)) +* 0.3 (2016-03-01, [log](https://github.com/Pathoschild/SMAPI/compare/Alpha0.2...0.3)) +* 0.2 (2016-02-29, [log](https://github.com/Pathoschild/SMAPI/compare/Alpha0.1...Alpha0.2) +* 0.1 (2016-02-28) diff --git a/docs/technical-docs.md b/docs/technical-docs.md new file mode 100644 index 00000000..d37d327d --- /dev/null +++ b/docs/technical-docs.md @@ -0,0 +1,137 @@ +← [README](README.md) + +This file provides more technical documentation about SMAPI. If you only want to use or create +mods, this section isn't relevant to you; see the main README to use or create mods. + +## Contents +* [Development](#development) + * [Compiling from source](#compiling-from-source) + * [Debugging a local build](#debugging-a-local-build) + * [Preparing a release](#preparing-a-release) +* [Customisation](#customisation) + * [Configuration file](#configuration-file) + * [Command-line arguments](#command-line-arguments) + * [Compile flags](#compile-flags) + +## Development +### Compiling from source +Using an official SMAPI release is recommended for most users. + +SMAPI uses some C# 7 code, so you'll need at least +[Visual Studio 2017](https://www.visualstudio.com/vs/community/) on Windows, +[MonoDevelop 7.0](http://www.monodevelop.com/) on Linux, +[Visual Studio 2017 for Mac](https://www.visualstudio.com/vs/visual-studio-mac/), or an equivalent +IDE to compile it. It uses build configuration derived from the +[crossplatform mod config](https://github.com/Pathoschild/Stardew.ModBuildConfig#readme) to detect +your current OS automatically and load the correct references. Compile output will be placed in a +`bin` folder at the root of the git repository. + +### Debugging a local build +Rebuilding the solution in debug mode will copy the SMAPI files into your game folder. Starting +the `StardewModdingAPI` project with debugging from Visual Studio (on Mac or Windows) will launch +SMAPI with the debugger attached, so you can intercept errors and step through the code being +executed. This doesn't work in MonoDevelop on Linux, unfortunately. + +### Preparing a release +To prepare a crossplatform SMAPI release, you'll need to compile it on two platforms. See +[crossplatforming info](http://stardewvalleywiki.com/Modding:Creating_a_SMAPI_mod#Test_on_all_platforms) +on the wiki for the first-time setup. + +1. Update the version number in `GlobalAssemblyInfo.cs` and `Constants::Version`. Make sure you use a + [semantic version](http://semver.org). Recommended format: + + build type | format | example + :--------- | :-------------------------------- | :------ + dev build | `<version>-alpha.<timestamp>` | `2.0-alpha.20171230` + prerelease | `<version>-prerelease.<ID>` | `2.0-prerelease.2` + release | `<version>` | `2.0` + +2. In Windows: + 1. Rebuild the solution in _Release_ mode. + 2. Rename `bin/Packaged` to `SMAPI <version>` (e.g. `SMAPI 2.0`). + 2. Transfer the `SMAPI <version>` folder to Linux or Mac. + _This adds the installer executable and Windows files. We'll do the rest in Linux or Mac, + since we need to set Unix file permissions that Windows won't save._ + +2. In Linux or Mac: + 1. Rebuild the solution in _Release_ mode. + 2. Copy `bin/internal/Packaged/Mono` into the `SMAPI <version>` folder. + 3. If you did everything right so far, you should have a folder like this: + + ``` + SMAPI-2.x/ + install.exe + readme.txt + internal/ + Mono/ + Mods/* + Mono.Cecil.dll + Newtonsoft.Json.dll + StardewModdingAPI + StardewModdingAPI.AssemblyRewriters.dll + StardewModdingAPI.config.json + StardewModdingAPI.exe + StardewModdingAPI.pdb + StardewModdingAPI.xml + steam_appid.txt + System.Numerics.dll + System.Runtime.Caching.dll + System.ValueTuple.dll + Windows/ + Mods/* + Mono.Cecil.dll + Newtonsoft.Json.dll + StardewModdingAPI.AssemblyRewriters.dll + StardewModdingAPI.config.json + StardewModdingAPI.exe + StardewModdingAPI.pdb + StardewModdingAPI.xml + System.ValueTuple.dll + steam_appid.txt + ``` + 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... + * 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`. + +## Customisation +### Configuration file +You can customise the SMAPI behaviour by editing the `StardewModdingAPI.config.json` file in your +game folder. + +Basic fields: + +field | purpose +----------------- | ------- +`DeveloperMode` | Default `false` (except in _SMAPI for developers_ releases). Whether to enable features intended for mod developers (mainly more detailed console logging). +`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. +`VerboseLogging` | Default `false`. Whether SMAPI should log more information about the game context. +`ModData` | Internal metadata about SMAPI mods. Changing this isn't recommended and may destabilise your game. See documentation in the file. + +### Command-line arguments +The SMAPI installer recognises three command-line arguments: + +argument | purpose +-------- | ------- +`--install` | Preselects the install action, skipping the prompt asking what the user wants to do. +`--uninstall` | Preselects the uninstall action, skipping the prompt asking what the user wants to do. +`--game-path "path"` | Specifies the full path to the folder containing the Stardew Valley executable, skipping automatic detection and any prompt to choose a path. If the path is not valid, the installer displays an error. + +SMAPI itself recognises two arguments, but 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.) + +### Compile flags +SMAPI uses a small number of conditional compilation constants, which you can set by editing the +`<DefineConstants>` element in `StardewModdingAPI.csproj`. Supported constants: + +flag | purpose +---- | ------- +`SMAPI_FOR_WINDOWS` | Indicates that SMAPI is being compiled on Windows for players on Windows. Set automatically in `crossplatform.targets`. |
