minor refactoring

This commit...
- removes key fields added to non-keyed types like NetListWatcher and SnapshotListDiff;
- fixes existing chests not being watched;
- fixes diffs not correctly updated for added/removed chests;
- performs minor cleanup, adds missing docs, etc.

7 files changed, 128 insertions, 88 deletions

diff --git a/src/SMAPI/Framework/Events/EventManager.cs b/src/SMAPI/Framework/Events/EventManager.cs
index dad45f95..892cbc7b 100644
--- a/src/SMAPI/Framework/Events/EventManager.cs
+++ b/src/SMAPI/Framework/Events/EventManager.cs
@@ -148,8 +148,8 @@ namespace StardewModdingAPI.Framework.Events
         /// <summary>Raised after objects are added or removed in a location.</summary>
         public readonly ManagedEvent<ObjectListChangedEventArgs> ObjectListChanged;
 
-        /// <summary>Raised after a new item is added or removed from a chest in a location.</summary>
-        public readonly ManagedEvent<ChestItemChangedEventArgs> ChestItemsChanged;
+        /// <summary>Raised after items are added or removed from a chest.</summary>
+        public readonly ManagedEvent<ChestInventoryChangedEventArgs> ChestInventoryChanged;
 
         /// <summary>Raised after terrain features (like floors and trees) are added or removed in a location.</summary>
         public readonly ManagedEvent<TerrainFeatureListChangedEventArgs> TerrainFeatureListChanged;
@@ -224,7 +224,7 @@ namespace StardewModdingAPI.Framework.Events
             this.LocationListChanged = ManageEventOf<LocationListChangedEventArgs>(nameof(IModEvents.World), nameof(IWorldEvents.BuildingListChanged));
             this.NpcListChanged = ManageEventOf<NpcListChangedEventArgs>(nameof(IModEvents.World), nameof(IWorldEvents.NpcListChanged));
             this.ObjectListChanged = ManageEventOf<ObjectListChangedEventArgs>(nameof(IModEvents.World), nameof(IWorldEvents.ObjectListChanged));
-            this.ChestItemsChanged = ManageEventOf<ChestItemChangedEventArgs>(nameof(IModEvents.World), nameof(IWorldEvents.ChestItemChanged));
+            this.ChestInventoryChanged = ManageEventOf<ChestInventoryChangedEventArgs>(nameof(IModEvents.World), nameof(IWorldEvents.ChestInventoryChanged));
             this.TerrainFeatureListChanged = ManageEventOf<TerrainFeatureListChangedEventArgs>(nameof(IModEvents.World), nameof(IWorldEvents.TerrainFeatureListChanged));
 
             this.LoadStageChanged = ManageEventOf<LoadStageChangedEventArgs>(nameof(IModEvents.Specialized), nameof(ISpecializedEvents.LoadStageChanged));
diff --git a/src/SMAPI/Framework/Events/ModWorldEvents.cs b/src/SMAPI/Framework/Events/ModWorldEvents.cs
index 8d6701ec..2ae69669 100644
--- a/src/SMAPI/Framework/Events/ModWorldEvents.cs
+++ b/src/SMAPI/Framework/Events/ModWorldEvents.cs
@@ -51,10 +51,11 @@ namespace StardewModdingAPI.Framework.Events
             remove => this.EventManager.ObjectListChanged.Remove(value);
         }
 
-        public event EventHandler<ChestItemChangedEventArgs> ChestItemChanged
+        /// <summary>Raised after items are added or removed from a chest.</summary>
+        public event EventHandler<ChestInventoryChangedEventArgs> ChestInventoryChanged
         {
-            add => this.EventManager.ChestItemsChanged.Add(value);
-            remove => this.EventManager.ChestItemsChanged.Remove(value);
+            add => this.EventManager.ChestInventoryChanged.Add(value);
+            remove => this.EventManager.ChestInventoryChanged.Remove(value);
         }
 
         /// <summary>Raised after terrain features (like floors and trees) are added or removed in a location.</summary>
diff --git a/src/SMAPI/Framework/SGame.cs b/src/SMAPI/Framework/SGame.cs
index 564fec1d..64da1cf1 100644
--- a/src/SMAPI/Framework/SGame.cs
+++ b/src/SMAPI/Framework/SGame.cs
@@ -703,8 +703,15 @@ namespace StardewModdingAPI.Framework
                                     events.ObjectListChanged.Raise(new ObjectListChangedEventArgs(location, locState.Objects.Added, locState.Objects.Removed));
 
                                 // chest items changed
-                                if (locState.ChestItems.IsChanged)
-                                    events.ChestItemsChanged.Raise(new ChestItemChangedEventArgs(location, locState.ChestItems.Added, locState.ChestItems.Removed, locState.ChestItems.Key));
+                                if (events.ChestInventoryChanged.HasListeners())
+                                {
+                                    foreach (var pair in locState.ChestItems)
+                                    {
+                                        var diff = pair.Value;
+                                        if (diff.IsChanged)
+                                            events.ChestInventoryChanged.Raise(new ChestInventoryChangedEventArgs(location, pair.Key, diff.Added, diff.Removed));
+                                    }
+                                }
 
                                 // terrain features changed
                                 if (locState.TerrainFeatures.IsChanged)
diff --git a/src/SMAPI/Framework/SnapshotListDiff.cs b/src/SMAPI/Framework/SnapshotListDiff.cs
index b14cacdb..d4d5df50 100644
--- a/src/SMAPI/Framework/SnapshotListDiff.cs
+++ b/src/SMAPI/Framework/SnapshotListDiff.cs
@@ -29,18 +29,10 @@ namespace StardewModdingAPI.Framework
         /// <summary>The added values.</summary>
         public IEnumerable<T> Added => this.AddedImpl;
 
-        public Microsoft.Xna.Framework.Vector2 Key;
 
         /*********
         ** Public methods
         *********/
-
-        public void Update(ICollectionWatcher<T> watcher, Microsoft.Xna.Framework.Vector2 key)
-        {
-            this.Key = key;
-            this.Update(watcher.IsChanged, watcher.Removed, watcher.Added);
-        }
-
         /// <summary>Update the snapshot.</summary>
         /// <param name="isChanged">Whether the value changed since the last update.</param>
         /// <param name="removed">The removed values.</param>
diff --git a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs
index cac66356..8aa0eab5 100644
--- a/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs
+++ b/src/SMAPI/Framework/StateTracking/FieldWatchers/NetListWatcher.cs
@@ -1,21 +1,18 @@
-using System;
 using System.Collections.Generic;
 using Netcode;
 
 namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
 {
-    internal class NetListWatcher<TKey, TValue> : BaseDisposableWatcher, ICollectionWatcher<TValue>
+    /// <summary>A watcher which detects changes to a net list field.</summary>
+    /// <typeparam name="TValue">The list value type.</typeparam>
+    internal class NetListWatcher<TValue> : BaseDisposableWatcher, ICollectionWatcher<TValue>
         where TValue : class, INetObject<INetSerializable>
     {
-
-
         /*********
         ** Fields
         *********/
         /// <summary>The field being watched.</summary>
-        private readonly NetList<TValue, Netcode.NetRef<TValue>> Field;
-
-        public TKey Key { get; }
+        private readonly NetList<TValue, NetRef<TValue>> Field;
 
         /// <summary>The pairs added since the last reset.</summary>
         private readonly IList<TValue> AddedImpl = new List<TValue>();
@@ -23,26 +20,47 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
         /// <summary>The pairs removed since the last reset.</summary>
         private readonly IList<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 NetListWatcher(NetList<TValue, Netcode.NetRef<TValue>> field, TKey key)
+        public NetListWatcher(NetList<TValue, NetRef<TValue>> field)
         {
             this.Field = field;
-            this.Key = key;
             field.OnElementChanged += this.OnElementChanged;
             field.OnArrayReplaced += this.OnArrayReplaced;
         }
 
-        public bool IsChanged => this.AddedImpl.Count > 0 || this.RemovedImpl.Count > 0;
-
-        public IEnumerable<TValue> Added => this.AddedImpl;
+        /// <summary>Set the current value as the baseline.</summary>
+        public void Reset()
+        {
+            this.AddedImpl.Clear();
+            this.RemovedImpl.Clear();
+        }
 
-        public IEnumerable<TValue> Removed => this.RemovedImpl;
+        /// <summary>Update the current value if needed.</summary>
+        public void Update()
+        {
+            this.AssertNotDisposed();
+        }
 
-        public void Dispose()
+        /// <summary>Stop watching the field and release all references.</summary>
+        public override void Dispose()
         {
             if (!this.IsDisposed)
             {
@@ -53,47 +71,37 @@ namespace StardewModdingAPI.Framework.StateTracking.FieldWatchers
             base.Dispose();
         }
 
-        public void Reset()
-        {
-            this.AddedImpl.Clear();
-            this.RemovedImpl.Clear();
-        }
-
-        public void Update()
-        {
-            this.AssertNotDisposed();
-        }
 
         /*********
         ** Private methods
         *********/
-        private void OnArrayReplaced(NetList<TValue, Netcode.NetRef<TValue>> list, IList<TValue> before, IList<TValue> after)
+        /// <summary>A callback invoked when the value list is replaced.</summary>
+        /// <param name="list">The net field whose values changed.</param>
+        /// <param name="oldValues">The previous list of values.</param>
+        /// <param name="newValues">The new list of values.</param>
+        private void OnArrayReplaced(NetList<TValue, NetRef<TValue>> list, IList<TValue> oldValues, IList<TValue> newValues)
         {
             this.AddedImpl.Clear();
             this.RemovedImpl.Clear();
 
-            foreach(var obj in after)
-                this.AddedImpl.Add(obj);
+            foreach (TValue value in newValues)
+                this.AddedImpl.Add(value);
 
-            foreach(var obj in before)
-                this.RemovedImpl.Add(obj);
+            foreach (TValue value in oldValues)
+                this.RemovedImpl.Add(value);
         }
 
-        private void OnElementChanged(NetList<TValue, Netcode.NetRef<TValue>> list, int index, TValue oldValue, TValue newValue)
+        /// <summary>A callback invoked when an entry is replaced.</summary>
+        /// <param name="list">The net field whose values changed.</param>
+        /// <param name="index">The list index which changed.</param>
+        /// <param name="oldValue">The previous value.</param>
+        /// <param name="newValue">The new value.</param>
+        private void OnElementChanged(NetList<TValue, NetRef<TValue>> list, int index, TValue oldValue, TValue newValue)
         {
-
-            /* checks for stack addition / subtraction changing stacks does not fire off an element changed event
-            if ((oldValue != null && newValue != null) && oldValue.CompareTo(newValue) < 0)
-                this.AddedImpl.Add(newValue);
-            //Stack Removed from
-            if ((oldValue != null && newValue != null) && oldValue.CompareTo(newValue) > 0)
-                this.RemovedImpl.Add(newValue);
-                */
-
-            if(newValue!=null)
+            if (newValue != null)
                 this.AddedImpl.Add(newValue);
 
-            if(oldValue!=null)
+            if (oldValue != null)
                 this.RemovedImpl.Add(oldValue);
         }
     }
diff --git a/src/SMAPI/Framework/StateTracking/LocationTracker.cs b/src/SMAPI/Framework/StateTracking/LocationTracker.cs
index ef4a8b64..170fd537 100644
--- a/src/SMAPI/Framework/StateTracking/LocationTracker.cs
+++ b/src/SMAPI/Framework/StateTracking/LocationTracker.cs
@@ -5,9 +5,9 @@ using StardewModdingAPI.Framework.StateTracking.FieldWatchers;
 using StardewValley;
 using StardewValley.Buildings;
 using StardewValley.Locations;
+using StardewValley.Objects;
 using StardewValley.TerrainFeatures;
-using Object = StardewValley.Object;
-using Chest = StardewValley.Objects.Chest;
+using SObject = StardewValley.Object;
 
 namespace StardewModdingAPI.Framework.StateTracking
 {
@@ -43,12 +43,14 @@ namespace StardewModdingAPI.Framework.StateTracking
         public ICollectionWatcher<NPC> NpcsWatcher { get; }
 
         /// <summary>Tracks added or removed objects.</summary>
-        public IDictionaryWatcher<Vector2, Object> ObjectsWatcher { get; }
+        public IDictionaryWatcher<Vector2, SObject> ObjectsWatcher { get; }
 
         /// <summary>Tracks added or removed terrain features.</summary>
         public IDictionaryWatcher<Vector2, TerrainFeature> TerrainFeaturesWatcher { get; }
 
-        public Dictionary<Vector2, NetListWatcher<Vector2, Item>> activeChestWatchers = new Dictionary<Vector2, NetListWatcher<Vector2, Item>>();
+        /// <summary>Tracks items added or removed to chests.</summary>
+        public Dictionary<Vector2, ICollectionWatcher<Item>> ChestWatchers = new Dictionary<Vector2, ICollectionWatcher<Item>>();
+
 
         /*********
         ** Public methods
@@ -76,13 +78,8 @@ namespace StardewModdingAPI.Framework.StateTracking
                 this.ObjectsWatcher,
                 this.TerrainFeaturesWatcher
             });
-        }
 
-        /// <summary>Stop watching the player fields and release all references.</summary>
-        public void Dispose()
-        {
-            foreach (IWatcher watcher in this.Watchers)
-                watcher.Dispose();
+            this.UpdateChestWatcherList(added: location.Objects.Pairs, removed: new KeyValuePair<Vector2, SObject>[0]);
         }
 
         /// <summary>Update the current value if needed.</summary>
@@ -91,24 +88,7 @@ namespace StardewModdingAPI.Framework.StateTracking
             foreach (IWatcher watcher in this.Watchers)
                 watcher.Update();
 
-            foreach (KeyValuePair<Vector2, Object> obj in this.ObjectsWatcher.Added.Where(p => p.Value is Chest))
-            {
-                if (!this.activeChestWatchers.ContainsKey(obj.Key))
-                {
-                    //create a new watcher for chests items
-                    Chest temp = obj.Value as Chest;
-                    NetListWatcher<Vector2, Item> tempItemWatcher = new NetListWatcher<Vector2, Item>(temp.items, obj.Key);
-                    this.Watchers.Add(tempItemWatcher);
-                    this.activeChestWatchers.Add(obj.Key, tempItemWatcher);
-                }
-            }
-
-            foreach (KeyValuePair<Vector2, Object> obj in this.ObjectsWatcher.Removed)
-            {
-                this.activeChestWatchers.TryGetValue(obj.Key, out NetListWatcher<Vector2, Item> tempItemWatcher);
-                this.Watchers.Remove(tempItemWatcher);
-                this.activeChestWatchers.Remove(obj.Key);
-            } 
+            this.UpdateChestWatcherList(added: this.ObjectsWatcher.Added, removed: this.ObjectsWatcher.Removed);
         }
 
         /// <summary>Set the current value as the baseline.</summary>
@@ -117,5 +97,43 @@ namespace StardewModdingAPI.Framework.StateTracking
             foreach (IWatcher watcher in this.Watchers)
                 watcher.Reset();
         }
+
+        /// <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>Update the watcher list for added or removed chests.</summary>
+        /// <param name="added">The objects added to the location.</param>
+        /// <param name="removed">The objects removed from the location.</param>
+        private void UpdateChestWatcherList(IEnumerable<KeyValuePair<Vector2, SObject>> added, IEnumerable<KeyValuePair<Vector2, SObject>> removed)
+        {
+            // remove unused watchers
+            foreach (KeyValuePair<Vector2, SObject> pair in removed)
+            {
+                if (pair.Value is Chest && this.ChestWatchers.TryGetValue(pair.Key, out ICollectionWatcher<Item> watcher))
+                {
+                    this.Watchers.Remove(watcher);
+                    this.ChestWatchers.Remove(pair.Key);
+                }
+            }
+
+            // add new watchers
+            foreach (KeyValuePair<Vector2, SObject> pair in added)
+            {
+                if (pair.Value is Chest chest && !this.ChestWatchers.ContainsKey(pair.Key))
+                {
+                    ICollectionWatcher<Item> watcher = new NetListWatcher<Item>(chest.items);
+                    this.Watchers.Add(watcher);
+                    this.ChestWatchers.Add(pair.Key, watcher);
+                }
+            }
+        }
     }
 }
diff --git a/src/SMAPI/Framework/StateTracking/Snapshots/LocationSnapshot.cs b/src/SMAPI/Framework/StateTracking/Snapshots/LocationSnapshot.cs
index 31cf29c3..4074336b 100644
--- a/src/SMAPI/Framework/StateTracking/Snapshots/LocationSnapshot.cs
+++ b/src/SMAPI/Framework/StateTracking/Snapshots/LocationSnapshot.cs
@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using System.Linq;
 using Microsoft.Xna.Framework;
 using StardewValley;
 using StardewValley.Buildings;
@@ -33,7 +34,8 @@ namespace StardewModdingAPI.Framework.StateTracking.Snapshots
         /// <summary>Tracks added or removed terrain features.</summary>
         public SnapshotListDiff<KeyValuePair<Vector2, TerrainFeature>> TerrainFeatures { get; } = new SnapshotListDiff<KeyValuePair<Vector2, TerrainFeature>>();
 
-        public SnapshotListDiff<Item> ChestItems { get; } = new SnapshotListDiff<Item>();
+        /// <summary>Tracks changed chest inventories.</summary>
+        public IDictionary<Vector2, SnapshotListDiff<Item>> ChestItems { get; } = new Dictionary<Vector2, SnapshotListDiff<Item>>();
 
 
         /*********
@@ -50,6 +52,7 @@ namespace StardewModdingAPI.Framework.StateTracking.Snapshots
         /// <param name="watcher">The watcher to snapshot.</param>
         public void Update(LocationTracker watcher)
         {
+            // main lists
             this.Buildings.Update(watcher.BuildingsWatcher);
             this.Debris.Update(watcher.DebrisWatcher);
             this.LargeTerrainFeatures.Update(watcher.LargeTerrainFeaturesWatcher);
@@ -57,8 +60,19 @@ namespace StardewModdingAPI.Framework.StateTracking.Snapshots
             this.Objects.Update(watcher.ObjectsWatcher);
             this.TerrainFeatures.Update(watcher.TerrainFeaturesWatcher);
 
-            foreach (var obj in watcher.activeChestWatchers)
-                this.ChestItems.Update(obj.Value, obj.Key);
+            // chest inventories
+            foreach (Vector2 key in this.ChestItems.Keys.ToArray())
+            {
+                if (!watcher.ChestWatchers.ContainsKey(key))
+                    this.ChestItems.Remove(key);
+            }
+            foreach (var pair in watcher.ChestWatchers)
+            {
+                if (!this.ChestItems.TryGetValue(pair.Key, out var diff))
+                    this.ChestItems[pair.Key] = diff = new SnapshotListDiff<Item>();
+
+                diff.Update(pair.Value);
+            }
         }
     }
 }