add reflection API for mods (#185)

13 files changed, 525 insertions, 11 deletions

diff --git a/src/StardewModdingAPI/Advanced/ConfigFile.cs b/src/StardewModdingAPI/Advanced/ConfigFile.cs
index 1aba2f2c..1a2e6618 100644
--- a/src/StardewModdingAPI/Advanced/ConfigFile.cs
+++ b/src/StardewModdingAPI/Advanced/ConfigFile.cs
@@ -9,7 +9,7 @@ namespace StardewModdingAPI.Advanced
         /*********
         ** Accessors
         *********/
-        /// <summary>Provides methods for interacting with the mod directory, including read/writing the config file.</summary>
+        /// <summary>Provides simplified APIs for writing mods.</summary>
         public IModHelper ModHelper { get; set; }
 
         /// <summary>The file path from which the model was loaded, relative to the mod directory.</summary>
diff --git a/src/StardewModdingAPI/Advanced/IConfigFile.cs b/src/StardewModdingAPI/Advanced/IConfigFile.cs
index 841f4c58..5bc31a88 100644
--- a/src/StardewModdingAPI/Advanced/IConfigFile.cs
+++ b/src/StardewModdingAPI/Advanced/IConfigFile.cs
@@ -6,7 +6,7 @@
         /*********
         ** Accessors
         *********/
-        /// <summary>Provides methods for interacting with the mod directory, including read/writing the config file.</summary>
+        /// <summary>Provides simplified APIs for writing mods.</summary>
         IModHelper ModHelper { get; set; }
 
         /// <summary>The file path from which the model was loaded, relative to the mod directory.</summary>
diff --git a/src/StardewModdingAPI/Framework/Reflection/PrivateField.cs b/src/StardewModdingAPI/Framework/Reflection/PrivateField.cs
new file mode 100644
index 00000000..6e7e3382
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Reflection/PrivateField.cs
@@ -0,0 +1,94 @@
+using System;
+using System.Reflection;
+using StardewModdingAPI.Reflection;
+
+namespace StardewModdingAPI.Framework.Reflection
+{
+    /// <summary>A private field obtained through reflection.</summary>
+    /// <typeparam name="TValue">The field value type.</typeparam>
+    internal class PrivateField<TValue> : IPrivateField<TValue>
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The type that has the field.</summary>
+        private readonly Type ParentType;
+
+        /// <summary>The object that has the instance field (if applicable).</summary>
+        private readonly object Parent;
+
+        /// <summary>The display name shown in error messages.</summary>
+        private string DisplayName => $"{this.ParentType.FullName}::{this.FieldInfo.Name}";
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The reflection metadata.</summary>
+        public FieldInfo FieldInfo { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="parentType">The type that has the field.</param>
+        /// <param name="obj">The object that has the instance field (if applicable).</param>
+        /// <param name="field">The reflection metadata.</param>
+        /// <param name="isStatic">Whether the field is static.</param>
+        /// <exception cref="ArgumentNullException">The <paramref name="parentType"/> or <paramref name="field"/> is null.</exception>
+        /// <exception cref="ArgumentException">The <paramref name="obj"/> is null for a non-static field, or not null for a static field.</exception>
+        public PrivateField(Type parentType, object obj, FieldInfo field, bool isStatic)
+        {
+            // validate
+            if (parentType == null)
+                throw new ArgumentNullException(nameof(parentType));
+            if (field == null)
+                throw new ArgumentNullException(nameof(field));
+            if (isStatic && obj != null)
+                throw new ArgumentException("A static field cannot have an object instance.");
+            if (!isStatic && obj == null)
+                throw new ArgumentException("A non-static field must have an object instance.");
+
+            // save
+            this.ParentType = parentType;
+            this.Parent = obj;
+            this.FieldInfo = field;
+        }
+
+        /// <summary>Get the field value.</summary>
+        public TValue GetValue()
+        {
+            try
+            {
+                return (TValue)this.FieldInfo.GetValue(this.Parent);
+            }
+            catch (InvalidCastException)
+            {
+                throw new InvalidCastException($"Can't convert the private {this.DisplayName} field from {this.FieldInfo.FieldType.FullName} to {typeof(TValue).FullName}.");
+            }
+            catch (Exception ex)
+            {
+                throw new Exception($"Couldn't get the value of the private {this.DisplayName} field", ex);
+            }
+        }
+
+        /// <summary>Set the field value.</summary>
+        //// <param name="value">The value to set.</param>
+        public void SetValue(TValue value)
+        {
+            try
+            {
+                this.FieldInfo.SetValue(this.Parent, value);
+            }
+            catch (InvalidCastException)
+            {
+                throw new InvalidCastException($"Can't assign the private {this.DisplayName} field a {typeof(TValue).FullName} value, must be compatible with {this.FieldInfo.FieldType.FullName}.");
+            }
+            catch (Exception ex)
+            {
+                throw new Exception($"Couldn't set the value of the private {this.DisplayName} field", ex);
+            }
+        }
+    }
+}
diff --git a/src/StardewModdingAPI/Framework/Reflection/PrivateMethod.cs b/src/StardewModdingAPI/Framework/Reflection/PrivateMethod.cs
new file mode 100644
index 00000000..5b882eed
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Reflection/PrivateMethod.cs
@@ -0,0 +1,100 @@
+using System;
+using System.Reflection;
+using StardewModdingAPI.Reflection;
+
+namespace StardewModdingAPI.Framework.Reflection
+{
+    /// <summary>A private method obtained through reflection.</summary>
+    internal class PrivateMethod : IPrivateMethod
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>The type that has the method.</summary>
+        private readonly Type ParentType;
+
+        /// <summary>The object that has the instance method (if applicable).</summary>
+        private readonly object Parent;
+
+        /// <summary>The display name shown in error messages.</summary>
+        private string DisplayName => $"{this.ParentType.FullName}::{this.MethodInfo.Name}";
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The reflection metadata.</summary>
+        public MethodInfo MethodInfo { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="parentType">The type that has the method.</param>
+        /// <param name="obj">The object that has the instance method(if applicable).</param>
+        /// <param name="method">The reflection metadata.</param>
+        /// <param name="isStatic">Whether the field is static.</param>
+        /// <exception cref="ArgumentNullException">The <paramref name="parentType"/> or <paramref name="method"/> is null.</exception>
+        /// <exception cref="ArgumentException">The <paramref name="obj"/> is null for a non-static method, or not null for a static method.</exception>
+        public PrivateMethod(Type parentType, object obj, MethodInfo method, bool isStatic)
+        {
+            // validate
+            if (parentType == null)
+                throw new ArgumentNullException(nameof(parentType));
+            if (method == null)
+                throw new ArgumentNullException(nameof(method));
+            if (isStatic && obj != null)
+                throw new ArgumentException("A static method cannot have an object instance.");
+            if (!isStatic && obj == null)
+                throw new ArgumentException("A non-static method must have an object instance.");
+
+            // save
+            this.ParentType = parentType;
+            this.Parent = obj;
+            this.MethodInfo = method;
+        }
+
+        /// <summary>Invoke the method.</summary>
+        /// <typeparam name="TValue">The return type.</typeparam>
+        /// <param name="arguments">The method arguments to pass in.</param>
+        public TValue Invoke<TValue>(params object[] arguments)
+        {
+            // invoke method
+            object result;
+            try
+            {
+                result = this.MethodInfo.Invoke(this.Parent, arguments);
+            }
+            catch (Exception ex)
+            {
+                throw new Exception($"Couldn't invoke the private {this.DisplayName} field", ex);
+            }
+
+            // cast return value
+            try
+            {
+                return (TValue)result;
+            }
+            catch (InvalidCastException)
+            {
+                throw new InvalidCastException($"Can't convert the return value of the private {this.DisplayName} method from {this.MethodInfo.ReturnType.FullName} to {typeof(TValue).FullName}.");
+            }
+        }
+
+        /// <summary>Invoke the method.</summary>
+        /// <param name="arguments">The method arguments to pass in.</param>
+        public void Invoke(params object[] arguments)
+        {
+            // invoke method
+            try
+            {
+                this.MethodInfo.Invoke(this.Parent, arguments);
+            }
+            catch (Exception ex)
+            {
+                throw new Exception($"Couldn't invoke the private {this.DisplayName} field", ex);
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/StardewModdingAPI/Framework/Reflection/ReflectionHelper.cs b/src/StardewModdingAPI/Framework/Reflection/ReflectionHelper.cs
new file mode 100644
index 00000000..17758a39
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Reflection/ReflectionHelper.cs
@@ -0,0 +1,197 @@
+using System;
+using System.Reflection;
+using StardewModdingAPI.Reflection;
+
+namespace StardewModdingAPI.Framework.Reflection
+{
+    /// <summary>Provides helper methods for accessing private game code.</summary>
+    internal class ReflectionHelper : IReflectionHelper
+    {
+        /*********
+        ** Public methods
+        *********/
+        /****
+        ** Fields
+        ****/
+        /// <summary>Get a private instance field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="obj">The object which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        /// <returns>Returns the field wrapper, or <c>null</c> if the field doesn't exist and <paramref name="required"/> is <c>false</c>.</returns>
+        public IPrivateField<TValue> GetPrivateField<TValue>(object obj, string name, bool required = true)
+        {
+            // validate
+            if (obj == null)
+                throw new ArgumentNullException(nameof(obj), "Can't get a private instance field from a null object.");
+
+            // get field from hierarchy
+            IPrivateField<TValue> field = this.GetFieldFromHierarchy<TValue>(obj.GetType(), obj, name, BindingFlags.Instance | BindingFlags.NonPublic);
+            if (required && field == null)
+                throw new InvalidOperationException($"The {obj.GetType().FullName} object doesn't have a private '{name}' instance field.");
+            return field;
+        }
+
+        /// <summary>Get a private static field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="type">The type which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        public IPrivateField<TValue> GetPrivateField<TValue>(Type type, string name, bool required = true)
+        {
+            // get field from hierarchy
+            IPrivateField<TValue> field = this.GetFieldFromHierarchy<TValue>(type, null, name, BindingFlags.NonPublic | BindingFlags.Static);
+            if (required && field == null)
+                throw new InvalidOperationException($"The {type.FullName} object doesn't have a private '{name}' static field.");
+            return field;
+        }
+
+        /****
+        ** Field values
+        ** (shorthand since this is the most common case)
+        ****/
+        /// <summary>Get the value of a private instance field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="obj">The object which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        /// <remarks>This is a shortcut for <see cref="GetPrivateField{TValue}(object,string,bool)"/> followed by <see cref="IPrivateField{TValue}.GetValue"/>.</remarks>
+        public TValue GetPrivateValue<TValue>(object obj, string name, bool required = true)
+        {
+            return this.GetPrivateField<TValue>(obj, name, required).GetValue();
+        }
+
+        /// <summary>Get the value of a private static field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="type">The type which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        /// <remarks>This is a shortcut for <see cref="GetPrivateField{TValue}(Type,string,bool)"/> followed by <see cref="IPrivateField{TValue}.GetValue"/>.</remarks>
+        public TValue GetPrivateValue<TValue>(Type type, string name, bool required = true)
+        {
+            return this.GetPrivateField<TValue>(type, name, required).GetValue();
+        }
+
+        /****
+        ** Methods
+        ****/
+        /// <summary>Get a private instance method.</summary>
+        /// <param name="obj">The object which has the method.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        public IPrivateMethod GetPrivateMethod(object obj, string name, bool required = true)
+        {
+            // validate
+            if (obj == null)
+                throw new ArgumentNullException(nameof(obj), "Can't get a private instance method from a null object.");
+
+            // get method from hierarchy
+            IPrivateMethod method = this.GetMethodFromHierarchy(obj.GetType(), obj, name, BindingFlags.Instance | BindingFlags.NonPublic);
+            if (required && method == null)
+                throw new InvalidOperationException($"The {obj.GetType().FullName} object doesn't have a private '{name}' instance method.");
+            return method;
+        }
+
+        /// <summary>Get a private static method.</summary>
+        /// <param name="type">The type which has the method.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        public IPrivateMethod GetPrivateMethod(Type type, string name, bool required = true)
+        {
+            // get method from hierarchy
+            IPrivateMethod method = this.GetMethodFromHierarchy(type, null, name, BindingFlags.NonPublic | BindingFlags.Static);
+            if (required && method == null)
+                throw new InvalidOperationException($"The {type.FullName} object doesn't have a private '{name}' static method.");
+            return method;
+        }
+
+        /****
+        ** Methods by signature
+        ****/
+        /// <summary>Get a private instance method.</summary>
+        /// <param name="obj">The object which has the method.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="argumentTypes">The argument types of the method signature to find.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        public IPrivateMethod GetPrivateMethod(object obj, string name, Type[] argumentTypes, bool required = true)
+        {
+            // validate parent
+            if (obj == null)
+                throw new ArgumentNullException(nameof(obj), "Can't get a private instance method from a null object.");
+
+            // get method from hierarchy
+            PrivateMethod method = this.GetMethodFromHierarchy(obj.GetType(), obj, name, BindingFlags.Instance | BindingFlags.NonPublic, argumentTypes);
+            if (required && method == null)
+                throw new InvalidOperationException($"The {obj.GetType().FullName} object doesn't have a private '{name}' instance method with that signature.");
+            return method;
+        }
+
+        /// <summary>Get a private static method.</summary>
+        /// <param name="type">The type which has the method.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="argumentTypes">The argument types of the method signature to find.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        public IPrivateMethod GetPrivateMethod(Type type, string name, Type[] argumentTypes, bool required = true)
+        {
+            // get field from hierarchy
+            PrivateMethod method = this.GetMethodFromHierarchy(type, null, name, BindingFlags.NonPublic | BindingFlags.Static, argumentTypes);
+            if (required && method == null)
+                throw new InvalidOperationException($"The {type.FullName} object doesn't have a private '{name}' static method with that signature.");
+            return method;
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Get a field from the type hierarchy.</summary>
+        /// <typeparam name="TValue">The expected field type.</typeparam>
+        /// <param name="type">The type which has the field.</param>
+        /// <param name="obj">The object which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="bindingFlags">The reflection binding which flags which indicates what type of field to find.</param>
+        private IPrivateField<TValue> GetFieldFromHierarchy<TValue>(Type type, object obj, string name, BindingFlags bindingFlags)
+        {
+            FieldInfo field = null;
+            for (; type != null && field == null; type = type.BaseType)
+                field = type.GetField(name, bindingFlags);
+
+            return field != null
+                ? new PrivateField<TValue>(type, obj, field, isStatic: bindingFlags.HasFlag(BindingFlags.Static))
+                : null;
+        }
+
+        /// <summary>Get a method from the type hierarchy.</summary>
+        /// <param name="type">The type which has the method.</param>
+        /// <param name="obj">The object which has the method.</param>
+        /// <param name="name">The method name.</param>
+        /// <param name="bindingFlags">The reflection binding which flags which indicates what type of method to find.</param>
+        private IPrivateMethod GetMethodFromHierarchy(Type type, object obj, string name, BindingFlags bindingFlags)
+        {
+            MethodInfo method = null;
+            for (; type != null && method == null; type = type.BaseType)
+                method = type.GetMethod(name, bindingFlags);
+
+            return method != null
+                ? new PrivateMethod(type, obj, method, isStatic: bindingFlags.HasFlag(BindingFlags.Static))
+                : null;
+        }
+
+        /// <summary>Get a method from the type hierarchy.</summary>
+        /// <param name="type">The type which has the method.</param>
+        /// <param name="obj">The object which has the method.</param>
+        /// <param name="name">The method name.</param>
+        /// <param name="bindingFlags">The reflection binding which flags which indicates what type of method to find.</param>
+        /// <param name="argumentTypes">The argument types of the method signature to find.</param>
+        private PrivateMethod GetMethodFromHierarchy(Type type, object obj, string name, BindingFlags bindingFlags, Type[] argumentTypes)
+        {
+            MethodInfo method = null;
+            for (; type != null && method == null; type = type.BaseType)
+                method = type.GetMethod(name, bindingFlags, null, argumentTypes, null);
+
+            return method != null
+                ? new PrivateMethod(type, obj, method, isStatic: bindingFlags.HasFlag(BindingFlags.Static))
+                : null;
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/StardewModdingAPI/IModHelper.cs b/src/StardewModdingAPI/IModHelper.cs
index 1af7df6b..709c8692 100644
--- a/src/StardewModdingAPI/IModHelper.cs
+++ b/src/StardewModdingAPI/IModHelper.cs
@@ -1,6 +1,8 @@
-namespace StardewModdingAPI
+using StardewModdingAPI.Reflection;
+
+namespace StardewModdingAPI
 {
-    /// <summary>Provides methods for interacting with a mod directory.</summary>
+    /// <summary>Provides simplified APIs for writing mods.</summary>
     public interface IModHelper
     {
         /*********
@@ -9,6 +11,9 @@
         /// <summary>The mod directory path.</summary>
         string DirectoryPath { get; }
 
+        /// <summary>Simplifies access to private game code.</summary>
+        IReflectionHelper Reflection { get; }
+
 
         /*********
         ** Public methods
diff --git a/src/StardewModdingAPI/Mod.cs b/src/StardewModdingAPI/Mod.cs
index 05122df5..21551771 100644
--- a/src/StardewModdingAPI/Mod.cs
+++ b/src/StardewModdingAPI/Mod.cs
@@ -13,10 +13,11 @@ namespace StardewModdingAPI
         /// <summary>The backing field for <see cref="Mod.PathOnDisk"/>.</summary>
         private string _pathOnDisk;
 
+
         /*********
         ** Accessors
         *********/
-        /// <summary>Provides methods for interacting with the mod directory, such as read/writing a config file or custom JSON files.</summary>
+        /// <summary>Provides simplified APIs for writing mods.</summary>
         public IModHelper Helper { get; internal set; }
 
         /// <summary>Writes messages to the console and log file.</summary>
@@ -74,12 +75,12 @@ namespace StardewModdingAPI
         public virtual void Entry(params object[] objects) { }
 
         /// <summary>The mod entry point, called after the mod is first loaded.</summary>
-        /// <param name="helper">Provides methods for interacting with the mod directory, such as read/writing a config file or custom JSON files.</param>
+        /// <param name="helper">Provides simplified APIs for writing mods.</param>
         [Obsolete("This overload is obsolete since SMAPI 1.1.")]
         public virtual void Entry(ModHelper helper) { }
 
         /// <summary>The mod entry point, called after the mod is first loaded.</summary>
-        /// <param name="helper">Provides methods for interacting with the mod directory, such as read/writing a config file or custom JSON files.</param>
+        /// <param name="helper">Provides simplified APIs for writing mods.</param>
         public virtual void Entry(IModHelper helper) { }
 
 
diff --git a/src/StardewModdingAPI/ModHelper.cs b/src/StardewModdingAPI/ModHelper.cs
index 6a7e200a..781deff4 100644
--- a/src/StardewModdingAPI/ModHelper.cs
+++ b/src/StardewModdingAPI/ModHelper.cs
@@ -2,11 +2,13 @@
 using System.IO;
 using Newtonsoft.Json;
 using StardewModdingAPI.Advanced;
+using StardewModdingAPI.Framework.Reflection;
+using StardewModdingAPI.Reflection;
 
 namespace StardewModdingAPI
 {
-    /// <summary>Provides methods for interacting with a mod directory.</summary>
-    [Obsolete("Use " + nameof(IModHelper) + " instead.")]
+    /// <summary>Provides simplified APIs for writing mods.</summary>
+    [Obsolete("Use " + nameof(IModHelper) + " instead.")] // only direct mod access to this class is obsolete
     public class ModHelper : IModHelper
     {
         /*********
@@ -15,6 +17,9 @@ namespace StardewModdingAPI
         /// <summary>The mod directory path.</summary>
         public string DirectoryPath { get; }
 
+        /// <summary>Simplifies access to private game code.</summary>
+        public IReflectionHelper Reflection { get; } = new ReflectionHelper();
+
 
         /*********
         ** Public methods
diff --git a/src/StardewModdingAPI/Reflection/IPrivateField.cs b/src/StardewModdingAPI/Reflection/IPrivateField.cs
new file mode 100644
index 00000000..f758902f
--- /dev/null
+++ b/src/StardewModdingAPI/Reflection/IPrivateField.cs
@@ -0,0 +1,26 @@
+using System.Reflection;
+
+namespace StardewModdingAPI.Reflection
+{
+    /// <summary>A private field obtained through reflection.</summary>
+    /// <typeparam name="TValue">The field value type.</typeparam>
+    public interface IPrivateField<TValue>
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The reflection metadata.</summary>
+        FieldInfo FieldInfo { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get the field value.</summary>
+        TValue GetValue();
+
+        /// <summary>Set the field value.</summary>
+        //// <param name="value">The value to set.</param>
+        void SetValue(TValue value);
+    }
+}
\ No newline at end of file
diff --git a/src/StardewModdingAPI/Reflection/IPrivateMethod.cs b/src/StardewModdingAPI/Reflection/IPrivateMethod.cs
new file mode 100644
index 00000000..4790303b
--- /dev/null
+++ b/src/StardewModdingAPI/Reflection/IPrivateMethod.cs
@@ -0,0 +1,27 @@
+using System.Reflection;
+
+namespace StardewModdingAPI.Reflection
+{
+    /// <summary>A private method obtained through reflection.</summary>
+    public interface IPrivateMethod
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The reflection metadata.</summary>
+        MethodInfo MethodInfo { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Invoke the method.</summary>
+        /// <typeparam name="TValue">The return type.</typeparam>
+        /// <param name="arguments">The method arguments to pass in.</param>
+        TValue Invoke<TValue>(params object[] arguments);
+
+        /// <summary>Invoke the method.</summary>
+        /// <param name="arguments">The method arguments to pass in.</param>
+        void Invoke(params object[] arguments);
+    }
+}
\ No newline at end of file
diff --git a/src/StardewModdingAPI/Reflection/IReflectionHelper.cs b/src/StardewModdingAPI/Reflection/IReflectionHelper.cs
new file mode 100644
index 00000000..f5d7d547
--- /dev/null
+++ b/src/StardewModdingAPI/Reflection/IReflectionHelper.cs
@@ -0,0 +1,53 @@
+using System;
+
+namespace StardewModdingAPI.Reflection
+{
+    /// <summary>Simplifies access to private game code.</summary>
+    public interface IReflectionHelper
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get a private instance field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="obj">The object which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        IPrivateField<TValue> GetPrivateField<TValue>(object obj, string name, bool required = true);
+
+        /// <summary>Get a private static field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="type">The type which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        IPrivateField<TValue> GetPrivateField<TValue>(Type type, string name, bool required = true);
+
+        /// <summary>Get the value of a private instance field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="obj">The object which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        /// <remarks>This is a shortcut for <see cref="GetPrivateField{TValue}(object,string,bool)"/> followed by <see cref="IPrivateField{TValue}.GetValue"/>.</remarks>
+        TValue GetPrivateValue<TValue>(object obj, string name, bool required = true);
+
+        /// <summary>Get the value of a private static field.</summary>
+        /// <typeparam name="TValue">The field type.</typeparam>
+        /// <param name="type">The type which has the field.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        /// <remarks>This is a shortcut for <see cref="GetPrivateField{TValue}(Type,string,bool)"/> followed by <see cref="IPrivateField{TValue}.GetValue"/>.</remarks>
+        TValue GetPrivateValue<TValue>(Type type, string name, bool required = true);
+
+        /// <summary>Get a private instance method.</summary>
+        /// <param name="obj">The object which has the method.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        IPrivateMethod GetPrivateMethod(object obj, string name, bool required = true);
+
+        /// <summary>Get a private static method.</summary>
+        /// <param name="type">The type which has the method.</param>
+        /// <param name="name">The field name.</param>
+        /// <param name="required">Whether to throw an exception if the private field is not found.</param>
+        IPrivateMethod GetPrivateMethod(Type type, string name, bool required = true);
+    }
+}
diff --git a/src/StardewModdingAPI/StardewModdingAPI.csproj b/src/StardewModdingAPI/StardewModdingAPI.csproj
index a90a0686..59edc0c9 100644
--- a/src/StardewModdingAPI/StardewModdingAPI.csproj
+++ b/src/StardewModdingAPI/StardewModdingAPI.csproj
@@ -161,6 +161,9 @@
     <Compile Include="Framework\DeprecationManager.cs" />
     <Compile Include="Framework\InternalExtensions.cs" />
     <Compile Include="Framework\ModAssemblyLoader.cs" />
+    <Compile Include="Framework\Reflection\PrivateField.cs" />
+    <Compile Include="Framework\Reflection\PrivateMethod.cs" />
+    <Compile Include="Framework\Reflection\ReflectionHelper.cs" />
     <Compile Include="IModHelper.cs" />
     <Compile Include="Framework\LogFileManager.cs" />
     <Compile Include="LogLevel.cs" />
@@ -182,6 +185,9 @@
     <Compile Include="Program.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="Inheritance\SGame.cs" />
+    <Compile Include="Reflection\IPrivateField.cs" />
+    <Compile Include="Reflection\IPrivateMethod.cs" />
+    <Compile Include="Reflection\IReflectionHelper.cs" />
     <Compile Include="Version.cs" />
   </ItemGroup>
   <ItemGroup>
diff --git a/src/TrainerMod/TrainerMod.cs b/src/TrainerMod/TrainerMod.cs
index 9572c494..f0c7549f 100644
--- a/src/TrainerMod/TrainerMod.cs
+++ b/src/TrainerMod/TrainerMod.cs
@@ -40,7 +40,7 @@ namespace TrainerMod
         ** Public methods
         *********/
         /// <summary>The mod entry point, called after the mod is first loaded.</summary>
-        /// <param name="helper">Provides methods for interacting with the mod directory, such as read/writing a config file or custom JSON files.</param>
+        /// <param name="helper">Provides simplified APIs for writing mods.</param>
         public override void Entry(IModHelper helper)
         {
             this.RegisterCommands();
@@ -694,7 +694,7 @@ namespace TrainerMod
             else
                 this.LogValueNotSpecified();
         }
-        
+
         /****
         ** Helpers
         ****/