rewrite world/player state tracking (#453)

15 files changed, 880 insertions, 162 deletions

diff --git a/src/SMAPI/Framework/SGame.cs b/src/SMAPI/Framework/SGame.cs
index 4ec46e5c..cea86dfb 100644
--- a/src/SMAPI/Framework/SGame.cs
+++ b/src/SMAPI/Framework/SGame.cs
@@ -1,6 +1,6 @@
 using System;
-using System.Collections;
 using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Text;
@@ -13,6 +13,8 @@ using StardewModdingAPI.Events;
 using StardewModdingAPI.Framework.Events;
 using StardewModdingAPI.Framework.Input;
 using StardewModdingAPI.Framework.Reflection;
+using StardewModdingAPI.Framework.StateTracking;
+using StardewModdingAPI.Framework.StateTracking.FieldWatchers;
 using StardewModdingAPI.Framework.Utilities;
 using StardewValley;
 using StardewValley.BellsAndWhistles;
@@ -22,6 +24,7 @@ using StardewValley.Tools;
 using xTile.Dimensions;
 using xTile.Layers;
 using SFarmer = StardewValley.Farmer;
+using SObject = StardewValley.Object;
 
 namespace StardewModdingAPI.Framework
 {
@@ -60,6 +63,9 @@ namespace StardewModdingAPI.Framework
         /// <remarks>Skipping a few frames ensures the game finishes initialising the world before mods try to change it.</remarks>
         private int AfterLoadTimer = 5;
 
+        /// <summary>Whether the after-load events were raised for this session.</summary>
+        private bool RaisedAfterLoadEvent;
+
         /// <summary>Whether the game is returning to the menu.</summary>
         private bool IsExitingToTitle;
 
@@ -75,50 +81,26 @@ namespace StardewModdingAPI.Framework
         /// <summary>The player input as of the previous tick.</summary>
         private InputState PreviousInput = new InputState();
 
-        /// <summary>The window size value at last check.</summary>
-        private Point PreviousWindowSize;
-
-        /// <summary>The save ID at last check.</summary>
-        private ulong PreviousSaveID;
-
-        /// <summary>A hash of <see cref="Game1.locations"/> at last check.</summary>
-        private int PreviousGameLocations;
-
-        /// <summary>A hash of the current location's <see cref="GameLocation.objects"/> at last check.</summary>
-        private int PreviousLocationObjects;
-
-        /// <summary>The player's inventory at last check.</summary>
-        private IDictionary<Item, int> PreviousItems;
-
-        /// <summary>The player's combat skill level at last check.</summary>
-        private int PreviousCombatLevel;
-
-        /// <summary>The player's farming skill level at last check.</summary>
-        private int PreviousFarmingLevel;
-
-        /// <summary>The player's fishing skill level at last check.</summary>
-        private int PreviousFishingLevel;
-
-        /// <summary>The player's foraging skill level at last check.</summary>
-        private int PreviousForagingLevel;
+        /// <summary>The underlying watchers for convenience. These are accessible individually as separate properties.</summary>
+        private readonly List<IWatcher> Watchers = new List<IWatcher>();
 
-        /// <summary>The player's mining skill level at last check.</summary>
-        private int PreviousMiningLevel;
+        /// <summary>Tracks changes to the window size.</summary>
+        private readonly IValueWatcher<Point> WindowSizeWatcher;
 
-        /// <summary>The player's luck skill level at last check.</summary>
-        private int PreviousLuckLevel;
+        /// <summary>Tracks changes to the current player.</summary>
+        private PlayerTracker CurrentPlayerTracker;
 
-        /// <summary>The player's location at last check.</summary>
-        private GameLocation PreviousGameLocation;
+        /// <summary>Tracks changes to the time of day (in 24-hour military format).</summary>
+        private readonly IValueWatcher<int> TimeWatcher;
 
-        /// <summary>The active game menu at last check.</summary>
-        private IClickableMenu PreviousActiveMenu;
+        /// <summary>Tracks changes to the save ID.</summary>
+        private readonly IValueWatcher<ulong> SaveIdWatcher;
 
-        /// <summary>The mine level at last check.</summary>
-        private int PreviousMineLevel;
+        /// <summary>Tracks changes to the location list.</summary>
+        private readonly ICollectionWatcher<GameLocation> LocationsWatcher;
 
-        /// <summary>The time of day (in 24-hour military format) at last check.</summary>
-        private int PreviousTime;
+        /// <summary>Tracks changes to <see cref="Game1.activeClickableMenu"/>.</summary>
+        private readonly IValueWatcher<IClickableMenu> ActiveMenuWatcher;
 
         /// <summary>The previous content locale.</summary>
         private LocalizedContentManager.LanguageCode? PreviousLocale;
@@ -156,7 +138,10 @@ namespace StardewModdingAPI.Framework
         /// <param name="onGameInitialised">A callback to invoke after the game finishes initialising.</param>
         internal SGame(IMonitor monitor, Reflector reflection, EventManager eventManager, Action onGameInitialised)
         {
-            // initialise
+            // init XNA
+            Game1.graphics.GraphicsProfile = GraphicsProfile.HiDef;
+
+            // init SMAPI
             this.Monitor = monitor;
             this.Events = eventManager;
             this.FirstUpdate = true;
@@ -165,8 +150,21 @@ namespace StardewModdingAPI.Framework
             if (this.ContentCore == null) // shouldn't happen since CreateContentManager is called first, but let's init here just in case
                 this.ContentCore = new ContentCore(this.Content.ServiceProvider, this.Content.RootDirectory, Thread.CurrentThread.CurrentUICulture, this.Monitor, reflection);
 
-            // set XNA option required by Stardew Valley
-            Game1.graphics.GraphicsProfile = GraphicsProfile.HiDef;
+            // init watchers
+            Game1.locations = new ObservableCollection<GameLocation>();
+            this.SaveIdWatcher = WatcherFactory.ForEquatable(() => Game1.hasLoadedGame ? Game1.uniqueIDForThisGame : 0);
+            this.WindowSizeWatcher = WatcherFactory.ForEquatable(() => new Point(Game1.viewport.Width, Game1.viewport.Height));
+            this.TimeWatcher = WatcherFactory.ForEquatable(() => Game1.timeOfDay);
+            this.ActiveMenuWatcher = WatcherFactory.ForReference(() => Game1.activeClickableMenu);
+            this.LocationsWatcher = WatcherFactory.ForObservableCollection((ObservableCollection<GameLocation>)Game1.locations);
+            this.Watchers.AddRange(new IWatcher[]
+            {
+                this.SaveIdWatcher,
+                this.WindowSizeWatcher,
+                this.TimeWatcher,
+                this.ActiveMenuWatcher,
+                this.LocationsWatcher
+            });
         }
 
         /****
@@ -203,32 +201,59 @@ namespace StardewModdingAPI.Framework
                     return;
                 }
 
-                // While a background new-day task is in progress, the game skips its own update logic
-                // and defers to the XNA Update method. Running mod code in parallel to the background
-                // update is risky, because data changes can conflict (e.g. collection changed during
-                // enumeration errors) and data may change unexpectedly from one mod instruction to the
-                // next.
+                // While a background task is in progress, the game may make changes to the game
+                // state while mods are running their code. This is risky, because data changes can
+                // conflict (e.g. collection changed during enumeration errors) and data may change
+                // unexpectedly from one mod instruction to the next.
                 // 
                 // Therefore we can just run Game1.Update here without raising any SMAPI events. There's
                 // a small chance that the task will finish after we defer but before the game checks,
                 // which means technically events should be raised, but the effects of missing one
                 // update tick are neglible and not worth the complications of bypassing Game1.Update.
-                if (Game1._newDayTask != null)
+                if (Game1._newDayTask != null || Game1.gameMode == Game1.loadingMode)
                 {
                     base.Update(gameTime);
                     this.Events.Specialised_UnvalidatedUpdateTick.Raise();
                     return;
                 }
 
-                // game is asynchronously loading a save, block mod events to avoid conflicts
-                if (Game1.gameMode == Game1.loadingMode)
+                /*********
+                ** Update context
+                *********/
+                if (Context.IsSaveLoaded && !SaveGame.IsProcessing /*still loading save*/ && this.AfterLoadTimer >= 0)
                 {
-                    base.Update(gameTime);
-                    this.Events.Specialised_UnvalidatedUpdateTick.Raise();
-                    return;
+                    if (Game1.dayOfMonth != 0) // wait until new-game intro finishes (world not fully initialised yet)
+                        this.AfterLoadTimer--;
+                    Context.IsWorldReady = this.AfterLoadTimer <= 0;
                 }
 
                 /*********
+                ** Update watchers
+                *********/
+                // reset player
+                if (Context.IsWorldReady)
+                {
+                    if (this.CurrentPlayerTracker == null || this.CurrentPlayerTracker.Player != Game1.player)
+                    {
+                        this.CurrentPlayerTracker?.Dispose();
+                        this.CurrentPlayerTracker = new PlayerTracker(Game1.player);
+                    }
+                }
+                else
+                {
+                    if (this.CurrentPlayerTracker != null)
+                    {
+                        this.CurrentPlayerTracker.Dispose();
+                        this.CurrentPlayerTracker = null;
+                    }
+                }
+
+                // update values
+                foreach (IWatcher watcher in this.Watchers)
+                    watcher.Update();
+                this.CurrentPlayerTracker?.Update();
+
+                /*********
                 ** Save events + suppress events during save
                 *********/
                 // While the game is writing to the save file in the background, mods can unexpectedly
@@ -300,19 +325,12 @@ namespace StardewModdingAPI.Framework
                 /*********
                 ** After load events
                 *********/
-                if (Context.IsSaveLoaded && !SaveGame.IsProcessing /*still loading save*/ && this.AfterLoadTimer >= 0)
+                if (!this.RaisedAfterLoadEvent && Context.IsWorldReady)
                 {
-                    if (Game1.dayOfMonth != 0) // wait until new-game intro finishes (world not fully initialised yet)
-                        this.AfterLoadTimer--;
-
-                    if (this.AfterLoadTimer == 0)
-                    {
-                        this.Monitor.Log($"Context: loaded saved game '{Constants.SaveFolderName}', starting {Game1.currentSeason} {Game1.dayOfMonth} Y{Game1.year}.", LogLevel.Trace);
-                        Context.IsWorldReady = true;
-
-                        this.Events.Save_AfterLoad.Raise();
-                        this.Events.Time_AfterDayStarted.Raise();
-                    }
+                    this.RaisedAfterLoadEvent = true;
+                    this.Monitor.Log($"Context: loaded saved game '{Constants.SaveFolderName}', starting {Game1.currentSeason} {Game1.dayOfMonth} Y{Game1.year}.", LogLevel.Trace);
+                    this.Events.Save_AfterLoad.Raise();
+                    this.Events.Time_AfterDayStarted.Raise();
                 }
 
                 /*********
@@ -339,11 +357,10 @@ namespace StardewModdingAPI.Framework
                 // event because we need to notify mods after the game handles the resize, so the
                 // game's metadata (like Game1.viewport) are updated. That's a bit complicated
                 // since the game adds & removes its own handler on the fly.
-                if (Game1.viewport.Width != this.PreviousWindowSize.X || Game1.viewport.Height != this.PreviousWindowSize.Y)
+                if (this.WindowSizeWatcher.IsChanged)
                 {
-                    Point size = new Point(Game1.viewport.Width, Game1.viewport.Height);
                     this.Events.Graphics_Resize.Raise();
-                    this.PreviousWindowSize = size;
+                    this.WindowSizeWatcher.Reset();
                 }
 
                 /*********
@@ -431,10 +448,11 @@ namespace StardewModdingAPI.Framework
                 /*********
                 ** Menu events
                 *********/
-                if (Game1.activeClickableMenu != this.PreviousActiveMenu)
+                if (this.ActiveMenuWatcher.IsChanged)
                 {
-                    IClickableMenu previousMenu = this.PreviousActiveMenu;
-                    IClickableMenu newMenu = Game1.activeClickableMenu;
+                    IClickableMenu previousMenu = this.ActiveMenuWatcher.PreviousValue;
+                    IClickableMenu newMenu = this.ActiveMenuWatcher.CurrentValue;
+                    this.ActiveMenuWatcher.Reset(); // reset here so a mod changing the menu will be raised as a new event afterwards
 
                     // log context
                     if (this.VerboseLogging)
@@ -452,10 +470,6 @@ namespace StardewModdingAPI.Framework
                         this.Events.Menu_Changed.Raise(new EventArgsClickableMenuChanged(previousMenu, newMenu));
                     else
                         this.Events.Menu_Closed.Raise(new EventArgsClickableMenuClosed(previousMenu));
-
-                    // update previous menu
-                    // (if the menu was changed in one of the handlers, deliberately defer detection until the next update so mods can be notified of the new menu change)
-                    this.PreviousActiveMenu = newMenu;
                 }
 
                 /*********
@@ -463,70 +477,56 @@ namespace StardewModdingAPI.Framework
                 *********/
                 if (Context.IsWorldReady)
                 {
+                    // update player info
+                    PlayerTracker curPlayer = this.CurrentPlayerTracker;
+
                     // raise current location changed
-                    // ReSharper disable once PossibleUnintendedReferenceComparison
-                    if (Game1.currentLocation != this.PreviousGameLocation)
+                    if (curPlayer.TryGetNewLocation(out GameLocation newLocation))
                     {
                         if (this.VerboseLogging)
-                            this.Monitor.Log($"Context: set location to {Game1.currentLocation?.Name ?? "(none)"}.", LogLevel.Trace);
-                        this.Events.Location_CurrentLocationChanged.Raise(new EventArgsCurrentLocationChanged(this.PreviousGameLocation, Game1.currentLocation));
+                            this.Monitor.Log($"Context: set location to {newLocation.Name}.", LogLevel.Trace);
+                        this.Events.Location_CurrentLocationChanged.Raise(new EventArgsCurrentLocationChanged(curPlayer.LocationWatcher.PreviousValue, newLocation));
                     }
 
                     // raise location list changed
-                    if (this.GetHash(Game1.locations) != this.PreviousGameLocations)
+                    if (this.LocationsWatcher.IsChanged)
                         this.Events.Location_LocationsChanged.Raise(new EventArgsGameLocationsChanged(Game1.locations));
 
                     // raise events that shouldn't be triggered on initial load
-                    if (Game1.uniqueIDForThisGame == this.PreviousSaveID)
+                    if (!this.SaveIdWatcher.IsChanged)
                     {
                         // raise player leveled up a skill
-                        if (Game1.player.combatLevel != this.PreviousCombatLevel)
-                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(EventArgsLevelUp.LevelType.Combat, Game1.player.combatLevel));
-                        if (Game1.player.farmingLevel != this.PreviousFarmingLevel)
-                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(EventArgsLevelUp.LevelType.Farming, Game1.player.farmingLevel));
-                        if (Game1.player.fishingLevel != this.PreviousFishingLevel)
-                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(EventArgsLevelUp.LevelType.Fishing, Game1.player.fishingLevel));
-                        if (Game1.player.foragingLevel != this.PreviousForagingLevel)
-                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(EventArgsLevelUp.LevelType.Foraging, Game1.player.foragingLevel));
-                        if (Game1.player.miningLevel != this.PreviousMiningLevel)
-                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(EventArgsLevelUp.LevelType.Mining, Game1.player.miningLevel));
-                        if (Game1.player.luckLevel != this.PreviousLuckLevel)
-                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(EventArgsLevelUp.LevelType.Luck, Game1.player.luckLevel));
+                        foreach (KeyValuePair<EventArgsLevelUp.LevelType, IValueWatcher<int>> pair in curPlayer.GetChangedSkills())
+                            this.Events.Player_LeveledUp.Raise(new EventArgsLevelUp(pair.Key, pair.Value.CurrentValue));
 
                         // raise player inventory changed
-                        ItemStackChange[] changedItems = this.GetInventoryChanges(Game1.player.Items, this.PreviousItems).ToArray();
+                        ItemStackChange[] changedItems = curPlayer.GetInventoryChanges().ToArray();
                         if (changedItems.Any())
                             this.Events.Player_InventoryChanged.Raise(new EventArgsInventoryChanged(Game1.player.Items, changedItems.ToList()));
 
                         // raise current location's object list changed
-                        if (this.GetHash(Game1.currentLocation.objects) != this.PreviousLocationObjects)
-                            this.Events.Location_LocationObjectsChanged.Raise(new EventArgsLocationObjectsChanged(Game1.currentLocation.objects.FieldDict));
+                        if (curPlayer.TryGetLocationChanges(out IDictionaryWatcher<Vector2, SObject> _))
+                            this.Events.Location_LocationObjectsChanged.Raise(new EventArgsLocationObjectsChanged(curPlayer.GetCurrentLocation().objects.FieldDict));
 
                         // raise time changed
-                        if (Game1.timeOfDay != this.PreviousTime)
-                            this.Events.Time_TimeOfDayChanged.Raise(new EventArgsIntChanged(this.PreviousTime, Game1.timeOfDay));
+                        if (this.TimeWatcher.IsChanged)
+                            this.Events.Time_TimeOfDayChanged.Raise(new EventArgsIntChanged(this.TimeWatcher.PreviousValue, this.TimeWatcher.CurrentValue));
 
                         // raise mine level changed
-                        if (Game1.mine != null && Game1.mine.mineLevel != this.PreviousMineLevel)
-                            this.Events.Mine_LevelChanged.Raise(new EventArgsMineLevelChanged(this.PreviousMineLevel, Game1.mine.mineLevel));
+                        if (curPlayer.TryGetNewMineLevel(out int mineLevel))
+                        {
+                            this.Monitor.Log("curPlayer mine level changed", LogLevel.Alert);
+                            this.Events.Mine_LevelChanged.Raise(new EventArgsMineLevelChanged(curPlayer.MineLevelWatcher.PreviousValue, mineLevel));
+                        }
                     }
-
-                    // update state
-                    this.PreviousGameLocations = this.GetHash(Game1.locations);
-                    this.PreviousGameLocation = Game1.currentLocation;
-                    this.PreviousCombatLevel = Game1.player.combatLevel;
-                    this.PreviousFarmingLevel = Game1.player.farmingLevel;
-                    this.PreviousFishingLevel = Game1.player.fishingLevel;
-                    this.PreviousForagingLevel = Game1.player.foragingLevel;
-                    this.PreviousMiningLevel = Game1.player.miningLevel;
-                    this.PreviousLuckLevel = Game1.player.luckLevel;
-                    this.PreviousItems = Game1.player.Items.Where(n => n != null).Distinct().ToDictionary(n => n, n => n.Stack);
-                    this.PreviousLocationObjects = this.GetHash(Game1.currentLocation.objects);
-                    this.PreviousTime = Game1.timeOfDay;
-                    this.PreviousMineLevel = Game1.mine?.mineLevel ?? 0;
-                    this.PreviousSaveID = Game1.uniqueIDForThisGame;
                 }
 
+                // update state
+                this.CurrentPlayerTracker?.Reset();
+                this.LocationsWatcher.Reset();
+                this.SaveIdWatcher.Reset();
+                this.TimeWatcher.Reset();
+
                 /*********
                 ** Game update
                 *********/
@@ -982,7 +982,7 @@ namespace StardewModdingAPI.Framework
                                 }
                                 Game1.drawPlayerHeldObject(Game1.player);
                             }
-label_140:
+                            label_140:
                             if ((Game1.player.UsingTool || Game1.pickingTool) && Game1.player.CurrentTool != null && ((!Game1.player.CurrentTool.Name.Equals("Seeds") || Game1.pickingTool) && (Game1.currentLocation.Map.GetLayer("Front").PickTile(new Location(Game1.player.getStandingX(), (int)Game1.player.Position.Y - 38), Game1.viewport.Size) != null && Game1.currentLocation.Map.GetLayer("Front").PickTile(new Location(Game1.player.getStandingX(), Game1.player.getStandingY()), Game1.viewport.Size) == null)))
                                 Game1.drawTool(Game1.player);
                             if (Game1.currentLocation.Map.GetLayer("AlwaysFront") != null)
@@ -1204,52 +1204,7 @@ label_140:
         {
             Context.IsWorldReady = false;
             this.AfterLoadTimer = 5;
-            this.PreviousSaveID = 0;
-        }
-
-
-
-        /// <summary>Get the player inventory changes between two states.</summary>
-        /// <param name="current">The player's current inventory.</param>
-        /// <param name="previous">The player's previous inventory.</param>
-        private IEnumerable<ItemStackChange> GetInventoryChanges(IEnumerable<Item> current, IDictionary<Item, int> previous)
-        {
-            current = current.Where(n => n != null).ToArray();
-            foreach (Item item in current)
-            {
-                // stack size changed
-                if (previous != null && previous.ContainsKey(item))
-                {
-                    if (previous[item] != item.Stack)
-                        yield return new ItemStackChange { Item = item, StackChange = item.Stack - previous[item], ChangeType = ChangeType.StackChange };
-                }
-
-                // new item
-                else
-                    yield return new ItemStackChange { Item = item, StackChange = item.Stack, ChangeType = ChangeType.Added };
-            }
-
-            // removed items
-            if (previous != null)
-            {
-                foreach (var entry in previous)
-                {
-                    if (current.Any(i => i == entry.Key))
-                        continue;
-
-                    yield return new ItemStackChange { Item = entry.Key, StackChange = -entry.Key.Stack, ChangeType = ChangeType.Removed };
-                }
-            }
-        }
-
-        /// <summary>Get a hash value for an enumeration.</summary>
-        /// <param name="enumerable">The enumeration of items to hash.</param>
-        private int GetHash(IEnumerable enumerable)
-        {
-            int hash = 0;
-            foreach (object v in enumerable)
-                hash ^= v.GetHashCode();
-            return hash;
+            this.RaisedAfterLoadEvent = false;
         }
 
         /// <summary>Raise the <see cref="GraphicsEvents.OnPostRenderEvent"/> if there are any listeners.</summary>
diff --git a/src/SMAPI/Framework/StateTracking/Comparers/EquatableComparer.cs b/src/SMAPI/Framework/StateTracking/Comparers/EquatableComparer.cs
new file mode 100644
index 00000000..a96ffdb6
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/Comparers/EquatableComparer.cs
@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+
+namespace StardewModdingAPI.Framework.StateTracking.Comparers
+{
+    /// <summary>Compares instances using <see cref="IEqualityComparer{T}.Equals(T,T)"/>.</summary>
+    /// <typeparam name="T">The value type.</typeparam>
+    internal class EquatableComparer<T> : IEqualityComparer<T> where T : IEquatable<T>
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Determines whether the specified objects are equal.</summary>
+        /// <returns>true if the specified objects are equal; otherwise, false.</returns>
+        /// <param name="x">The first object to compare.</param>
+        /// <param name="y">The second object to compare.</param>
+        public bool Equals(T x, T y)
+        {
+            if (x == null)
+                return y == null;
+            return x.Equals(y);
+        }
+
+        /// <summary>Get a hash code for the specified object.</summary>
+        /// <param name="obj">The value.</param>
+        public int GetHashCode(T obj)
+        {
+            return RuntimeHelpers.GetHashCode(obj);
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/Comparers/ObjectReferenceComparer.cs b/src/SMAPI/Framework/StateTracking/Comparers/ObjectReferenceComparer.cs
new file mode 100644
index 00000000..ef9adafb
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/Comparers/ObjectReferenceComparer.cs
@@ -0,0 +1,29 @@
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+
+namespace StardewModdingAPI.Framework.StateTracking.Comparers
+{
+    /// <summary>A comparer which considers two references equal if they point to the same instance.</summary>
+    /// <typeparam name="T">The value type.</typeparam>
+    internal class ObjectReferenceComparer<T> : IEqualityComparer<T>
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Determines whether the specified objects are equal.</summary>
+        /// <returns>true if the specified objects are equal; otherwise, false.</returns>
+        /// <param name="x">The first object to compare.</param>
+        /// <param name="y">The second object to compare.</param>
+        public bool Equals(T x, T y)
+        {
+            return object.ReferenceEquals(x, y);
+        }
+
+        /// <summary>Get a hash code for the specified object.</summary>
+        /// <param name="obj">The value.</param>
+        public int GetHashCode(T obj)
+        {
+            return RuntimeHelpers.GetHashCode(obj);
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/BaseDisposableWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/BaseDisposableWatcher.cs
new file mode 100644
index 00000000..40ec6c57
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/BaseDisposableWatcher.cs
@@ -0,0 +1,36 @@
+using System;
+
+namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
+{
+    /// <summary>The base implementation for a disposable watcher.</summary>
+    internal abstract class BaseDisposableWatcher : IDisposable
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>Whether the watcher has been disposed.</summary>
+        protected bool IsDisposed { get; private set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Stop watching the field and release all references.</summary>
+        public virtual void Dispose()
+        {
+            this.IsDisposed = true;
+        }
+
+
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Throw an exception if the watcher is disposed.</summary>
+        /// <exception cref="ObjectDisposedException">The watcher is disposed.</exception>
+        protected void AssertNotDisposed()
+        {
+            if (this.IsDisposed)
+                throw new ObjectDisposedException(this.GetType().Name);
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs
new file mode 100644
index 00000000..d51fc2ac
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/ComparableWatcher.cs
@@ -0,0 +1,62 @@
+using System;
+using System.Collections.Generic;
+
+namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
+{
+    /// <summary>A watcher which detects changes to a value using a specified <see cref="IEqualityComparer{T}"/> instance.</summary>
+    internal class ComparableWatcher<T> : IValueWatcher<T>
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>Get the current value.</summary>
+        private readonly Func<T> GetValue;
+
+        /// <summary>The equality comparer.</summary>
+        private readonly IEqualityComparer<T> Comparer;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The field value at the last reset.</summary>
+        public T PreviousValue { get; private set; }
+
+        /// <summary>The latest value.</summary>
+        public T CurrentValue { get; private set; }
+
+        /// <summary>Whether the value changed since the last reset.</summary>
+        public bool IsChanged { get; private set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="getValue">Get the current value.</param>
+        /// <param name="comparer">The equality comparer which indicates whether two values are the same.</param>
+        public ComparableWatcher(Func<T> getValue, IEqualityComparer<T> comparer)
+        {
+            this.GetValue = getValue;
+            this.Comparer = comparer;
+            this.PreviousValue = getValue();
+        }
+
+        /// <summary>Update the current value if needed.</summary>
+        public void Update()
+        {
+            this.CurrentValue = this.GetValue();
+            this.IsChanged = !this.Comparer.Equals(this.PreviousValue, this.CurrentValue);
+        }
+
+        /// <summary>Set the current value as the baseline.</summary>
+        public void Reset()
+        {
+            this.PreviousValue = this.CurrentValue;
+            this.IsChanged = false;
+        }
+
+        /// <summary>Release any references if needed when the field is no longer needed.</summary>
+        public void Dispose() { }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs
new file mode 100644
index 00000000..7a2bf84e
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetDictionaryWatcher.cs
@@ -0,0 +1,103 @@
+using System.Collections.Generic;
+using Netcode;
+
+namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
+{
+    /// <summary>A watcher which detects changes to a net dictionary field.</summary>
+    /// <typeparam name="TKey">The dictionary key type.</typeparam>
+    /// <typeparam name="TValue">The dictionary value type.</typeparam>
+    /// <typeparam name="TField">The net type equivalent to <typeparamref name="TValue"/>.</typeparam>
+    /// <typeparam name="TSerialDict">The serializable dictionary type that can store the keys and values.</typeparam>
+    /// <typeparam name="TSelf">The net field instance type.</typeparam>
+    internal class NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf> : BaseDisposableWatcher, IDictionaryWatcher<TKey, TValue>
+        where TField : class, INetObject<INetSerializable>, new()
+        where TSerialDict : IDictionary<TKey, TValue>, new()
+        where TSelf : NetDictionary<TKey, TValue, TField, TSerialDict, TSelf>
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The pairs added since the last reset.</summary>
+        private readonly IDictionary<TKey, TValue> PairsAdded = new Dictionary<TKey, TValue>();
+
+        /// <summary>The pairs demoved since the last reset.</summary>
+        private readonly IDictionary<TKey, TValue> PairsRemoved = new Dictionary<TKey, TValue>();
+
+        /// <summary>The field being watched.</summary>
+        private readonly NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> Field;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether the collection changed since the last reset.</summary>
+        public bool IsChanged => this.PairsAdded.Count > 0 || this.PairsRemoved.Count > 0;
+
+        /// <summary>The values added since the last reset.</summary>
+        public IEnumerable<KeyValuePair<TKey, TValue>> Added => this.PairsAdded;
+
+        /// <summary>The values removed since the last reset.</summary>
+        public IEnumerable<KeyValuePair<TKey, TValue>> Removed => this.PairsRemoved;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="field">The field to watch.</param>
+        public NetDictionaryWatcher(NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> field)
+        {
+            this.Field = field;
+
+            field.OnValueAdded += this.OnValueAdded;
+            field.OnValueRemoved += this.OnValueRemoved;
+        }
+
+        /// <summary>Update the current value if needed.</summary>
+        public void Update()
+        {
+            this.AssertNotDisposed();
+        }
+
+        /// <summary>Set the current value as the baseline.</summary>
+        public void Reset()
+        {
+            this.AssertNotDisposed();
+
+            this.PairsAdded.Clear();
+            this.PairsRemoved.Clear();
+        }
+
+        /// <summary>Stop watching the field and release all references.</summary>
+        public override void Dispose()
+        {
+            if (!this.IsDisposed)
+            {
+                this.Field.OnValueAdded -= this.OnValueAdded;
+                this.Field.OnValueRemoved -= this.OnValueRemoved;
+            }
+            base.Dispose();
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>A callback invoked when an entry is added to the dictionary.</summary>
+        /// <param name="key">The entry key.</param>
+        /// <param name="value">The entry value.</param>
+        private void OnValueAdded(TKey key, TValue value)
+        {
+            this.PairsAdded[key] = value;
+        }
+
+        /// <summary>A callback invoked when an entry is removed from the dictionary.</summary>
+        /// <param name="key">The entry key.</param>
+        /// <param name="value">The entry value.</param>
+        private void OnValueRemoved(TKey key, TValue value)
+        {
+            if (!this.PairsRemoved.ContainsKey(key))
+                this.PairsRemoved[key] = value;
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs
new file mode 100644
index 00000000..188ed9f3
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetValueWatcher.cs
@@ -0,0 +1,83 @@
+using Netcode;
+
+namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
+{
+    /// <summary>A watcher which detects changes to a net value field.</summary>
+    internal class NetValueWatcher<T, TSelf> : BaseDisposableWatcher, IValueWatcher<T> where TSelf : NetFieldBase<T, TSelf>
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The field being watched.</summary>
+        private readonly NetFieldBase<T, TSelf> Field;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether the value changed since the last reset.</summary>
+        public bool IsChanged { get; private set; }
+
+        /// <summary>The field value at the last reset.</summary>
+        public T PreviousValue { get; private set; }
+
+        /// <summary>The latest value.</summary>
+        public T CurrentValue { get; private set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="field">The field to watch.</param>
+        public NetValueWatcher(NetFieldBase<T, TSelf> field)
+        {
+            this.Field = field;
+            this.PreviousValue = field.Value;
+            this.CurrentValue = field.Value;
+
+            field.fieldChangeVisibleEvent += this.OnValueChanged;
+            field.fieldChangeEvent += this.OnValueChanged;
+        }
+
+        /// <summary>Update the current value if needed.</summary>
+        public void Update()
+        {
+            this.AssertNotDisposed();
+        }
+
+        /// <summary>Set the current value as the baseline.</summary>
+        public void Reset()
+        {
+            this.AssertNotDisposed();
+
+            this.PreviousValue = this.CurrentValue;
+            this.IsChanged = false;
+        }
+
+        /// <summary>Stop watching the field and release all references.</summary>
+        public override void Dispose()
+        {
+            if (!this.IsDisposed)
+            {
+                this.Field.fieldChangeEvent -= this.OnValueChanged;
+                this.Field.fieldChangeVisibleEvent -= this.OnValueChanged;
+            }
+            base.Dispose();
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>A callback invoked when the field's value changes.</summary>
+        /// <param name="field">The field being watched.</param>
+        /// <param name="oldValue">The old field value.</param>
+        /// <param name="newValue">The new field value.</param>
+        private void OnValueChanged(TSelf field, T oldValue, T newValue)
+        {
+            this.CurrentValue = newValue;
+            this.IsChanged = true;
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs
new file mode 100644
index 00000000..34a97097
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/ObservableCollectionWatcher.cs
@@ -0,0 +1,86 @@
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Collections.Specialized;
+using System.Linq;
+
+namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
+{
+    /// <summary>A watcher which detects changes to an observable collection.</summary>
+    internal class ObservableCollectionWatcher<TValue> : BaseDisposableWatcher, ICollectionWatcher<TValue>
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The field being watched.</summary>
+        private readonly ObservableCollection<TValue> Field;
+
+        /// <summary>The pairs added since the last reset.</summary>
+        private readonly List<TValue> AddedImpl = new List<TValue>();
+
+        /// <summary>The pairs demoved since the last reset.</summary>
+        private readonly List<TValue> RemovedImpl = new List<TValue>();
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether the collection changed since the last reset.</summary>
+        public bool IsChanged => this.AddedImpl.Count > 0 || this.RemovedImpl.Count > 0;
+
+        /// <summary>The values added since the last reset.</summary>
+        public IEnumerable<TValue> Added => this.AddedImpl;
+
+        /// <summary>The values removed since the last reset.</summary>
+        public IEnumerable<TValue> Removed => this.RemovedImpl;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="field">The field to watch.</param>
+        public ObservableCollectionWatcher(ObservableCollection<TValue> field)
+        {
+            this.Field = field;
+            field.CollectionChanged += this.OnCollectionChanged;
+        }
+
+        /// <summary>Update the current value if needed.</summary>
+        public void Update()
+        {
+            this.AssertNotDisposed();
+        }
+
+        /// <summary>Set the current value as the baseline.</summary>
+        public void Reset()
+        {
+            this.AssertNotDisposed();
+
+            this.AddedImpl.Clear();
+            this.RemovedImpl.Clear();
+        }
+
+        /// <summary>Stop watching the field and release all references.</summary>
+        public override void Dispose()
+        {
+            if (!this.IsDisposed)
+                this.Field.CollectionChanged -= this.OnCollectionChanged;
+            base.Dispose();
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>A callback invoked when an entry is added or removed from the collection.</summary>
+        /// <param name="sender">The event sender.</param>
+        /// <param name="e">The event arguments.</param>
+        private void OnCollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
+        {
+            if (e.NewItems != null)
+                this.AddedImpl.AddRange(e.NewItems.Cast<TValue>());
+            if (e.OldItems != null)
+                this.RemovedImpl.AddRange(e.OldItems.Cast<TValue>());
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs
new file mode 100644
index 00000000..bf261bb5
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/WatcherFactory.cs
@@ -0,0 +1,54 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using Netcode;
+using StardewModdingAPI.Framework.StateTracking.Comparers;
+
+namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
+{
+    /// <summary>Provides convenience wrappers for creating watchers.</summary>
+    internal static class WatcherFactory
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get a watcher for an <see cref="IEquatable{T}"/> value.</summary>
+        /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="getValue">Get the current value.</param>
+        public static ComparableWatcher<T> ForEquatable<T>(Func<T> getValue) where T : IEquatable<T>
+        {
+            return new ComparableWatcher<T>(getValue, new EquatableComparer<T>());
+        }
+
+        /// <summary>Get a watcher which detects when an object reference changes.</summary>
+        /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="getValue">Get the current value.</param>
+        public static ComparableWatcher<T> ForReference<T>(Func<T> getValue)
+        {
+            return new ComparableWatcher<T>(getValue, new ObjectReferenceComparer<T>());
+        }
+
+        /// <summary>Get a watcher for an observable collection.</summary>
+        /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="collection">The observable collection.</param>
+        public static ObservableCollectionWatcher<T> ForObservableCollection<T>(ObservableCollection<T> collection)
+        {
+            return new ObservableCollectionWatcher<T>(collection);
+        }
+
+        /// <summary>Get a watcher for a net dictionary.</summary>
+        /// <typeparam name="TKey">The dictionary key type.</typeparam>
+        /// <typeparam name="TValue">The dictionary value type.</typeparam>
+        /// <typeparam name="TField">The net type equivalent to <typeparamref name="TValue"/>.</typeparam>
+        /// <typeparam name="TSerialDict">The serializable dictionary type that can store the keys and values.</typeparam>
+        /// <typeparam name="TSelf">The net field instance type.</typeparam>
+        /// <param name="field">The net field.</param>
+        public static NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf> ForNetDictionary<TKey, TValue, TField, TSerialDict, TSelf>(NetDictionary<TKey, TValue, TField, TSerialDict, TSelf> field)
+            where TField : class, INetObject<INetSerializable>, new()
+            where TSerialDict : IDictionary<TKey, TValue>, new()
+            where TSelf : NetDictionary<TKey, TValue, TField, TSerialDict, TSelf>
+        {
+            return new NetDictionaryWatcher<TKey, TValue, TField, TSerialDict, TSelf>(field);
+        }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/ICollectionWatcher.cs b/src/SMAPI/Framework/StateTracking/ICollectionWatcher.cs
new file mode 100644
index 00000000..7a7759e3
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/ICollectionWatcher.cs
@@ -0,0 +1,17 @@
+using System.Collections.Generic;
+
+namespace StardewModdingAPI.Framework.StateTracking
+{
+    /// <summary>A watcher which tracks changes to a collection.</summary>
+    internal interface ICollectionWatcher<out TValue> : IWatcher
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The values added since the last reset.</summary>
+        IEnumerable<TValue> Added { get; }
+
+        /// <summary>The values removed since the last reset.</summary>
+        IEnumerable<TValue> Removed { get; }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/IDictionaryWatcher.cs b/src/SMAPI/Framework/StateTracking/IDictionaryWatcher.cs
new file mode 100644
index 00000000..691ed377
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/IDictionaryWatcher.cs
@@ -0,0 +1,7 @@
+using System.Collections.Generic;
+
+namespace StardewModdingAPI.Framework.StateTracking
+{
+    /// <summary>A watcher which tracks changes to a dictionary.</summary>
+    internal interface IDictionaryWatcher<TKey, TValue> : ICollectionWatcher<KeyValuePair<TKey, TValue>> { }
+}
diff --git a/src/SMAPI/Framework/StateTracking/IValueWatcher.cs b/src/SMAPI/Framework/StateTracking/IValueWatcher.cs
new file mode 100644
index 00000000..4afca972
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/IValueWatcher.cs
@@ -0,0 +1,15 @@
+namespace StardewModdingAPI.Framework.StateTracking
+{
+    /// <summary>A watcher which tracks changes to a value.</summary>
+    internal interface IValueWatcher<out T> : IWatcher
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The field value at the last reset.</summary>
+        T PreviousValue { get; }
+
+        /// <summary>The latest value.</summary>
+        T CurrentValue { get; }
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/IWatcher.cs b/src/SMAPI/Framework/StateTracking/IWatcher.cs
new file mode 100644
index 00000000..8c7fa51c
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/IWatcher.cs
@@ -0,0 +1,24 @@
+using System;
+
+namespace StardewModdingAPI.Framework.StateTracking
+{
+    /// <summary>A watcher which detects changes to something.</summary>
+    internal interface IWatcher : IDisposable
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether the value changed since the last reset.</summary>
+        bool IsChanged { get; }
+
+
+        /*********
+        ** Methods
+        *********/
+        /// <summary>Update the current value if needed.</summary>
+        void Update();
+
+        /// <summary>Set the current value as the baseline.</summary>
+        void Reset();
+    }
+}
diff --git a/src/SMAPI/Framework/StateTracking/PlayerTracker.cs b/src/SMAPI/Framework/StateTracking/PlayerTracker.cs
new file mode 100644
index 00000000..81e074ec
--- /dev/null
+++ b/src/SMAPI/Framework/StateTracking/PlayerTracker.cs
@@ -0,0 +1,202 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.Xna.Framework;
+using StardewModdingAPI.Events;
+using StardewModdingAPI.Framework.StateTracking.FieldWatchers;
+using StardewValley;
+using StardewValley.Locations;
+using SFarmer = StardewValley.Farmer;
+using SObject = StardewValley.Object;
+
+namespace StardewModdingAPI.Framework.StateTracking
+{
+    /// <summary>Tracks changes to a player's data.</summary>
+    internal class PlayerTracker : IDisposable
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The player's inventory as of the last reset.</summary>
+        private IDictionary<Item, int> PreviousInventory;
+
+        /// <summary>The player's inventory change as of the last update.</summary>
+        private IDictionary<Item, int> CurrentInventory;
+
+        /// <summary>The player's last valid location.</summary>
+        private GameLocation LastValidLocation;
+
+        /// <summary>The underlying watchers.</summary>
+        private readonly List<IWatcher> Watchers = new List<IWatcher>();
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The player being tracked.</summary>
+        public SFarmer Player { get; }
+
+        /// <summary>The player's current location.</summary>
+        public IValueWatcher<GameLocation> LocationWatcher { get; }
+
+        /// <summary>Tracks changes to the player's current location's objects.</summary>
+        public IDictionaryWatcher<Vector2, SObject> LocationObjectsWatcher { get; private set; }
+
+        /// <summary>The player's current mine level.</summary>
+        public IValueWatcher<int> MineLevelWatcher { get; }
+
+        /// <summary>Tracks changes to the player's skill levels.</summary>
+        public IDictionary<EventArgsLevelUp.LevelType, IValueWatcher<int>> SkillWatchers { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="player">The player to track.</param>
+        public PlayerTracker(SFarmer player)
+        {
+            // init player data
+            this.Player = player;
+            this.PreviousInventory = this.GetInventory();
+
+            // init trackers
+            this.LocationWatcher = WatcherFactory.ForReference(this.GetCurrentLocation);
+            this.LocationObjectsWatcher = WatcherFactory.ForNetDictionary(this.GetCurrentLocation().objects);
+            this.MineLevelWatcher = WatcherFactory.ForEquatable(() => this.LastValidLocation is MineShaft mine ? mine.mineLevel : 0);
+            this.SkillWatchers = new Dictionary<EventArgsLevelUp.LevelType, IValueWatcher<int>>
+            {
+                [EventArgsLevelUp.LevelType.Combat] = WatcherFactory.ForEquatable(() => player.combatLevel),
+                [EventArgsLevelUp.LevelType.Farming] = WatcherFactory.ForEquatable(() => player.farmingLevel),
+                [EventArgsLevelUp.LevelType.Fishing] = WatcherFactory.ForEquatable(() => player.fishingLevel),
+                [EventArgsLevelUp.LevelType.Foraging] = WatcherFactory.ForEquatable(() => player.foragingLevel),
+                [EventArgsLevelUp.LevelType.Luck] = WatcherFactory.ForEquatable(() => player.luckLevel),
+                [EventArgsLevelUp.LevelType.Mining] = WatcherFactory.ForEquatable(() => player.miningLevel)
+            };
+
+            // track watchers for convenience
+            this.Watchers.AddRange(new IWatcher[]
+            {
+                this.LocationWatcher,
+                this.LocationObjectsWatcher,
+                this.MineLevelWatcher
+            });
+            this.Watchers.AddRange(this.SkillWatchers.Values);
+        }
+
+        /// <summary>Update the current values if needed.</summary>
+        public void Update()
+        {
+            // update valid location
+            this.LastValidLocation = this.GetCurrentLocation();
+
+            // update watchers
+            foreach (IWatcher watcher in this.Watchers)
+                watcher.Update();
+
+            // replace location objects watcher
+            if (this.LocationWatcher.IsChanged)
+            {
+                this.Watchers.Remove(this.LocationObjectsWatcher);
+                this.LocationObjectsWatcher.Dispose();
+
+                this.LocationObjectsWatcher = WatcherFactory.ForNetDictionary(this.GetCurrentLocation().objects);
+                this.Watchers.Add(this.LocationObjectsWatcher);
+            }
+
+            // update inventory
+            this.CurrentInventory = this.GetInventory();
+        }
+
+        /// <summary>Reset all trackers so their current values are the baseline.</summary>
+        public void Reset()
+        {
+            foreach (IWatcher watcher in this.Watchers)
+                watcher.Reset();
+
+            this.PreviousInventory = this.CurrentInventory;
+        }
+
+        /// <summary>Get the player's current location, ignoring temporary null values.</summary>
+        /// <remarks>The game will set <see cref="Character.currentLocation"/> to null in some cases, e.g. when they're a secondary player in multiplayer and transition to a location that hasn't been synced yet. While that's happening, this returns the player's last valid location instead.</remarks>
+        public GameLocation GetCurrentLocation()
+        {
+            return this.Player.currentLocation ?? this.LastValidLocation;
+        }
+
+        /// <summary>Get the player inventory changes between two states.</summary>
+        public IEnumerable<ItemStackChange> GetInventoryChanges()
+        {
+            IDictionary<Item, int> previous = this.PreviousInventory;
+            IDictionary<Item, int> current = this.GetInventory();
+            foreach (Item item in previous.Keys.Union(current.Keys))
+            {
+                if (!previous.TryGetValue(item, out int prevStack))
+                    yield return new ItemStackChange { Item = item, StackChange = item.Stack, ChangeType = ChangeType.Added };
+                else if (!current.TryGetValue(item, out int newStack))
+                    yield return new ItemStackChange { Item = item, StackChange = -item.Stack, ChangeType = ChangeType.Removed };
+                else if (prevStack != newStack)
+                    yield return new ItemStackChange { Item = item, StackChange = newStack - prevStack, ChangeType = ChangeType.StackChange };
+            }
+        }
+
+        /// <summary>Get the player skill levels which changed.</summary>
+        public IEnumerable<KeyValuePair<EventArgsLevelUp.LevelType, IValueWatcher<int>>> GetChangedSkills()
+        {
+            return this.SkillWatchers.Where(p => p.Value.IsChanged);
+        }
+
+        /// <summary>Get the player's new location if it changed.</summary>
+        /// <param name="location">The player's current location.</param>
+        /// <returns>Returns whether it changed.</returns>
+        public bool TryGetNewLocation(out GameLocation location)
+        {
+            location = this.LocationWatcher.CurrentValue;
+            return this.LocationWatcher.IsChanged;
+        }
+
+        /// <summary>Get object changes to the player's current location if they there as of the last reset.</summary>
+        /// <param name="watcher">The object change watcher.</param>
+        /// <returns>Returns whether it changed.</returns>
+        public bool TryGetLocationChanges(out IDictionaryWatcher<Vector2, SObject> watcher)
+        {
+            if (this.LocationWatcher.IsChanged)
+            {
+                watcher = null;
+                return false;
+            }
+
+            watcher = this.LocationObjectsWatcher;
+            return watcher.IsChanged;
+        }
+
+        /// <summary>Get the player's new mine level if it changed.</summary>
+        /// <param name="mineLevel">The player's current mine level.</param>
+        /// <returns>Returns whether it changed.</returns>
+        public bool TryGetNewMineLevel(out int mineLevel)
+        {
+            mineLevel = this.MineLevelWatcher.CurrentValue;
+            return this.MineLevelWatcher.IsChanged;
+        }
+
+        /// <summary>Stop watching the player fields and release all references.</summary>
+        public void Dispose()
+        {
+            foreach (IWatcher watcher in this.Watchers)
+                watcher.Dispose();
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Get the player's current inventory.</summary>
+        private IDictionary<Item, int> GetInventory()
+        {
+            return this.Player.Items
+                .Where(n => n != null)
+                .Distinct()
+                .ToDictionary(n => n, n => n.Stack);
+        }
+    }
+}
diff --git a/src/SMAPI/StardewModdingAPI.csproj b/src/SMAPI/StardewModdingAPI.csproj
index 9b4a496e..5fe3e32c 100644
--- a/src/SMAPI/StardewModdingAPI.csproj
+++ b/src/SMAPI/StardewModdingAPI.csproj
@@ -131,6 +131,19 @@
     <Compile Include="Framework\Serialisation\CrossplatformConverters\RectangleConverter.cs" />
     <Compile Include="Framework\Serialisation\CrossplatformConverters\ColorConverter.cs" />
     <Compile Include="Framework\Serialisation\CrossplatformConverters\PointConverter.cs" />
+    <Compile Include="Framework\StateTracking\Comparers\EquatableComparer.cs" />
+    <Compile Include="Framework\StateTracking\Comparers\ObjectReferenceComparer.cs" />
+    <Compile Include="Framework\StateTracking\FieldWatchers\BaseDisposableWatcher.cs" />
+    <Compile Include="Framework\StateTracking\FieldWatchers\ComparableWatcher.cs" />
+    <Compile Include="Framework\StateTracking\FieldWatchers\NetDictionaryWatcher.cs" />
+    <Compile Include="Framework\StateTracking\FieldWatchers\NetValueWatcher.cs" />
+    <Compile Include="Framework\StateTracking\FieldWatchers\ObservableCollectionWatcher.cs" />
+    <Compile Include="Framework\StateTracking\FieldWatchers\WatcherFactory.cs" />
+    <Compile Include="Framework\StateTracking\ICollectionWatcher.cs" />
+    <Compile Include="Framework\StateTracking\IDictionaryWatcher.cs" />
+    <Compile Include="Framework\StateTracking\IValueWatcher.cs" />
+    <Compile Include="Framework\StateTracking\IWatcher.cs" />
+    <Compile Include="Framework\StateTracking\PlayerTracker.cs" />
     <Compile Include="Framework\Utilities\ContextHash.cs" />
     <Compile Include="Framework\Utilities\PathUtilities.cs" />
     <Compile Include="IContentPack.cs" />