add delegating mod hooks for mod use

docs/release-notes.md

@@ -12,6 +12,7 @@
   * Fixed save backups being empty in rare cases on macOS.
 
 * For mod authors:
+  * Added `DelegatingModHooks` utility for rare cases where a mod needs to override SMAPI's mod hooks in the game directly.
   * Updated to Newtonsoft.Json 13.0.2 (see [changes](https://github.com/JamesNK/Newtonsoft.Json/releases/tag/13.0.2)) and Pintail 2.2.1 (see [changes](https://github.com/Nanoray-pl/Pintail/blob/master/docs/release-notes.md#222)).
 
 ## 3.18.1

src/SMAPI/Framework/SCore.cs

@@ -258,7 +258,11 @@ namespace StardewModdingAPI.Framework
                     monitor: this.Monitor,
                     reflection: this.Reflection,
                     eventManager: this.EventManager,
-                    modHooks: new SModHooks(this.OnNewDayAfterFade, this.Monitor),
+                    modHooks: new SModHooks(
+                        parent: new ModHooks(),
+                        beforeNewDayAfterFade: this.OnNewDayAfterFade,
+                        monitor: this.Monitor
+                    ),
                     multiplayer: this.Multiplayer,
                     exitGameImmediately: this.ExitGameImmediately,
 
@@ -1795,7 +1799,7 @@ namespace StardewModdingAPI.Framework
                     // call entry method
                     try
                     {
-                        mod.Entry(mod.Helper!);
+                        mod.Entry(mod.Helper);
                     }
                     catch (Exception ex)
                     {
@@ -1822,7 +1826,7 @@ namespace StardewModdingAPI.Framework
                     }
 
                     // validate mod doesn't implement both GetApi() and GetApi(mod)
-                    if (metadata.Api != null && mod.GetType().GetMethod(nameof(Mod.GetApi), new Type[] { typeof(IModInfo) })!.DeclaringType != typeof(Mod))
+                    if (metadata.Api != null && mod.GetType().GetMethod(nameof(Mod.GetApi), new[] { typeof(IModInfo) })!.DeclaringType != typeof(Mod))
                         metadata.LogAsMod($"Mod implements both {nameof(Mod.GetApi)}() and {nameof(Mod.GetApi)}({nameof(IModInfo)}), which isn't allowed. The latter will be ignored.", LogLevel.Error);
                 }
                 Context.HeuristicModsRunningCode.TryPop(out _);

src/SMAPI/Framework/SModHooks.cs

@@ -1,11 +1,12 @@
 using System;
 using System.Threading.Tasks;
+using StardewModdingAPI.Utilities;
 using StardewValley;
 
 namespace StardewModdingAPI.Framework
 {
     /// <summary>Invokes callbacks for mod hooks provided by the game.</summary>
-    internal class SModHooks : ModHooks
+    internal class SModHooks : DelegatingModHooks
     {
         /*********
         ** Fields
@@ -21,25 +22,24 @@ namespace StardewModdingAPI.Framework
         ** Public methods
         *********/
         /// <summary>Construct an instance.</summary>
+        /// <param name="parent">The underlying hooks to call by default.</param>
         /// <param name="beforeNewDayAfterFade">A callback to invoke before <see cref="Game1.newDayAfterFade"/> runs.</param>
         /// <param name="monitor">Writes messages to the console.</param>
-        public SModHooks(Action beforeNewDayAfterFade, IMonitor monitor)
+        public SModHooks(ModHooks parent, Action beforeNewDayAfterFade, IMonitor monitor)
+            : base(parent)
         {
             this.BeforeNewDayAfterFade = beforeNewDayAfterFade;
             this.Monitor = monitor;
         }
 
-        /// <summary>A hook invoked when <see cref="Game1.newDayAfterFade"/> is called.</summary>
+        /// <inheritdoc />
-        /// <param name="action">The vanilla <see cref="Game1.newDayAfterFade"/> logic.</param>
         public override void OnGame1_NewDayAfterFade(Action action)
         {
             this.BeforeNewDayAfterFade();
             action();
         }
 
-        /// <summary>Start an asynchronous task for the game.</summary>
+        /// <inheritdoc />
-        /// <param name="task">The task to start.</param>
-        /// <param name="id">A unique key which identifies the task.</param>
         public override Task StartTask(Task task, string id)
         {
             this.Monitor.Log($"Synchronizing '{id}' task...");
@@ -48,9 +48,7 @@ namespace StardewModdingAPI.Framework
             return task;
         }
 
-        /// <summary>Start an asynchronous task for the game.</summary>
+        /// <inheritdoc />
-        /// <param name="task">The task to start.</param>
-        /// <param name="id">A unique key which identifies the task.</param>
         public override Task<T> StartTask<T>(Task<T> task, string id)
         {
             this.Monitor.Log($"Synchronizing '{id}' task...");

src/SMAPI/Utilities/DelegatingModHooks.cs

@@ -0,0 +1,137 @@
+using System;
+using System.Threading.Tasks;
+using Microsoft.Xna.Framework.Input;
+using StardewModdingAPI.Events;
+using StardewModdingAPI.Framework;
+using StardewValley;
+using StardewValley.Events;
+
+namespace StardewModdingAPI.Utilities
+{
+    /// <summary>An implementation of <see cref="ModHooks"/> which automatically calls the parent instance for any method that's not overridden.</summary>
+    /// <remarks>The mod hooks are primarily meant for SMAPI to use. Using this directly in mods is a last resort, since it's very easy to break SMAPI this way. This class requires that SMAPI is present in the parent chain.</remarks>
+    public class DelegatingModHooks : ModHooks
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The underlying instance to delegate to by default.</summary>
+        public ModHooks Parent { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="modHooks">The underlying instance to delegate to by default.</param>
+        public DelegatingModHooks(ModHooks modHooks)
+        {
+            this.AssertSmapiInChain(modHooks);
+
+            this.Parent = modHooks;
+        }
+
+        /// <summary>Raised before the in-game clock changes.</summary>
+        /// <param name="action">Run the vanilla update logic.</param>
+        /// <remarks>In mods, consider using <see cref="IGameLoopEvents.TimeChanged"/> instead.</remarks>
+        public override void OnGame1_PerformTenMinuteClockUpdate(Action action)
+        {
+            this.Parent.OnGame1_PerformTenMinuteClockUpdate(action);
+        }
+
+        /// <summary>Raised before initializing the new day and saving.</summary>
+        /// <param name="action">Run the vanilla update logic.</param>
+        /// <remarks>In mods, consider using <see cref="IGameLoopEvents.DayEnding"/> or <see cref="IGameLoopEvents.Saving"/> instead.</remarks>
+        public override void OnGame1_NewDayAfterFade(Action action)
+        {
+            this.Parent.OnGame1_NewDayAfterFade(action);
+        }
+
+        /// <summary>Raised before showing the end-of-day menus (e.g. shipping menus, level-up screen, etc).</summary>
+        /// <param name="action">Run the vanilla update logic.</param>
+        public override void OnGame1_ShowEndOfNightStuff(Action action)
+        {
+            this.Parent.OnGame1_ShowEndOfNightStuff(action);
+        }
+
+        /// <summary>Raised before updating the gamepad, mouse, and keyboard input state.</summary>
+        /// <param name="keyboardState">The keyboard state.</param>
+        /// <param name="mouseState">The mouse state.</param>
+        /// <param name="gamePadState">The gamepad state.</param>
+        /// <param name="action">Run the vanilla update logic.</param>
+        /// <remarks>In mods, consider using <see cref="IInputEvents"/> instead.</remarks>
+        public override void OnGame1_UpdateControlInput(ref KeyboardState keyboardState, ref MouseState mouseState, ref GamePadState gamePadState, Action action)
+        {
+            this.Parent.OnGame1_UpdateControlInput(ref keyboardState, ref mouseState, ref gamePadState, action);
+        }
+
+        /// <summary>Raised before a location is updated for the local player entering it.</summary>
+        /// <param name="location">The location that will be updated.</param>
+        /// <param name="action">Run the vanilla update logic.</param>
+        /// <remarks>In mods, consider using <see cref="IPlayerEvents.Warped"/> instead.</remarks>
+        public override void OnGameLocation_ResetForPlayerEntry(GameLocation location, Action action)
+        {
+            this.Parent.OnGameLocation_ResetForPlayerEntry(location, action);
+        }
+
+        /// <summary>Raised before the game checks for an action to trigger for a player interaction with a tile.</summary>
+        /// <param name="location">The location being checked.</param>
+        /// <param name="tileLocation">The tile position being checked.</param>
+        /// <param name="viewport">The game's current position and size within the map, measured in pixels.</param>
+        /// <param name="who">The player interacting with the tile.</param>
+        /// <param name="action">Run the vanilla update logic.</param>
+        /// <returns>Returns whether the interaction was handled.</returns>
+        public override bool OnGameLocation_CheckAction(GameLocation location, xTile.Dimensions.Location tileLocation, xTile.Dimensions.Rectangle viewport, Farmer who, Func<bool> action)
+        {
+            return this.Parent.OnGameLocation_CheckAction(location, tileLocation, viewport, who, action);
+        }
+
+        /// <summary>Raised before the game picks a night event to show on the farm after the player sleeps.</summary>
+        /// <param name="action">Run the vanilla update logic.</param>
+        /// <returns>Returns the selected farm event.</returns>
+        public override FarmEvent OnUtility_PickFarmEvent(Func<FarmEvent> action)
+        {
+            return this.Parent.OnUtility_PickFarmEvent(action);
+        }
+
+        /// <summary>Start an asynchronous task for the game.</summary>
+        /// <param name="task">The task to start.</param>
+        /// <param name="id">A unique key which identifies the task.</param>
+        public override Task StartTask(Task task, string id)
+        {
+            return this.Parent.StartTask(task, id);
+        }
+
+        /// <summary>Start an asynchronous task for the game.</summary>
+        /// <typeparam name="T">The type returned by the task when it completes.</typeparam>
+        /// <param name="task">The task to start.</param>
+        /// <param name="id">A unique key which identifies the task.</param>
+        public override Task<T> StartTask<T>(Task<T> task, string id)
+        {
+            return this.Parent.StartTask<T>(task, id);
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Assert that SMAPI's mod hook implementation is in the inheritance chain.</summary>
+        /// <param name="hooks">The mod hooks to check.</param>
+        private void AssertSmapiInChain(ModHooks hooks)
+        {
+            // this is SMAPI
+            if (this is SModHooks)
+                return;
+
+            // SMAPI in delegated chain
+            for (ModHooks? cur = hooks; cur != null; cur = (cur as DelegatingModHooks)?.Parent)
+            {
+                if (cur is SModHooks)
+                    return;
+            }
+
+            // SMAPI not found
+            throw new InvalidOperationException($"Can't create a {nameof(DelegatingModHooks)} instance without SMAPI's mod hooks in the parent chain.");
+        }
+    }
+}