path: root/docs/release-notes.md

# Release notes
## 2.8 (upcoming)
* For players:
  * Added support for subfolders under `Mods`, for players who want to organise their mods.
  * Moved most SMAPI files into a `smapi-internal` subfolder.
  * Moved save backups into a `save-backups` subfolder (instead of `Mods/SaveBackup/backups`). Note that previous backups will be deleted when you update.
  * Update checks now work even when the mod has no update keys in most cases.
  * Fixed some game install paths not detected on Windows.
  * Fixed installer duplicating bundled mods if you moved them after the last install.
  * Fixed crash when a mod manifest is corrupted.
  * Fixed error-handling when initialising paths.
  * Updated compatibility list.

* For modders:
  * Added [data API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Data).
  * Added `IContentPack.WriteJsonFile` method.
  * Added IntelliSense documentation when not using the 'for developers' version of SMAPI.
  * Fixed `IContentPack.ReadJsonFile` allowing non-relative paths.
  * Suppressed the game's 'added crickets' debug output.
  * **Breaking change:** `helper.ModRegistry` now returns `IModInfo` instead of `IManifest` directly. This lets SMAPI return more metadata about mods in future versions.
  * **Breaking change:** most SMAPI files have been moved into a `smapi-internal` subfolder. This won't affect compiled mods, but you'll need to update the mod build config NuGet package when compiling mods.

* For SMAPI developers:
  * Added a 'paranoid warnings' option which reports mods using potentially sensitive .NET APIs (like file or shell access) in the mod issues list.
  * Adjusted `SaveBackup` mod to make it easier to account for custom mod subfolders in the installer.
  * Installer no longer special-cases Omegasis' older `SaveBackup` mod (now named `AdvancedSaveBackup`).

## 2.7
* For players:
  * Updated for Stardew Valley 1.3.28.
  * Improved how mod issues are listed in the console and log.
  * Revamped installer. It now...
    * uses a new format that should be more intuitive;
    * lets players on Linux/Mac choose the console color scheme (SMAPI will auto-detect it on Windows);
    * and validates requirements earlier.
  * Fixed custom festival maps always using spring tilesheets.
  * Fixed `player_add` command not recognising return scepter.
  * Fixed `player_add` command showing fish twice.
  * Fixed some SMAPI logs not deleted when starting a new session.
  * Updated compatibility list.

* For modders:
  * Added support for `.json` data files in the content API (including Content Patcher).
  * Added propagation for asset changes through the content API for...
    * child sprites;
    * dialogue;
    * map tilesheets.
  * Added `--mods-path` CLI command-line argument to switch between mod folders.
  * All enums are now JSON-serialised by name instead of numeric value. (Previously only a few enums were serialised that way. JSON files which already have numeric enum values will still be parsed fine.)
  * Fixed false compatibility error when constructing multidimensional arrays.
  * Fixed `.ToSButton()` methods not being public.

* For SMAPI developers:
  * Dropped support for pre-SMAPI-2.6 update checks in the web API.  
    _These are no longer useful, even if the player still has earlier versions of SMAPI. Older versions of SMAPI won't launch in Stardew Valley 1.3 (so they won't check for updates), and newer versions of SMAPI/mods won't work with older versions of the game._

## 2.6
* For players:
  * Updated for Stardew Valley 1.3.
  * Added automatic save backups.
  * Improved update checks:
    * added beta update channel;
    * added update alerts for incompatible mods with an unofficial update on the wiki;
    * added update alerts for optional files on Nexus;
    * added console warning for mods which don't have update checks configured;
    * added more visible prompt in beta channel for SMAPI updates;
    * fixed mod update checks failing if a mod only has prerelease versions on GitHub;
    * fixed Nexus mod update alerts not showing HTTPS links.
  * Improved mod warnings in the console.
  * Improved error when game can't start audio.
  * Improved the Console Commands mod:
    * Added `player_add name`, which adds items to your inventory by name instead of ID.
    * Fixed `world_setseason` not running season-change logic.
    * Fixed `world_setseason` not normalising the season value.
    * Fixed `world_settime` sometimes breaking NPC schedules (e.g. so they stay in bed).
    * Removed the `player_setlevel` and `player_setspeed` commands, which weren't implemented in a useful way. Use a mod like CJB Cheats Menu if you need those.
  * Fixed `SEHException` errors for some players.
  * Fixed performance issues for some players.
  * Fixed default color scheme on Mac or in PowerShell (configurable via `StardewModdingAPI.config.json`).
  * Fixed installer error on Linux/Mac in some cases.
  * Fixed installer not finding some game paths or showing duplicate paths.
  * Fixed installer not removing some SMAPI files.
  * Fixed launch issue for Linux players with some terminals. (Thanks to HanFox and kurumushi!)
  * Fixed abort-retry loop if a mod crashed when intercepting assets during startup.
  * Fixed some mods failing if the player name is blank.
  * Fixed errors when a mod references a missing assembly.
  * Fixed `AssemblyResolutionException` errors in rare cases.
  * Renamed `install.exe` to `install on Windows.exe` to avoid confusion.
  * Updated compatibility list.

* For the web UI:
  * Added option to download SMAPI from Nexus.
  * Added log parser redesign that should be more intuitive.
  * Added log parser option to view raw log.
  * Changed log parser filters to show `DEBUG` messages by default.
  * Fixed design on smaller screens.
  * Fixed log parser issue when content packs have no description.
  * Fixed log parser mangling crossplatform paths in some cases.
  * Fixed `smapi.io/install` not linking to a useful page.

* For modders:
  * Added [input API](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Input) for reading and suppressing keyboard, controller, and mouse input.
  * Added code analysis in the NuGet package to flag common issues as warnings.
  * Replaced `LocationEvents` to support multiplayer:
    * now raised for all locations;
    * now includes added/removed building interiors;
    * each event now provides a list of added/removed values;
    * added buildings-changed event.
  * Added `Context.IsMultiplayer` and `Context.IsMainPlayer` flags.
  * Added `Constants.TargetPlatform` which says whether the game is running on Linux, Mac, or Windows.
  * Added `semanticVersion.IsPrerelease()` method.
  * Added support for launching multiple instances transparently. This removes the former `--log-path` command-line argument.
  * Added support for custom seasonal tilesheets when loading an unpacked `.tbin` map.
  * Added Harmony DLL for internal use by SMAPI. (Mods should still include their own copy for backwards compatibility, and in case it's removed later. SMAPI will always load its own version though.)
  * Added option to suppress update checks for a specific mod in `StardewModdingAPI.config.json`.
  * Added absolute pixels to `ICursorPosition`.
  * Added support for reading/writing `ISemanticVersion` to JSON.
  * Added support for reloading NPC schedules through the content API.
  * Reimplemented the content API so it works more reliably in many edge cases.
  * Reimplemented input suppression to work more consistently in many cases.
  * The order of update keys now affects which URL players see in update alerts.
  * Fixed assets loaded by temporary content managers not being editable by mods.
  * Fixed assets not reloaded consistently when the player switches language.
  * Fixed error if a mod loads a PNG while the game is loading (e.g. custom map tilesheets via `IAssetLoader`).
  * Fixed error if a mod translation file is empty.
  * Fixed input suppression not working consistently for clicks.
  * Fixed console input not saved to the log.
  * Fixed `Context.IsPlayerFree` being false during festivals.
  * Fixed `helper.ModRegistry.GetApi` errors not always mentioning which interface caused the issue.
  * Fixed console commands being invoked asynchronously.
  * Fixed mods able to intercept other mods' assets via the internal asset keys.
  * Fixed mods able to indirectly change other mods' data through shared content caches.
  * Fixed `SemanticVersion` allowing invalid versions in some cases.
  * **Breaking changes** (see [migration guide](https://stardewvalleywiki.com/Modding:Migrate_to_Stardew_Valley_1.3)):
     * Dropped some deprecated APIs.
     * `LocationEvents` have been rewritten.
     * Mods can't intercept chatbox input.
     * Mod IDs should only contain letters, numbers, hyphens, dots, and underscores. That allows their use in many contexts like URLs. This restriction is now enforced. (In regex form: `^[a-zA-Z0-9_.-]+$`.)

* For SMAPI developers:
  * Added more consistent crossplatform handling, including MacOS detection.
  * Added beta update channel.
  * Added optional mod metadata to the web API (including Nexus info, wiki metadata, etc).
  * Added early prototype of SMAPI 3.0 events via `helper.Events`.
  * Added early prototype of mod handler toolkit.
  * Added Harmony for SMAPI's internal use.
  * Added metadata dump option in `StardewModdingAPI.config.json` for troubleshooting some cases.
  * Added more stylish pufferchick on the home page.
  * Rewrote update checks:
    * Moved most logic into the web API.
    * Changed web API to require mod IDs.
    * Changed web API to also fetch metadata from SMAPI's internal mod DB and the wiki.
  * Rewrote world/player state tracking. The new implementation is much more efficient than previous method, uses net field events where available, and lays the groundwork for more advanced events in SMAPI 3.0.
  * Split mod DB out of `StardewModdingAPI.config.json` into its own file.
  * Updated to Mono.Cecil 0.10.

## 2.5.5
* For players:
  * Fixed mod not loaded if it has an optional dependency that's loaded but skipped.
  * Fixed mod update alerts not shown if one mod has an invalid remote version.
  * Fixed SMAPI update alerts linking to the GitHub repository instead of [smapi.io](https://smapi.io).
  * Fixed SMAPI update alerts for draft releases.
  * Fixed error when two content packs use different capitalisation for the same required mod ID.
  * Fixed rare crash if the game duplicates an item.

* For the [log parser][]:
  * Tweaked UI.

## 2.5.4
* For players:
  * Fixed some textures not updated when a mod changes them.
  * Fixed visual bug on Linux/Mac when mods overlay textures.
  * Fixed error when mods remove an asset editor/loader.
  * Fixed minimum game version incorrectly increased in SMAPI 2.5.3.

* For the [log parser][]:
  * Fixed error when log text contains certain tokens.

* For modders:
  * Updated to Json.NET 11.0.2.

* For SMAPI developers:
  * Added support for beta update track to support upcoming Stardew Valley 1.3 beta.

## 2.5.3
* For players:
  * Simplified and improved skipped-mod messages.
  * Fixed rare crash with some combinations of manifest fields and internal mod data.
  * Fixed update checks failing for Nexus Mods due to a change in their API.
  * Fixed update checks failing for some older mods with non-standard versions.
  * Fixed failed update checks being cached for an hour (now cached 5 minutes).
  * Fixed error when a content pack needs a mod that couldn't be loaded.
  * Fixed Linux ["magic number is wrong" errors](https://github.com/mono/mono/issues/6752) by changing default terminal order.
  * Updated compatibility list and added update checks for more mods.

* For the [log parser][]:
  * Fixed incorrect filtering in some cases.
  * Fixed error if mods have duplicate names.
  * Fixed parse bugs if a mod has no author name.

* For SMAPI developers:
  * Internal changes to support the upcoming Stardew Valley 1.3 update.

## 2.5.2
* For modders:
  * Fixed issue where replacing an asset through `asset.AsImage()` or `asset.AsDictionary()` didn't take effect.

* For the [log parser][]:
  * Fixed blank page after uploading a log in some cases.

## 2.5.1
* For players:
  * Fixed event error in rare cases.

## 2.5
* For players:
  * **Added support for [content packs](https://stardewvalleywiki.com/Modding:Content_packs)**.  
    <small>_Content packs are collections of files for a SMAPI mod to load. These can be installed directly under `Mods` like a normal SMAPI mod, get automatic update and compatibility checks, and provide convenient APIs to the mods that read them._</small>
  * Added mod detection for unhandled errors (so most errors now mention which mod caused them).
  * Added install scripts for Linux/Mac (no more manual terminal commands!).
  * Added the missing mod's name and URL to dependency errors.
  * Fixed uninstall script not reporting when done on Linux/Mac.
  * Updated compatibility list and enabled update checks for more mods.

* For modders:
  * Added support for content packs and new APIs to read them.
  * Added support for `ISemanticVersion` in JSON models.
  * Added `SpecialisedEvents.UnvalidatedUpdateTick` event for specialised use cases.
  * Added path normalising to `ReadJsonFile` and `WriteJsonFile` helpers (so no longer need `Path.Combine` with those).
  *