Merge branch 'develop' into stable

80 files changed, 993 insertions, 255 deletions

diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs
index b71c6195..6a1cd188 100644
--- a/src/SMAPI/Constants.cs
+++ b/src/SMAPI/Constants.cs
@@ -29,7 +29,7 @@ namespace StardewModdingAPI
         ** Public
         ****/
         /// <summary>SMAPI's current semantic version.</summary>
-        public static ISemanticVersion ApiVersion { get; } = new Toolkit.SemanticVersion("2.8.2");
+        public static ISemanticVersion ApiVersion { get; } = new Toolkit.SemanticVersion("2.9.0");
 
         /// <summary>The minimum supported version of Stardew Valley.</summary>
         public static ISemanticVersion MinimumGameVersion { get; } = new GameVersion("1.3.32");
@@ -91,9 +91,12 @@ namespace StardewModdingAPI
         /// <summary>The file path which stores the detected update version for the next run.</summary>
         internal static string UpdateMarker => Path.Combine(Constants.InternalFilesPath, "StardewModdingAPI.update.marker");
 
-        /// <summary>The full path to the folder containing mods.</summary>
+        /// <summary>The default full path to search for mods.</summary>
         internal static string DefaultModsPath { get; } = Path.Combine(Constants.ExecutionPath, "Mods");
 
+        /// <summary>The actual full path to search for mods.</summary>
+        internal static string ModsPath { get; set; }
+
         /// <summary>The game's current semantic version.</summary>
         internal static ISemanticVersion GameVersion { get; } = new GameVersion(Constants.GetGameVersion());
 
diff --git a/src/SMAPI/Context.cs b/src/SMAPI/Context.cs
index c7aed81d..cd1cf1c2 100644
--- a/src/SMAPI/Context.cs
+++ b/src/SMAPI/Context.cs
@@ -22,7 +22,7 @@ namespace StardewModdingAPI
         /// <summary>Whether <see cref="IsPlayerFree"/> is true and the player is free to move (e.g. not using a tool).</summary>
         public static bool CanPlayerMove => Context.IsPlayerFree && Game1.player.CanMove;
 
-        /// <summary>Whether the game is currently running the draw loop. This isn't relevant to most mods, since you should use <see cref="GraphicsEvents.OnPostRenderEvent"/> to draw to the screen.</summary>
+        /// <summary>Whether the game is currently running the draw loop. This isn't relevant to most mods, since you should use <see cref="IDisplayEvents"/> events to draw to the screen.</summary>
         public static bool IsInDrawLoop { get; internal set; }
 
         /// <summary>Whether <see cref="IsWorldReady"/> and the player loaded the save in multiplayer mode (regardless of whether any other players are connected).</summary>
diff --git a/src/SMAPI/Events/BuildingListChangedEventArgs.cs b/src/SMAPI/Events/BuildingListChangedEventArgs.cs
index 9bc691fc..0237342f 100644
--- a/src/SMAPI/Events/BuildingListChangedEventArgs.cs
+++ b/src/SMAPI/Events/BuildingListChangedEventArgs.cs
@@ -29,7 +29,7 @@ namespace StardewModdingAPI.Events
         /// <param name="location">The location which changed.</param>
         /// <param name="added">The buildings added to the location.</param>
         /// <param name="removed">The buildings removed from the location.</param>
-        public BuildingListChangedEventArgs(GameLocation location, IEnumerable<Building> added, IEnumerable<Building> removed)
+        internal BuildingListChangedEventArgs(GameLocation location, IEnumerable<Building> added, IEnumerable<Building> removed)
         {
             this.Location = location;
             this.Added = added.ToArray();
diff --git a/src/SMAPI/Events/ContentEvents.cs b/src/SMAPI/Events/ContentEvents.cs
index 3ee0560b..99369cae 100644
--- a/src/SMAPI/Events/ContentEvents.cs
+++ b/src/SMAPI/Events/ContentEvents.cs
@@ -1,9 +1,12 @@
+#if !SMAPI_3_0_STRICT
 using System;
+using StardewModdingAPI.Framework;
 using StardewModdingAPI.Framework.Events;
 
 namespace StardewModdingAPI.Events
 {
     /// <summary>Events raised when the game loads content.</summary>
+    [Obsolete("Use " + nameof(Mod.Helper) + "." + nameof(IModHelper.Events) + " instead. See https://smapi.io/3.0 for more info.")]
     public static class ContentEvents
     {
         /*********
@@ -12,6 +15,9 @@ namespace StardewModdingAPI.Events
         /// <summary>The core event manager.</summary>
         private static EventManager EventManager;
 
+        /// <summary>Manages deprecation warnings.</summary>
+        private static DeprecationManager DeprecationManager;
+
 
         /*********
         ** Events
@@ -19,7 +25,11 @@ namespace StardewModdingAPI.Events
         /// <summary>Raised after the content language changes.</summary>
         public static event EventHandler<EventArgsValueChanged<string>> AfterLocaleChanged
         {
-            add => ContentEvents.EventManager.Legacy_LocaleChanged.Add(value);
+            add
+            {
+                ContentEvents.DeprecationManager.WarnForOldEvents();
+                ContentEvents.EventManager.Legacy_LocaleChanged.Add(value);
+            }
             remove => ContentEvents.EventManager.Legacy_LocaleChanged.Remove(value);
         }
 
@@ -29,9 +39,12 @@ namespace StardewModdingAPI.Events
         *********/
         /// <summary>Initialise the events.</summary>
         /// <param name="eventManager">The core event manager.</param>
-        internal static void Init(EventManager eventManager)
+        /// <param name="deprecationManager">Manages deprecation warnings.</param>
+        internal static void Init(EventManager eventManager, DeprecationManager deprecationManager)
         {
             ContentEvents.EventManager = eventManager;
+            ContentEvents.DeprecationManager = deprecationManager;
         }
     }
 }
+#endif
diff --git a/src/SMAPI/Events/ControlEvents.cs b/src/SMAPI/Events/ControlEvents.cs
index 56a4fa3f..5626ff81 100644
--- a/src/SMAPI/Events/ControlEvents.cs
+++ b/src/SMAPI/Events/ControlEvents.cs
@@ -1,10 +1,13 @@
+#if !SMAPI_3_0_STRICT
 using System;
 using Microsoft.Xna.Framework.Input;
+using StardewModdingAPI.Framework;
 using StardewModdingAPI.Framework.Events;
 
 namespace StardewModdingAPI.Events
 {
     /// <summary>Events raised when the player uses a controller, keyboard, or mouse.</summary>
+    [Obsolete("Use " + nameof(Mod.Helper) + "." + nameof(IModHelper.Events) + " instead. See https://smapi.io/3.0 for more info.")]
     public static class ControlEvents
     {
         /*********
@@ -13,6 +16,9 @@ namespace StardewModdingAPI.Events
         /// <summary>The core event manager.</summary>
         private static EventManager EventManager;
 
+        /// <summary>Manages deprecation warnings.</summary>
+        private static DeprecationManager DeprecationManager;
+
 
         /*********
         ** Events
@@ -20,56 +26,88 @@ namespace StardewModdingAPI.Events
         /// <summary>Raised when the <see cref="KeyboardState"/> changes. That happens when the player presses or releases a key.</summary>
         public static event EventHandler<EventArgsKeyboardStateChanged> KeyboardChanged
         {
-            add => ControlEvents.EventManager.Legacy_KeyboardChanged.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_KeyboardChanged.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_KeyboardChanged.Remove(value);
         }
 
         /// <summary>Raised after the player presses a keyboard key.</summary>
         public static event EventHandler<EventArgsKeyPressed> KeyPressed
         {
-            add => ControlEvents.EventManager.Legacy_KeyPressed.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_KeyPressed.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_KeyPressed.Remove(value);
         }
 
         /// <summary>Raised after the player releases a keyboard key.</summary>
         public static event EventHandler<EventArgsKeyPressed> KeyReleased
         {
-            add => ControlEvents.EventManager.Legacy_KeyReleased.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_KeyReleased.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_KeyReleased.Remove(value);
         }
 
         /// <summary>Raised when the <see cref="MouseState"/> changes. That happens when the player moves the mouse, scrolls the mouse wheel, or presses/releases a button.</summary>
         public static event EventHandler<EventArgsMouseStateChanged> MouseChanged
         {
-            add => ControlEvents.EventManager.Legacy_MouseChanged.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_MouseChanged.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_MouseChanged.Remove(value);
         }
 
         /// <summary>The player pressed a controller button. This event isn't raised for trigger buttons.</summary>
         public static event EventHandler<EventArgsControllerButtonPressed> ControllerButtonPressed
         {
-            add => ControlEvents.EventManager.Legacy_ControllerButtonPressed.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_ControllerButtonPressed.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_ControllerButtonPressed.Remove(value);
         }
 
         /// <summary>The player released a controller button. This event isn't raised for trigger buttons.</summary>
         public static event EventHandler<EventArgsControllerButtonReleased> ControllerButtonReleased
         {
-            add => ControlEvents.EventManager.Legacy_ControllerButtonReleased.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_ControllerButtonReleased.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_ControllerButtonReleased.Remove(value);
         }
 
         /// <summary>The player pressed a controller trigger button.</summary>
         public static event EventHandler<EventArgsControllerTriggerPressed> ControllerTriggerPressed
         {
-            add => ControlEvents.EventManager.Legacy_ControllerTriggerPressed.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_ControllerTriggerPressed.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_ControllerTriggerPressed.Remove(value);
         }
 
         /// <summary>The player released a controller trigger button.</summary>
         public static event EventHandler<EventArgsControllerTriggerReleased> ControllerTriggerReleased
         {
-            add => ControlEvents.EventManager.Legacy_ControllerTriggerReleased.Add(value);
+            add
+            {
+                ControlEvents.DeprecationManager.WarnForOldEvents();
+                ControlEvents.EventManager.Legacy_ControllerTriggerReleased.Add(value);
+            }
             remove => ControlEvents.EventManager.Legacy_ControllerTriggerReleased.Remove(value);
         }
 
@@ -79,9 +117,12 @@ namespace StardewModdingAPI.Events
         *********/
         /// <summary>Initialise the events.</summary>
         /// <param name="eventManager">The core event manager.</param>
-        internal static void Init(EventManager eventManager)
+        /// <param name="deprecationManager">Manages deprecation warnings.</param>
+        internal static void Init(EventManager eventManager, DeprecationManager deprecationManager)
         {
             ControlEvents.EventManager = eventManager;
+            ControlEvents.DeprecationManager = deprecationManager;
         }
     }
 }
+#endif
diff --git a/src/SMAPI/Events/CursorMovedEventArgs.cs b/src/SMAPI/Events/CursorMovedEventArgs.cs
index 453743b9..43ff90ce 100644
--- a/src/SMAPI/Events/CursorMovedEventArgs.cs
+++ b/src/SMAPI/Events/CursorMovedEventArgs.cs
@@ -21,7 +21,7 @@ namespace StardewModdingAPI.Events
         /// <summary>Construct an instance.</summary>
         /// <param name="oldPosition">The previous cursor position.</param>
         /// <param name="newPosition">The new cursor position.</param>
-        public CursorMovedEventArgs(ICursorPosition oldPosition, ICursorPosition newPosition)
+        internal CursorMovedEventArgs(ICursorPosition oldPosition, ICursorPosition newPosition)
         {
             this.OldPosition = oldPosition;
             this.NewPosition = newPosition;
diff --git a/src/SMAPI/Events/DebrisListChangedEventArgs.cs b/src/SMAPI/Events/DebrisListChangedEventArgs.cs
index 1337bd3b..68328885 100644
--- a/src/SMAPI/Events/DebrisListChangedEventArgs.cs
+++ b/src/SMAPI/Events/DebrisListChangedEventArgs.cs
@@ -28,7 +28,7 @@ namespace StardewModdingAPI.Events
         /// <param name="location">The location which changed.</param>
         /// <param name="added">The debris added to the location.</param>
         /// <param name="removed">The debris removed from the location.</param>
-        public DebrisListChangedEventArgs(GameLocation location, IEnumerable<Debris> added, IEnumerable<Debris> removed)
+        internal DebrisListChangedEventArgs(GameLocation location, IEnumerable<Debris> added, IEnumerable<Debris> removed)
         {
             this.Location = location;
             this.Added = added.ToArray();
diff --git a/src/SMAPI/Events/EventArgsClickableMenuChanged.cs b/src/SMAPI/Events/EventArgsClickableMenuChanged.cs
index 2a2aa163..a0b903b7 100644
--- a/src/SMAPI/Events/EventArgsClickableMenuChanged.cs
+++ b/src/SMAPI/Ev