rewrite world/player state tracking (#453)

13 files changed, 750 insertions, 0 deletions

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);
+        }
+    }
+}